Skip to content

Documentation Index

Auto-generated; do not hand-edit. Regenerate with sb codebase docs-index --write.

Generated 2026-05-27T05:48:08.300507+00:00 from docs (113 markdown files indexed; excluded subdirs: archive).

Use this as a routing table — read the linked file directly when you need the detail. Don't try to hold every doc in working memory.

(top-level)

  • agent_identity_checklist.md — Agent Identity Design Checklist — > Use this checklist when designing, reviewing, or extending any code that > creates, accepts, or acts on an agent identity in SecondBrain…
  • agent_identity_design.md — Agent Identity in SecondBrain — Design — > Status: implementation in progress, 2026-05-17. Companion to > agent_identity_checklist.md. This d…
  • company-brain-readiness-checklist.md — Company Brain Readiness Checklist — YC's Company Brain framing is specific: it is not just company-wide search or a chatbot over documents. A real Company Brain should pull fr…
  • company_brain.md — Company Brain — Company Brain is a workspace-scoped layer on top of the SecondBrain substrate, not a parallel runtime. Each workspace owns a dedicated SQ…
  • index.md — SecondBrain — A local-first runtime for grounded retrieval, durable memory, governed tool execution, and agent workflows. Everything runs on your machine…

builders/

  • builders/add-a-tool.md — Add A Tool — The smallest public builder path is to add a custom tool using brain.patterns.
  • builders/evals.md — Evals — SecondBrain has multiple eval and quality layers already.
  • builders/workforce-specs.md — Workforce Specs — This page is for contributors and automation authors extending the AI workforce layer. For the operator workflow, start with [guides/workfo…

components/

  • components/a2a.md — A2A — SecondBrain’s brain/a2a package now treats the local queue as a delivery layer for A2A-shaped contracts rather than as a standalone bespo…
  • components/antahkarana/api.md — Antahkarana API — The Antahkarana package exposes the cognitive-loop primitives used by the CLI and chat runtime. Builder integrations should prefer the publ…
  • components/antahkarana/overview.md — Antahkarana — Antahkarana is the Vedic-inspired cognitive layer that sits above the core runtime in SecondBrain. It is an engineering responsibility map…
  • components/antahkarana/stack.md — Antahkarana Stack — Antahkarana is SecondBrain's Vedic-inspired engineering layer for local-first agent runtimes. It sits above the execution substrate and tur…
  • components/data-agent/api.md — Data Agent API — DataAgent is the advanced grounded answer surface for analytical and structured questions.
  • components/environments/overview.md — Environments — The environment subsystem is SecondBrain's local control plane for replayable agent-task episodes: reset a bounded state, apply structured…
  • components/kernel/overview.md — brain/kernel — SecondBrain Kernel Reference — Last updated: 2026-03-02 (as-built, corrected against source)
  • components/marketing/overview.md — Marketer — sb marketer is the campaign-planning agent surface in SecondBrain.
  • components/mcp/api.md — MCP API — SecondBrain ships a curated MCP Marketplace registry and CLI for discovering, searching, and configuring Model Context Protocol servers.
  • components/mcp/overview.md — MCP In SecondBrain — SecondBrain treats MCP as a governed capability plane rather than a loose collection of server-specific adapters.
  • components/patterns/overview.md — Agent Patterns — SecondBrain ships a canonical agent-pattern library in brain/patterns/.
  • components/travel/overview.md — Travel — sb travel is the domain-specific travel planning surface in SecondBrain.

contributor/

  • contributor/README.md — DevEx Docs — This directory is the contributor-facing entrypoint for working on SecondBrain itself.
  • contributor/agent-operability.md — Agent Operability — SecondBrain is designed to be worked on by coding agents under human direction. Keep the repo legible enough that an agent can discover con…
  • contributor/cli-checklist.md — CLI Change Checklist — Use this checklist whenever a change adds, removes, renames, or changes behavior for an sb command, option, argument, help string, defaul…
  • contributor/component-tests.md — Component Test Entrypoints — Use this page to choose the smallest useful validation loop for the component you touched. Start with the narrow loop, then expand only whe…
  • contributor/quickstart.md — Contributor Quickstart — The main setup path for contributors working from a user-owned local checkout. Brings up a working dev environment, validates the CLI and s…
  • contributor/testing-strategy.md — Testing Strategy — SecondBrain has outgrown the "put new coverage in one more smoke file" phase. The practical strategy going forward should be:

explanation/

  • explanation/adapters-and-tools.md — Adapters And Tools — Current as of 2026-04-25.
  • explanation/agent-harness-claude-code-learnings.md — Agent Harness Claude Code Learnings — SecondBrain already had several pieces of a governed local agent runtime:
  • explanation/architecture.md — Architecture — This is the canonical architecture reference for the SecondBrain repo. It explains how a request enters, what runtime loop handles it, wher…
  • explanation/autodata.md — AutoData — Agentic Self-Instruct — > Re-implementation of Meta AI's > AutoData > (Kulikov et al., 2026) inside Secon…
  • explanation/chat-reliability.md — sb chat Reliability Architecture — *Added 2026-04-16 — see brain/chat/transport_events.py, brain/chat/transport.py, brain/chat/turn_journal.py, `brain/chat/commands/dia…
  • explanation/context-pack.md — Context Pack Spec — A context pack is the bounded runtime context assembled for one question, task, or turn.
  • explanation/embeddings.md — Embeddings & Retrieval — SecondBrain ships a pluggable embedding stack with seven providers, two modern API rerankers, query expansion, adaptive top-k, and an offli…
  • explanation/how-context-works.md — How Context Works — SecondBrain does not treat "context" as just prompt stuffing.
  • explanation/integrations.md — Integrations Architecture — SecondBrain integrates three external services — Ollama, n8n, and Dify — without replacing any part of its cognitive core. The core (planni…
  • explanation/observability.md — Observability — Current as of 2026-04-25.
  • explanation/plugging-into-claude-code.md — Plugging into the SecondBrain Memory API — The SecondBrain Memory API is the durable memory + grounded-retrieval layer agents plug into. AI you can audit: every response carr…
  • explanation/policy-and-approvals.md — Policy And Approvals — Open-source users need to understand when SecondBrain reads, writes, asks for approval, or reaches outside the machine.
  • explanation/prompt-caching.md — Prompt caching — SecondBrain runs many turns per session that share a stable prefix — the system prompt, the tool catalog, and (in agentic loops) the same c…
  • explanation/runtime-flow.md — Example End-to-End Flow (Refreshed 2026-04-25) — User runs an interactive planning/research session, adjusts runtime behavior live, asks a grounded question, and then inspects the local st…

harness/

how-to/

  • how-to/auto-dreaming.md — Auto-Dreaming — sb brain dream synthesizes cross-session insights from episodic memory. By default it runs only when you invoke it. Two automation hooks…
  • how-to/automations.md — Automations and routines — SecondBrain integrates recurring automations (similar in spirit to scheduled/API agent “routines”): you define a prompt and schedule on…
  • how-to/chat.md — Chat — sb chat is the interactive REPL for grounded, tool-using conversations in SecondBrain. It runs multi-turn local-first conversations, resu…
  • how-to/company-brain.md — Company Brain — Company Brain compiles local operating knowledge into cited, agent-facing skill drafts. It is for company know-how such as processes, polic…
  • how-to/docker-quickstart.md — Docker quickstart — Bring up the SecondBrain Memory API in a single container with docker compose up. This is the shortest path from a clean machine to a run…
  • how-to/gateway.md — Gateway — The gateway is SecondBrain's persistent runtime surface for channel-backed sessions, approvals, and outbound delivery state.
  • how-to/grounded-answer.md — Grounded Reasoning — The grounded reasoning subsystem is the closed-corpus reasoning path behind sb grounded.
  • how-to/ingest-and-index.md — Ingest And Context — This guide covers the current ingestion path, promoted knowledge flow, and context-compilation surfaces.
  • how-to/integrations/apple-m365.md — Local Apple Data Plane for Microsoft 365 / Exchange — This integration lets SecondBrain read Microsoft 365 / Exchange email and calendar data locally on macOS without using Microsoft Graph, Ent…
  • how-to/integrations/claude-code.md — Claude Code Integration — This guide covers how SecondBrain integrates with Claude Code — turning your vault into a live context layer inside every coding session.
  • how-to/integrations/microsoft365.md — Microsoft 365 Graph Sync — SecondBrain can pull user-authorized Microsoft 365 content into the local vault through Microsoft Graph. This is the direct Graph path for…
  • how-to/integrations/music.md — Local Music Integration — SecondBrain includes a local-first music preference subsystem currently backing Spotify. It operates exclusively in the local runtime datab…
  • how-to/integrations/outlook.md — Outlook Ingestion on macOS — This guide shows how to pull selected Microsoft Outlook messages into SecondBrain on a local Mac.
  • how-to/integrations-overview.md — Optional Integrations Operator Guide — SecondBrain can use Ollama, n8n, Dify, and plugin-backed connectors such as Microsoft Teams without giving up planning, memory, approvals,…
  • how-to/memory.md — Memory — SecondBrain has a first-class persistent memory subsystem exposed through sb memory.
  • how-to/plugins.md — Plugins — SecondBrain plugins are declarative capability bundles. A plugin manifest tells operators which connector, kernel tool, MCP server, skill,…
  • how-to/provider-keys.md — Provider Keys — This is the active setup guide for configuring provider secrets in SecondBrain.
  • how-to/quality-control.md — Quality Control Plane — The quality control plane unifies runtime traces, eval suites, grounded trajectories, autotune runs, and conversation improvement reports i…
  • how-to/user-guides/cognitive-briefs.md — Cognitive briefs and capture pipeline — End-to-end user guide for the daily brief, weekly synthesis, and the Telegram + Readwise capture adapters. Together they turn S…
  • how-to/user-guides/knowledge-assimilation.md — Knowledge assimilation lifecycle — SecondBrain can now track an idea as it moves from raw intake to reflected understanding to practiced knowledge.
  • how-to/user-guides/memory-layer-integrations.md — Memory layer integration guide — SecondBrain can serve as the durable memory and grounded retrieval layer for Claude Code, Cursor, Codex, ChatGPT, custom agents, and local…
  • how-to/workflows.md — Workflows — SecondBrain workflow support lives under sb workflow and the brain/workflows/ package.
  • how-to/workforces.md — AI Workforce — SecondBrain workforces are declarative, local-first teams of background agents. They reuse existing runtime primitives instead of adding a…

reference/

  • reference/agent-harness-frontend-contract.md — Agent Harness Frontend Contract — Added 2026-04-21. This document is the implementation-aligned source of truth for how agent runtime state reaches frontend clients.
  • reference/builder-apis.md — Builder API Inventory — This page records the supported builder-facing imports and commands for SecondBrain. Import from these package facades rather than from int…
  • reference/cli.md — CLI Reference — Auto-generated from brain/ui_schema/cli_schema.json via sb docs cli-reference --write. Do not hand-edit.
  • reference/decisions.md — Decision Namespaces — Auto-generated from brain.decisions.namespace.DECISION_NAMESPACES via sb docs decisions --write. Do not hand-edit.
  • reference/local-agent-stack.md — Local Agent Stack — SecondBrain can route private work to local model profiles and run generated code or shell commands under deterministic execution-isolation…
  • reference/memory-api.md — SecondBrain Memory API v1 — > AI you can audit. Memory that improves itself. A memory + > grounded-retrieval API that other agents (Claude Code, Cursor, ChatGPT, >…
  • reference/patterns/async.md — Async Patterns — All sync patterns have async equivalents that never block the event loop. The key concurrency primitive is run_concurrent() — runs N…
  • reference/patterns/compose.md — Pattern Composition — Two primitives for building multi-step agentic pipelines out of simpler patterns.
  • reference/patterns/hitl.md — Human-in-the-Loop Agent — HITLAgent adds approval gates to the ReAct loop. Before every tool call, a review_fn is called with a HITLStep describing the pro…
  • reference/patterns/index.md — Pattern API Reference — This section groups the API-facing documentation for the public agent-pattern surfaces in brain/patterns/.
  • reference/patterns/memory.md — Conversation Memory — ConversationMemory gives any pattern a persistent, searchable short-term memory. Add past interactions, retrieve recent history, keyword-…
  • reference/patterns/multi_agent.md — Multi-Agent Orchestrator — MultiAgentOrchestrator fans out to multiple sub-agents in parallel using ThreadPoolExecutor, then synthesises their outputs.
  • reference/patterns/plan_execute.md — Plan & Execute Agent — The Plan-and-Execute pattern (Wang et al., 2023) separates planning from execution: 1. Plan: LLM generates a list of discrete steps…
  • reference/patterns/prompts.md — Prompt Registry — brain.patterns.prompts ships a versioned, centralized registry of all pattern prompts. Override any system prompt without touching patter…
  • reference/patterns/rag.md — RAG Agent — RAGAgent (Lewis et al., 2020) retrieves relevant chunks before generating an answer, grounding the response in supplied documents rather…
  • reference/patterns/react.md — ReAct Agent — The ReAct pattern (Yao et al., 2022) interleaves reasoning (Thought) and acting (Action) steps. The agent iterates until it reaches…
  • reference/patterns/reflexion.md — Reflexion Agent — Reflexion (Shinn et al., 2023) generates an answer, critiques it, then refines. The agent stops early if the critique finds no issues.
  • reference/patterns/streaming.md — Streaming ReAct Agent — StreamingReActAgent wraps the ReAct pattern with a generator interface. Instead of blocking until a final answer, it **yields `PatternEve…
  • reference/patterns/testing.md — Testing Agent Patterns — brain.patterns.testing provides first-class utilities for writing deterministic, fast, zero-API-key tests against any pattern.
  • reference/patterns/tools.md — Tool Specs — ToolSpec and the @tool decorator wrap plain Python functions with typed metadata — name, description, and a JSON-schema parameter defin…
  • reference/patterns/tracing.md — Pattern Tracing — TracedPattern wraps any BasePattern with OpenTelemetry spans so every run appears in your observability backend (Arize Phoenix, Jaeger,…
  • reference/providers.md — Providers — Auto-generated from brain.providers.provider_registry via sb docs providers --write. Do not hand-edit.
  • reference/quality.md — Memory API v1 — Published Quality Scorecard — The Memory API's brand promise is AI you can audit: every memory-bearing response carries a Citation envelope (defined in `contracts/…
  • reference/sdk-stability.md — SDK Stability — Current as of 2026-05-04.
  • reference/skills.md — Skills Reference — Auto-generated; do not hand-edit. Regenerate with sb skills docs-write.

releases/

  • releases/v0.3.0-draft.md — v0.3.0 Draft Release Notes — SecondBrain is now a public local-first runtime for grounded retrieval, memory, governed execution, and offline-friendly agent patterns.

roadmap/

  • roadmap/governed-action-runtime.md — Governed Action Runtime Improvement Plan — SecondBrain already has strong local-first building blocks: kernel tool policies, approval gates, agent identity, MCP governance, backgroun…
  • roadmap/v0.3.md — v0.3 Roadmap — A credible public release of the existing repo:

tutorials/

  • tutorials/developer-workflow.md — Developer Workflow Demo — This demo is for users who want to evaluate SecondBrain as a builder surface after the personal-knowledge demo works. It stays offline-frie…
  • tutorials/personal-knowledge.md — Personal Knowledge Demo — This is the main new-user demo. It proves that SecondBrain can ingest a small local corpus, build local context, and answer from citations…
  • tutorials/quickstart.md — Quickstart — Get one grounded answer from local demo data in 5 minutes. No provider keys required. After the demo works, decide whether to configure you…

user-guides/

  • user-guides/improvement-loop/overview.md — Environment And Improvement Loop User Guide — SecondBrain's improvement loop is a local, auditable harness for turning real failures into measured changes. It combines four planes: