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.

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:

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

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