# Graft

> Local-first semantic cache for AI agents. A small C daemon + CLI that remembers what your agent learned across sessions. Plugs into Claude Code, Codex, Gemini CLI, and Claude Desktop / ChatGPT via MCP. No LLM calls, no SaaS, no API key.

- **Type:** MCP server
- **Install:** `agentstack add mcp-aendrix03-graft`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AEndrix03](https://agentstack.voostack.com/s/aendrix03)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [AEndrix03](https://github.com/AEndrix03)
- **Source:** https://github.com/AEndrix03/Graft

## Install

```sh
agentstack add mcp-aendrix03-graft
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

graft

Local-first agentic memory for AI coding agents.
Stop solving the same problems twice. Give Claude Code, Codex and any other agent a persistent memory
that survives sessions, context resets and machine switches — locally, with no cloud and no API key.

C11 · SQLite + sqlite-vec + FTS5 · llama.cpp + BGE-M3 · MessagePack · AF_UNIX socket · optional REST + 3D viewer

[](./LICENSE)
[](#project-status)
[](./docs/install/)
[](./docs/install/)
[](./docs/profiles/)
[](./docs/)

Made for Claude Code · Codex · ChatGPT · Claude Desktop · Gemini CLI · Open Code · and your own microservices.

---

## Why Graft?

AI coding agents are productive — but they forget everything when the session ends.

They forget:
- the root cause of that bug you debugged for three hours last week
- the architectural decision you made and _why_ you made it
- the Spring / Angular / Docker gotcha that bit you twice
- project-specific conventions that aren't in any README
- the dependency constraint that rules out a whole class of solutions

Every session starts from zero. Every fixed bug risks being re-debugged. Every decision risks being re-debated.

**Graft turns hard-won agent reasoning into reusable agentic memory.**

It is not a vector database, a RAG framework, or a chatbot platform. It is the smallest useful thing that makes your agent's knowledge survive its session — local-first, no SaaS, no API key, one binary, one SQLite file.

---

## Agentic memory, not a vector DB

Graft is shaped around how an **agent** writes and reads notes about its own work — not around how an application indexes a document corpus.

| Vector DB / RAG store          | Graft (agentic memory)                                     |
| ------------------------------ | ---------------------------------------------------------- |
| Index documents you already have | Capture decisions, gotchas, and root causes as an agent solves them |
| Query → top-k chunks            | Query → verified `STRONG` / `WEAK` / `MISS` with a single best answer |
| You decide what to ingest       | The agent decides what is worth remembering, in-loop       |
| Stateless reads                 | Edges + supersession track how knowledge evolves           |
| Library / managed service       | Local binary, single SQLite file, no SDK to bind to        |

If you need a vector DB, use a vector DB. Graft is for the layer above: **persistent reasoning the agent can build on**, not a search index over your files.

---

## Install in 30 seconds

```bash
brew tap AEndrix03/graft https://github.com/AEndrix03/Graft.git
brew install graft
graft stats
```

That's it. No daemon to start. No model to download by hand. No config to write.

> Not on macOS / Linux Homebrew? Run the cross-platform installer:
>
> ```bash
> git clone https://github.com/AEndrix03/graft.git && cd graft
> bash scripts/install.sh         # Linux, macOS, Windows MSYS2
> pwsh scripts/install.ps1        # Windows (auto-installs MSYS2 if needed)
> ```
>
> Optional GPU acceleration: `GRAFT_GPU=cuda bash scripts/install.sh` (NVIDIA CUDA) or `GRAFT_GPU=hip bash scripts/install.sh` (AMD ROCm 6 / 7). Builds are kept lightweight so contributors can iterate without long compile cycles.

Full installation reference: [`docs/install/`](./docs/install/).

---

## See it in action — 60 seconds

```console
$ graft query "spring boot validation cascade nested DTO"
{ "status": 0, "result": { "hit": "MISS" } }

# ... you debug the issue, find the answer ...

$ graft insert \
    --title "Spring Boot @Valid cascade on nested DTOs needs @Valid on the field plus @Validated on the controller" \
    --body  "Without @Valid on the nested field, constraints inside it are silently ignored. Tested on Spring Boot 3.2; matches the Jakarta Validation spec." \
    --keyword spring-boot --keyword validation --keyword gotcha
{ "status": 0, "result": { "id_hex": "019e09a95e7a...", "duplicate": false } }

# ... weeks later, on another machine, in another agent ...

$ graft query "why is my @Valid annotation not cascading on a nested DTO field"
{
  "status": 0,
  "result": {
    "hit":   "STRONG",
    "title": "Spring Boot @Valid cascade on nested DTOs needs @Valid on the field plus @Validated on the controller",
    "body":  "Without @Valid on the nested field, constraints inside it are silently ignored. ..."
  }
}
```

The two queries used **different phrasing**. The match is semantic plus lexical, gated by a verify step that **refuses to claim a hit when the signals are weak** — so your agent never quotes confidently-wrong answers.

---

## What you get

Each capability is labelled by maturity: **Stable** = shipped and used by the integrations; **Experimental** = wired up but rough edges or no benchmarks; **Vision** = a future direction, partially scaffolded at most.

#### Cache-first retrieval · *Stable*
`graft query ` returns `STRONG` / `WEAK` / `MISS`. STRONG injects title + body straight into the agent's context, so the agent does not have to choose between a list of candidates.

#### Hybrid search · *Stable*
`graft retrieve` fuses dense (BGE-M3 cosine) and lexical (BM25 over title and body) via Reciprocal Rank Fusion.

#### Graph walks · *Stable*
`graft explore` follows keyword and semantic edges with beam search and MMR diversity, decay `gamma^step`.

#### Multi-tenant profiles · *Stable*
Isolated DBs and sockets per profile (`work`, `personal`, project-scoped).
Import / export / merge as plain SQLite files.

#### Local-first · *Stable*
Single binary, single DB file, no network.
Models run on CPU out of the box; opt-in to CUDA or ROCm 6 / 7 with a build flag.

#### Optional REST + 3D viewer · *Experimental*
Flip a flag in `config.yaml`, get JSON endpoints and a browser-based graph explorer with click-to-edit (atomic supersession). API surface still evolving.

#### Agent integrations · *Stable*
Claude Code, Codex, and Open Code skills via `graft setup`; Claude Desktop / ChatGPT via MCP; Gemini CLI via `GEMINI.md`.

#### Microservice cache pattern · *Experimental*
Design pattern: L1 Redis + L2 graft semantic cache + L3 graft + LLM. Reference docs, no published benchmarks. [See the pattern](./docs/microservices/).

#### Remote / team memory · *Vision*
A shared memory store across machines or teammates is a planned direction, not a shipped feature. Today: per-machine local profiles, plus export / import / merge as SQLite files.

---

## Core concepts

| Term | What it means |
| ---- | ------------- |
| **Memory node** | A `title` (retrieval anchor) + `body` (full context) + keywords. The unit graft stores and retrieves. |
| **Profile** | An isolated memory space with its own DB and daemon. Switch with `GRAFT_PROFILE=name`. |
| **Semantic cache** | `graft query` — verified top-1 lookup. Returns STRONG, WEAK or MISS. No hallucinated hits. |
| **Graph edge** | Keyword or semantic link between nodes. Enables `graft explore` to walk connected knowledge. |
| **Supersession** | Replacing an outdated node while keeping the old one visible as `SUPERSEDED`. History stays, mistakes don't propagate. |
| **Confidence** | STRONG = both semantic similarity and lexical overlap pass the verify gate. WEAK = semantic signal only. |

Full glossary → [`docs/concepts.md`](./docs/concepts.md).

---

## Built for AI development tools

```text
┌─────────────────────────────┐    ┌─────────────────────────────┐
│ LLM chat clients            │    │ Coding agents (CLI-based)   │
│ Claude Desktop · ChatGPT    │    │ Claude Code · Codex · ...   │
└──────────────┬──────────────┘    └──────────────┬──────────────┘
               │ MCP (stdio or HTTPS)             │ subprocess
               ▼                                  ▼
┌─────────────────────────────┐    ┌─────────────────────────────┐
│ integrations/mcp-server/    │    │ graft CLI                   │
│  · server.py  (stdio)       │───▶│  → unix socket              │
│  · oauth_gateway.py (HTTP)  │    │                             │
└─────────────────────────────┘    └──────────────┬──────────────┘
                                                  ▼
                                     ┌─────────────────────────────┐
                                     │ graftd (daemon)             │
                                     │  SQLite + sqlite-vec + FTS5 │
                                     │  + BGE-M3 (llama.cpp)       │
                                     └─────────────────────────────┘
```

| Agent          | Integration               | Setup |
| -------------- | ------------------------- | ----- |
| Claude Code    | Skills                    | `graft setup claudecode` |
| Codex          | Skills                    | `graft setup codex` |
| Claude Desktop | MCP server (stdio)        | `integrations/claude-ai/claude_desktop_config.json` |
| ChatGPT        | MCP server (stdio or HTTP)| `integrations/chatgpt/mcp_config.json` |
| Gemini CLI     | `GEMINI.md` memory file   | `integrations/gemini-cli/` |
| Open Code      | Skills                    | `graft setup opencode` |

Each adapter ships **skills** that tell the model *when* to search and *when* to save. Hook and agent-instruction installers are currently kept out of `graft setup`; use the integration docs for manual wiring if needed.

Full integration matrix and setup: **[`docs/integrations/`](./docs/integrations/)**.

---

## Beyond agent tooling — a microservice cache pattern *(experimental)*

The same primitives that serve an agent (verified semantic cache + write-back) also slot in front of an LLM in a microservice. The pattern below is **a recommended design, not a benchmarked production stack** — share it with a back-end team that wants fewer LLM calls and is willing to validate it on their own workload:

```text
                       ┌──────────────────────────────┐
        ┌────────────► │  L1 — Redis                  │  exact key match
        │              │  cache:      │
        │              └──────────────┬───────────────┘
        │                  MISS       │
        │                             ▼
  Client                 ┌──────────────────────────────┐
   request ─────────────►│  L2 — graft semantic cache   │  paraphrase-aware,
        ▲                │  GET /v1/match?text=...      │  verified STRONG/WEAK/MISS
        │                └──────────────┬───────────────┘
        │                    MISS       │
        │                               ▼
        │                 ┌──────────────────────────────┐
        │                 │  L3 — graft + LLM            │  top-k retrieve +
        │                 │  GET /v1/search → LLM        │  LLM synthesis
        │                 │  POST /v1/insert (writeback) │  writeback for next time
        └─────────────────└──────────────────────────────┘
```

| Layer | What it answers | Cost shape |
| ----- | --------------- | ---------- |
| **L1** Redis              | "Have we seen *this exact prompt* before?"           | RAM bytes |
| **L2** graft semantic     | "Have we seen *a question that means this* before?"  | local CPU |
| **L3** graft + LLM        | "We haven't. Let me reason from related memories."   | LLM tokens |

The idea: L3 answers get written back through `POST /v1/insert`, so the next caller hits L2 instead of regenerating with the LLM. Real savings depend entirely on your traffic — there are no published benchmarks yet.

Full pattern, sample code, deployment shapes, and failure modes: **[`docs/microservices/`](./docs/microservices/)**.

---

## Try it now — a real round-trip

```bash
graft insert \
  --title "First memory" \
  --body  "If this is retrievable below, graft is wired correctly." \
  --keyword smoke-test

graft query "the very first thing I saved"
# → "hit": "STRONG" + the body you just inserted
```

If you see `"hit": "STRONG"`, your pipeline is healthy: BGE-M3 embedding ↔ `sqlite-vec` vector index ↔ FTS5 lexical ↔ multi-signal verifier are all talking to each other.

---

## Architecture in one diagram

```mermaid
flowchart LR
    subgraph Clients["AI clients"]
      A1["Claude Code"]
      A2["Codex"]
      A3["ChatGPT / Claude Desktop"]
      A4["Gemini CLI / Open Code"]
      A5["Your microservice"]
    end

    subgraph Adapters["Adapters (integrations/)"]
      S["Skills · optional AGENTS.md / Hooks"]
      M["MCP server (Python)"]
    end

    Browser["3D Viewer (browser)"]

    A1 --> S
    A2 --> S
    A4 --> S
    A3 --> M
    A5 -->|HTTPS / OAuth| M
    S --> CLI["graft (CLI)"]
    M --> CLI
    Browser -->|HTTP/JSON| Daemon
    CLI -->|AF_UNIX socketMessagePack| Daemon["graftd"]
    Daemon --> Storage[("SQLite + sqlite-vec + FTS5nodes · edges · keywords · vectors")]
    Daemon --> Embed["llama.cpp + BGE-M31024-dim embeddings"]
```

Pipelines:

- **insert** — `embed(title)` → upsert keywords → `vector_topk` per keyword (KEYWORD edges) → `vector_topk + MMR` (SEMANTIC edges) → **one atomic SQLite transaction**.
- **query** — `embed(text)` → `vector_topk(10)` → trigram-Jaccard + cosine (+ optional cross-encoder) verify → STRONG / WEAK / MISS gating.
- **retrieve** — three lists (vec, BM25 title, BM25 body) → RRF fusion → top-k.
- **explore** — seed via `vector_topk` filtered by keyword → beam search with MMR + decay `gamma^step`.

Full architecture: [`docs/architecture/`](./docs/architecture/).

---

## Documentation

Everything is broken down by feature. Each page ends with a **"What's missing and how to improve it"** section — pick one and open a PR.

| Folder | What's inside |
| ------ | ------------- |
| [`concepts.md`](./docs/concepts.md)             | Glossary: node, profile, semantic cache, edge, supersession, confidence. |
| [`use-cases.md`](./docs/use-cases.md)           | Concrete scenarios: coding agent memory, bug fix reuse, project decisions, team memory. |
| [`install/`](./docs/install/)                   | Homebrew, install scripts, manual build, GPU builds, first-run check. |
| [`release/`](./docs/release/)                   | Versioning, GitHub Releases, signed assets, SBOM, `graft upgrade`. |
| [`architecture/`](./docs/architecture/)         | CLI ↔ daemon split, wire protocol, request lifecycle. |
| [`cli/`](./docs/cli/)                           | Every `graft` / `graftd` subcommand and flag. |
| [`storage/`](./docs/storage/)                   | SQLite schema, sqlite-vec, FTS5, atomic supersession, idempotency, WAL. |
| [`embeddings/`](./docs/embeddings/)             | BGE-M3 (1024-dim), llama.cpp, CPU vs CUDA vs ROCm. |
| [`retrieval/`](./docs/retrieval/)               | `query` (cache), `retrieve` (RRF), `explore` (beam + MMR), the verify pipeline. |
| [`insert/`](./docs/insert/)                     | Insert pipeline, keyword / semantic edges, MMR diversity, content hashing, `classify`. |
| [`profiles/`](./docs/profiles/)                 | Multi-tenancy, per-profile DB + socket + daemon, export / import / merge / remote sync. |
| [`http-api/`](./docs/http-api/)                 | Optional REST layer, per-endpoint flags, examples. |
| [`viewer/`](./docs/viewer/)                     | Browser 3D viewer (Vue + three.js + CodeMirror), modes, edit-with-supersession. |
| [`integrations/`](./docs/integrations/)         | Per-agent adapters + MCP gateway. |
| [`microservices/`](./docs/microservices/)       | The L1 Redis + L2 graft + L3 graft + AI stack. |
| [`maintenance/`](./docs/maintenance/)           | `stats`, `consolidate`, usage log, `analytics`. |
| [`configuration/`](./docs/configuration/)       | Every key in `config.yaml`, every recognised environment variable. |

The full index lives at **[`docs/`](./docs/)**.

---

## Why graft, not _other-thing_?

Plenty of agent-memory projects exist (mem0, Letta, Zep, Cognee, Graphiti, ...). They're libraries you import into a Python app, or services you self-host with a database. Graft picks a different shape:

- **A binary, not a library.** The CLI is the contract. Any agent that can run a subprocess can use it — no Python runtime, no SDK version drift between client and server.
- **Daemon + AF_UN

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AEndrix03](https://github.com/AEndrix03)
- **Source:** [AEndrix03/Graft](https://github.com/AEndrix03/Graft)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aendrix03-graft
- Seller: https://agentstack.voostack.com/s/aendrix03
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.