Most “AI agents” are still a smart model sitting behind a tool menu. They answer, retrieve, call an API, and write a note to a vector store. Useful, but thin. They forget what happened last week, they cannot show you why they trusted a fact, their actions are hard to bound, and a session that went wrong is almost impossible to replay.
SecondBrain is the opposite bet. It is an open-source, local-first agent operating system: cognition, memory, governed tools, durable sessions, workflows, quality loops, and bounded self-improvement in one inspectable runtime that runs on your own machine. State, traces, memory, knowledge, approvals, and artifacts live locally, where you can read them.
This post is the system tour: what it is, the loop it runs, the Memory API that lets other agents plug in, why local-first changes the trust posture, and how to run the whole thing in one command.
October 16 contract revision: this is an upstream architecture tour, not a current runtime assurance report. Concrete installation, license and Memory API claims are bounded to inspected commit acec9678c05e80e859802a4e4e18f187e35d66b5, already used by the September reference review. Its MIT license applies to that upstream project; this ContextOS repository retains its own all-rights-reserved license. No install, benchmark or deployed control was executed here.
More than chat or RAG
Most AI tooling gives you one useful slice: chat, search, orchestration, tools, evals, or memory. Real agentic work needs those pieces to behave as one system. SecondBrain is built around a fuller loop, not a single capability.
That makes SecondBrain a local agent platform with a Memory API on top, not just another assistant shell.
The Memory API: the part other agents plug into
The cleanest on-ramp is the Memory API v1. Other agents — Claude Code, Cursor, Codex, ChatGPT, or your own — connect over HTTP and MCP. The pinned API declares citation-bearing responses. Its Citation requires chunk_hash, source_path and retrieved_at; anchor, text_span and score are optional. Not every endpoint is a grounded answer, and a citation supports traceability rather than proving source truth or current reader permission.
curl -H "Authorization: Bearer ${SB_SERVE_TOKEN:?provide a current scoped token}" \
-H "Content-Type: application/json" \
-d '{"query":"migration plan","top_k":5}' \
http://localhost:8765/v1/memory/recallObtain the token from a trusted pinned installation for the exact workspace; do not evaluate uninspected shell output from a server. The HTTP example is not executed here.
It is not a static index. The Antahkarana cognitive stack (Chitta synthesis, Manas predictive context, Viveka quality gate, Karma outcome ledger) and the Autotune prompt-mutation loop are wired into the serving path itself. Each layer’s contribution is published as a Prometheus counter (secondbrain_*_total) and as a JSON envelope at GET /v1/cognitive/uplift — so activity is inspectable. A counter increment does not prove causal quality improvement, correct authorization or conformance. If a layer never fires, its counter stays at zero and you can see it.
A few details that matter for builders:
- Public
/v1/HTTP routes with an OpenAPI contract atcontracts/memory_api_v1.yaml, plus MCP tools with named parity for the same surface. - A citation-density gate on grounded answers that refuses thin-evidence responses by default.
- An upstream-reported quality scorecard in the pinned README, not independently reproduced here: synthetic seed
nDCG@10 = 0.94,MRR = 0.94,recall@10 = 1.00; and a dogfood run (SecondBrain indexing its own repo) measuring 2.1× better recall and 3.5× better precision than grep. - Multi-tenancy behind
SB_MULTI_TENANT=1: per-workspace token, vault, and state.
Why local-first changes the trust posture
Local-first agents sit near private notes, source code, documents, credentials, calendars, and long-running work state. That proximity is only useful if the runtime can govern what the model sees and what the system does. Local-first does not mean unbounded — safety comes from explicit boundaries.
Where configured state is local and inspectable, the failure modes have somewhere to live: traces you can read, approvals you can audit, and memory writes that go through review instead of silently becoming future truth.
A cognitive layer, not just retrieval
Chat and agent flows can pass through the Antahkarana stack before or around tool execution — structured attention, identity, goals, judgment, guardrails, memory, witness-style audit, and functional-state monitoring. It is framed as a Vedic-inspired engineering model with clear boundaries between traditional faculties and modern runtime responsibilities. If that idea interests you, the full architecture is in Antahkarana Stack: A Cognitive Layer for Local-First Agents.
The practical payoff is promotion-aware knowledge: sb capture, sb ingest, and sb ingest-pipeline move material from raw capture, to promoted knowledge, to compiled runtime context — with working, episodic, and curated long-term memory kept separate. Sleep-time sessions synthesize proposed durable memories into a review queue instead of writing them silently. This is the same promotion-aware model we argue for in AI Agent Memory Is Broken.
Self-improvement that stays bounded
The most over-promised idea in agents is “self-improvement.” SecondBrain treats Autotune as constrained optimization, not unrestricted self-editing. Lane specs declare the mutable files, evaluators, benchmark packs, and acceptance rules. Each candidate keeps its run record, diff, metrics, and cognitive trace.
sb autotune validate repl_prompt
sb autotune bench repl_prompt
sb autotune run repl_prompt --pack smoke
sb quality gate --surface allThe guardrails are the point: Prana, Manas, Buddhi, and Viveka gate budget, priority, attempt framing, and mutation safety before any change applies; deterministic evaluators and ensemble acceptance decide whether a candidate is kept; promotion gates block unsafe promotion when baselines are missing or judge agreement is insufficient; and accepted candidates are preserved as candidate branches, not auto-merged. This is the same replay-driven discipline we describe in Replayable Environments and the Harness Improvement Loop.
How it maps to ContextOS
SecondBrain is an inspectable implementation lineage for ContextOS; the mapping below is architectural correspondence, not verified conformance to every current profile/control. The five planes map cleanly onto its modules:
| ContextOS plane | SecondBrain surface |
|---|---|
| Intelligence | Promotion-aware knowledge, working/episodic/long-term memory, Chitta consolidation |
| Context | Hybrid retrieval, context packs, Manas working-memory assembly |
| Decision | AgenticRuntime Planner → Executor → Critic, Buddhi judgment, durable background sessions |
| Action | Governed tool gateway, MCP and A2A capability planes, approval modes |
| Trust | Policies and approvals, traces, evals, replay cases, quality gates, Autotune |
If you want to read the spec, start at Foundations. To inspect one implementation on your laptop, evaluate the pinned repo and its stated support boundaries. The module-by-module mapping lives in the SecondBrain reference.
Run the whole thing in one command
The fastest first run is the repo-local quickstart. It keeps config, state, and a mutable demo-vault copy inside the checkout, seeded from synthetic fixtures — and it returns a real, citation-first answer without needing an LLM provider key. You need Python 3.12 or 3.13.
git clone https://github.com/contextosai/SecondBrain-collab.git
cd SecondBrain-collab
git checkout acec9678c05e80e859802a4e4e18f187e35d66b5
make quickstartThat creates a virtualenv, installs the package in editable mode, writes portable config, ingests the demo vault, builds the offline context index, and asks a grounded question with --no-synthesize so the first answer returns demo-vault citations instead of calling a provider. Prefer Docker? make quickstart-docker brings up sb serve with the Memory API live at http://localhost:8765/v1/.
Then the first commands look like this:
source .venv/bin/activate
export SB_CONFIG=$PWD/.secondbrain/config/config.yaml
export SB_STATE_DIR=$PWD/.secondbrain/state
export SB_VAULT_DIR=$PWD/.secondbrain/demo_vault
sb doctor
sb ingest "$SB_VAULT_DIR/00_inbox/orion-launch-notes.md"
sb context index
sb ask "What are the main active priorities for the Orion release?" --no-synthesizeWhat local-first still has to enforce
Local storage does not prove local inference, safe localhost access or no telemetry. Admit actual recipients/processors, purpose, residency and retention across all nine data stages; inspect model endpoints and plugin/tool routes. Govern current owner/tenant/audience/purpose and all ancestor restrictions/revocation, candidate intake, readership and every cache/index/trace/export copy with correction/deletion receipts. Memory forget/unindex is not proof of all-copy erasure.
Proactive/background work needs current full-action/evidence/immutable-pin stored approval and entitled independent quorum where required, native risk/guardrails, actual active containment/credential/data controls and provider preconditions. Policy errors stop compilation. Protected atomic run/operation/approval/budget stores and enforced generation fencing govern resume. Original shared spent/reserved capacity includes children, reviewers, retries and repair; unknown provider effects retain identity/reservations. Cancellation and tuple rollback cannot prove stop/reversal.
Select exact profiles and collect current independent useful, denial and fault conformance evidence for the actual workflow/release/environment. Source availability, compatibility-mode names, counters and a local quickstart are insufficient deployment proof.
Where to help
Some surfaces are more mature than others, and the repo is explicit about that. The core supported path — setup, doctor, ingest, context, ask, chat basics, brain.sdk, brain.patterns, docs, and examples — is the easiest place to start. The cleanest extension points are custom tools built with the brain.patterns.tools.tool decorator, workflow specs, MCP servers, A2A agent cards, and domain agents that reuse the shared context, memory, policy, and persistence layers.