SecondBrain Memory API v1¶

AI you can audit. Memory that improves itself. A memory + grounded-retrieval API that other agents (Claude Code, Cursor, ChatGPT, Codex, custom) plug into via HTTP and MCP. Every response carries a Citation envelope so callers can audit the provenance of every claim — and the same serving path runs the Antahkarana cognitive stack (Chitta, Manas, Viveka, Karma) plus Autotune, with each layer's contribution published as a counter so the self-improvement claim is measurable, not marketing.

Status: Draft. Contract artifact at contracts/memory_api_v1.yaml (in the repo root). v1.1 adds the knowledge assimilation lifecycle to the public Memory API.

The Memory API returns grounded data; the calling agent brings the LLM and synthesis. We don't try to be the LLM — we try to be the layer that makes any LLM trustworthy by giving it citations on every recall.

If a route or tool is not in this document, it is internal-only and may change without notice.

Public surface¶

#	HTTP	MCP tool	What it does
1	`POST /v1/memory/recall`	`secondbrain_recall`	Hybrid retrieval over the workspace vault
2	`POST /v1/memory/ingest`	`secondbrain_ingest`	Add a file or text to the vault and index it
2b	`POST /v1/memory/forget`	`secondbrain_forget`	Unindex by `source_path` or `chunk_hash` (idempotent)
3	`POST /v1/memory/pack`	`secondbrain_pack`	Build a bounded ContextPack for an intent
3a	`POST /v1/memory/assimilation/shravan`	`secondbrain_shravan_add`	Capture source-aware intake with authority, lineage, questions, and citation
3b	`POST /v1/memory/assimilation/manan`	`secondbrain_manan_reflect`	Reflect on intake, extract claims, questions, counterpoints, and principles
3c	`POST /v1/memory/assimilation/nididhyasan`	`secondbrain_nididhyasan_implement`	Convert reflection into a habit, task, rule, checklist, project, or principle
3d	`GET /v1/memory/assimilation/status`	`secondbrain_knowledge_status`	Show knowledge maturity counts, recent records, and citations
3e	`GET /v1/memory/assimilation/review`	`secondbrain_knowledge_review`	Review captured knowledge that still needs reflection or practice
4	`POST /v1/grounded/answer`	`secondbrain_grounded_answer`	Closed-corpus QA with citations + trajectory
4s	`POST /v1/grounded/answer/stream`	(SSE only)	Same as `grounded/answer` but streams `run_started` / `step` / `run_complete` SSE events
5	`POST /v1/grounded/eval`	`secondbrain_grounded_eval`	Score an agent output against expected nuggets
6	`GET /v1/decisions`	`secondbrain_decisions_list`	List decision records, namespace + cursor
7	`GET /v1/decisions/{ref}`	`secondbrain_decisions_get`	Fetch a single decision
8	`POST /v1/decisions`	`secondbrain_decisions_record`	Record a new decision (idempotent)
9	`POST /v1/decisions/extract`	`secondbrain_decision_extract`	Parse decisions from markdown without persisting
10	`POST /v1/meetings/extract`	`secondbrain_meeting_extract`	Run the meeting copilot on a transcript
11	`GET /v1/open_loops`	`secondbrain_open_loops`	List unresolved TODO/OPENLOOP markers
12	`GET /v1/audit/event_log`	`secondbrain_audit`	Tail the event log; trajectory replay via `?trajectory_id=`
13	`GET /v1/cognitive/uplift`	(read `/metrics` for MCP)	Snapshot of what each Antahkarana layer + Autotune contributed; `?since=7d` for time-windowed reads (durable across restarts), per-tenant `by_workspace` breakdown

The Citation envelope¶

Every memory-bearing response carries one or more Citation objects:

{
  "chunk_hash": "sha256:...",
  "source_path": "/workspace/vault/01_projects/launch_plan.md",
  "anchor": "## Risks",
  "text_span": "the migration must complete before May 12...",
  "score": 0.83,
  "retrieved_at": "2026-05-07T10:14:22Z"
}

chunk_hash is the durable content-addressed identity of the chunk (SHA-256 of normalized chunk text). Two ingests of the same content produce the same hash. Use it to dedupe, cache, or verify a chunk hasn't drifted.
source_path + anchor are the human-readable location.
text_span is the literal evidence text. It is what callers cite to users.
score is the retrieval confidence in [0, 1].

GroundedAnswer requires citations to be non-empty. A grounded answer with zero citations is a contract violation.

Knowledge assimilation lifecycle¶

The Memory API now distinguishes between captured, reflected, and practiced knowledge:

Shravan -> Manan -> Nididhyasan -> Lived Memory

Use the assimilation routes when a note should mature before it becomes durable operating knowledge.

curl -s -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
  -H "Content-Type: application/json" \
  http://localhost:8765/v1/memory/assimilation/shravan \
  -d '{
    "content": "No raw capture should go directly into durable memory.",
    "source_type": "design_note",
    "source_title": "Memory lifecycle note",
    "authority": "primary",
    "trust_score": 0.9,
    "relevance_score": 1.0
  }'

The response includes the durable stage record, a knowledge_maturity score, citations, and the next_stage. Manan and Nididhyasan continue the lifecycle:

curl -s -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
  -H "Content-Type: application/json" \
  http://localhost:8765/v1/memory/assimilation/manan \
  -d '{"shravan_id": "shravan_..."}'

curl -s -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
  -H "Content-Type: application/json" \
  http://localhost:8765/v1/memory/assimilation/nididhyasan \
  -d '{"manan_id": "manan_...", "implementation_type": "rule"}'

Set propose_memory: true on Nididhyasan to enqueue a governed long-term-memory review proposal. The route does not bypass memory governance.

Trajectory replay¶

Every grounded answer returns a trajectory_id. Replay it via:

GET /v1/audit/event_log?trajectory_id=<id>

This returns the full sequence of retrieval calls, tool invocations, and intermediate reasoning steps that produced the answer. This is the literal auditability promise.

Auth and tenancy¶

Authorization: Bearer <workspace_token>

The token is scoped to a single workspace. The token determines workspace_id; callers cannot cross workspaces by header. The optional x-sb-actor-id header attributes the action within the workspace but is auth-bound (rejected if it disagrees with the token's allowed actors).

Workspace tokens are issued via:

sb workspace token issue --workspace <name>

Multi-tenancy is in scope for the Memory API v1 but lands behind a feature flag (SB_MULTI_TENANT=1) until Phase 3 ships. Single-workspace installs migrate transparently to workspace=default.

What's NOT in the Memory API¶

These exist in SecondBrain but are not part of the public Memory API:

The broader HTTP surface beyond the routes above (chat, sessions, work graph, A2A bus, automations, integrations, plugins, cognitive layers, etc.) is internal-only. Callers should not depend on it; it may change.
secondbrain_ask — multi-source LLM synthesis. The Memory API returns data; agents bring the LLM. ask is a CLI convenience, not part of the v1 contract.
Vertical agents (marketer, travel, superpowers) — moved under examples/ as reference implementations of the Memory API.
The Antahkarana cognitive stack (chitta, manas, atman, ahamkara, karma, sankalpa) — SecondBrain's signature internal-driver layers. These power retrieval quality, salience tuning, predictive context loading, and self-narrative under the hood. They are deliberately not public API routes; the Memory API exposes their effects (better recall, better citations, better packs), not their internals. The names stay.

What's coming next¶

Likely candidates, not committed: - Per-actor rate limits and budgets visible in audit/event_log - Workspace-level eval suites attached to a workspace token - Richer retrieval filters over knowledge maturity state

Versioning¶

The Memory API is versioned at the URL prefix (/v1/). Breaking changes ship as /v2/. Additive changes (new optional fields, new routes) ship under /v1/. The OpenAPI document at contracts/memory_api_v1.yaml is the source of truth.