Argus: Shared Structural Memory for AI Coding Agents

Every AI coding session I started had the same cold open: the agent would fan out across the codebase with grep and find, re-reading files it had effectively seen before, then confidently generate a utility function that already existed three directories away. I built Argus to end that loop.

The problem: agents with no memory

AI coding assistants are stateless about your codebase. Every session starts from zero, which produces the same four failure modes:

Blind rescanning. Agents shell out to grep, find, and cat across thousands of files to answer questions a symbol index could answer in milliseconds.
Duplicated code. Without a map of what exists, agents reinvent helpers, types, and modules that are already there — the same clone in a new file.
Burned tokens. Raw file scans dump tens of thousands of tokens of irrelevant source into the context window before any real work starts.
Fearful refactors. Rename a function and nobody can tell you what breaks. Agents either refuse the refactor or break callers they never found.

What Argus is

Argus is a Codebase Dictionary and Evolution MCP server. It parses your codebase with tree-sitter — functions, classes, methods, interfaces, signatures, docstrings, and call relationships — into a local SQLite index, then serves that index to AI agents over the Model Context Protocol. Agents query structure instead of scanning files.

Each project keeps its own isolated .mcp-codebase.db next to the code. On startup Argus runs a hash-delta sync (unchanged files are skipped), then watches for changes. Eight languages are supported: TypeScript, TSX, JavaScript, Python, Go, Rust, PHP, and Ruby. Nothing leaves your machine in the default setup.

Is this just RAG?

Kind of — but without the fuzzy part.

Classic RAG chunks your code into text blobs, embeds them, and retrieves by vector similarity: this looks related. That works for docs, but for code it returns near-misses, burns tokens on irrelevant chunks, and can’t answer structural questions like “who calls this?” or “is this dead code?”

Argus does the retrieval half of RAG symbolically instead of statistically — a compiler’s view of the code instead of a search engine’s:

Index. RAG: text chunks + embeddings. Argus: parsed AST — symbols, signatures, call graph.
Retrieval. RAG: similarity search (approximate). Argus: exact queries — lookup, dependents, duplicates.
Token cost. RAG: high (whole chunks). Argus: low (signatures + pointers, bodies on demand).
Failure mode. RAG: wrong-but-plausible chunks. Argus: nothing found — an honest miss, not a hallucinated hit.

The two stack nicely: Argus for exact structure, vector search for fuzzy “find code that does X” queries. Best of both worlds.

Hybrid search

lookup_dictionary now takes a mode. The default exact is the original substring matching — deterministic and unchanged. Pass hybrid and two more recall tiers kick in after the exact hits:

Lexical. Token and prefix search over names, signatures, and docstrings (SQLite FTS5, zero new dependencies), plus edit-distance typo tolerance — noramlize finds normalize.
Semantic. Optional embedding similarity through a local Ollama sidecar, for conceptual queries where no word overlaps (“retry with backoff” finds withRetry). Vectors live in the project’s own index and sync in the background; no Ollama, no problem — the tier stays off and everything else works.

One startup probe decides: if Ollama answers at http://127.0.0.1:11434, semantic search is on:

ollama pull nomic-embed-text   # first: an embedding model
argus --root /path/to/project --ollama

In team serve mode the server does all embedding work, so one sidecar covers every connected agent.

How to use it

1. Index your project

Build once, then point Argus at a project root. It creates the index and keeps it fresh with a file watcher:

npm install
npm run build
npm test

node dist/src/index.js --root /path/to/project

2. Connect your agent

Point your MCP client at the built entrypoint. For Claude Code, add it to the MCP config:

{
  "mcpServers": {
    "argus": {
      "command": "node",
      "args": ["/path/to/argus/dist/src/index.js", "--root", "/path/to/project"]
    }
  }
}

Or register it from the CLI:

Claude mcp add argus -- node /path/to/argus/dist/src/index.js --root /path/to/project

3. Add the agent rule

The index only pays off if agents actually consult it. Add this to the project's AGENTS.md:

Before generating any new function, utility, module, or class, you MUST call the lookup_dictionary MCP tool to check if equivalent or reusable code already exists in the project. Never scan raw project files using shell commands (cat, grep, find) unless explicitly requested for inline editing.

4. Share it with your team (optional)

Solo over stdio is the default. For a team, run one shared server with a token:

ARGUS_TOKEN=$(openssl rand -hex 24) node dist/src/index.js serve --config argus.json

That exposes the MCP endpoint over Streamable HTTP, a JSON API, and an admin UI with health, search, and blast-radius views.

The six tools

lookup_dictionary. Find existing symbols by name — signatures, file paths, line numbers, docstrings. Pass mode: "hybrid" for typo-tolerant and semantic matches.
get_codebase_map. Exported symbols and signatures per file; the quick orientation tour.
get_symbol_details. The exact source block for one symbol — no surrounding file.
check_blast_radius. Incoming dependents plus outgoing dependencies before you refactor.
find_duplicates. Symbols sharing a normalized name and signature.
find_dead_code. Symbols nothing calls — conservative, so reviewed deletions stay safe.

What changed for me

The practical difference is session startup: instead of a multi-thousand-token spelunking phase, the agent asks the index targeted questions — does this exist, who calls it, what breaks if I move it — and starts editing with a map instead of a flashlight. Duplicates get caught before they are written, and refactors come with a blast radius attached.

If you pair with AI agents on a real codebase, give your agent a memory. Your tokens (and your utils folder) will thank you.

Argus is open source — browse the code, try it on your own repo, and contribute: github.com/iamstoick/argus