greymatter

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

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.

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.

Safety hooks on edits and commands. Before Claude writes a file or runs a shell command, policy hooks classify the target by sensitivity and blast radius and either warn, block, or ask for confirmation. Unparseable commands get flagged for manual review. Configurable per path.

Project reorientation. When a session touches a project it hasn't seen in a while, --reorient <project> returns the recent session history, decisions made, and files touched — usually under 300 tokens of context you would otherwise re-acquire by reading 10+ files.

Project-ambiguous recall. When you reference conversations by count rather than by project — "last session", "a couple sessions ago", "the session before that" — --recent [N] returns the N most recent sessions across all projects, ordered by start time, with each session tagged with every project it touched. Cross-project sessions appear once with all projects listed, not once per project.

Local-only data. Everything lives in SQLite under ~/.claude/greymatter/. Nothing syncs externally, nothing leaves your machine.

Single runtime dependency. Just better-sqlite3. No language servers, no external services, no API keys.

Prerequisites

• Node.js 18 or newer
• Claude Code CLI

Installation