SecondBrain — Reference Implementation

SecondBrain is an open-source, local-first agent operating system that implements many ContextOS patterns in running code: governed tool execution, durable sessions, promotion-aware memory, bounded improvement, and a Memory API exposed through HTTP and MCP. It is a reference implementation and research input, not proof that every current ContextOS schema or conformance test is implemented end-to-end.

If you want to read the spec, start at Foundations. If you want to run the spec on your laptop and inspect every layer, start at SecondBrain.

Why this matters for ContextOS

ContextOS is the portable specification. SecondBrain is one implementation-shaped source of evidence:

• Many foundation primitives have inspectable code paths and tests.
• Its contracts can be compared against ContextOS schemas to find alignment and gaps.
• Its operational experience supplies evidence for which harness patterns work in practice; it does not automatically promote a SecondBrain-specific type into the normative ContextOS surface.

The Memory API ships a published quality scorecard (synthetic seed: nDCG@10 = 0.94, MRR = 0.94; dogfood: 2.1× better recall and 3.5× better precision than grep) and a GET /v1/cognitive/uplift route that exposes per-layer contribution counters. The self-improvement claim is auditable, not marketing.

ContextOS primitive → SecondBrain module

The mapping below is a navigation table from spec to source. Every right-hand path is a real directory or file in the repo as of main.

Intelligence plane

Context plane

Decision plane

Action plane

Trust plane

What SecondBrain adds on top of the spec

SecondBrain is a reference, not a clone — some surfaces extend the spec rather than just implementing it. Treat these as proven patterns ContextOS may absorb upstream:

• Antahkarana cognitive stack. A named decomposition of the cognitive loop: chitta (synthesis), manas (predictive context), buddhi (judgment), viveka (quality gate), atman (identity), ahamkara (self-model). Each layer exposes a counter at GET /v1/cognitive/uplift so the contribution is auditable.
• Memory API v1 with citation envelopes. Every response carries a Citation envelope (chunk_hash, source_path, anchor, text_span, score, retrieved_at). 13 HTTP routes + 13 MCP tools with named parity. Contract at contracts/memory_api_v1.yaml.
• Citation density gate. Grounded answers refuse thin-evidence responses by default — a concrete enforcement of the Trust plane’s evidence-coverage requirement.
• Autotune as constrained optimization. Lane specs declare mutable files, evaluators, benchmark packs, and acceptance rules. Promotion gates block unsafe promotion when baselines are missing, smoke evidence failed, or judge agreement is insufficient. This is the Improvement Loop’s “harness as a search target” framing in working code.
• Durable workspaces and checkpoints. sb tasks workspace status audits worktree health; sb tasks workspace promote is a dry-run-first, --apply --yes-guarded fast-forward path. Compensates ContextOS’s specified-but-not-shipped rollback contract with a real implementation.

Quickstart

git clone https://github.com/contextosai/SecondBrain-collab.git
cd SecondBrain-collab
make quickstart-docker

The Memory API comes up live at http://localhost:8765/v1/. Once it is running:

eval "$(uv run sb serve-token env)"
curl -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"query":"migration plan","top_k":5}' \
     http://localhost:8765/v1/memory/recall

Inspect a run’s DecisionRecord-equivalent receipt:

sb traces list
sb traces show <trace_id>

Inspect what a context pack is putting in front of the model:

sb context explain <run_id>
sb context doctor

Where to read next

• In SecondBrain:
  • AGENTS.md — the primary navigation file for any agent operating in the repo.
  • docs/index.md — full doc routing table.
  • docs/harness/overview.md — SecondBrain’s harness architecture in its own words.
  • docs/explanation/agent-harness-claude-code-learnings.md — what the project learned closing harness gaps inspired by Claude Code’s permission model.
  • docs/reference/quality.md — the published quality scorecard, including the dogfood-vs-grep numbers.
  • brain/autotune/OPERATING.md — running the autotune loop in practice.
• In ContextOS:
  • Harness Engineering — the discipline SecondBrain implements.
  • Improvement Loop — the spec’s view of the autotune-style outer loop.
  • Reviewer Agents — the taxonomy SecondBrain’s agent_profiles.yaml instantiates.

Caveats

• SecondBrain is a reference implementation, not a deployment of ContextOS as a managed product. It is local-first by design.
• Some primitives in the spec are richer than what is yet shipped or evidenced in SecondBrain, notably native multidimensional ActionRisk, the full multi-region deployment blueprint, and exact ContextOS schema conformance for every runtime artifact. The repo’s operating guidance is in brain/autotune/OPERATING.md and its harness docs.
• Contributions that close spec-vs-implementation gaps land upstream in this docs site and downstream in SecondBrain in lockstep — see the “files to touch together” map in this repo’s CLAUDE.md.