Example End-to-End Flow (Refreshed 2026-04-25)¶

Scenario¶

User runs an interactive planning/research session, adjusts runtime behavior live, asks a grounded question, and then inspects the local state left behind.

This example is offline-safe when using --provider local; replace the provider and model with a configured model when you want real synthesis.

1) Commands Run¶

cd /path/to/SecondBrain   # the repo root (your clone)

# Optional: keep local sources indexed. Incremental ingest is the default.
sb ingest vault/

# Optional: rebuild the context index explicitly.
sb context index

# Start chat with local-only generation and a named persisted session.
sb chat --provider local --web off --session research-project

Inside chat:

/agent research
/model local-echo
/topk 9
/think high
/status
What are my top open loops and the best next 3 actions?
/sources
/exit

For a configured cloud or Ollama model, use the same flow with a different provider/model pair:

sb chat --provider openai --model "$SB_OPENAI_MODEL" --web off --session research-project
sb chat --provider ollama --model qwen3.5:9b --web off --session research-project

2) Representative Runtime Output¶

Agent profile set to research
web=auto, top_k=8, think=medium, steps=8, timeout=120s

Model set to local-echo

Top-k set to 9
Think level set to high

Session: research-project
Provider: local (local-echo)
Profile: research
Web mode: off
Permission mode: ask
Think level: high
Top-k: 9
Tool sets: code, git, projects, research, testing, workflow
Turn limits: steps=8, timeout=120s

If user runs /team without subagents:

/team requires sub-agent tools. Restart with sb chat --subagents.

With subagents enabled:

sb chat --provider openai --subagents --session planning-team

3) Context Pack Skeleton¶

Source schema: brain/context_packs/schema_v2.py

{
  "schema_version": "context_pack.v2",
  "pack_id": "cp_...",
  "created_at": "2026-04-25T...Z",
  "intent": "What are my top open loops and the best next 3 actions?",
  "constraints": [
    "local_first",
    "cite_sources"
  ],
  "preferences": [],
  "relevant_facts": [
    {
      "path": "vault/01_projects/project-alpha.md",
      "anchor": "vault/01_projects/project-alpha.md#next-steps",
      "text": "...",
      "score": 0.42
    }
  ],
  "prior_decisions": [
    {
      "decision_id": "dec_...",
      "title": "Adopt split SQLite state",
      "rationale": "...",
      "source_path": "vault/03_decisions/...md"
    }
  ],
  "open_loops": [
    "[01_projects/project-alpha.md:37] finalize milestone dates"
  ],
  "suggested_plan": [
    {
      "step_id": "s1",
      "title": "Prioritize open loops",
      "dependencies": [],
      "tool_requirements": [
        "open_loops",
        "local_search"
      ],
      "risk_level": "low"
    }
  ],
  "allowed_actions": [
    "read",
    "plan",
    "write_with_confirmation"
  ],
  "success_criteria": [
    "grounded",
    "actionable",
    "cited"
  ],
  "policy_controls": {
    "permission_mode": "ask"
  },
  "web_mode": "off"
}

4) Citation Format In Chat¶

Local citations from TurnResult.local_citations are shown as anchors:

Local citations:
- vault/01_projects/project-alpha.md#next-steps
- vault/03_decisions/extracted_20260425_134950.md

Web citations are shown only when web search is enabled:

Web citations:
- Example Source: https://example.com/article

5) Event Lineage For This Flow¶

Runtime event data lands under the configured settings.paths.state_dir. Operational state is split across domain databases; chat/session records are in runtime.db.

Typical records written:

chat_sessions row update (provider, model, web_mode, message_count, updated_at)
chat_messages rows for user and assistant messages
tool_calls rows for tool name, arguments, result JSON, status, and latency
session_events rows for streamable session events and checkpoints
observation_envelopes rows for serve/runtime observability where applicable
context-pack, ingest, memory, and decision records when those subsystems run

Representative tool_calls record shape:

{
  "session_id": "research-project",
  "tool_name": "local_search",
  "tool_args_json": "{\"query\":\"open loops\",\"top_k\":9}",
  "tool_result_json": "{...}",
  "status": "ok",
  "latency_ms": 34
}

6) Serve UI View Of The Same Runtime¶

sb serve

The FastAPI daemon mounts the React UI and exposes the same session/runtime state through routers under brain/serve/routers/. Chat stream event types are declared in brain/serve/chat_runtime.py::STREAM_EVENT_TYPES; the UI handles them in serve-ui/src/lib/chat.ts::HANDLED_EVENT_TYPES and checks for drift via GET /stream-events on startup.

7) Background Session Variant¶

Durable sessions use the same context, policy, and persistence foundations but store background-specific state:

sb sessions start "Summarize the top open loops and propose next actions" \
  --engine native \
  --session-id bg-open-loops

Expected state:

background_agent_sessions tracks status, engine, runner kind, heartbeat, retry/expiry metadata, approval request IDs, and parent/branch metadata
background_agent_checkpoints stores resumable summaries and cursors
background_agent_artifacts stores final outputs or claimed file artifacts
session_events streams state/checkpoint updates to serve/UI surfaces

8) Module Path Trace¶

Chat and slash command handling: brain/chat/repl.py
Serve chat and SSE contract: brain/serve/chat_runtime.py
UI stream reducer: serve-ui/src/lib/chat.ts
Agent tool loop and tool logging: brain/agent/harness.py
Tool registry and dynamic skills: brain/agent/tools.py
Prompt rebuilding after runtime changes: brain/agent/prompts.py
Retrieval: brain/retrieve/hybrid.py
Context pack assembly: brain/context_packs/service.py
Session persistence: brain/chat/session_store.py
Event logging: brain/state/event_log.py
Background sessions: brain/background_sessions/
DB topology: brain/db/topology.py
Current migrations: legacy brain/db/migrations/001_initial_schema.sql through 048_chat_turn_journal.sql, plus split domain migrations under brain/db/migrations/{runtime,memory,knowledge,work,travel}/