grag

Local graph memory for AI agents. Keep code structure, documents and decisions in a project knowledge graph that your agent can query and update across sessions.

Documentation · Getting started · PyPI · DeepWiki

grag combines an embedded LadybugDB database with MCP tools, full-text search and optional vector retrieval. It returns source citations and connected context under a configurable budget. The package is gragdb; the command and Python import are grag.

Start with your project

Python 3.10–3.14. Use a stable CLI installation so the launcher survives changes to your project's virtual environment:

pipx install 'gragdb[code]'
cd your-project
grag init

uv tool install 'gragdb[code]' or pip install 'gragdb[code]' also works. The code extra enables non-Python parsers; plain gragdb can index Python.

Restart your MCP client, then ask:

Index this project's source directory with grag. Show me where the authentication functions are defined, with file and line citations.

Remember why we chose this authentication approach, with its source, and link the decision to the relevant code.

init supports Claude Code, Cursor, Windsurf and Zed. Use --client claude or --client cursor to select explicitly. It saves the checkout's database and port, installs agent guidance, and configures a shared server that starts on first use. grag status shows its address and log; grag stop shuts it down cleanly.

grag init --ingest also indexes immediately. Scanning honors .gitignore and .gragignore, and skips nested repositories/worktrees and symlinks. Choose the intended roots; see scope and language coverage.

Windows: grag 0.9.0+ Windows x64 wheels include the required OpenSSL DLLs. Some agent harnesses require starting the shared server in a separate terminal. The Windows installation notes cover that case, source builds and offline readiness checks.

What it helps with

• Find code structure: definitions, signatures and line ranges, with supported import/call relationships. Source bodies stay in your files.
• Keep project memory: agents save decisions, tasks and evidence, and can preserve correction history when updating them.
• Connect documents and code: index Markdown sections and link mentioned symbols.
• Retrieve focused context: BM25 search, optional embeddings, graph expansion, citations and explicit truncation. Budgets use a byte-based token estimate.
• Share across harnesses: Claude Code and Cursor can use one database through one owning server. New worktrees get separate databases by default.
• Preserve continuity: consistent backups retain authored history and retry receipts, with verified restore into a separate database.

Code coverage varies. Python, JS/TS and Go support conservative static relationships; framework scripts and Java/C# overload identities also have explicit coverage. See language coverage. An absent edge does not prove no relationship exists. grag complements source search; useful answers and token savings depend on the question, graph and harness.

Local by default

The default install uses BM25 without an embedding service. Graph storage and retrieval run locally. Native extensions and optional grammars/models can require first-use downloads; prepare those assets before offline use. Your agent harness may send retrieved context to its model provider.

Local embeddings are optional through gragdb[embed-local] and ONNX Runtime. Installing that extra makes a later init configure them automatically; model preparation costs time, disk and memory. The optional remote provider sends embedding input to its configured endpoint.

Go deeper

The maintained documentation lives in docs/ and publishes to GitHub Pages, including the maintained architecture guide. DeepWiki is a supplementary, generated architecture guide; check its displayed source commit and indexing date before relying on it.

MIT license.