memory-for-ai

An MCP server that turns a codebase into a persistent knowledge graph — functions, classes, call chains, HTTP routes, cross-service links — so an AI coding agent answers structural questions with graph queries instead of reading file after file.

Windows native x64 only; MSYS2 CLANG64 is the development toolchain. See support and verification. One self-contained native executable. 162 languages via vendored tree-sitter grammars, refined by embedded Hybrid-LSP type resolution. 23 MCP tools. No language runtime, no Docker, no API key, no telemetry — everything runs locally.

• Are you an AI agent? Read docs/AGENT_GUIDE.md — the complete operating manual (tool catalog, task→tool playbooks, correctness protocol, per-project tuning). docs/llms.txt is the machine-readable index.
• Installing for a specific project? Jump to Per-project install — one command, zero global config, one isolated graph named after the repo.
• Want proof it pays off before adopting? docs/MEASURING.md — a 15-minute spot check and a full A/B protocol to measure token and tool-call savings on your own repository. A worked example with real numbers (and real caveats), measured on this repository itself: docs/AB-RESULTS.md.

Research — design and evaluation are described in Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277): across 31 real repositories, 10× fewer tokens and 2.1× fewer tool calls vs. file-by-file exploration, at 83% answer quality (92% for the file-by-file baseline).

Quick start

30-second machine check first (details: docs/INSTALL.md — Preflight):

1. Platform is native Windows x64 (Intel/AMD), with ~2 GB free disk. ARM64, emulation, Linux, macOS and WSL are unsupported.
2. Windows: powershell -Command "$PSVersionTable.PSVersion" must print a version — search_code shells out to PowerShell at runtime; if the WindowsPowerShell\v1.0 directory is missing from PATH, add it before installing.
3. git --version works (watcher freshness + detect_changes).
4. Already installed once? memory-for-ai --version tells you — re-running the installer is the update, indexes survive.

Windows (PowerShell):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/LonelyTraderBay/memory-for-ai/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1        # remove Mark-of-the-Web
.\install.ps1

Then restart your coding agent and say "Index this project". Done.

The installer downloads the verified release archive for your platform, verifies its SHA-256 against checksums.txt, installs the binary, and configures every coding agent it detects (Claude Code, Codex, Gemini CLI, Cursor, VS Code, Windsurf, and ~40 more — see Multi-agent support). Options: --skip-config (binary only), --dir=<path>, --clients=<list>, --project / --name=<name> (per-project mode). Full reference, including all package managers, manual MCP config, containers/CI, and uninstall: docs/INSTALL.md.

Antivirus note: Microsoft Defender may flag a release binary as Trojan:Script/Wacatac.B!ml — a known false positive (typically 61 of ~62 engines clean; the same family flags gh, llama.cpp, and Microsoft's own Go toolchain). Evidence and self-verification steps: Antivirus False Positives.

Per-project install

One binary can serve any number of repositories, but sometimes a project deserves its own fenced memory: an MCP server named after the repo, an index no other repo can see, and zero edits to global agent config. That is --project:

# From the repository root, after downloading install.ps1
.\install.ps1 --project

What it does: installs/refreshes the shared binary, writes a project-local .mcp.json entry named memory-for-ai-<repo-directory> pinned with --scope=<repo>, and indexes the repository immediately. An agent opened in that repo sees exactly one server serving exactly that graph; opening a different repo sees its own. Use the PowerShell installer for this supported platform. Details and guarantees: docs/INSTALL.md and docs/CONFIGURATION.md.

What it does

index_repository parses the whole tree (tree-sitter syntax pass + Hybrid-LSP type resolution), builds a graph of nodes (Function, Class, Route, Package, …) and edges (CALLS, IMPORTS, IMPLEMENTS, DATA_FLOWS, HTTP_CALLS, CROSS_*, …), and persists it to SQLite under ~/.cache/memory-for-ai/. A background watcher re-indexes on Git/filesystem changes. After that, the agent's questions become millisecond graph queries:

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")
             → caller tree for indexed CALLS edges, one call, ~250 tokens

In the maintainer's measured C example: grep 38 files, read ~33,000 tokens, and still miss indirect callers. This is a task-specific result, not a completeness guarantee for every repository.

There is no built-in LLM: your MCP client is the intelligence layer; this tool is the structural memory. Typical wins:

• Callers / callees / blast radius — trace_path, detect_changes follow indexed relationships across files. The counts are exact for stored edges, but event callbacks (such as JSX props) or partially parsed code may not be represented; verify coverage and source before relying on an empty trace.
• Architecture in one call — get_architecture: languages, packages, entry points, routes, hotspots, layers, community-detection clusters.
• Dead code, complexity hotspots, dependency graph, security-evidence graph — via query_graph (read-only Cypher subset).
• Memory across sessions — the graph persists; manage_adr persists architecture decisions beside it.

Performance

Measured on Apple M3 Pro (see docs/MEASURING.md to reproduce on your own workload):

Token efficiency (five structural queries on the same repo): ~3,400 tokens via the graph vs ~412,000 tokens via file-by-file exploration. A single-cause measurement recipe and the honest cost model (including the fixed per-session tool-list overhead) are documented in docs/MEASURING.md.

Documentation map

CLI mode

Every MCP tool also runs as a local one-shot command (no daemon, no standing process; stdout stays machine-clean):