SecondBrain — Reference Implementation

SecondBrain is an open-source, local-first agent operating system that puts the ContextOS spec into running code. Mapping ContextOS primitives to concrete SecondBrain modules.

ReferenceLast reviewed: 2026-05-09 Edit on GitHub

At a glance

SecondBrain is an open-source, local-first agent operating system that implements the ContextOS spec end-to-end. It is the most complete public reference of the Harness Engineering discipline in running code: governed tool execution, durable sessions, promotion-aware memory, an autotune-driven improvement loop, and a memory API that other agents (Claude Code, Cursor, Codex, custom) plug into via HTTP and MCP.

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.


Website	sb.chat
Repo	github.com/contextosai/SecondBrain
License	MIT
Primary language	Python (with a Swift Mac shell and a Vite/React operator UI)
Posture	Local-first; one-command Docker quickstart
Surfaces	`sb` CLI, FastAPI Memory API, MCP server, A2A capability plane, brain.sdk

Why this matters for ContextOS

ContextOS is the spec. Specs without a working implementation drift into theory; implementations without a spec drift into ad-hoc choices. SecondBrain is the bridge:

Every primitive in Foundations has a concrete code path.
Every contract in Implementation has a typed schema you can import.
Every property in Harness Engineering — context-aware, policy-governed, tool-controlled, validated, observable, reversible, measurable, continuously improving — is enforced by named modules with tests.

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

ContextOS primitive	SecondBrain location
Memory Model — promotion-aware tiers (working / episodic / semantic / durable) with review queue and contradiction handling	`brain/memory/` — working, episodic, long-term separation; sleep-time synthesis writes to a review queue, not directly
Knowledge Graph — evidence-bound graph with GraphRAG retrieval	`brain/retrieval/` — hybrid retrieval; promoted-knowledge-first
Ontology — versioned, governed canonical schema	`ontology/` + `contracts/`
Identity Layer — CEIDs, SIDs, agent workload identity	per-workspace tokens behind `SB_MULTI_TENANT=1`; design at `docs/multi_tenancy_design.md`

Context plane

ContextOS primitive	SecondBrain location
Context Pack — eight-stage compilation into a `CompiledContext`	`brain/context_packs/`
`CompiledContext` — bounded per-request state	`sb context explain <run_id>` and `sb context doctor` produce the per-run view
Agentic Context Engineering — bucket scoring, provenance, dynamic injection	`brain/context/` + retrieval rank hints from `sb context doctor --write-rank-hints`

Decision plane

ContextOS primitive	SecondBrain location
Cognitive loop - perception -> attention -> identity -> goals -> judgment -> policy gate -> action -> consolidation -> reflection	`brain/antahkarana/` — `chitta`, `manas`, `buddhi`, `viveka`, `atman`, `ahamkara` modules
Orchestration — bounded Planner / Executor / Critic + durable background sessions	`brain/agent_runtime/` + `brain/background_sessions/`
`RunContext`, `RunBudget`, `RunTrace`	`brain/agent_harness/contracts.py` — task runs, context budgets, permission decisions, checkpoints, verification plans, run traces
`DecisionRecord` — typed per-turn record	`AgentRunTrace` receipts in `brain/agent_harness/turn_traces.py`; persisted by `trace_store.py`; inspect via `sb traces list` / `sb traces show <id>`

Action plane

ContextOS primitive	SecondBrain location
Tool Gateway — only path to external effect	`brain/orchestrator/action_gateway.py`
`ApprovalMode` — `read_only` / `local_write` / `network` / `delegated` / `destructive`	`brain/policies/approval_mode.py` plus Claude-Code-style aliases (`plan_only`, `auto_read`, `auto_edit_local`, `auto_safe`, `dangerous_requires_approval`)
Adapter mesh — MCP / A2A / OpenAPI / custom	`brain/adapters/` + `brain/a2a/`
Skills	`brain/skills/` — discovery, loader, registry, router, runtime

Trust plane

ContextOS primitive	SecondBrain location
Governance — policy outside agent code, JsonLogic-style bundles, guardrails	`brain/policies/` — `engine.py`, `bundles.py`, `guardrails.py`, `injection.py`, `command_safety.py`, `obligations.py`
Approval gates	`brain/orchestrator/approvals.py` + durable approval pauses in background sessions
Evaluation and Observability — evaluators on Policy / Utility / Latency / Safety / Economics, OTEL traces, replay	`brain/evals/` (graders, goldens, dogfood, replay) + `brain/eval/`; quality scorecard at `docs/reference/quality.md`
Improvement Loop — Insight Synthesizer, Strategy Compiler, Feedback Store, Autotune	`brain/autotune/` — lanes, evaluators, promotion gate, ensemble acceptance, mutation safety; see `OPERATING.md`
Reviewer Agents — security / architecture / data / etc.	`contracts/registry/agent_profiles.yaml` — ships `security-reviewer`, `repo-scanner`, `memory-curator` profiles
Durable rollback / reversal	file checkpoint create/list/diff/rewind via `sb checkpoint` / `sb rewind`; auto pre-mutation checkpoints on chat code writes, gateway `write_file`, vault writes
`AGENTS.md` — primary navigation for agents	`/AGENTS.md`

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.git
cd SecondBrain
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/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 in SecondBrain (notably the full multi-region deployment blueprint and the regulated-action audit contract). The repo’s roadmap is in brain/autotune/OPERATING.md and the harness comparison doc.
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.