SecondBrain — Reference Implementation

This page maps a dated SecondBrain source snapshot to ContextOS patterns: governed tools, durable sessions, promotion-aware memory, bounded improvement, and a Memory API exposed through HTTP and MCP. It is implementation research input, not proof that every current ContextOS schema, exact profile or conformance case is implemented end-to-end.

Start at Foundations to read the spec, and use this source map to investigate a concrete implementation. Before running the historical quickstart, review the pinned project’s own setup, trust-domain, credential and data requirements.

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 pinned quality scorecard reports synthetic nDCG@10/MRR of 0.94 on 30 golden queries using hash-mode embeddings. Its 25-query dogfood test uses a simplified token-overlap retriever, generous substring relevance and a bounded ripgrep baseline; it reports recall 0.92 versus 0.44 and precision 0.33 versus 0.10. These source-reported measurements were not rerun here and do not establish live production retrieval or causal self-improvement. Per-layer contribution counters support inspection but need controlled comparisons to attribute outcome improvement.

ContextOS primitive → SecondBrain module

The mapping below preserves the original 2026-09-03 navigation review at the pinned commit. A source path or similarly named receipt is not a schema validator, observed enforcement test or current deployment attestation.

Intelligence plane

Context plane

Decision plane

Action plane

Trust plane

What SecondBrain adds on top of the spec

Some surfaces extend the spec. Treat these as reported implementation patterns to evaluate before any versioned promotion into ContextOS:

• 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. The snapshot documents sb tasks workspace status and a dry-run-first sb tasks workspace promote path. File/worktree restoration does not prove external-effect compensation, current approval binding or fenced resume under ContextOS’s new execution attachments.

Quickstart

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

The historical setup expects the Memory API at http://localhost:8765/v1/; this review did not start it. Once your verified local deployment 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.
• The historical source-map review did not establish complete native multidimensional ActionRisk, multi-region operational behavior or exact ContextOS schema conformance for every artifact. This is a limit of the evidence reviewed, not a conclusion that current source lacks those capabilities. Consult the pinned operating guidance and perform a new release-specific assessment.
• Contributions that close spec-vs-implementation gaps land upstream in this docs site and downstream in SecondBrain in lockstep — following the “files to touch together” map in the specification’s maintainer notes.

The new Execution Contract requires a fresh crosswalk for exact profile/feature support, complete action/stored approval binding, current grant/ancestor revocation, observed sandbox/egress/data routes, owned operation/checkpoint/budget stores and verified useful/denied/fault cases. Those runtime controls are not evaluated by this page’s review. Do not infer they are present or absent from this historical module map. Apply the conformance assessment to the actual implementation/release/environment/workflow with independently verified current evidence.