second-brain-graph 0.1.1

A living, always-fresh, low-token map of every project: files, links, areas and mechanics, with a navigable 3D view.

Second Brain (SB)

A living, always-fresh, low-token map of every project — files, links, areas and mechanics — that an AI assistant can query instead of re-reading everything, and that a human can explore in a navigable 3D graph.

🇮🇹 Leggi in italiano →

Not "another place to store stuff". It's the canonical, per-project picture that stays in sync with your files so you never lose track: no forgotten pieces, no "we discussed that three chats ago", no stale docs.

_{The offline 3D viewer on a real, multi-project workspace (names anonymized): nodes colored by type, grouped here by type, with a click-through detail panel.}

---

Why this exists

A project gets more complex over time. Files drift, some go orphaned or quietly broken, the mental model of "what's where and how it connects" gets fuzzier, and an AI assistant loses the thread between one chat and the next — so every session starts by re-reading and re-searching files. That is slow, incomplete, and burns tokens repeatedly — and it only gets worse as the project grows.

Second Brain builds the project's graph once and keeps it fresh incrementally (outside the model, at near-zero token cost). The assistant queries it and gets compact answers; a human opens the 3D view and sees the whole project at a glance.

It is not a RAG system: no embeddings, no vector store, no LLM needed to build the graph. It maps the structural relationships between files, which makes it complementary to RAG and purpose-built for one thing: situational awareness at a very low token cost.

What makes it different

• Read-only on your sources — it indexes, it never modifies your files. Run it on anything without risk.
• Files are the truth — the graph is derived (in .secondbrain/) and always regenerable; contents are never duplicated into it.
• Zero runtime dependencies — the core runs on the Python standard library alone. No conflicts, instant install, works in CI / containers / air-gapped boxes.
• Low token cost by design — queries return ids, types, sizes and connections, never file contents, so orienting an assistant costs a few hundred tokens, not tens of thousands.
• Anti-drift gate — refuses to call the graph "fine" while something is stale, orphaned, or broken.
• Offline 3D viewer — the data is inlined and the 3D library is vendored next to the page; the viewer works fully offline, no CDN, nothing for a script blocker to break.
• Optional MCP server — exposes the same low-token queries to MCP-aware assistants, behind an optional extra so the core stays dependency-free.

See it on a real project (anonymized)

A read-only measurement on a mature, multi-repo project (identity withheld): ~1,684 knowledge files across 17 top-level areas, indexed in ~1.3 s (index graph.json = 0.91 MB).

Three ways to answer the same four questions about the project — what's here, list every recorded decision, which files are truncated/empty, the most-connected files — in three separate clean chats:

Metric	NOTHING (manual)	TODAY (manual)	WITH Second Brain
Time	~8.5 min	~9 min	~3–4 min
Working tokens	opaque	opaque	~3–4k, self-measured
Decisions found	112 (wrong)	131 (wrong)	117 (exact)
Truncated files	3	0 (missed)	2 (exact)
Files counted	2,174	2,174	1,684 (exact)
Reproducible / verifiable	no	no	yes

Two things stand out. (1) The two manual runs disagree with each other — 112 vs 131 decisions, 3 vs 0 truncated files (the second missed them entirely): the by-hand method is non-deterministic and unverifiable. (2) Second Brain returns the exact, identical answer every run, with far fewer tokens and in less than half the time.

Just to orient an assistant on the whole project — something you pay for every session — reading the curated source-of-truth docs costs ~229,000 tokens; the second-brain map digest costs ~270 tokens: ~800× less, and roughly constant as the project grows (the full index is queried, never loaded into context).

And it surfaces what even curated docs miss: genuinely truncated/corrupted files (with UTF-16/encoding false positives excluded), ~45 empty files, ~1,390 orphan files (~80%), 117 decisions and ~626 cross-references now explicit and queryable, plus 13 files already stale within seconds of indexing (a live system constantly writing) — which is exactly why the map has to update itself.

_{Illustrative — the continuity problem SB removes: over many sessions a hand-kept map drifts as orphans and stale files pile up, while a queryable graph stays current.}

The same structure, the code layer

Second Brain's code-import layer renders the whole workspace as a graph you can actually read:

Install

pip install second-brain-graph              # from PyPI
pip install "second-brain-graph[mcp]"       # + optional MCP server
pip install -e .                            # or from a clone

On PyPI. Requires Python 3.10+. Runtime dependencies: none (standard library only). The package installs the second-brain command and the second_brain import module.

Quickstart

second-brain build  .          # index a project -> .secondbrain/graph.json
second-brain gate   .          # anti-drift check: broken refs, stale files, orphans
second-brain view   .          # write the offline 3D viewer -> .secondbrain/view.html
second-brain stats  .          # quick counts by node/edge type
second-brain map    .          # compact digest: areas, sizes, most-connected files
second-brain find   util .     # find nodes by name or path
second-brain neighbors second_brain/model.py .   # a node and its connections
second-brain assess .          # one-shot before/after report: problems + token savings

Drill down by pointing the tool at a subfolder — second-brain view ./src/api renders just that area in full detail, while the top-level view stays light via backbone mode (areas + the knowledge-connected core; isolated data files are summarized on their area node).

Viewing the 3D graph

1. Generate the viewer: second-brain view .
2. Open it: double-click the file it writes — .secondbrain/view.html — in any browser. No server, no install: the data is inlined and the 3D library is bundled next to the page, so it works fully offline.
3. Explore: left-drag to orbit, scroll to zoom, double-click a node for its details. Use the left panel to search, group by type / area / folder, or show only orphans.

Query layer (for AI assistants)

second-brain map, find, and neighbors return compact, budgeted answers (ids, types, sizes, connections — never file contents). An optional MCP server exposes the same queries to MCP-aware assistants:

pip install "second-brain-graph[mcp]"
second-brain-mcp .      # serves map / find / neighbors / subgraph / health over stdio

See docs/mcp.md for the tools and their shapes.

How it works

1. Index — walk the project, classify each file into a typed node, and extract edges: Python imports (via ast), JS/TS imports, documentation references (markdown links, [[wikilinks]], and plain path mentions in prose — the part standard tools miss), and area membership. Operational nodes (decisions found in the docs, sessions from git commits) are added too.
2. Stay fresh — content-hash diffing rebuilds only what changed (outside the model).
3. Query / view — a human gets the 3D view; an assistant queries the low-token layer.

On false positives: plain path mentions in prose are inherently noisy. Second Brain handles this asymmetrically — markdown links and wikilinks are intentional (an unresolved one is reported as broken), but a plain prose mention is used only if it resolves to a real file; otherwise it is dropped as noise and never creates a broken reference. Deep import parsing is Python and JS/TS today; other languages contribute via documentation links.

The full node/edge taxonomy, the graph.json schema, and the classification rules are documented in docs/graph-format.md.

Try the before/after yourself

Run these in separate clean chats (read-only), then compare the answers and the token/time cost. Replace /path/to/project with a real project.

TODAY (your current method):

READ-ONLY: do not modify, create, delete or move any file. On the project at
/path/to/project, work with your NORMAL method (reference docs, memory, the tools you
usually use). Give me a COMPLETE, ACCURATE picture answering these 4 questions:
1) how many files (excluding images, venvs, caches, .git) and the breakdown by type;
2) list ALL decisions recorded in the docs (D-XXX, ADR-N, RFC-N);
3) which files are truncated/corrupted (null-byte) or empty (zero-byte);
4) the 10 most-connected files. When done, tell me the time and tokens you used.

WITH Second Brain (index already built — query it, don't re-read files):

READ-ONLY. Second Brain's index is already built — only query it. Use ONLY:
  python -m second_brain map   "/path/to/project"
  python -m second_brain stats "/path/to/project"
  python -m second_brain find <text> "/path/to/project"
and read /path/to/project/.secondbrain/assessment.md. Answer the same 4 questions, then
tell me the time and tokens you used.

Status & roadmap

Alpha (v0.1). Working today: the typed graph, the anti-drift gate, the offline 3D viewer, the low-token query layer (map/find/neighbors/subgraph), operational nodes (decisions/sessions), and the optional MCP server. Next: richer reference resolution and a PyPI release.

Development

pip install -e ".[dev,mcp]"
ruff check second-brain tests
pytest -q

Contributions are welcome — see CONTRIBUTING.md and the design principles (read-only, zero-deps, low-token, deterministic). Security reports: SECURITY.md.

License

MIT.