Advenire-Consulting/greymatter

README preview

# greymatter

Code + conversation knowledge graph for Claude Code. Indexes your codebase and past sessions into a local SQLite store, exposes structured queries Claude can call instead of greping, and keeps behavioral preferences that shape how Claude works with you. All data stays on your machine.

greymatter is the successor to [thebrain](https://github.com/Advenire-Consulting/thebrain) — same goal, rebuilt around a single unified graph instead of separate regional databases. Smaller surface, faster lookups, modular extractor interface for adding new language support.

## What it does

**Code navigation without grep.** Scans your codebase and builds a structured graph of how files connect — imports, exports, routes, database references, function and class definitions. Queries like "what imports this file," "what's the blast radius of changing it," and "show the body of this function" return in one call instead of a grep-then-read chain. Works across every project in your workspace.

**Blast radius that includes textual contracts.** Most code graphs stop at imports. They miss slash commands that shell out to scripts by path, READMEs quoting filenames, rules files pointing at specific modules, and plan docs that cite sources. greymatter pairs its structural blast radius with `grep.js` — a project-aware content search with surrounding context — so before you rename or delete a file, you see every reference to it, code or text. Paired sequences like `--blast-radius` + `grep.js <filename>` are documented in the Combined Recipes section of [`docs/tool-index.md`](docs/tool-index.md#combined-recipes).

**Conversation recall across sessions.** Indexes your Claude Code conversation history — the JSONL files Claude already writes — into a searchable store. "What did we decide about the auth system?" returns the actual back-and-forth. A tiered read ladder (digest → decision → focus → full) lets Claude confirm it has the right session before committing to read the verbatim text.

**Behavioral preferences that persist.** Flag moments that matter with `/dopamine` (lessons from what worked or what burned you) and `/oxytocin` (relational dynamics that shape collaboration). These compile into decision gates that load at session start, so Claude doesn't re-learn your preferences every time.

**Optional MCP server.** Exposes the graph as structured tools over the Model Context Protocol — usable from Claude Desktop, Claude Code, Cursor, Continue, or any MCP-compatible client. Off by default; one command flips it on and regenerates the rules file with tool descriptors instead of CLI flag vocabulary. CLI behavior is unchanged when the server is off, and `disable` restores it round-trip. Full client snippets, tool list, and troubleshooting in [`docs/mcp-server.md`](docs/mcp-server.md).

**Test-map alerts.** Opt-in stale-test-pair detector. For each project you enable, greymatter cross-references recent source changes against their paired test files and flags source commits that didn't carry a matching test update (`stale_pair`) or source files that never had a test at all (`missing_test`). Pairing logic lives in each language extractor — JavaScript, TypeScript, Python, and Svelte ship with pairing enabled; adding another language is an extractor change, not a core change. The session-start hook runs an incremental scan per opted-in project; `scripts/test-alerts.js` handles mid-session re-runs and full-codebase audits; `/test-map` summarizes findings for the current project and can convert them into TodoWrite items.

View full repository on GitHub →