sqlite-graph-memory 0.3.1__tar.gz → 0.3.3__tar.gz

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/CHANGELOG.md

@@ -4,7 +4,66 @@ 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.1 — unreleased
+## v0.3.3 — 2026-10-26
+
+**Hidden note files are skipped like hidden folders.** A note whose filename starts with a
+dot, such as `.ideas.md` or `.draft.md`, used to be indexed when it sat in the vault root or a
+visible folder, while the same file inside `.drafts/` was skipped. Now both are skipped, so
+after re-indexing those notes stop showing up in answers. `BRAIN_INDEX_HIDDEN=1` brings back
+the old behaviour and indexes hidden files and folders alike. `eval/build_gold.py` now walks the
+vault with the indexer's own filter, so it follows the same rule and the same variable instead
+of keeping its own copy (issue #25).
+
+**The MCP server works from a source checkout and finds your index where you launch it**
+(issue #24, reported by @Kaap10). `sgm-mcp` used to run the recall child with its working
+directory set to the package folder, so a relative `BRAIN_INDEX_DIR=index` resolved inside
+site-packages and your own index was never found; from a plain clone without `pip install -e`,
+`python src/sqlite_graph_memory/mcp_server.py --test` failed with ModuleNotFoundError. Recall now
+runs in the server's own working directory, and CI reproduces the user's launch: installed wheel,
+relative index, started from another directory.
+
+**A three-question feedback form.** "What were you trying to do, what broke, which machine": an
+issue template, a README section, and a link printed next to the missing-index error, because
+this project collects no telemetry and that form is how we learn what is missing.
+
+## 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

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlite-graph-memory
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -49,10 +49,16 @@ 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:
 vector search finds the entry points, the `[[wikilinks]]` you already wrote are the graph.
@@ -95,6 +101,11 @@ The answer lives in `tool-lanternfish` ("Lanternfish is written in Elixir"). The
 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.
@@ -102,7 +113,10 @@ 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).
+[`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
 
@@ -112,7 +126,7 @@ points, the `[[wikilinks]]` you already wrote by hand are the graph, and a cross
 reranks what the hop dragged in.
 SQLite is the only database ([`schema.sql`](src/sqlite_graph_memory/schema.sql)).
 
-Status: **pilot**, and the word is load-bearing: it runs daily in one real setup (a ~100k-note
+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](#whats-intentionally-missing), which is
 where the uneven test coverage is described.
@@ -189,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
@@ -237,7 +252,7 @@ present, and CPU works fine for small corpora.
 
 ### What `--ab` looks like
 
-Output of `brain_ask.py` with `--ab`, on a toy 4-note corpus (real runs use a ~100k-note vault):
+Output of `brain_ask.py` with `--ab`, on a toy 4-note corpus (real runs use an index of ~28k notes / ~93k chunks):
 
 ```
 A/B RECALL: how should agent memory work
@@ -281,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
@@ -342,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.**
 
@@ -351,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
@@ -376,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
@@ -414,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
 
@@ -428,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
 
@@ -444,6 +491,16 @@ Questions, war stories, or you want to run this on your own fleet:
 - 🌐 [palo-alto.ai](https://palo-alto.ai) · [Palo Alto AI Research Lab](https://github.com/tonydzi)
 - 🧪 **Engineers: want to test-drive this setup?** Message me — I hand out free starter seeds to engineers who test and report back.
 
+## Tell us what is missing
+
+You tried this on your own notes and something was missing or broke. That is the most useful
+thing anyone can tell us.
+
+- **You started and it did not work:** [open the 3-question form](https://github.com/tonydzi/sqlite-graph-memory/issues/new?template=feature_request.yml) (what you tried, what broke, which machine).
+- **Not sure it is a bug, or just an idea:** [Discussions → Ideas](https://github.com/tonydzi/sqlite-graph-memory/discussions/categories/ideas).
+
+Nothing in this package phones home. There is no telemetry, so we only know what you write to us.
+
 ## Contributors welcome — and there is a queue
 
 Issues labelled [`accepted`](https://github.com/tonydzi/sqlite-graph-memory/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/README.md

@@ -1,7 +1,13 @@
-# 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:
 vector search finds the entry points, the `[[wikilinks]]` you already wrote are the graph.
@@ -44,6 +50,11 @@ The answer lives in `tool-lanternfish` ("Lanternfish is written in Elixir"). The
 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.
@@ -51,7 +62,10 @@ 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).
+[`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
 
@@ -61,7 +75,7 @@ points, the `[[wikilinks]]` you already wrote by hand are the graph, and a cross
 reranks what the hop dragged in.
 SQLite is the only database ([`schema.sql`](src/sqlite_graph_memory/schema.sql)).
 
-Status: **pilot**, and the word is load-bearing: it runs daily in one real setup (a ~100k-note
+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](#whats-intentionally-missing), which is
 where the uneven test coverage is described.
@@ -138,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
@@ -186,7 +201,7 @@ present, and CPU works fine for small corpora.
 
 ### What `--ab` looks like
 
-Output of `brain_ask.py` with `--ab`, on a toy 4-note corpus (real runs use a ~100k-note vault):
+Output of `brain_ask.py` with `--ab`, on a toy 4-note corpus (real runs use an index of ~28k notes / ~93k chunks):
 
 ```
 A/B RECALL: how should agent memory work
@@ -230,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
@@ -291,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.**
 
@@ -300,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
@@ -325,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
@@ -363,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
 
@@ -377,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
 
@@ -393,6 +440,16 @@ Questions, war stories, or you want to run this on your own fleet:
 - 🌐 [palo-alto.ai](https://palo-alto.ai) · [Palo Alto AI Research Lab](https://github.com/tonydzi)
 - 🧪 **Engineers: want to test-drive this setup?** Message me — I hand out free starter seeds to engineers who test and report back.
 
+## Tell us what is missing
+
+You tried this on your own notes and something was missing or broke. That is the most useful
+thing anyone can tell us.
+
+- **You started and it did not work:** [open the 3-question form](https://github.com/tonydzi/sqlite-graph-memory/issues/new?template=feature_request.yml) (what you tried, what broke, which machine).
+- **Not sure it is a bug, or just an idea:** [Discussions → Ideas](https://github.com/tonydzi/sqlite-graph-memory/discussions/categories/ideas).
+
+Nothing in this package phones home. There is no telemetry, so we only know what you write to us.
+
 ## Contributors welcome — and there is a queue
 
 Issues labelled [`accepted`](https://github.com/tonydzi/sqlite-graph-memory/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/bench/README.md

@@ -140,7 +140,7 @@ has seen.
 
 ## Limits, stated up front
 
-- 202 notes is small. Dense retrieval at this size is easier than in a 100k-note vault,
+- 202 notes is small. Dense retrieval at this size is easier than in the ~28k-note production index,
   so the bench measures failure modes, and it does not show how a system scales.
 - The text is English only and comes from templates. The sentences are cleaner than real
   notes, and that flatters extractive systems.

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/eval/build_gold.py

@@ -40,6 +40,9 @@ import sys
 from collections import Counter
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'src'))
+from sqlite_graph_memory.index_notes import iter_notes  # noqa: E402
+
 WIKILINK_RX = re.compile(r'\[\[([^\]\|#]+)(?:[|#][^\]]*)?\]\]')
 CYRILLIC_RX = re.compile(r'[а-яё]', re.I)
 
@@ -121,10 +124,10 @@ def read_notes(notes_dir, stems, folders=None):
     """Every indexed note, parsed into the fields the four classes need."""
     root = Path(notes_dir)
     paths = []
-    for p in sorted(root.rglob('*.md')):
+    # The indexer's own walk: hidden files and dirs, conflict copies and BRAIN_INDEX_HIDDEN
+    # are decided in one place, so a gold answer is never a note the indexer would skip.
+    for p in iter_notes(root):
         rel = p.relative_to(root)
-        if any(part.startswith('.') for part in rel.parts[:-1]): continue
-        if 'sync-conflict' in p.name: continue
         if folders and (not rel.parts[:-1] or rel.parts[0] not in folders): continue
         if p.stem.lower() not in stems: continue
         paths.append(p)

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/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.1 → sqlite_graph_memory-0.3.3}/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:
@@ -100,7 +109,7 @@ All components share standard configuration variables:
 | `BRAIN_INDEX_DIR` | `./index` | Directory where `index_notes.py` writes and `brain_ask.py` reads `_brain_e5.npy` and metadata. |
 | `TURNSTATE_DB` | `./turnstate.db` | SQLite database holding per-turn ledger (`turns`) and A/B telemetry (`ab_recall`). |
 | `BRAIN_ANSWER_OUT` | `./_brain_answer.txt` | File where the formatted context bundle or answer is mirrored. |
-| `BRAIN_INDEX_HIDDEN` | `0` | If `1`, indexes hidden dot-directories too (by default skipped). |
+| `BRAIN_INDEX_HIDDEN` | `0` | If `1`, indexes hidden dot-files (`.draft.md`) and dot-directories too (by default both are skipped). |
 | `BRAIN_AB_JSON` | `None` | If set, `--ab` mode writes a structured JSON diff to this file path. |
 | `AB_SOURCE` | `work` | Telemetry label written to `ab_recall.source` (`work`, `eval`, etc.). |
 

{sqlite_graph_memory-0.3.1 → sqlite_graph_memory-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlite-graph-memory"
-version = "0.3.1"
+version = "0.3.3"
 description = "Associative memory for LLM agents: Graph RAG over a folder of markdown notes, in one SQLite file, with no server to run."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -68,6 +68,7 @@ Issues = "https://github.com/tonydzi/sqlite-graph-memory/issues"
 [project.scripts]
 sgm-index = "sqlite_graph_memory.index_notes:main"
 sgm-ask = "sqlite_graph_memory.brain_ask:main"
+sgm-stats = "sqlite_graph_memory.vault_stats:main"
 sgm-turnstate-hook = "sqlite_graph_memory.turnstate_hook:main"
 sgm-turnstate-show = "sqlite_graph_memory.turnstate_show:main"
 sgm-mcp = "sqlite_graph_memory.mcp_server:main"