Give Claude Code, Cursor, and Codex Persistent, Auditable Memory

Coding agents are brilliant and amnesiac. Claude Code, Cursor, and Codex can refactor a module or trace a bug across a dozen files — and then start the next session knowing none of it. They re-derive your repo conventions, forget last week’s architecture decision, and rediscover the test command you corrected them on twice already.

The usual patch is to bolt a vector store onto the agent. That helps it retrieve, but it does not help you trust: you cannot see why the agent believed a fact, whether that fact is still current, or which prior decision it is acting on. For a coding agent operating on a real repo, that gap is the whole problem.

SecondBrain takes a different shape: a shared, local-first Memory API that any agent plugs into over HTTP and MCP. It is open source, runs on your machine, and every memory-bearing response carries a Citation envelope back to the exact chunk that produced it. The brand promise is blunt: AI you can audit.

October 16 contract revision: this remains a dated integration guide, not a current runtime/CI evaluation. The immutable Memory API contract from the separately reviewed September 3 snapshot was selectively rechecked for routes and citation fields. Commands below are documented setup examples, not steps executed in this review. SecondBrain remains a separate implementation; shared names do not establish conformance to current ContextOS attachments.

The split that makes this work

The Memory API draws one clean line: it returns grounded data; the calling agent brings the LLM and the synthesis. SecondBrain does retrieval, provenance, decisions, and open loops. Claude Code does what it is already good at — reading the evidence and writing the code. Nobody re-implements memory inside each agent, and you get one durable store instead of four siloed ones.

Because the contract is HTTP plus MCP, the same surface is available two ways: a documented authenticated /v1/ HTTP route for any client, and a named MCP twin for any MCP-capable agent. An MCP-aware tool like Claude Code can call secondbrain_recall as a native tool; a script can POST /v1/memory/recall. Same data, same citations.

The citation envelope is the point

Every item the Memory API returns is wrapped in a provenance envelope. This is not metadata you can ignore — it is the durable identity of the evidence:

{
  "content": "The Orion release freezes scope on 2026-04-18.",
  "citation": {
    "chunk_hash": "sha256:9f2c…",
    "source_path": "03_decisions/2026-04-18-release-scope.md",
    "anchor": "Scope freeze",
    "text_span": "Scope is frozen as of 2026-04-18.",
    "score": 0.91,
    "retrieved_at": "2026-06-27T10:14:02Z"
  },
  "source_type": "hybrid"
}

The shortened hash is a display placeholder, not a valid integrity proof. In the pinned schema, chunk_hash, source_path and retrieved_at are required; anchor, text_span and score may be absent. A citation locates an asserted source, not proof of truth, freshness, entitlement or complete coverage.

The chunk_hash is a content-addressed SHA-256 of the normalized chunk, so the evidence has a stable identity even as files move. source_path plus anchor is the human-readable location; text_span is the literal quoted evidence. For a coding agent this is the difference between “the model said so” and “here is the decision file, line and span, that the model is acting on.” Grounded answers run behind a citation-density gate that refuses thin-evidence responses by default — which can hold an under-cited answer. Citation density does not guarantee that a source is correct, current or sufficient for the proposed action.

This is the operational answer to the problem we laid out in AI Agent Memory Is Broken: memory is not a search index, it is continuity you can audit.

The surface coding agents actually use

The API is small on purpose. The routes below cover the day-to-day loop, and each has a named MCP tool with the same behavior.

After obtaining a scoped service token through the trusted deployment setup and storing it outside model-visible state, a documented recall request uses a query and top_k:

curl -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"query":"what is the current test command?","top_k":5}' \
     http://localhost:8765/v1/memory/recall

Notice secondbrain_pack. Instead of dumping raw chunks into the agent’s context, you can ask for a ContextPack: a bounded bundle of the relevant facts, the decisions that govern them, and the open loops still in flight — each carrying its own citation. This is the project-specific API bundle, not the normative ContextPack v2 input or CompiledContext output of the ContextOS compiler. Validate and map eligible sources explicitly; matching names and citations do not prove shared schemas or current authority.

Memory that matures, not just accumulates

A vector store treats every write as equally true forever. SecondBrain’s Memory API (v1.1) adds a knowledge assimilation lifecycle so captured material has to earn durability:

For a coding agent the payoff is concrete: a freshly captured note (“we switched to pnpm test”) is intake, not gospel. It matures into practiced knowledge through review — so the agent does not act on an unverified one-off as if it were a settled repo convention. This is the promotion-aware discipline we argue for across the memory foundations, now exposed as an API.

Auditable by construction

The pinned project exposes inspectable evidence surfaces; local topology does not establish privacy, replay or tenant isolation by itself:

• GET /v1/cognitive/uplift returns a window-aggregated snapshot of what each cognitive layer contributed, mirrored by secondbrain_*_total Prometheus counters. If a layer never fires, its counter stays at zero and you can see it.
• GET /v1/audit/event_log tails the workspace event log and filters to a single trajectory — supporting eligible diagnostic reconstruction; it does not prove safe effect replay or byte-identical regeneration.
• Multi-tenancy behind SB_MULTI_TENANT=1 gives each workspace its own token, vault, and state, which declares a project separation mechanism; actual configuration, access enforcement and denial tests must establish isolation.

The whole memory contract is pinned in the OpenAPI file at contracts/memory_api_v1.yaml, and a single end-to-end test (tests/test_memory_api_v1_e2e.py) asserts the Citation-envelope invariant on every memory-bearing response. These source-level contracts and tests express intended coverage; this review did not execute the service, test suite or remote CI.

Current memory and execution boundaries

Local storage and a cited chunk do not grant permission. Current owned namespace/tenant/readers/purpose and every ancestor restriction/revocation govern retrieval and children. Exact full-action stored approval/quorum and active sandbox/credential/data controls precede governed changes; policy-expression errors stop compilation with structured diagnostics. Actual processors/recipients/residency/retention apply across all nine data stages, including candidate capture, inference, telemetry, cache and export.

The documented forget route unindexes content. That cannot prove deletion of source files, summaries, backups, exports or downstream processor copies. Inventory actual derivatives and require record/operation/artifact-bound correction/deletion receipts; pending/failed/externally unknown propagation remains incomplete. Audit metadata has its own retention policy.

Protected atomic ownership/approval/budget stores and generation fencing govern proactive wake/resume, with original shared spent/reserved capacity across children, reviewers and retries. Stable operations and verified provider semantics govern uncertain effects; a key, cancelled task or restored conversation cannot establish stop or reversal. Exact profiles and current independent conformance require useful, denial and fault evidence for the actual workflow/release/environment. Neither an e2e test name nor citation envelope establishes it.

Run it and point an agent at it

The Docker quickstart brings up sb serve with the Memory API live in one command — no provider key required for the first grounded answer, because retrieval and citations don’t need an LLM:

git clone https://github.com/contextosai/SecondBrain-collab.git
cd SecondBrain-collab
 
make quickstart-docker
# Memory API is now live at http://localhost:8765/v1/

From there, ingest your notes or repo docs with secondbrain_ingest, then have your agent call secondbrain_recall or secondbrain_pack before it answers. The first time Claude Code cites the exact decision file behind a suggestion instead of hand-waving, the difference is obvious.

What to read next

• SecondBrain: A Local-First Agent Operating System You Can Run, Inspect, and Trust
• AI Agent Memory Is Broken
• Promotion-Aware Memory in Code
• SecondBrain Reference Implementation