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.
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 inituv 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.
- 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.
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.
| Task | Guide |
|---|---|
| Understand the components and data flow | Architecture |
| Install and verify a first session | Getting started |
| Index code or documents | Code · Documents |
| Save, revise and retrieve evidence | Memory · Retrieval |
| Connect multiple clients or move a checkout | Servers · Projects |
| Diagnose startup, locks or recovery | Troubleshooting · Recovery |
| Configure tools and resource limits | MCP · Configuration · Limits |
| Develop and measure grag | Development · Contributing |
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.