rustbrain

CLI for a Rust-native second brain — local Markdown + SQLite knowledge graph for humans and AI agents.

Write ordinary notes (docs/**/*.md, Obsidian-style WikiLinks). Index Rust code with Tree-Sitter. Search with FTS5. Expand the graph. Pack agent context under a token budget. All offline, project-scoped, Git-friendly.

  docs/*.md  +  src/**/*.rs  +  CHANGELOG.md  +  Cargo.toml deps
        │              │              │                │
        ▼              ▼              ▼                ▼
   WikiLinks      tree-sitter    hub: changelog   docs.rs notes
   frontmatter     symbols
        └──────────────┬──────────────┴────────────────┘
                       ▼
              .brain/db.sqlite   ← source of truth
                       │
                       ▼
              .brain/graph.mmap  ← CSR neighborhood cache
                       │
                       ▼
         query · context · graph · doctor · agents

Library API: rustbrain-core
Full flag book: docs/CLI.md
Repo: github.com/shan-alexander/rustbrain

Why rustbrain?

Install

cargo install rustbrain --locked
# pin: cargo install rustbrain --version 0.3.20 --locked

# ensure the binary is on PATH
export PATH="$HOME/.cargo/bin:$PATH"
rustbrain --version

Requirements: Rust 1.80+, a C toolchain (bundled SQLite + tree-sitter).
License: MIT OR Apache-2.0.

Getting started (5 minutes)

1. One-shot setup (recommended)

cd your-project

rustbrain setup --yes

This will:

1. Create .brain/db.sqlite
2. Scaffold docs/ (goals, ADRs, analysis, plans, …)
3. Write root AGENTS.md + docs/AGENTS.md (agent protocol)
4. Harvest README → docs/goals/from-readme.md (if present)
5. Harvest Cargo.toml deps → docs.rs notes under docs/references/crates/
6. Optional AST module map
7. Sync (index) + doctor

Skip pieces when you need to:

rustbrain setup --yes --no-crate-docs    # no docs.rs harvest
rustbrain setup --yes --no-agents-md     # no AGENTS.md write
rustbrain setup --yes --force            # overwrite generated files

2. Capture knowledge

# Preferred: type + title only → scaffold → edit the printed path → sync
rustbrain note new --type adr --title "Use local SQLite"
# edit docs/adr/use-local-sqlite.md  (Status / Context / Decision / Consequences)

rustbrain note new --type plan --title "Q3 platform roadmap"
# edit checkboxes / status: backlog | in_progress | qa | done | cancelled | blocked

rustbrain note new --type analysis --title "query path bench 2026-07-31"
rustbrain note new --type goal --title "Ship offline agent context"

rustbrain sync

3. Search & orient (agents and humans)

rustbrain query "sqlite" --scores
rustbrain query "status:in_progress" --type plan --scores
rustbrain query "serde" --scores              # docs.rs note after setup harvest

rustbrain context "why local sqlite"
rustbrain context "what shipped"
rustbrain context "roadmap priorities"

rustbrain graph docs/adr/use-local-sqlite.md
rustbrain graph changelog                     # if CHANGELOG.md exists
rustbrain doctor
rustbrain doctor --orphans

4. Everyday loop

# After editing docs or code:
rustbrain sync

# Soft-link orphans / normalize WikiLinks when needed:
rustbrain links --auto
rustbrain links --apply --dry-run
rustbrain links --apply --write

# Live re-index while editing:
rustbrain watch --debounce-ms 300

Command reference (overview)

Full flags and nuances: docs/CLI.md.

Note types (quick map)

Root hubs (when files exist):

Plan status tokens (after sync): status:backlog, status:in_progress, status:qa, status:done, status:cancelled, status:blocked.

Agent protocol (HITL)

After setup, agents should treat AGENTS.md / docs/AGENTS.md as the project mandate:

1. Orient with rustbrain context "…" before large refactors
2. Search with query / graph instead of inventing history
3. Capture with note new scaffolds + WikiLinks / symbol:
4. sync after doc or code changes
5. Never invent ADR history or changelog entries

Customize the cookbook:

rustbrain setup --yes --agents-template ./AGENTS.template.md
# or commit AGENTS.template.md / .rustbrain/AGENTS.template.md
# or export RUSTBRAIN_AGENTS_TEMPLATE=/path/to/template.md

Linking notes and code

---
node_type: adr
tags: [storage]
---
# Use local SQLite

Decision: keep the brain in-process.

See [[docs/concepts/fts5]] and symbol:Database::open.

/// Primary store. Decision: [[docs/adr/use-local-sqlite]].
pub struct Database { /* … */ }

On sync:

• Note → code: anchors
• Code rustdoc → note: doc_links

Portability

rustbrain export --out team.brainbundle --decouple-ast
# copy file to another machine / repo
rustbrain import --input team.brainbundle -w /other/project
rustbrain sync -w /other/project

Exit codes

Library usage

Embed the same engine in tools and agents via rustbrain-core:

[dependencies]
rustbrain-core = "0.3"

See that crate’s README for full Rust API examples (Brain, query_ranked, context_for_prompt_with, …).

License

MIT OR Apache-2.0