loop-memory 0.4.18__tar.gz → 0.4.20__tar.gz

{loop_memory-0.4.18 → loop_memory-0.4.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.18
+Version: 0.4.20
 Summary: A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI.
 Author: Loop Memory contributors <loop-memory@users.noreply.github.com>
 License-Expression: MIT
@@ -34,6 +34,7 @@ Provides-Extra: dev
 Requires-Dist: pytest~=8.0; extra == "dev"
 Requires-Dist: coverage~=7.0; extra == "dev"
 Requires-Dist: ruff~=0.5; extra == "dev"
+Requires-Dist: build~=1.2; extra == "dev"
 Provides-Extra: all
 Requires-Dist: openai~=1.30; extra == "all"
 Requires-Dist: chromadb~=0.4; extra == "all"
@@ -66,6 +67,10 @@ Dynamic: license-file
 
 ---
 
+> **What's new in 0.4.20** — **the packaging test works on the oldest supported Python** (audit 2026-11-01, patch follow-up to 0.4.19). The 0.4.19 packaging test parsed `pyproject.toml` with `tomllib`, which is stdlib only from Python **3.11** onwards, while the project declares `requires-python = ">=3.10"` — so the 3.10 CI job failed with `ModuleNotFoundError: No module named 'tomllib'` while 3.11 and 3.12 passed, the classic shape of a bug that only bites the oldest supported interpreter. The check now reads the `[tool.setuptools.package-data]` table directly (it is a flat mapping of package name to a list of glob strings), and a new case runs it in a subprocess with `tomllib` blocked at the import system level, so the 3.10 path is exercised on every version rather than only on the 3.10 runner. No behaviour change — the 0.4.19 distribution is unchanged and correct. 1 new regression case; suite at **1004 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0420---2026-11-01)
+
+> **What's new in 0.4.19** — **the PyPI wheel now ships the whole dashboard and the benchmark fixture** (audit 2026-11-01, packaging follow-up to 0.4.18). The 0.4.18 wheel contained exactly two data files — `loop_memory/py.typed` and `loop_memory/serve/static/index.html` — because the package-data declaration was `loop_memory = ["py.typed", "serve/static/*.html"]`, and that glob is **not recursive**. Every CSS, JavaScript, i18n and image asset and the new benchmark fixture were **missing from the distribution**. Reproduced against the published wheel: `pip install loop-memory` started a server whose `GET /` returned `200` but whose `GET /static/js/main.js` and `GET /static/css/app.css` both returned **404** — a blank dashboard — and `loop-memory bench` crashed with `FileNotFoundError` on the packaged fixture. The declaration is now per package with recursive globs (`"loop_memory.serve.static" = ["**/*.html", "**/*.css", "**/*.js", "**/*.json", "**/*.svg"]`, `"loop_memory.bench" = ["fixtures/*.json"]`), so a new asset is picked up without anyone remembering to extend it, and the wheel contains all 32 non-Python files in the package tree. A new packaging test builds the real wheel and sdist **from a pristine source copy** — setuptools caches its file list in `egg-info/SOURCES.txt` and packages a stale `build/lib`, so building in the working tree would make the test pass for the wrong reason — and asserts every non-Python file actually reaches the distribution, then unpacks the wheel and runs the benchmark out of it. 8 new regression cases; suite at **1003 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0419---2026-11-01)
+
 > **What's new in 0.4.18** — **the BM25 channel no longer publishes a score that collapses to zero, and there is finally a benchmark that measures it** (audit 2026-11-01, weekly ecosystem sync). SQLite's FTS5 `bm25()` computes the classic idf `log((N - n + 0.5) / (n + 0.5))` and **clamps every non-positive idf to `1e-6`** — so a query term present in 49 % of the corpus keeps a real idf while one present in 51 % has its weight annihilated, a factor of ~40 000 between two almost equally discriminative terms. With the `trigram` tokenizer that is the *normal* case for CJK (`知识图` alone occurs in more than half of any knowledge-graph-heavy corpus), and the visible symptom was the 0.4.15 evidence chain reporting **`bm25: 0.0`** — "this hit because bm25 0.0". The published score is now a textbook BM25 (`k1 = 1.2`, `b = 0.75`) with the Lucene / BM25+ idf `log(1 + (N - n + 0.5) / (n + 0.5))`, which is strictly positive for every term, so the scale cannot collapse. **A document that contains the query verbatim now outranks one that merely contains the same scattered trigrams** — the transferable half of `rohitg00/agentmemory` v0.9.31's prefix-score fix (2026-10-26: strict recall-all@5 **65.74 % → 84.68 %**, +18.94 pp), whose release note is careful to call its numbers "component retrieval results on inspected development data, not held-out answer accuracy". The `LIKE` fallback and the FTS5 hits are finally on the **same scale** (a `LIKE`-only hit used to publish the memory's `importance` under the name `bm25`). The candidate set is unchanged — the fix re-ranks, it does not add or drop documents. New **`loop-memory bench`**: a deterministic retrieval-quality benchmark over a fixed, versioned fixture (30 memories, 12 wiki pages, 11 judged queries) reporting **recall@1/3/5, MRR@10, nDCG@10** with the fixture's revision and the SHA-256 of its bytes; the run is fully offline (**no provider API is called, $0, no network**) and builds its store in a throwaway directory. On the shipped fixture the channel scored **MRR@10 = 0.6061, recall@1 = 0.2273, nDCG@10 = 0.7078** before and **1.0000 / 0.9545 / 1.0000** after — and the report keeps the raw FTS5 score next to the repaired one, so the defect stays visible instead of being quietly fixed and forgotten. Source: *agentmemory* v0.9.31 evaluation methodology + the FTS5 idf clamp in SQLite's `fts5_aux.c` (Apache-2.0 — *pattern only, no code copied*); honcho v3.4.1's "a filter must not silently drop a term" and v3.5.0's "a conclusion must cite its source" were reviewed and need no code (AGPL-3.0 — *pattern only*). 37 new regression cases; suite at **995 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0418---2026-11-01)
 > **What's new in 0.4.17** — **a dry-run dream pass no longer writes to the database** (audit 2026-10-25). `loop-memory dream` and `POST /api/v1/dream` have always documented themselves as *"nothing is written unless `apply=True`"* — but the pass's decay stage called `MemoryStore.rescore_all()` unconditionally, which rewrote the `memories.score` column of **every** row while claiming to only inspect the store. The expiry and merge decisions were correctly left unapplied; the score decay was not. `rescore_all()` now takes a `dry_run` flag: it computes every new score and reports how many rows *would* change but issues no `UPDATE`, and the dream pass runs it with `dry_run=not apply`. A dry run still reports the size of the decay job through `report.rescored` while touching nothing. The contract wording is now exact rather than aspirational — a dry run changes **no memory data** (no expiry, no supersession, no rescore); the single write it still performs is one `cognitive_audit` row per proposed action with `action="suggest"` instead of `"applied"`, because that row *is* the reviewable plan the dashboard shows before you commit to it (`record_audit=False` suppresses even that). Also fixed in this release: `publish.yml` now sends `make_latest` as a JSON **boolean** (`gh api -F`) instead of a JSON **string** — GitHub's release API ignores the string form, so the "mark as latest" step had been returning 200 and reporting success while promoting nothing, leaving `/releases/latest` pointing at v0.4.14 through the 0.4.15 and 0.4.16 ships. The step now also re-reads `/releases/latest` and fails the job when the tag does not match, instead of trusting the exit code. 3 new regression cases (`tests/test_dream_2026_10_25.py`); suite at **958 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0417---2026-10-25)
 > **What's new in 0.4.16** — **subject-key logical fact slots + `latest_only` recall + the "dream" sleep-time consolidation pass** (audit 2026-10-25, weekly ecosystem sync — Mem0 v2.2.1 "Dream", arXiv 2605.27366 "In Defense of Forgotten", Zep/Graphiti temporal edges, Letta memory blocks). New nullable `subject_key` column on `memories` names the *logical slot* a fact occupies (`"editor.preference"`); `upsert_memory(subject_key=...)` makes the new row the live version and soft-supersedes the previous one with a `superseded_by` pointer, so the version history survives and `recall_as_of()` can still answer "what did we believe last week?". The content-hash dedup path is now slot-aware — two different slots holding the same text stay two rows. `SCHEMA_VERSION` bumps 12 → 13 with an idempotent in-place migration. New `latest_only=False` flag on `recall()` / `recall_hybrid()` (Mem0 v2 `SearchMemoryOptions.latest_only` parity) collapses the answer in three layers: rows outside their validity window at *now* are dropped, a subject-key slot resolves to its newest **live** row (looked up in the store, so a stale version never comes back just because it matched the query better), and near-duplicate texts cluster by token Jaccard (default 0.85) with the newest row winning. Wired through `GET /api/recall?latest_only=1`, `GET /api/v1/recall?latest_only=1`, `loop-memory recall --latest-only` and `MemoryClient.recall(latest_only=True)`. New `loop_memory/jobs/dream.py` implements the sleep-time consolidation Mem0 v2 calls the "Dream" — deterministic, zero-dep and **non-destructive**: it decays scores, then judges every row past its deadline on **utility** (`0.45 × importance + 0.30 × usage + 0.25 × recency`) so a frequently-recalled old fact is *protected* while a never-used stale row is **soft-expired** (`invalid_at` stamped, row kept, history kept) instead of deleted, and finally merges near-duplicates into a supersession chain. Run it with `loop-memory dream [--apply] [--json]` or `POST /api/v1/dream` — it is a **dry run by default** and every decision lands in `cognitive_audit` so the dashboard can show and revert it. New store primitives `expire_memory()` / `revive_memory()`, and `memory_stats()` now reports `subject_key`, `ttl`, `valid_at`, `invalid_at` and a derived `ttl_state`. **Also fixed a real defect**: the hybrid recall path (BM25 / LIKE / semantic channels) did not filter `superseded_by`, so `recall_hybrid()` — the production path behind the CLI, MCP server and dashboard — returned both versions of a superseded fact. Source: Mem0 v2.2.1 Dream + ADD-only architecture + arXiv 2605.27366 utility-aware eviction + Zep/Graphiti bi-temporal edges (pattern only, no code copied). 77 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0416---2026-10-25)

{loop_memory-0.4.18 → loop_memory-0.4.20}/README.md

@@ -22,6 +22,10 @@
 
 ---
 
+> **What's new in 0.4.20** — **the packaging test works on the oldest supported Python** (audit 2026-11-01, patch follow-up to 0.4.19). The 0.4.19 packaging test parsed `pyproject.toml` with `tomllib`, which is stdlib only from Python **3.11** onwards, while the project declares `requires-python = ">=3.10"` — so the 3.10 CI job failed with `ModuleNotFoundError: No module named 'tomllib'` while 3.11 and 3.12 passed, the classic shape of a bug that only bites the oldest supported interpreter. The check now reads the `[tool.setuptools.package-data]` table directly (it is a flat mapping of package name to a list of glob strings), and a new case runs it in a subprocess with `tomllib` blocked at the import system level, so the 3.10 path is exercised on every version rather than only on the 3.10 runner. No behaviour change — the 0.4.19 distribution is unchanged and correct. 1 new regression case; suite at **1004 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0420---2026-11-01)
+
+> **What's new in 0.4.19** — **the PyPI wheel now ships the whole dashboard and the benchmark fixture** (audit 2026-11-01, packaging follow-up to 0.4.18). The 0.4.18 wheel contained exactly two data files — `loop_memory/py.typed` and `loop_memory/serve/static/index.html` — because the package-data declaration was `loop_memory = ["py.typed", "serve/static/*.html"]`, and that glob is **not recursive**. Every CSS, JavaScript, i18n and image asset and the new benchmark fixture were **missing from the distribution**. Reproduced against the published wheel: `pip install loop-memory` started a server whose `GET /` returned `200` but whose `GET /static/js/main.js` and `GET /static/css/app.css` both returned **404** — a blank dashboard — and `loop-memory bench` crashed with `FileNotFoundError` on the packaged fixture. The declaration is now per package with recursive globs (`"loop_memory.serve.static" = ["**/*.html", "**/*.css", "**/*.js", "**/*.json", "**/*.svg"]`, `"loop_memory.bench" = ["fixtures/*.json"]`), so a new asset is picked up without anyone remembering to extend it, and the wheel contains all 32 non-Python files in the package tree. A new packaging test builds the real wheel and sdist **from a pristine source copy** — setuptools caches its file list in `egg-info/SOURCES.txt` and packages a stale `build/lib`, so building in the working tree would make the test pass for the wrong reason — and asserts every non-Python file actually reaches the distribution, then unpacks the wheel and runs the benchmark out of it. 8 new regression cases; suite at **1003 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0419---2026-11-01)
+
 > **What's new in 0.4.18** — **the BM25 channel no longer publishes a score that collapses to zero, and there is finally a benchmark that measures it** (audit 2026-11-01, weekly ecosystem sync). SQLite's FTS5 `bm25()` computes the classic idf `log((N - n + 0.5) / (n + 0.5))` and **clamps every non-positive idf to `1e-6`** — so a query term present in 49 % of the corpus keeps a real idf while one present in 51 % has its weight annihilated, a factor of ~40 000 between two almost equally discriminative terms. With the `trigram` tokenizer that is the *normal* case for CJK (`知识图` alone occurs in more than half of any knowledge-graph-heavy corpus), and the visible symptom was the 0.4.15 evidence chain reporting **`bm25: 0.0`** — "this hit because bm25 0.0". The published score is now a textbook BM25 (`k1 = 1.2`, `b = 0.75`) with the Lucene / BM25+ idf `log(1 + (N - n + 0.5) / (n + 0.5))`, which is strictly positive for every term, so the scale cannot collapse. **A document that contains the query verbatim now outranks one that merely contains the same scattered trigrams** — the transferable half of `rohitg00/agentmemory` v0.9.31's prefix-score fix (2026-10-26: strict recall-all@5 **65.74 % → 84.68 %**, +18.94 pp), whose release note is careful to call its numbers "component retrieval results on inspected development data, not held-out answer accuracy". The `LIKE` fallback and the FTS5 hits are finally on the **same scale** (a `LIKE`-only hit used to publish the memory's `importance` under the name `bm25`). The candidate set is unchanged — the fix re-ranks, it does not add or drop documents. New **`loop-memory bench`**: a deterministic retrieval-quality benchmark over a fixed, versioned fixture (30 memories, 12 wiki pages, 11 judged queries) reporting **recall@1/3/5, MRR@10, nDCG@10** with the fixture's revision and the SHA-256 of its bytes; the run is fully offline (**no provider API is called, $0, no network**) and builds its store in a throwaway directory. On the shipped fixture the channel scored **MRR@10 = 0.6061, recall@1 = 0.2273, nDCG@10 = 0.7078** before and **1.0000 / 0.9545 / 1.0000** after — and the report keeps the raw FTS5 score next to the repaired one, so the defect stays visible instead of being quietly fixed and forgotten. Source: *agentmemory* v0.9.31 evaluation methodology + the FTS5 idf clamp in SQLite's `fts5_aux.c` (Apache-2.0 — *pattern only, no code copied*); honcho v3.4.1's "a filter must not silently drop a term" and v3.5.0's "a conclusion must cite its source" were reviewed and need no code (AGPL-3.0 — *pattern only*). 37 new regression cases; suite at **995 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0418---2026-11-01)
 > **What's new in 0.4.17** — **a dry-run dream pass no longer writes to the database** (audit 2026-10-25). `loop-memory dream` and `POST /api/v1/dream` have always documented themselves as *"nothing is written unless `apply=True`"* — but the pass's decay stage called `MemoryStore.rescore_all()` unconditionally, which rewrote the `memories.score` column of **every** row while claiming to only inspect the store. The expiry and merge decisions were correctly left unapplied; the score decay was not. `rescore_all()` now takes a `dry_run` flag: it computes every new score and reports how many rows *would* change but issues no `UPDATE`, and the dream pass runs it with `dry_run=not apply`. A dry run still reports the size of the decay job through `report.rescored` while touching nothing. The contract wording is now exact rather than aspirational — a dry run changes **no memory data** (no expiry, no supersession, no rescore); the single write it still performs is one `cognitive_audit` row per proposed action with `action="suggest"` instead of `"applied"`, because that row *is* the reviewable plan the dashboard shows before you commit to it (`record_audit=False` suppresses even that). Also fixed in this release: `publish.yml` now sends `make_latest` as a JSON **boolean** (`gh api -F`) instead of a JSON **string** — GitHub's release API ignores the string form, so the "mark as latest" step had been returning 200 and reporting success while promoting nothing, leaving `/releases/latest` pointing at v0.4.14 through the 0.4.15 and 0.4.16 ships. The step now also re-reads `/releases/latest` and fails the job when the tag does not match, instead of trusting the exit code. 3 new regression cases (`tests/test_dream_2026_10_25.py`); suite at **958 passed / 4 skipped**. [Full CHANGELOG →](./CHANGELOG.md#0417---2026-10-25)
 > **What's new in 0.4.16** — **subject-key logical fact slots + `latest_only` recall + the "dream" sleep-time consolidation pass** (audit 2026-10-25, weekly ecosystem sync — Mem0 v2.2.1 "Dream", arXiv 2605.27366 "In Defense of Forgotten", Zep/Graphiti temporal edges, Letta memory blocks). New nullable `subject_key` column on `memories` names the *logical slot* a fact occupies (`"editor.preference"`); `upsert_memory(subject_key=...)` makes the new row the live version and soft-supersedes the previous one with a `superseded_by` pointer, so the version history survives and `recall_as_of()` can still answer "what did we believe last week?". The content-hash dedup path is now slot-aware — two different slots holding the same text stay two rows. `SCHEMA_VERSION` bumps 12 → 13 with an idempotent in-place migration. New `latest_only=False` flag on `recall()` / `recall_hybrid()` (Mem0 v2 `SearchMemoryOptions.latest_only` parity) collapses the answer in three layers: rows outside their validity window at *now* are dropped, a subject-key slot resolves to its newest **live** row (looked up in the store, so a stale version never comes back just because it matched the query better), and near-duplicate texts cluster by token Jaccard (default 0.85) with the newest row winning. Wired through `GET /api/recall?latest_only=1`, `GET /api/v1/recall?latest_only=1`, `loop-memory recall --latest-only` and `MemoryClient.recall(latest_only=True)`. New `loop_memory/jobs/dream.py` implements the sleep-time consolidation Mem0 v2 calls the "Dream" — deterministic, zero-dep and **non-destructive**: it decays scores, then judges every row past its deadline on **utility** (`0.45 × importance + 0.30 × usage + 0.25 × recency`) so a frequently-recalled old fact is *protected* while a never-used stale row is **soft-expired** (`invalid_at` stamped, row kept, history kept) instead of deleted, and finally merges near-duplicates into a supersession chain. Run it with `loop-memory dream [--apply] [--json]` or `POST /api/v1/dream` — it is a **dry run by default** and every decision lands in `cognitive_audit` so the dashboard can show and revert it. New store primitives `expire_memory()` / `revive_memory()`, and `memory_stats()` now reports `subject_key`, `ttl`, `valid_at`, `invalid_at` and a derived `ttl_state`. **Also fixed a real defect**: the hybrid recall path (BM25 / LIKE / semantic channels) did not filter `superseded_by`, so `recall_hybrid()` — the production path behind the CLI, MCP server and dashboard — returned both versions of a superseded fact. Source: Mem0 v2.2.1 Dream + ADD-only architecture + arXiv 2605.27366 utility-aware eviction + Zep/Graphiti bi-temporal edges (pattern only, no code copied). 77 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0416---2026-10-25)

loop_memory-0.4.20/loop_memory/bench/fixtures/default.json

@@ -0,0 +1,363 @@
+{
+  "name": "loop-memory-default",
+  "revision": 2,
+  "description": "Deterministic retrieval-quality fixture for Loop Memory. 30 memories + 12 wiki pages, 11 judged queries. The corpus is deliberately knowledge-graph-heavy so the trigram '知识图' occurs in 18/30 memories (60%), which pushes SQLite's bm25() inverse document frequency below zero and onto its 1e-6 floor -- the defect this benchmark exists to measure. Query q10 ('知识图谱') has no rare term at all, so every one of its terms is clamped and the whole channel score collapses; the report shows the raw FTS5 score alongside the repaired one. Most other queries pair one document that contains the query verbatim with a shorter near miss, so the exact-match rule is measurable too.",
+  "corpus": [
+    {
+      "id": "kg-01",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的整体架构由存储层、抽取层和查询层三个部分组成"
+    },
+    {
+      "id": "kg-02",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的存储层使用图数据库保存实体和关系并支持按租户分区隔离，同时提供冷热分层和定期归档能力以控制存储成本"
+    },
+    {
+      "id": "kg-03",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的抽取层负责从文档中识别实体和属性并写入草稿库"
+    },
+    {
+      "id": "kg-04",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的查询层同时提供自然语言接口和图遍历接口两种风格"
+    },
+    {
+      "id": "kg-05",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的实体消歧依赖上下文窗口并且最终需要人工复核确认"
+    },
+    {
+      "id": "kg-06",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的关系抽取分为显式关系和隐含关系两大类别来处理"
+    },
+    {
+      "id": "kg-07",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的增量更新由定时任务和事件触发两种模式共同驱动"
+    },
+    {
+      "id": "kg-08",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的质量评估覆盖完整性和一致性两个维度来衡量"
+    },
+    {
+      "id": "kg-09",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的可视化界面支持力导向图和时间轴视图两种呈现方式"
+    },
+    {
+      "id": "kg-10",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的权限模型区分全局空间和项目空间两套隔离策略"
+    },
+    {
+      "id": "kg-11",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的版本控制会记录每次抽取的输入快照和输出差异明细"
+    },
+    {
+      "id": "kg-12",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的导入流程支持 JSONL 和 CSV 两种常见的文件格式"
+    },
+    {
+      "id": "kg-13",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的导出流程会把实体、关系和来源标识一并写出到磁盘"
+    },
+    {
+      "id": "kg-14",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的部署方式分为单机模式和容器模式两套基础设施方案"
+    },
+    {
+      "id": "kg-15",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "知识图谱构建流程的第一步是切分输入文档并保留原始偏移量用于后续的实体对齐工作，同时需要保留切分器的版本号以便回溯"
+    },
+    {
+      "id": "kg-16",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "构建流程的第一步是切分知识图谱的输入文档"
+    },
+    {
+      "id": "kg-17",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱的构建流程包含切分和抽取两个阶段"
+    },
+    {
+      "id": "kg-18",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱在存储层之上还有一层缓存用于加速热点查询"
+    },
+    {
+      "id": "kg-19",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "知识图谱术语表把实体、关系、属性和来源这四个概念放在同一份文档里对照说明，知识图谱的每个概念都要有明确定义和清晰的边界"
+    },
+    {
+      "id": "kg-20",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "知识图谱构建的准备工作包括确认数据源和配置抽取参数"
+    },
+    {
+      "id": "en-01",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "Kubernetes ingress controller runs in the platform namespace and watches every ingress object that is created inside the cluster so that routing rules stay in sync with the declared service definitions"
+    },
+    {
+      "id": "en-02",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "The ingress controller for kubernetes was migrated to a new namespace"
+    },
+    {
+      "id": "en-03",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "The blue green rollout switches production traffic between two clusters and keeps the old one warm so that a rollback stays a single configuration change instead of a rebuild"
+    },
+    {
+      "id": "en-04",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "Rolling upgrades were replaced by a blue-green style rollout"
+    },
+    {
+      "id": "en-05",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "The operator rotates the tls certificate manually every ninety days"
+    },
+    {
+      "id": "en-08",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "Rotate TLS certificate without any downtime by scheduling the sidecar renewal job ahead of expiry so that the new chain is presented before the old one is revoked"
+    },
+    {
+      "id": "en-09",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "The recall budget caps how many characters a single injected context block may occupy before truncation removes the tail of the payload and the remaining slots are handed to the next ranked memory"
+    },
+    {
+      "id": "en-10",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "Budget enforcement happens during the merge step, so recall limits apply equally to the fast path and to the slower fallback path"
+    },
+    {
+      "id": "en-11",
+      "kind": "fact",
+      "importance": 0.6,
+      "text": "Knowledge graph ingestion runs as a background job that batches documents and writes entities into the graph store within the configured window and reports how many records were skipped"
+    },
+    {
+      "id": "en-12",
+      "kind": "fact",
+      "importance": 0.5,
+      "text": "Ingestion of the graph pipeline is scheduled nightly and refreshed whenever the source corpus changes"
+    }
+  ],
+  "wiki": [
+    {
+      "slug": "deploy-runbook",
+      "title": "部署流程",
+      "importance": 0.6,
+      "body": "部署流程分为预发验证、灰度发布和全量发布三个阶段，每个阶段都要值班同学确认指标符合预期之后才能继续推进下一步的工作安排，遇到异常时按回滚预案处理"
+    },
+    {
+      "slug": "rollback-guide",
+      "title": "回滚指引",
+      "importance": 0.5,
+      "body": "回滚的操作步骤与正向流程类似但需要先冻结变更窗口并在值班表上记录"
+    },
+    {
+      "slug": "incident-review",
+      "title": "故障复盘",
+      "importance": 0.5,
+      "body": "故障复盘包括时间线重建、根因定位和改进行动项三个部分"
+    },
+    {
+      "slug": "cert-rotation",
+      "title": "证书轮换",
+      "importance": 0.5,
+      "body": "证书轮换由 sidecar 代理每九十天自动执行一次并记录审计日志"
+    },
+    {
+      "slug": "kg-glossary",
+      "title": "知识图谱术语表",
+      "importance": 0.5,
+      "body": "本术语表统一了实体、关系、属性和来源四个核心概念的叫法"
+    },
+    {
+      "slug": "onboarding",
+      "title": "新人上手",
+      "importance": 0.5,
+      "body": "新人上手流程分为环境准备、阅读规范和第一个改动三步"
+    },
+    {
+      "slug": "nda-signing",
+      "title": "合同签署流程",
+      "importance": 0.5,
+      "body": "签署流程需要法务和业务双方在系统中确认后才会正式生效"
+    },
+    {
+      "slug": "deploy-signoff",
+      "title": "上线签署流程",
+      "importance": 0.5,
+      "body": "上线签署流程由发布负责人和值班同学共同完成，之后才进入部署流水线等待执行"
+    },
+    {
+      "slug": "rotation-policy",
+      "title": "轮换策略",
+      "importance": 0.5,
+      "body": "策略规定书轮换窗口每月开放一次，实际执行由平台自动化任务完成"
+    },
+    {
+      "slug": "cert-exceptions",
+      "title": "证书例外",
+      "importance": 0.5,
+      "body": "证书轮换策略的例外情况需要人工审批并记录原因"
+    },
+    {
+      "slug": "release-notes",
+      "title": "发布说明",
+      "importance": 0.6,
+      "body": "发布流程要求每次上线都要附上变更说明和影响范围，回滚流程与部署流程的触发条件不同需要分别评估，缺少变更说明的发布一律不予放行"
+    },
+    {
+      "slug": "release-pipeline",
+      "title": "发布流水线",
+      "importance": 0.5,
+      "body": "布流程的每一步都要有回滚预案，发布流水线在蓝绿切换中会先验证新环境的健康状态再切流量"
+    }
+  ],
+  "queries": [
+    {
+      "id": "q1",
+      "query": "知识图谱构建流程",
+      "channel": "memories",
+      "relevant": [
+        "kg-15"
+      ],
+      "note": "The authoritative step list contains the query verbatim; kg-16 and kg-17 match only the boundary trigrams. All three have the same term frequencies, so the pre-0.4.18 tie-break was document length, which demoted the complete note."
+    },
+    {
+      "id": "q2",
+      "query": "知识图谱的存储层",
+      "channel": "memories",
+      "relevant": [
+        "kg-02"
+      ],
+      "note": "kg-02 holds the query verbatim and is the longest of the three candidates; kg-01 and kg-18 are near misses."
+    },
+    {
+      "id": "q3",
+      "query": "kubernetes ingress controller",
+      "channel": "memories",
+      "relevant": [
+        "en-01"
+      ],
+      "note": "en-01 holds the query verbatim; en-02 mentions the same three terms in a different order."
+    },
+    {
+      "id": "q4",
+      "query": "blue green rollout",
+      "channel": "memories",
+      "relevant": [
+        "en-03"
+      ],
+      "note": "en-03 holds the query verbatim; en-04 uses a hyphenated form."
+    },
+    {
+      "id": "q5",
+      "query": "rotate tls certificate",
+      "channel": "memories",
+      "relevant": [
+        "en-08"
+      ],
+      "note": "en-08 holds the query verbatim; en-05 uses the verb form 'rotates'."
+    },
+    {
+      "id": "q6",
+      "query": "recall budget",
+      "channel": "memories",
+      "relevant": [
+        "en-09"
+      ],
+      "note": "en-09 holds the query verbatim; en-10 mentions both terms separately."
+    },
+    {
+      "id": "q7",
+      "query": "knowledge graph ingestion",
+      "channel": "memories",
+      "relevant": [
+        "en-11"
+      ],
+      "note": "en-11 holds the query verbatim; en-12 mentions both terms separately."
+    },
+    {
+      "id": "q8",
+      "query": "部署流程",
+      "channel": "wiki",
+      "relevant": [
+        "deploy-runbook"
+      ],
+      "note": "deploy-runbook holds the query verbatim; deploy-signoff matches the boundary trigrams '部署流' and '署流程' without the phrase."
+    },
+    {
+      "id": "q9",
+      "query": "发布流程",
+      "channel": "wiki",
+      "relevant": [
+        "release-notes"
+      ],
+      "note": "release-notes holds the query verbatim; release-pipeline matches the boundary trigrams '发布流' and '布流程' without the phrase."
+    },
+    {
+      "id": "q10",
+      "query": "知识图谱",
+      "channel": "memories",
+      "relevant": [
+        "kg-19"
+      ],
+      "note": "Every term of this query is common, so the raw FTS5 score collapses onto its 1e-6 idf floor. The repaired score keeps a usable scale and the verbatim match still ranks first."
+    },
+    {
+      "id": "q11",
+      "query": "知识图谱构建",
+      "channel": "memories",
+      "relevant": [
+        "kg-15",
+        "kg-20"
+      ],
+      "note": "Two documents are genuinely relevant and both are retrievable: the canonical step list and the preparation checklist. recall@1 therefore cannot reach 1.0 for this query, so the metric keeps headroom. kg-16 stays in the corpus as a distractor: it discusses the same first step but the trigram candidate query cannot see it, because it needs CJK word segmentation to match '知识图谱构建'."
+    }
+  ]
+}

{loop_memory-0.4.18 → loop_memory-0.4.20}/loop_memory/bench/runner.py

@@ -134,8 +134,21 @@ class BenchmarkReport:
 
 
 def default_fixture_path() -> Path:
-    """Absolute path of the fixture shipped with the package."""
-    return Path(__file__).resolve().parent / "fixtures" / "default.json"
+    """Absolute path of the fixture shipped with the package.
+
+    Audit 2026-11-01 (loop-memory 0.4.19): the fixture is *package
+    data*.  It was not declared in ``pyproject.toml``, so the 0.4.18
+    wheel shipped without it and ``loop-memory bench`` died with a
+    ``FileNotFoundError`` on every PyPI install.  ``importlib.resources``
+    is the fallback for installs whose files are not reachable through
+    ``__file__``.
+    """
+    direct = Path(__file__).resolve().parent / "fixtures" / "default.json"
+    if direct.is_file():
+        return direct
+    from importlib.resources import files
+
+    return Path(str(files("loop_memory.bench").joinpath("fixtures").joinpath("default.json")))
 
 
 def load_fixture(path: str | Path | None = None) -> tuple[dict[str, Any], str]:
@@ -146,7 +159,16 @@ def load_fixture(path: str | Path | None = None) -> tuple[dict[str, Any], str]:
     re-serialisation of it.
     """
     p = Path(path).expanduser() if path else default_fixture_path()
-    raw = p.read_bytes()
+    try:
+        raw = p.read_bytes()
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(
+            f"benchmark fixture not found: {p}\n"
+            "The default fixture ships as package data; if you installed "
+            "loop-memory from PyPI and this is the packaged fixture, the "
+            "distribution is missing it (that was the 0.4.18 bug fixed "
+            "in 0.4.19). Pass --fixture PATH to point at your own."
+        ) from exc
     digest = hashlib.sha256(raw).hexdigest()
     data = json.loads(raw.decode("utf-8"))
     if not isinstance(data, dict):

{loop_memory-0.4.18 → loop_memory-0.4.20}/loop_memory/cli/commands/bench.py

@@ -85,7 +85,11 @@ def run_bench(args: list) -> int:
 
     from ...bench.runner import compare_reports, load_fixture, run_benchmark
 
-    fixture, digest = load_fixture(ns.fixture)
+    try:
+        fixture, digest = load_fixture(ns.fixture)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
     report = run_benchmark(
         fixture, fixture_sha256=digest, top_k=ns.top_k
     ).to_dict()