Every task, an agent starts blind: it greps a term, opens a file, follows an import, backs out, tries again - rebuilding a picture of a codebase it mapped an hour ago and threw away. Codebase memory builds that picture once and lets the agent query it: a knowledge graph of the symbols each file defines (functions, classes, interfaces, types, …), the modules it imports, and which symbol calls or references which.
This is structural memory of your code - complementary to Recall, which is session memory of what you did. It is on by default; everything runs locally and your code never leaves your machine.
Native, no dependencies
The engine is built into enigma - a zero-dependency TypeScript indexer. There is no external binary, no npx, no third-party package: extraction is deterministic (regex-per-language over the common languages - TS/JS, Python, Go, Rust, Java, Ruby, PHP, C#, Kotlin, C/C++). It is honest “structural-lite”, not a compiler-grade AST, but enough to map a codebase with nothing to install and nothing to fetch.
The graph also holds what sits around the code: Markdown and MDX notes (one node per heading down to level 3), SQL schemas (tables, views, functions), Prisma models, and YAML/TOML config (top-level keys, compose services, CI jobs). A doc that links a file, or names a function in inline code, is connected to it, so asking about a subsystem finds its note and changing a function shows the docs that describe it. Docs under references/, examples/, fixtures/ or vendor/ are left out: they are somebody else’s.
Every edge says how it was learned. One read from an import or a declaration in the same file is extracted; one matched by name (a language whose imports do not say what they bind, or a doc’s inline-code mention) is marked inferred, and callers prints it that way so you can weigh it.
Turning the setting on exposes enigma’s code-graph tools to your agents through enigma’s own MCP server. The graph is stored per project as JSON under ~/.enigma/codegraph, so the CLI, the MCP tools and the dashboard all read the same store.
What your agent can ask
| Question | Tool | CLI |
|---|---|---|
| Where is the code for this task? | enigma_codegraph_ask |
codegraph ask "<question>" |
| What breaks if I change this? | enigma_codegraph_trace |
codegraph callers <symbol> --depth 2 |
| What is this file’s API? | enigma_codegraph_skeleton |
codegraph skeleton <file> |
| What does this repo look like? | enigma_codegraph_map |
codegraph map |
| One page to start from | session start (below) | codegraph report |
| Every occurrence, ranked | enigma_codegraph_grep |
codegraph grep "<regex>" |
| Draw what depends on what | dashboard Code graph tab | codegraph graph [focus] |
ask blends word matching with a walk over the graph, so the result is the code wired into what you asked about rather than whatever happened to share a word with it, and each hit carries an exact path and line range with the source inlined. grep attributes every hit to the symbol enclosing it and ranks groups by how much other code depends on that symbol - the part plain grep -rn cannot tell you.
Every query stats the tree first and re-indexes only what moved, so an answer describes the code as it is right now, uncommitted edits included. enigma codegraph check reports drift without repairing it, and exits non-zero when the graph has fallen behind - usable as a CI gate.
In a git repository the graph covers what git covers: tracked files plus untracked ones your .gitignore does not exclude. A build output, a dependency cache or a downloaded dataset sitting beside your source is not part of your codebase, and walking it would cost more than indexing the code does.
It rides along in the session
The tools above are the pull half: the agent calls them when it decides to. In Claude Code the graph is also pushed, through four hooks, so it arrives without being asked:
| When | What arrives |
|---|---|
| Session start | The repo report, once, plus a short note naming the tools: the codebase’s functional areas (files grouped by how they depend on each other, not by folder), each with its key symbols and its docs, and the project’s own notes. About 1k tokens, cached, so it is paid once per session - and it replaces the first calls a fresh session (or one after /clear) would spend exploring. |
| Every prompt | Up to three locators for the nodes that task touches - path:line only, never inlined code. |
| After an edit | What depends on the file just written, while you can still widen the change. |
| End of a turn that changed code | A background re-index, so the next answer is current. |
The per-prompt hook is deliberately quiet: a prompt too short to retrieve on, a match too weak to trust, or a pointer already given this session all produce nothing. A hook that fires on every prompt has to earn each interruption, or the agent learns to ignore the channel.
Locators rather than code, on purpose. The session-start block is written once and rides the prompt cache; a per-prompt block is fresh input on every turn, so inlining source there would spend thousands of tokens a turn to save a read that may never happen. The agent pulls the span itself when a pointer looks right.
Claude Code only. The other agents have no equivalent per-prompt event, so wiring them would spend a process per turn to produce nothing - they still get the MCP tools, which work everywhere.
Turn it off
enigma config code-graph off
On by default. Turning it off removes the tools and the hooks; -l scopes the change to this project. Turning it back on takes effect in your agent’s next session - the tools and hooks are read at startup.
Nothing needs indexing by hand: the first query indexes the project it is asked from.
You can also toggle it, index a project, run a query and see how far the graph has drifted from the code in the dashboard’s Code graph tab.
See it
The Code graph tab draws the graph itself. Nodes are files and symbols, sized by how many other files depend on them and coloured by the directory they live in; edges are the imports, calls and references between them. Click a node for its signature and location, double-click to pull in its neighbours, and type a symbol or file in the focus box to re-centre on it. Switch between the symbol view and the file/import view, and widen the neighbourhood from one hop to four.
A repo has far more nodes than a picture can carry, so the view always draws a ranked slice - the code the rest of the codebase depends on most - and says when the cap left something out.
enigma codegraph graph [focus]
The same slice in the terminal, or as Graphviz DOT with --dot (pipe it into dot -Tsvg). --scope files draws the import graph instead of the symbol graph, --depth N widens the neighbourhood around a focus, and --limit N sets the node cap. --json prints the raw nodes and edges.
Use it
enigma codegraph [action]
Manage: index [path] builds the graph (defaults to the current directory), projects lists indexed projects, arch [project] prints the architecture overview, search <name> finds symbols by name. Turning the tools on and off is enigma config code-graph on|off, like every other setting.
Query: ask returns ranked hits with --source to inline the code; callers/callees walk dependencies with --depth N; skeleton prints one file’s signatures; map orients you in an unfamiliar repo; grep finds every occurrence grouped by symbol; graph cuts a drawable slice (--scope files, --dot); check reports drift. All of them take --in <path>, --limit N, --json and --no-refresh.
Once it’s on, your agent queries the graph directly over MCP, which typically replaces many grep/read cycles with a single structural query.
Privacy
Everything runs in-process and is stored locally under ~/.enigma/codegraph. Turning the setting off removes the tools from your agents; the dashboard reads the graph from the local store, never over the network.