This is the developer reference for graft, the local-first agentic memory layer for AI coding agents. Each section is a feature folder; open the one you care about.
If you are new to graft, start with concepts and use cases — they explain the mental model without C internals.
If you only want to try graft, jump to install/ and you'll be running in under a minute.
If you want to embed graft in your own service stack, read microservices/ first — that's the canonical L1 / L2 / L3 caching pattern.
If you want to understand the internals, start with architecture/ and follow the diagram.
| Page / Folder | What's inside |
|---|---|
concepts.md |
Mental model: node, profile, semantic cache, edge, supersession, confidence, local-first. |
use-cases.md |
Concrete workflows: coding agent memory, bug fix reuse, architectural decisions, team memory. |
install/ |
Homebrew, install scripts, manual build, GPU builds, first-run check. |
release/ |
Versioning, GitHub Releases, signed assets, SBOM, graft upgrade. |
architecture/ |
CLI ↔ daemon split, the wire protocol, the request/response lifecycle. |
cli/ |
Every graft / graftd subcommand and flag, with examples. |
storage/ |
SQLite schema, sqlite-vec, FTS5, atomic supersession, idempotency, WAL. |
embeddings/ |
BGE-M3 (1024-dim), llama.cpp, threading, CPU vs CUDA vs ROCm. |
retrieval/ |
query (cache lookup), retrieve (RRF), explore (beam + MMR), the verify pipeline. |
insert/ |
Insert pipeline, keyword / semantic edge construction, MMR diversity, content hashing, classify. |
profiles/ |
Multi-tenancy, per-profile DB + socket + daemon, export / import / merge / remote sync. |
http-api/ |
Optional REST layer, per-endpoint flags, response envelope, examples. |
viewer/ |
Browser 3D viewer (Vue + three.js + CodeMirror), build, modes, edit-with-supersession. |
integrations/ |
Claude Code, Codex, Claude Desktop, ChatGPT, Gemini CLI, Open Code, MCP / OAuth gateway. |
microservices/ |
The L1 Redis + L2 graft semantic + L3 graft + AI agentic stack. Read this before embedding graft. |
maintenance/ |
stats, consolidate, the usage log, analytics, what to run when. |
configuration/ |
Every key in config.yaml, every recognised environment variable, defaults table. |
| File | Status |
|---|---|
HTTP-API.md |
Superseded by http-api/. Kept for backward-compatible links. |
Homebrew.md |
Superseded by install/. Kept for backward-compatible links. |
- Inline checkboxes show stable / experimental / planned state.
- ✅ stable — covered by tests, used by integrations, safe to depend on.
- 🟡 experimental — works end-to-end but the API or the threshold defaults may change.
- 🟠 planned — wiring is in place, but the implementation is a stub. See the "What's missing" section of the relevant page.
- Code samples assume
graftis inPATH. The daemon (graftd) auto-starts on the first CLI call. - Where examples show JSON, that's the same JSON-ish format the CLI prints (a deterministic pretty-print of the MessagePack response).
Each page ends with a "What's missing and how to improve it" section that lists known gaps and TODOs. Pick one. Open a PR with the change plus a short note in CONTRIBUTING.md if the change is non-trivial. PRs are very welcome — graft is alpha and the docs are the friendliest place to start.