sqlite-graph-memory AGENTS.md

AGENTS.md — working in this repo

Written for AI coding agents, and equally readable by a human contributor. Short on purpose.

What this repo is

The extracted memory layer of a personal second-brain agent setup: vector retrieval for entry points, hand-curated [[wikilinks]] for association, a cross-encoder rerank, and SQLite for the only two things worth persisting — a per-turn ledger and A/B telemetry.

Status: pilot. It runs daily in one real setup and it is deliberately minimal. It is not a framework and should not grow into one. The interesting claim here is what it does not need: no graph database, no ETL, no entity-extraction pass.

Stack and layout

• Python + SQLite (stdlib driver). requirements.txt covers the embedding/rerank models only.
• index_notes.py — chunk + embed a markdown folder (e5-base) into a .npy/.pkl index.
• brain_ask.py — the recall pipeline: dense retrieve → optional --graph 1-hop wikilink expansion → cross-encoder rerank → top-12. --ab runs vector-only and vector+graph, diffs them, and logs the delta to SQLite.
• turnstate_hook.py — agent Stop-hook; appends one row per assistant turn. Zero tokens, pure stdlib. turnstate_show.py is the read-only viewer.
• schema.sql — documents both tables (turns, ab_recall).
• examples/claude-code-stop-hook.json — how the hook gets wired.

How to verify a change

There is no test suite yet — that is a known gap with an open issue, and closing it is welcome work. Until then, a change is verified by running it and pasting the output:

python index_notes.py <folder-of-markdown>     # build an index over a small sample
python brain_ask.py "<question>" --graph       # recall, with graph expansion
python brain_ask.py "<question>" --ab          # both arms + the logged delta
python turnstate_show.py                       # what the ledger captured

Use a synthetic notes folder — five or six files with a couple of [[wikilinks]] between them is enough to show a behaviour change. Never paste real notes into an issue or PR.