git:20260801.649e0a2 to git:20260830.c409aab

# 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:

```bash

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.

If you touch retrieval, `--ab` is the honest way to show your change helps: it produces a measured

delta, not an opinion.

## Conventions

- **The graph is not materialized in SQL.** Edges are parsed from the notes at query time, bounded

to 1 hop and 40 neighbours. That keeps the graph in sync with the notes at zero maintenance cost.

Materializing an edge table is a real option — but only when hop depth or corpus size demands it,

and with the measurement that shows it.

- **The turn ledger costs zero tokens.** Anything that puts a model call in the hook path is

rejected on principle: it runs after *every* turn.

- Stdlib and boring SQL. One file, no ORM, no migrations framework.

- The indexer must ignore what is not a note: editor state, sync-conflict copies, versioned

backups. Silently indexing five copies of one file is a bug we have already had.

## Boundaries — what needs a human

- **Turning the pilot into a framework** — plugin systems, abstraction layers, a config format.

Open an issue; the answer is usually "not yet, and here is why".

- **Changing the embedding or reranker model.** It invalidates every existing index; needs a

measured before/after and a note in the README.

- **Schema changes** to `turns` or `ab_recall` — existing data lives in those tables.

## The deal

Your copyright stays yours, there is no CLA, and issues labelled `accepted` are free to take —

comment "claiming this". Full terms:

If an AI wrote your change, say so in the PR and confirm you ran it. Welcome here — we do it daily.

Unread generated code is the one thing that gets closed on sight.