sqlite-graph-memory

sqlite-graph-memory: persistent memory for Claude Code, Cursor and Codex over your own markdown notes

Your coding agent remembers what you already wrote down, and reaches the note a plain search misses by following the links between your notes. It is an MCP server and a CLI over any folder of markdown, Obsidian vaults included: pip install, point it at the folder, and Claude Code, Cursor, Codex or any other MCP client can recall from it.

Your agent forgets everything between sessions, and plain vector search gives it back flat, unrelated chunks. This gives it associative recall over your own markdown notes: vector search finds the entry points, the `[[wikilinks]]` you already wrote are the graph. One SQLite file, no graph database, no ETL pass, no server.

Install in your client

Already using your own agent rules and projects? The Russian existing-setup guide combines this memory backend with the optional starter-kit method, preserves existing settings, and checks recall in a fresh chat. Install one memory connection per client; the starter-kit memory plugin and manual registration are alternatives.

Build the index once (any folder of markdown; uv gives you uvx):

BRAIN_INDEX_DIR=$HOME/.sgm-index uvx --python 3.12 --from 'sqlite-graph-memory[lite]' sgm-index ~/notes

--python 3.12 is deliberate. onnxruntime has no wheels for Python 3.14 on an Intel Mac, or on Apple Silicon below macOS 14. On such a machine an unpinned uvx falls back to release 0.3.5, which has no [lite], and sgm-index then stops and asks for [embeddings].

Then point your client at the server. Use the absolute path of that index folder.

Cold-start timeout (0.3.5 and later). The MCP server starts recall in a separate process with a default deadline of 180 seconds; a first call on a clean Windows install took 89 s, which the old fixed 60 s always cut off. Override with BRAIN_RECALL_TIMEOUT (integer seconds, 1 to 600; invalid values return an error). Your MCP client's own tool timeout must also allow the longer call. On 0.3.3 and earlier the deadline is a fixed 60 s: upgrade, or use sgm-ask --ask directly, and do not report MCP recall as verified merely because the CLI works.

Claude Code

claude mcp add sqlite-graph-memory -e BRAIN_INDEX_DIR=$HOME/.sgm-index -- uvx --python 3.12 --with 'sqlite-graph-memory[lite]' sqlite-graph-memory

Cursor (~/.cursor/mcp.json; Claude Desktop, Zed and Windsurf take the same mcpServers block)

{

"mcpServers": { "sqlite-graph-memory": { "command": "uvx", "args": ["--python", "3.12", "--with", "sqlite-graph-memory[lite]", "sqlite-graph-memory"], "env": { "BRAIN_INDEX_DIR": "/absolute/path/to/.sgm-index" } } } }

VS Code (.vscode/mcp.json in the workspace)

{

"servers": { "sqlite-graph-memory": { "type": "stdio", "command": "uvx", "args": ["--python", "3.12", "--with", "sqlite-graph-memory[lite]", "sqlite-graph-memory"], "env": { "BRAIN_INDEX_DIR": "/absolute/path/to/.sgm-index" } } } }

Codex (~/.codex/config.toml)

[mcp_servers.sqlite-graph-memory]

command = "uvx" args = ["--python", "3.12", "--with", "sqlite-graph-memory[lite]", "sqlite-graph-memory"] env = { BRAIN_INDEX_DIR = "/absolute/path/to/.sgm-index" }

Size, du -sh of a fresh Python 3.12 venv on an x86_64 Mac (1 Nov 2026): the base install is 26 MB and has no torch (numpy only, enough for the graph half and the SQLite ledger); with [embeddings] (torch) it is 879 MB, 540 MB of that torch 2.2.2 CPU. With [lite], the same two models on ONNX Runtime and no torch, it is 155 MB (Windows, Python 3.12, 3 Nov 2026), installs in 12 s, and one MCP recall on the 202-note bench vault took 7.0 s against 33.8 s through torch on the same machine, with the same top hits and scores. [lite] is picked automatically when installed; SGM_BACKEND=torch forces torch (for a GPU). An index built by either backend is searched correctly by the other. Already installed with pip? Replace uvx --python 3.12 --with ... sqlite-graph-memory by sgm-mcp (examples/mcp-config.json). Agents that read files first: llms.txt.

Three commands

pip install 'sqlite-graph-memory[lite]'

sgm-index ./notes sgm-ask --ab "In which programming language is the tool behind Project Ouzel written?"

On an Intel Mac, use Python 3.12 with pip install. On a newer Python it can quietly install 0.3.5, which has no [lite].

./notes is any folder of markdown notes. Re-running sgm-index only re-embeds notes that are new or changed since the last run (tracked by a manifest next to the index); pass --full to force a complete rebuild.

To get exactly the output below, use the 202-note synthetic vault from this repo (it is not inside the pip package):

git clone --depth 1 https://github.com/tonydzi/sqlite-graph-memory && cp -R sqlite-graph-memory/bench/vault ./notes

Real output, top 5 of 12:

--- DIRECT memory (vector) ---

1. [ 1.66] project-ouzel
2. [ -1.33] project-avocet
3. [ -1.79] tool-cobbleset
4. [ -2.44] meeting-2025-10-21-lighthouse-sync
5. [ -2.70] person-severin-ibarrondo

--- ASSOCIATIVE memory (vector+graph) ---

1. [ 1.66] project-ouzel
2. [ 1.14] tool-lanternfish <== +graph
3. [ -1.33] project-avocet
4. [ -1.79] tool-cobbleset
5. [ -2.44] meeting-2025-10-21-lighthouse-sync

The answer lives in tool-lanternfish ("Lanternfish is written in Elixir"). The question never names Lanternfish, so the vector pass does not find it in the top 12 at all. project-ouzel links to it, so one graph hop puts it second.

If that hop found something your vector search missed, a star is how other people with a notes folder find this repo. sgm-ask --ab asks the same once per machine, in a terminal only; SGM_NO_STAR_PROMPT=1 turns it off.

That is the idea in one query, and it is not a blanket win. On this same vault vector-only ranks ahead of graph mode overall; the numbers are in bench/. --ab exists so you can measure which one wins on your own notes.

What it is

Graph RAG on SQLite for AI agents — a working pilot, not a framework. It is the extracted memory layer of a personal "second brain" agent setup: vector search finds the entry points, the [[wikilinks]] you already wrote by hand are the graph, and dense similarity orders what the hop dragged in (a cross-encoder rerank is opt-in with --rerank; see below for why it is no longer the default). SQLite is the only database (schema.sql).

Status: pilot, and the word is load-bearing: it runs daily in one real setup (an index of ~28k curated notes, ~93k chunks, rebuilt nightly from a ~270k-file Obsidian vault driven by Claude Code), but it is deliberately minimal and makes no attempt to be general — see What's intentionally missing, which is where the uneven test coverage is described. Published as the companion code for an upcoming write-up on lightweight Graph RAG for agents; the one design note that is already written is docs/bitemporal.md.

Why

Most Graph RAG stacks assume a graph database, an ETL pipeline, and an entity-extraction pass — HippoRAG (arXiv:2405.14831) derives its KG that way, and Graphiti/Zep maintain a temporal one. For a single-user agent over a markdown knowledge base, all three are overkill:

• The graph already exists — Obsidian/Logseq/plain-markdown users hand-curate their edges as [[wikilinks]], and brain_ask.py just parses them. No extraction pass, and edge quality beats anything a model would mine.
• SQLite is enough — the only things worth persisting are derived state (a per-turn ledger) and telemetry, and both are defined in schema.sql. One file, stdlib driver, zero ops.
• Measure before adding a stage. The pilot shipped a cross-encoder reranker from day one; measured later, it lowered recall on long queries (our 184-question gold set: body nDCG@12 0.640 reranked vs 0.815 dense; DolphinBench Riley slice, 1000 sessions: R@5 0.48 vs 0.61). Since 0.3.7 it is off by default and stays available as --rerank / SGM_RERANK=1.

So the pilot's bet: *vector retrieval for entry points, hand-curated wikilinks for association, SQLite for everything that must persist.* All steps live in one file, brain_ask.py, in that order.

Architecture

Three layers, three failure-isolated components:

markdown notes (with [[wikilinks]])

│ ├── index_notes.py chunk + embed (e5-base) → .npy/.pkl index │ ├── brain_ask.py recall pipeline: │ 1. dense retrieve top-60 chunks, dedup by file │ 2. --graph +1-hop wikilink neighbours of top-15 hits (max 40) │ 3. order dense similarity → top-12 │ (--rerank: cross-encoder instead, opt-in) │ 4. --ab run vector-only AND vector+graph, diff, │ log the delta to SQLite (ab_recall) │ └── turnstate_hook.py agent Stop-hook: after every assistant turn, parse the transcript tail and append one row (ask, summary, files, tools, commands, decisions) to SQLite (turns). 0 LLM tokens, pure stdlib. turnstate_show.py = read-only viewer.

schema.sql documents both tables. The graph is not materialized in SQL: brain_ask.py parses edges from the notes at query time, bounded to 1 hop / 40 neighbours. That keeps the graph permanently in sync with the notes at zero maintenance cost; materialize an edge table only when hop depth or corpus size demands it.

Design choices that survived contact with reality

• Graph expansion is candidate generation, not ranking (brain_ask.py). Neighbours go into the same ranking pool as vector hits, so an irrelevant linked note gets buried. That is what makes 1-hop expansion safe to leave on.
• Entity gate (looks_like_entity in brain_ask.py). A/B telemetry showed graph expansion helps *theme* queries ("approaches to agent memory") but hurts *name/tool* lookups ("NotebookLM"): a name's card links to everything, so the hop pulls in noise. The heuristic in brain_ask.py is deliberately conservative, and switches the graph off only for name-shaped queries.
• Crash-safety as a policy. The graph hop (brain_ask.py) and the Stop-hook (turnstate_hook.py) are both wrapped, so any failure degrades to the previous behavior: vector-only recall, no ledger row. A memory layer must never make the agent worse than having no memory layer.
• **Measure, do