Metadata-Version: 2.4
Name: second-brain-graph
Version: 0.3.0
Summary: A living, always-fresh, low-token map of every project: files, links, areas and mechanics, with a navigable 2D community map.
Author-email: Lopax <lopax76@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/lopax76/second-brain
Project-URL: Repository, https://github.com/lopax76/second-brain
Project-URL: Issues, https://github.com/lopax76/second-brain/issues
Project-URL: Documentation, https://github.com/lopax76/second-brain#readme
Keywords: knowledge-graph,memory,ai-agents,documentation,code-graph,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Dynamic: license-file

# Second Brain (SB)

[![CI](https://github.com/lopax76/second-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/lopax76/second-brain/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/second-brain-graph.svg)](https://pypi.org/project/second-brain-graph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
[![Runtime deps](https://img.shields.io/badge/runtime%20deps-none-success.svg)](pyproject.toml)

**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 as a navigable **2D community map**.

🇮🇹 [Leggi in italiano →](README.it.md)

> 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.

![Second Brain viewer — anonymized backbone of a real multi-project workspace](docs/assets/ui-suite.png)

<sub>The offline viewer on a real, multi-project workspace (names anonymized): a flat 2D map with
files coloured and clustered into auto-detected communities, and a click-through detail panel.</sub>

---

## 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 **2D community map** 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.
- **Communities & impact** — auto-detects the project's real modules from how files link (not
  folders), and answers "what breaks if I change this?" (upstream/downstream impact) in one call.
- **`GRAPH_REPORT.md` one-pager** — the artifact an agent reads first instead of grepping: god
  nodes, communities, surprising links, decisions, and problems, regenerated on every build.
- **Offline graph viewer** — an interactive force-directed map (vis-network), coloured by
  community, with search, a click-to-inspect node panel with neighbour navigation, and a
  per-community show/hide legend. Data and library are inlined in one HTML file, so it works fully
  offline. The viewer is **adapted from [Graphify](https://github.com/safishamsi/graphify)** (MIT)
  — see [Acknowledgments](#acknowledgments).
- **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 | 131 | **112 (exact, every run)** |
| **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) — so the by-hand method is
non-deterministic and unverifiable: you can't tell the right answer (112) from a wrong one
(131). (2) Second Brain returns the **same answer every run** — 112, the correct count — with
far fewer tokens and in less than half the time. The win isn't a number nobody else could
reach; it's an exact, reproducible, queryable one instead of a coin-flip.

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).

<p align="center">
  <img src="docs/assets/chart-tokens.png" width="90%" alt="Tokens to orient (log scale): ~26.7M to read everything, ~4.09M all docs, ~229,000 today's curated docs, ~270 the Second Brain digest">
</p>

<p align="center">
  <img src="docs/assets/chart-accuracy.png" width="48%" alt="Accuracy: the two manual runs disagree (112 / 131); Second Brain returns the correct 112 on every run">
  <img src="docs/assets/chart-time.png" width="48%" alt="Time to answer: ~8.5 / ~9 min manual vs ~3–4 min with Second Brain; index build ~1.3 s once">
</p>

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%)**,
**112 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.

<p align="center">
  <img src="docs/assets/chart-memory.png" width="72%" alt="Illustrative: across many chats a hand-kept project map drifts while a queryable graph stays current">
</p>

<sub>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.</sub>

### The same structure, the code layer

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

![Graphify view of the workspace code graph](docs/assets/graphify-suite.png)

## Install

```bash
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](https://pypi.org/project/second-brain-graph/). Requires Python 3.10+. Runtime
dependencies: **none** (standard library only). The package installs the `second-brain` command
and the `second_brain` import module.

## Quickstart

```bash
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 2D community-map 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 impact second_brain/model.py .      # blast radius: what breaks / what it depends on
second-brain report .          # write GRAPH_REPORT.md: god nodes, communities, decisions, problems
second-brain assess .          # one-shot before/after report: problems + token savings
second-brain symbols second_brain/model.py       # function/class signatures in one Python file
second-brain agent install .   # add the SB directive to CLAUDE.md/AGENTS.md + a Claude Code hook
second-brain hook install .    # git post-commit/post-checkout: keep the graph fresh automatically
```

**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 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 and the rendering library are inlined into the single page, so it
   works fully offline.
3. **Explore:** the graph is laid out as a flat **2D map**, with files coloured and clustered into
   **communities** (auto-detected from how they link). Scroll to zoom, right-drag to pan,
   double-click a node for its details (including its impact radius). Use the left panel to search,
   switch grouping (community / area / folder / type), focus a single community, or show only
   orphans.

## Query layer (for AI assistants)

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

```bash
pip install "second-brain-graph[mcp]"
second-brain-mcp .      # serves project_map / find / neighbors / subgraph / impact / report / health
```

See [`docs/mcp.md`](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 2D community map; 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`](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. Working today: the typed graph, the anti-drift gate, the offline **2D community-map**
viewer, the low-token query layer (`map`/`find`/`neighbors` on the CLI; `subgraph` via MCP),
operational nodes
(decisions/sessions), and the optional MCP server. **v0.3** adds **community detection**
(real modules discovered from how files link), **impact queries** (`impact` — what breaks if you
change a node), a **`GRAPH_REPORT.md` one-pager** (`report`, regenerated on every build), and
**agent integration** (`agent install` writes a CLAUDE.md/AGENTS.md directive + a Claude Code
`PreToolUse` hook; `hook install` adds git hooks that rebuild the graph for free). It also carries
forward v0.2's **configurable `.secondbrain.json` taxonomy** and **Python symbol layer**
(`symbols`). Next: richer reference resolution and symbol layers for more languages.

## Development

```bash
pip install -e ".[dev,mcp]"
ruff check second_brain tests
pytest -q
```

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
[design principles](CONTRIBUTING.md#design-principles-please-keep-these-intact) (read-only,
zero-deps, low-token, deterministic). Security reports: [SECURITY.md](SECURITY.md).

## Acknowledgments

The interactive graph viewer is **adapted from [Graphify](https://github.com/safishamsi/graphify)**
by Safi Shamsi (MIT License) — its graph viewer is what this one is modelled on, and we're
grateful for it. The viewer renders with [vis-network](https://github.com/visjs/vis-network)
(Apache-2.0 OR MIT), bundled offline. Full details and license texts are in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License

[MIT](LICENSE).
