sqlite-graph-memory 0.3.0__tar.gz → 0.3.2__tar.gz

{sqlite_graph_memory-0.3.0 → sqlite_graph_memory-0.3.2}/CHANGELOG.md

@@ -4,6 +4,68 @@ What shipped, in plain words. Entries below v0.1.3 were written on 2026-09-05 fr
 release notes that already existed — the file itself did not exist until then, so those three are
 recorded after the fact rather than backdated to look contemporaneous.
 
+## v0.3.2 — 2026-10-24
+
+**The PageRank lane the README credits is now in the package** (#51). `ppr.py` runs
+personalized PageRank over the `[[wikilink]]` graph, seeded by the dense hits, and fuses it with
+the reranker by RRF while the reranker's top 5 stay where they are. Off by default (`SGM_PPR=1`
+or `sgm-ask --ppr`); `eval/run_eval.py --ppr` scores it as its own mode. Any failure returns the
+reranker's order. `tests/test_ppr.py` builds a hub note that pushes the reranker's rank-1 hit to
+position 11 when the guard is removed, and goes red if it is.
+
+**`sgm-stats <notes_dir>`: four health numbers for the link graph.** Orphan rate, links per
+page, share of pages in the main connected component, and share of concept pages whose
+`updated` date is older than 90 days, each with an ok/warn/fail verdict and a `--threshold-*`
+flag. Exit code 0/1/2 for cron. Reuses the indexer's note filter and the recall wikilink parser,
+so it measures the graph recall walks. On `bench/vault`: 26.2% orphans (fail), 4.65 links per
+page, 100% in one component. `tests/test_vault_stats.py` crosses every threshold on a synthetic
+vault and goes red when inbound links stop being counted.
+
+**A spec you can paste.** `BITEMPORAL.md` turns the close-don't-delete rule from
+`docs/bitemporal.md` into a block for any agent's `CLAUDE.md` or `AGENTS.md`: three fields
+(`valid_from`, `valid_to`, `superseded_by`), five rules, and a one-line attribution as the
+whole licence.
+
+**`llms.txt` for agents that read before they install.** One page: what this is, the three
+commands, MCP config for JSON clients, Claude Code and Codex, the bench numbers as they stand
+on the leaderboard, the eval commands, every environment variable.
+
+**The README says what it is for in its first line**: persistent memory for Claude Code,
+Cursor and Codex over your own markdown notes.
+
+**One star request, earned and once.** After a successful `sgm-ask --ab` in a terminal, one
+stderr line asks for a GitHub star. It is printed once per machine (a marker file in
+`~/.config/sqlite-graph-memory`, or `SGM_CONFIG_DIR`, created exclusively so two first runs
+at once still print one line), never under `CI`, never when stdout or stderr is piped, never
+when `BRAIN_AB_JSON` is set, and never with `SGM_NO_STAR_PROMPT=1`. If the line cannot be
+written, the marker is removed so the next run asks again. `tests/test_star_prompt.py` covers
+each guard and the call from `main()`, and goes red when any of them is removed.
+
+## v0.3.1 — 2026-10-19
+
+**Credit where it is due.** The MCP server that ships as `sgm-mcp` was written by Vardhman Gupta
+([@Kaap10](https://github.com/Kaap10)) in PR #8: the server, its tests and its docs. His
+follow-up fixes are the shared answer-file race (commit 3ce7061), the stdout fallback (PR #10)
+and the swallowed read errors (PR #14).
+He is now listed in the `authors` field of `pyproject.toml`, which is the attribution he asked for.
+
+**Indexing works on Intel Macs again.** A fresh `pip install 'sqlite-graph-memory[embeddings]'`
+on an x86_64 Mac with Python 3.12 crashed `sgm-index` with `NameError: name 'nn' is not
+defined`. Torch stops at 2.2 there, transformers 5.x needs 2.6 and quietly disables torch,
+and sentence-transformers 6.x requires transformers 5.x. The embeddings extra now caps
+transformers below 4.50 and sentence-transformers below 5 on that one platform. Measured
+both ways on the same machine: 0.3.0 from PyPI crashes, this build indexes the 202-note
+bench vault cleanly (204 chunks).
+
+**Listed in the official MCP Registry.** `server.json` describes the server as
+`io.github.tonydzi/sqlite-graph-memory`, the README carries the `mcp-name` line the registry
+checks, and the publish workflow lists the release after PyPI has it. The package also
+installs the MCP server under its own name, `sqlite-graph-memory`, so registry clients can
+start it with `uvx`.
+
+**The README opens with three commands and their real output** on the bench vault, including
+the honest caveat that vector-only ranks ahead of graph mode on that vault overall.
+
 ## bench-v0.1 — 2026-10-09
 
 **A benchmark other people can run.** Until now every retrieval number in this repo came from
@@ -24,6 +86,8 @@ On this vault, vector-only ranks ahead of graph mode. All of it is written out i
 
 ## v0.3.0 — 2026-10-07
 
+*Release record, added 2026-10-16: the package went to PyPI on 2026-10-15 and this GitHub release object was cut a day later, so the tag points at a commit slightly after the upload (it adds only the workflow's `skip-existing` flag). Also in 0.3.0 as uploaded: the embeddings extra pins `numpy<2` on Intel Macs, where torch stops at 2.2.*
+
 **You can install it now.** For three months this was a repository you had to clone, and for
 an engineer deciding whether to try something, a clone is a much bigger ask than a command.
 There is now a `pyproject.toml`, the modules live in `src/sqlite_graph_memory/`, and

{sqlite_graph_memory-0.3.0 → sqlite_graph_memory-0.3.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: sqlite-graph-memory
-Version: 0.3.0
+Version: 0.3.2
 Summary: Associative memory for LLM agents: Graph RAG over a folder of markdown notes, in one SQLite file, with no server to run.
 Project-URL: Homepage, https://github.com/tonydzi/sqlite-graph-memory
 Project-URL: Repository, https://github.com/tonydzi/sqlite-graph-memory
 Project-URL: Changelog, https://github.com/tonydzi/sqlite-graph-memory/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/tonydzi/sqlite-graph-memory/issues
-Author: Anton Dziatkovskii
+Author: Anton Dziatkovskii, Vardhman Gupta
 License: MIT License
         
         Copyright (c) 2026 Palo Alto AI Research Lab
@@ -44,22 +44,81 @@ Requires-Python: >=3.9
 Requires-Dist: numpy>=1.24
 Provides-Extra: embeddings
 Requires-Dist: numpy<2; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'embeddings'
+Requires-Dist: sentence-transformers<5; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'embeddings'
 Requires-Dist: sentence-transformers>=2.6; extra == 'embeddings'
+Requires-Dist: transformers<4.50; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'embeddings'
 Description-Content-Type: text/markdown
 
-# sqlite-graph-memory
+# sqlite-graph-memory: persistent memory for Claude Code, Cursor and Codex over your own markdown notes
+
+<!-- mcp-name: io.github.tonydzi/sqlite-graph-memory -->
+
+[![PyPI](https://img.shields.io/pypi/v/sqlite-graph-memory)](https://pypi.org/project/sqlite-graph-memory/) [![tests](https://img.shields.io/github/actions/workflow/status/tonydzi/sqlite-graph-memory/tests.yml?label=tests)](https://github.com/tonydzi/sqlite-graph-memory/actions/workflows/tests.yml) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.tonydzi%2Fsqlite--graph--memory-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=sqlite-graph-memory) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Long-term memory for coding agents that lives in the notes you already keep: 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 —
-one SQLite file, no graph database, no ETL pass, no server.**
+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.**
+
+## Three commands
 
 ```bash
-pip install sqlite-graph-memory
+pip install 'sqlite-graph-memory[embeddings]'
+sgm-index ./notes
+sgm-ask --ab "In which programming language is the tool behind Project Ouzel written?"
 ```
 
-> The first PyPI release has not landed yet (the publish workflow is in place).
-> Until it does: `pip install git+https://github.com/tonydzi/sqlite-graph-memory`
-> — same package, same five commands.
+`./notes` is any folder of markdown notes. To get exactly the output below, use the
+202-note synthetic vault from this repo (it is not inside the pip package):
+
+```bash
+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](https://github.com/tonydzi/sqlite-graph-memory) 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/`](bench/README.md). `--ab`
+exists so you can measure which one wins on your own notes.
+
+**From any MCP client** (Claude Desktop, Cursor, Zed, Windsurf): `sgm-mcp` after the install
+above, or `uvx --with 'sqlite-graph-memory[embeddings]' sqlite-graph-memory`. Set
+`BRAIN_INDEX_DIR` to the `index` folder `sgm-index` wrote. Config:
+[`examples/mcp-config.json`](examples/mcp-config.json). Claude Code:
+`claude mcp add sqlite-graph-memory -e BRAIN_INDEX_DIR=/path/to/index -- sgm-mcp`.
+Codex: a `[mcp_servers.sqlite-graph-memory]` table in `~/.codex/config.toml` with
+`command = "sgm-mcp"`. Agents that read files first: [`llms.txt`](llms.txt).
+
+## 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
@@ -144,12 +203,13 @@ an edge table only when hop depth or corpus size demands it.
 
 - No entity lane. The production setup has an extra retrieval lane over people/project
   cards; it is too entangled with personal data to publish.
-- No incremental indexing and no packaging. There IS an eval suite now — see
+- No incremental indexing (tracked in the issues). Packaging exists since v0.3.0 (`pip install sqlite-graph-memory`). There IS an eval suite now — see
   [Measure before you swap](#measure-before-you-swap--eval) — but it scores retrieval on
   wikilink-derived gold, which is weak supervision and says so out loud. Test coverage is uneven:
-  `index_notes.py`, `brain_ask.py` and `mcp_server.py` have unit tests, `turnstate_hook.py`
-  has none. Run `pytest -q` for the current count rather than trusting a number written in
-  prose here — that is how this file ended up claiming "no tests" while seven were passing.
+  `index_notes.py`, `brain_ask.py` and `mcp_server.py` have unit tests, and
+  `turnstate_hook.py` has write-path coverage. Run `pytest -q` for the current count rather
+  than trusting a number written in prose here — that is how this file ended up claiming
+  "no tests" while seven were passing.
   The status line above says **pilot** on purpose.
 
 ## Quickstart
@@ -236,6 +296,26 @@ board with one adapter file and a pull request: [bench/CONTRIBUTING.md](bench/CO
 CI recomputes every submitted number from the per-question outputs, so a typed-in number
 cannot get onto the board.
 
+## Health check — `sgm-stats`
+
+Four numbers about the link graph itself, no model and no index needed. It reads the notes with
+the same filter and the same `[[wikilink]]` parser as recall, so it measures the graph `--graph`
+actually walks. Thresholds follow [second-brain-os metrics](https://github.com/undefined-ui/second-brain-os/blob/main/docs/05-graphs/metrics.md);
+each is a `--threshold-*` flag. Exit code 0 ok, 1 warn, 2 fail, so it can sit in cron.
+
+```text
+$ sgm-stats bench/vault --today 2026-10-20
+202 pages in bench/vault
+
+FAIL  orphan_rate       26.2%   53 of 202 pages have no inbound link
+OK    avg_degree         4.65   940 resolved links over 202 pages
+OK    main_component   100.0%   202 of 202 pages; 1 component
+WARN  stale_concepts   100.0%   12 of 12 concept pages older than 90 days (as of 2026-10-20)
+```
+
+The synthetic bench vault fails the orphan check for a plain reason: its 40 meeting and 12 decision notes link out and nothing
+links back to them. `--json` gives the same report with the first orphan and stale page names.
+
 ## Measure before you swap — `eval/`
 
 Every "obvious" upgrade to a RAG pipeline — a newer embedder, a stronger reranker, hybrid
@@ -297,6 +377,17 @@ of guessing — 97% of the correct `bridge` answers were *already in the candida
 cross-encoder was dropping them, because the relation is structural, not textual. Widening
 retrieval, the obvious fix, would have done nothing at all.
 
+That lane ships in the package as `src/sqlite_graph_memory/ppr.py`, **off by default**: turn it
+on with `SGM_PPR=1` or `sgm-ask --ppr`, and score it with `python eval/run_eval.py --gold ...
+--ppr`, which adds a third mode next to `vector` and `graph`. The numbers above were measured on
+the graph pool, so the matching command is `sgm-ask --graph --ppr`; `--ppr` alone reorders the
+vector pool, and `--ab` leaves the lane out so its A/B log stays vector against graph. Any failure in it falls back to
+the reranker's order, like the graph hop. Be clear about what that reproduces: the bridge
+numbers above came from the maintainer's home vault and home pipeline on 2026-09-16, and they
+have not been re-run from the published package. The code is the same algorithm with the same
+constants (alpha 0.85, 10 PPR files, top 5 protected), but your vault will give your numbers,
+and `bench/` does not score this lane yet.
+
 Seven other changes were rejected by the same ruler, under one rule fixed in advance:
 **a regression worse than 0.01 nDCG@12 on any class reverts the change.**
 
@@ -306,10 +397,10 @@ Seven other changes were rejected by the same ruler, under one rule fixed in adv
 | Qwen3-Embedding-0.6B | body Recall 0.767 -> 0.683; reindex 2863 s vs 333 s -> **rejected** |
 | bge-reranker-v2-m3 | −0.011…−0.018 nDCG on every class except English (+0.041) -> **rejected** |
 | Qwen3-Reranker-0.6B | title −0.111 nDCG at 12x the cost -> **rejected** |
-| BM25 + RRF hybrid | temporal −0.035 -> **merged switched off** |
+| BM25 + RRF hybrid | temporal −0.035 -> **merged switched off** (in the home pipeline, not in this package) |
 | heading-path prefix in every chunk | body −0.023, temporal −0.035 -> **reverted** |
 | `sqlite-vec` (vec0) | full scan 11.99 s vs 0.14 s for a plain SQLite table, and its ANN missed 1.2 hits of 60 -> vectors live in SQLite, **the extension does not** |
-| bi-temporal demotion of superseded notes | temporal +0.130 nDCG on a 41-question temporal set, but title −0.012 -> **merged behind a flag, default off** |
+| bi-temporal demotion of superseded notes | temporal +0.130 nDCG on a 41-question temporal set, but title −0.012 -> **merged behind a flag, default off** (in the home pipeline, not in this package) |
 
 None of those verdicts is a claim about the models. They are claims about *this corpus with
 this ruler*, which is the only kind of claim a swap decision actually needs — and the reason
@@ -331,7 +422,7 @@ while the metric is broken never tested the metric.
 
 ## Roadmap
 
-**Now — [v0.1.1](https://github.com/tonydzi/sqlite-graph-memory/releases).**
+**Now — [latest release](https://github.com/tonydzi/sqlite-graph-memory/releases/latest)** (v0.3.1 on PyPI and in the MCP Registry as of 2026-10-19).
 The pilot as it runs daily: retrieval pipeline, per-turn ledger and A/B telemetry, all in
 `brain_ask.py` and `turnstate_hook.py`, plus the bi-temporal design note. Known defects live in
 the [tracker](https://github.com/tonydzi/sqlite-graph-memory/issues) rather than in footnotes
@@ -369,9 +460,10 @@ Both are set as constants (`E5_MODEL`, `RERANK_MODEL`) in `brain_ask.py` and sma
 to run on a laptop GPU; swap freely, since nothing in the pipeline depends on these
 specific models.
 
-## Cite this work
+## Maintainers
 
-If this repo shows up in your research, cite it via [CITATION.cff](CITATION.cff) (GitHub's "Cite this repository" button). Academic identity: Anton Dzyatkovsky publishes as **Anton Dziatkovskii** ([ORCID 0000-0001-7408-3054](https://orcid.org/0000-0001-7408-3054)).
+- **Anton Dziatkovskii** ([@tonydzi](https://github.com/tonydzi)): retrieval pipeline, ledger, bench, releases.
+- **Vardhman Gupta** ([@Kaap10](https://github.com/Kaap10)): the MCP server (`sgm-mcp`, PRs #8, #10, #14) and its tests; reviews on `mcp_server.py` route to him via CODEOWNERS.
 
 ## AI contributors
 
@@ -383,7 +475,7 @@ content** — no decorative credits. Lab-wide policy, one source for every repo:
 
 ## Cite this work
 
-The paper about this system — retrieval design, pilot telemetry, and the query-class-stratified evaluation protocol — is published: [DOI 10.5281/zenodo.22639718](https://doi.org/10.5281/zenodo.22639718) (preprint, CC BY 4.0). Machine-readable citation: [CITATION.cff](CITATION.cff).
+The paper about this system — retrieval design, pilot telemetry, and the query-class-stratified evaluation protocol — is published: [DOI 10.5281/zenodo.22639718](https://doi.org/10.5281/zenodo.22639718) (preprint, CC BY 4.0). Machine-readable citation: [CITATION.cff](CITATION.cff) (GitHub's "Cite this repository" button). Academic identity: Anton Dzyatkovsky publishes as **Anton Dziatkovskii** ([ORCID 0000-0001-7408-3054](https://orcid.org/0000-0001-7408-3054)).
 
 ## License
 

{sqlite_graph_memory-0.3.0 → sqlite_graph_memory-0.3.2}/README.md

@@ -1,16 +1,73 @@
-# sqlite-graph-memory
+# sqlite-graph-memory: persistent memory for Claude Code, Cursor and Codex over your own markdown notes
+
+<!-- mcp-name: io.github.tonydzi/sqlite-graph-memory -->
+
+[![PyPI](https://img.shields.io/pypi/v/sqlite-graph-memory)](https://pypi.org/project/sqlite-graph-memory/) [![tests](https://img.shields.io/github/actions/workflow/status/tonydzi/sqlite-graph-memory/tests.yml?label=tests)](https://github.com/tonydzi/sqlite-graph-memory/actions/workflows/tests.yml) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.tonydzi%2Fsqlite--graph--memory-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=sqlite-graph-memory) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Long-term memory for coding agents that lives in the notes you already keep: 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 —
-one SQLite file, no graph database, no ETL pass, no server.**
+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.**
+
+## Three commands
 
 ```bash
-pip install sqlite-graph-memory
+pip install 'sqlite-graph-memory[embeddings]'
+sgm-index ./notes
+sgm-ask --ab "In which programming language is the tool behind Project Ouzel written?"
 ```
 
-> The first PyPI release has not landed yet (the publish workflow is in place).
-> Until it does: `pip install git+https://github.com/tonydzi/sqlite-graph-memory`
-> — same package, same five commands.
+`./notes` is any folder of markdown notes. To get exactly the output below, use the
+202-note synthetic vault from this repo (it is not inside the pip package):
+
+```bash
+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](https://github.com/tonydzi/sqlite-graph-memory) 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/`](bench/README.md). `--ab`
+exists so you can measure which one wins on your own notes.
+
+**From any MCP client** (Claude Desktop, Cursor, Zed, Windsurf): `sgm-mcp` after the install
+above, or `uvx --with 'sqlite-graph-memory[embeddings]' sqlite-graph-memory`. Set
+`BRAIN_INDEX_DIR` to the `index` folder `sgm-index` wrote. Config:
+[`examples/mcp-config.json`](examples/mcp-config.json). Claude Code:
+`claude mcp add sqlite-graph-memory -e BRAIN_INDEX_DIR=/path/to/index -- sgm-mcp`.
+Codex: a `[mcp_servers.sqlite-graph-memory]` table in `~/.codex/config.toml` with
+`command = "sgm-mcp"`. Agents that read files first: [`llms.txt`](llms.txt).
+
+## 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
@@ -95,12 +152,13 @@ an edge table only when hop depth or corpus size demands it.
 
 - No entity lane. The production setup has an extra retrieval lane over people/project
   cards; it is too entangled with personal data to publish.
-- No incremental indexing and no packaging. There IS an eval suite now — see
+- No incremental indexing (tracked in the issues). Packaging exists since v0.3.0 (`pip install sqlite-graph-memory`). There IS an eval suite now — see
   [Measure before you swap](#measure-before-you-swap--eval) — but it scores retrieval on
   wikilink-derived gold, which is weak supervision and says so out loud. Test coverage is uneven:
-  `index_notes.py`, `brain_ask.py` and `mcp_server.py` have unit tests, `turnstate_hook.py`
-  has none. Run `pytest -q` for the current count rather than trusting a number written in
-  prose here — that is how this file ended up claiming "no tests" while seven were passing.
+  `index_notes.py`, `brain_ask.py` and `mcp_server.py` have unit tests, and
+  `turnstate_hook.py` has write-path coverage. Run `pytest -q` for the current count rather
+  than trusting a number written in prose here — that is how this file ended up claiming
+  "no tests" while seven were passing.
   The status line above says **pilot** on purpose.
 
 ## Quickstart
@@ -187,6 +245,26 @@ board with one adapter file and a pull request: [bench/CONTRIBUTING.md](bench/CO
 CI recomputes every submitted number from the per-question outputs, so a typed-in number
 cannot get onto the board.
 
+## Health check — `sgm-stats`
+
+Four numbers about the link graph itself, no model and no index needed. It reads the notes with
+the same filter and the same `[[wikilink]]` parser as recall, so it measures the graph `--graph`
+actually walks. Thresholds follow [second-brain-os metrics](https://github.com/undefined-ui/second-brain-os/blob/main/docs/05-graphs/metrics.md);
+each is a `--threshold-*` flag. Exit code 0 ok, 1 warn, 2 fail, so it can sit in cron.
+
+```text
+$ sgm-stats bench/vault --today 2026-10-20
+202 pages in bench/vault
+
+FAIL  orphan_rate       26.2%   53 of 202 pages have no inbound link
+OK    avg_degree         4.65   940 resolved links over 202 pages
+OK    main_component   100.0%   202 of 202 pages; 1 component
+WARN  stale_concepts   100.0%   12 of 12 concept pages older than 90 days (as of 2026-10-20)
+```
+
+The synthetic bench vault fails the orphan check for a plain reason: its 40 meeting and 12 decision notes link out and nothing
+links back to them. `--json` gives the same report with the first orphan and stale page names.
+
 ## Measure before you swap — `eval/`
 
 Every "obvious" upgrade to a RAG pipeline — a newer embedder, a stronger reranker, hybrid
@@ -248,6 +326,17 @@ of guessing — 97% of the correct `bridge` answers were *already in the candida
 cross-encoder was dropping them, because the relation is structural, not textual. Widening
 retrieval, the obvious fix, would have done nothing at all.
 
+That lane ships in the package as `src/sqlite_graph_memory/ppr.py`, **off by default**: turn it
+on with `SGM_PPR=1` or `sgm-ask --ppr`, and score it with `python eval/run_eval.py --gold ...
+--ppr`, which adds a third mode next to `vector` and `graph`. The numbers above were measured on
+the graph pool, so the matching command is `sgm-ask --graph --ppr`; `--ppr` alone reorders the
+vector pool, and `--ab` leaves the lane out so its A/B log stays vector against graph. Any failure in it falls back to
+the reranker's order, like the graph hop. Be clear about what that reproduces: the bridge
+numbers above came from the maintainer's home vault and home pipeline on 2026-09-16, and they
+have not been re-run from the published package. The code is the same algorithm with the same
+constants (alpha 0.85, 10 PPR files, top 5 protected), but your vault will give your numbers,
+and `bench/` does not score this lane yet.
+
 Seven other changes were rejected by the same ruler, under one rule fixed in advance:
 **a regression worse than 0.01 nDCG@12 on any class reverts the change.**
 
@@ -257,10 +346,10 @@ Seven other changes were rejected by the same ruler, under one rule fixed in adv
 | Qwen3-Embedding-0.6B | body Recall 0.767 -> 0.683; reindex 2863 s vs 333 s -> **rejected** |
 | bge-reranker-v2-m3 | −0.011…−0.018 nDCG on every class except English (+0.041) -> **rejected** |
 | Qwen3-Reranker-0.6B | title −0.111 nDCG at 12x the cost -> **rejected** |
-| BM25 + RRF hybrid | temporal −0.035 -> **merged switched off** |
+| BM25 + RRF hybrid | temporal −0.035 -> **merged switched off** (in the home pipeline, not in this package) |
 | heading-path prefix in every chunk | body −0.023, temporal −0.035 -> **reverted** |
 | `sqlite-vec` (vec0) | full scan 11.99 s vs 0.14 s for a plain SQLite table, and its ANN missed 1.2 hits of 60 -> vectors live in SQLite, **the extension does not** |
-| bi-temporal demotion of superseded notes | temporal +0.130 nDCG on a 41-question temporal set, but title −0.012 -> **merged behind a flag, default off** |
+| bi-temporal demotion of superseded notes | temporal +0.130 nDCG on a 41-question temporal set, but title −0.012 -> **merged behind a flag, default off** (in the home pipeline, not in this package) |
 
 None of those verdicts is a claim about the models. They are claims about *this corpus with
 this ruler*, which is the only kind of claim a swap decision actually needs — and the reason
@@ -282,7 +371,7 @@ while the metric is broken never tested the metric.
 
 ## Roadmap
 
-**Now — [v0.1.1](https://github.com/tonydzi/sqlite-graph-memory/releases).**
+**Now — [latest release](https://github.com/tonydzi/sqlite-graph-memory/releases/latest)** (v0.3.1 on PyPI and in the MCP Registry as of 2026-10-19).
 The pilot as it runs daily: retrieval pipeline, per-turn ledger and A/B telemetry, all in
 `brain_ask.py` and `turnstate_hook.py`, plus the bi-temporal design note. Known defects live in
 the [tracker](https://github.com/tonydzi/sqlite-graph-memory/issues) rather than in footnotes
@@ -320,9 +409,10 @@ Both are set as constants (`E5_MODEL`, `RERANK_MODEL`) in `brain_ask.py` and sma
 to run on a laptop GPU; swap freely, since nothing in the pipeline depends on these
 specific models.
 
-## Cite this work
+## Maintainers
 
-If this repo shows up in your research, cite it via [CITATION.cff](CITATION.cff) (GitHub's "Cite this repository" button). Academic identity: Anton Dzyatkovsky publishes as **Anton Dziatkovskii** ([ORCID 0000-0001-7408-3054](https://orcid.org/0000-0001-7408-3054)).
+- **Anton Dziatkovskii** ([@tonydzi](https://github.com/tonydzi)): retrieval pipeline, ledger, bench, releases.
+- **Vardhman Gupta** ([@Kaap10](https://github.com/Kaap10)): the MCP server (`sgm-mcp`, PRs #8, #10, #14) and its tests; reviews on `mcp_server.py` route to him via CODEOWNERS.
 
 ## AI contributors
 
@@ -334,7 +424,7 @@ content** — no decorative credits. Lab-wide policy, one source for every repo:
 
 ## Cite this work
 
-The paper about this system — retrieval design, pilot telemetry, and the query-class-stratified evaluation protocol — is published: [DOI 10.5281/zenodo.22639718](https://doi.org/10.5281/zenodo.22639718) (preprint, CC BY 4.0). Machine-readable citation: [CITATION.cff](CITATION.cff).
+The paper about this system — retrieval design, pilot telemetry, and the query-class-stratified evaluation protocol — is published: [DOI 10.5281/zenodo.22639718](https://doi.org/10.5281/zenodo.22639718) (preprint, CC BY 4.0). Machine-readable citation: [CITATION.cff](CITATION.cff) (GitHub's "Cite this repository" button). Academic identity: Anton Dzyatkovsky publishes as **Anton Dziatkovskii** ([ORCID 0000-0001-7408-3054](https://orcid.org/0000-0001-7408-3054)).
 
 ## License
 

{sqlite_graph_memory-0.3.0 → sqlite_graph_memory-0.3.2}/eval/run_eval.py

@@ -9,6 +9,8 @@ Every question is scored twice, in both retrieval modes, on the same candidates
 
     vector   dense retrieve -> rerank            (what you get without the graph)
     graph    dense -> 1-hop [[wikilinks]] -> rerank
+    ppr      graph, then personalized PageRank fused with the reranker by RRF, top 5
+             protected (only with --ppr; see src/sqlite_graph_memory/ppr.py)
 
 The difference between those two columns is the only honest answer to "does the graph
 actually help?" — and on our own vault the answer differed by class (see README).
@@ -16,6 +18,7 @@ actually help?" — and on our own vault the answer differed by class (see READM
 USAGE
     python eval/run_eval.py --gold eval/gold-2026-09-16.jsonl
     python eval/run_eval.py --gold ... --limit 20        # smoke run
+    python eval/run_eval.py --gold ... --ppr             # add the PageRank lane as a 3rd mode
     python eval/run_eval.py --selftest                   # metrics only, no model, no index
 
 Config (env): BRAIN_INDEX_DIR (index to score), TURNSTATE_DB (where --sqlite appends a
@@ -119,8 +122,8 @@ def selftest():
 
 
 # ------------------------------------------------------------------ runner
-def score_gold(gold, progress=True):
-    """Run every question through both modes. -> (rows, config dict)."""
+def score_gold(gold, progress=True, ppr=False):
+    """Run every question through both modes (three with ppr=True). -> (rows, config dict)."""
     from sqlite_graph_memory import brain_ask as ba
 
     dev = ba.pick_device()
@@ -135,15 +138,26 @@ def score_gold(gold, progress=True):
     by_base = ba.index_by_basename(meta)
     stem_of = lambda i: Path(meta[i]['path']).stem.lower()
 
-    rows, t0 = [], time.time()
+    rows, t0, ppr_ran = [], time.time(), False
     for k, g in enumerate(gold):
         tq = time.time()
         sims = ba.query_sims(enc, emb, g['query'])
         base = ba.retrieve_candidates(sims, meta)
         added = ba.expand_1hop(sims, meta, base, by_base)
+        lists = {'vector': ba.rerank_candidates(ce, g['query'], base, meta)}
+        if ppr:
+            # One rerank of the graph pool serves both modes: `graph` is its top-12, exactly
+            # what rerank_candidates(topn=12) returns, and `ppr` fuses the FULL list.
+            full = ba.rerank_candidates(ce, g['query'], base + added, meta, topn=None)
+            lists['graph'] = full[:TOPN]
+            lane = ba.ppr_lane(meta, sims, base)
+            ppr_ran = ppr_ran or bool(lane)
+            lists['ppr'] = ba.fuse_ppr(full, meta, lane, TOPN)
+        else:
+            lists['graph'] = ba.rerank_candidates(ce, g['query'], base + added, meta)
         res = {}
-        for mode, cand in (('vector', base), ('graph', base + added)):
-            ranked = [stem_of(i) for i, _ in ba.rerank_candidates(ce, g['query'], cand, meta)]
+        for mode, scored in lists.items():
+            ranked = [stem_of(i) for i, _ in scored]
             res[mode] = {'ranked': ranked,
                          'recall': recall_at(ranked, g['gold']),
                          'mrr': mrr_at(ranked, g['gold']),
@@ -163,6 +177,11 @@ def score_gold(gold, progress=True):
         sys.stderr.write('!! the graph added no neighbours to ANY question — link resolution or '
                          'the index is broken, not the graph. The graph rows below are the '
                          'vector rows.\n')
+    # Same silence, PPR lane: an empty lane falls back to the reranker order, so the ppr rows
+    # would equal the graph rows and read as "PPR adds nothing" when it never ran.
+    if ppr and rows and not ppr_ran:
+        sys.stderr.write('!! the PPR lane returned no files for ANY question (no edges, or it '
+                         'failed). The ppr rows below are the graph rows.\n')
     return rows, cfg
 
 
@@ -173,7 +192,7 @@ def summarize(rows):
     groups += [('lang:' + lg, [r for r in rows if r['lang'] == lg]) for lg in ('ru', 'en')]
     for name, rs in groups:
         if not rs: continue
-        for mode in ('vector', 'graph'):
+        for mode in [m for m in ('vector', 'graph', 'ppr') if m in rs[0]['res']]:
             out[(name, mode)] = {'n': len(rs),
                                  'recall': sum(r['res'][mode]['recall'] for r in rs) / len(rs),
                                  'mrr': sum(r['res'][mode]['mrr'] for r in rs) / len(rs),
@@ -197,6 +216,9 @@ def print_table(summary, cfg, gold_file):
         if (name, 'graph') in summary:
             d = summary[(name, 'graph')]['ndcg'] - summary[(name, 'vector')]['ndcg']
             print('graph effect on %-9s nDCG@12 %+.3f' % (name, d))
+        if (name, 'ppr') in summary:
+            d = summary[(name, 'ppr')]['ndcg'] - summary[(name, 'graph')]['ndcg']
+            print('ppr effect on   %-9s nDCG@12 %+.3f  (vs graph)' % (name, d))
 
 
 def write_sqlite(summary, cfg, gold_file, scores_file):
@@ -232,6 +254,8 @@ def main():
     ap.add_argument('--out', help='scores .jsonl (default: eval/scores-<timestamp>.jsonl)')
     ap.add_argument('--sqlite', action='store_true', help='also append to gold_eval in TURNSTATE_DB')
     ap.add_argument('--no-persist', action='store_true', help='print the table, write nothing')
+    ap.add_argument('--ppr', action='store_true',
+                    help='also score the PageRank lane (graph + PPR/RRF, reranker top 5 protected)')
     ap.add_argument('--selftest', action='store_true', help='check the metrics and exit')
     a = ap.parse_args()
 
@@ -256,7 +280,7 @@ def main():
     if a.limit: gold = gold[:a.limit]
     if not gold: sys.exit('gold file %s is empty' % gold_path)
 
-    rows, cfg = score_gold(gold)
+    rows, cfg = score_gold(gold, ppr=a.ppr)
     summary = summarize(rows)
     print_table(summary, cfg, a.gold)
     if os.environ.get('EVAL_MUTANT') == '1':

{sqlite_graph_memory-0.3.0 → sqlite_graph_memory-0.3.2}/examples/README.md

@@ -47,19 +47,28 @@ Add the server to your MCP client config (e.g. `claude_desktop_config.json` or C
 {
   "mcpServers": {
     "sqlite-graph-memory": {
-      "command": "python",
-      "args": [
-        "/absolute/path/to/sqlite-graph-memory/sgm-mcp"
-      ],
+      "command": "sgm-mcp",
       "env": {
-        "BRAIN_INDEX_DIR": "/absolute/path/to/sqlite-graph-memory/index",
-        "TURNSTATE_DB": "/absolute/path/to/sqlite-graph-memory/turnstate.db"
+        "BRAIN_INDEX_DIR": "/path/to/your/index",
+        "TURNSTATE_DB": "/path/to/your/turnstate.db"
       }
     }
   }
 }
 ```
 
+The same file is checked in as [`mcp-config.json`](mcp-config.json). `sgm-mcp` is on PATH after `pip install 'sqlite-graph-memory[embeddings]'`; if your client does not inherit that venv, use the absolute path to its `bin/sgm-mcp`.
+
+Two copy-paste doors that need no JSON editing:
+
+```bash
+# Claude Code
+claude mcp add sqlite-graph-memory -e BRAIN_INDEX_DIR=/path/to/your/index -e TURNSTATE_DB=/path/to/your/turnstate.db -- sgm-mcp
+
+# any client that speaks uvx (registry name io.github.tonydzi/sqlite-graph-memory)
+uvx --with 'sqlite-graph-memory[embeddings]' sqlite-graph-memory
+```
+
 ### Direct CLI Verification
 
 You can verify the MCP server directly from the command line without launching an MCP client: