open-memex 0.9.0-alpha.2 → 0.9.0-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/AGENTS.md +27 -2
  2. package/CHANGELOG.md +7 -1
  3. package/README.md +43 -4
  4. package/README.zh-CN.md +24 -3
  5. package/dist/.build-stamp +1 -1
  6. package/dist/cli.js +182 -4
  7. package/dist/config.js +11 -0
  8. package/dist/graph/extract.js +234 -0
  9. package/dist/graph/lint.js +89 -0
  10. package/dist/graph/outline.js +146 -0
  11. package/dist/graph/queries.js +122 -0
  12. package/dist/init.js +3 -1
  13. package/dist/mcp.js +3 -1
  14. package/dist/plugin-core.js +4 -0
  15. package/dist/retrieve/inject.js +26 -2
  16. package/dist/reuse-report.js +64 -0
  17. package/dist/review.js +16 -0
  18. package/dist/store/db.js +8 -2
  19. package/dist/store/graph.js +225 -0
  20. package/dist/store/sync.js +7 -3
  21. package/dist/store/usage.js +142 -27
  22. package/dist/tools/ops.js +22 -12
  23. package/docs/V2-DESIGN.md +4 -2
  24. package/docs/design/decisions.md +4 -1
  25. package/docs/design/knowledge-graph.md +1 -1
  26. package/package.json +66 -66
  27. package/scripts/smoke-mcp.ts +9 -0
  28. package/scripts/smoke-pure.ts +267 -0
  29. package/scripts/test-full.ts +198 -15
  30. package/skills/open-memex/SKILL.md +21 -0
  31. package/src/cli.ts +199 -6
  32. package/src/config.ts +17 -0
  33. package/src/graph/extract.ts +276 -0
  34. package/src/graph/lint.ts +107 -0
  35. package/src/graph/outline.ts +167 -0
  36. package/src/graph/queries.ts +143 -0
  37. package/src/init.ts +3 -1
  38. package/src/mcp.ts +3 -1
  39. package/src/plugin-core.ts +4 -0
  40. package/src/retrieve/inject.ts +27 -2
  41. package/src/reuse-report.ts +119 -0
  42. package/src/review.ts +15 -0
  43. package/src/store/db.ts +8 -2
  44. package/src/store/graph.ts +293 -0
  45. package/src/store/sync.ts +6 -2
  46. package/src/store/usage.ts +319 -178
  47. package/src/tools/ops.ts +23 -12
package/AGENTS.md CHANGED
@@ -35,10 +35,11 @@ npm run typecheck # tsc --noEmit — the only
35
35
  npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
36
36
  npm run cli -- useful <id...> # D77-L2: explicit useful signal + cumulative counters
37
37
  npm run cli -- <command> --help # per-command help (AI assistants discover flags this way)
38
- npm run cli -- sync-status # last sync time/kind + outbox drafts + repo review states + uncommitted files
38
+ npm run cli -- sync-status # last sync time/kind + outbox drafts + repo review states + uncommitted files + D77 reuse report
39
39
  npm run cli -- inventory [--format text|json|html] [--scope both] # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
40
40
  npm run cli -- audit [--scope project|personal|both] # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo, expired working-state notes (read-only)
41
41
  npm run cli -- wstate [--clear] # show/clear the session working-state note (D89 §3.6; the file it prints is editable directly)
42
+ npm run cli -- graph build | outline | neighbours <id> | path <a> <b> | lint # D91 structural graph (project scope only; no --scope)
42
43
  npm run cli -- pull # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
43
44
  npm run cli -- push # push current branch to remote (explicit only; open-memex never auto-pushes)
44
45
  npm run cli -- export [--scope project|personal|both] [--all] [-o <file>] # portable .tar.gz bundle (markdown + manifest); private excluded unless --all
@@ -126,7 +127,7 @@ Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (S
126
127
 
127
128
  **Markdown files are the source of truth; `index.db` is rebuildable.** `syncScope()` (in `src/store/sync.ts`) reconciles the two by mtime on plugin load and before every CLI read. When adding new frontmatter fields, update `Frontmatter` in `src/store/markdown.ts`, the `memories` table in `src/store/db.ts`, and `upsertFromFile` in `src/store/sync.ts` together, and bump the reindex path.
128
129
 
129
- D77-L2 counters are the one deliberate exception: `memory_usage` (in `index.db`, owned by `src/store/usage.ts`) holds `retrieved_count` / `useful_self` / `useful_team` keyed by memory id, is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema, and is NOT dropped by `rebuildIndexSchema` — accumulated telemetry has no Markdown source to rebuild from. They never go into frontmatter and never leave the machine. Only `memory_useful` (explicit), a human approve at review, and a supersede raise the useful side; passive retrieval (search/list/injection, opt-in via `record: true`) raises only `retrieved_count` — never "fix" this by counting exposure as useful.
130
+ D77-L2 counters are the one deliberate exception: `memory_usage` (in `index.db`, owned by `src/store/usage.ts`) holds `retrieved_count` / `useful_self` / `useful_team` keyed by memory id, is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema, and is NOT dropped by `rebuildIndexSchema` — accumulated telemetry has no Markdown source to rebuild from. They never go into frontmatter and never leave the machine. Only `memory_useful` (explicit), a human approve at review, and a supersede raise the useful side; passive retrieval (search/list/injection, opt-in via `record: true`) raises only `retrieved_count` — never "fix" this by counting exposure as useful. D77-L3's report (`loadReuseReport` in usage.ts, pure rendering in `src/reuse-report.ts`) rides `memory_status` / `cli sync-status`: per-scope rates with the useful split shown separately (self vs team, per D77), top reused, zombies (retrieved, never useful; retracted/archived excluded from both lists), and a lifecycle tag on superseded/deprecated entries so historical reuse never reads as current guidance.
130
131
 
131
132
  ## Scope keys
132
133
 
@@ -186,6 +187,30 @@ hook today, so the write path is instruction + tool; the tool description,
186
187
  the surfaced block, the MCP handshake, `init` instructions and the skill must
187
188
  keep saying the same thing.
188
189
 
190
+ **Knowledge graph (D91, §20 deterministic half) — derived, never a source.** `src/store/graph.ts`
191
+ owns `graph_edges`/`graph_meta` (created `IF NOT EXISTS` outside the versioned
192
+ schema, like D77's counters — the graph is rebuildable and disposable). Pure
193
+ logic lives in `src/graph/{extract,outline,queries,lint}.ts`; do not move DB calls
194
+ into them. Edge rules: `supersedes` (from the index's `superseded_by`),
195
+ `derived-from` (from the `derived_from` column — added in index v10),
196
+ body-mention (`[[ULID]]` EXTRACTED / bare ULID INFERRED), shared-tag at the
197
+ fixed ladder 1→low / 2→medium / ≥3→high with per-node/per-set caps. NEVER
198
+ lower a confidence or widen the caps without a measurement — the caps exist so
199
+ one universal tag cannot build an O(n²) edge set. The compiled outline joins
200
+ components **only by medium+ edges** (universal-tag collapse guard; fixture in
201
+ `smoke-pure.ts`) and is injected once at session start (`graphOutline`,
202
+ `graphOutlineLines`; exposure counts as D77 `retrieved`, never useful).
203
+ Every mutating path must call `refreshGraphQuiet` after the write — if you add
204
+ one (new tool, CLI verb, keyword-capture pattern, review transition), add the
205
+ refresh in the same change. The graph covers the cwd's **project** scope only (no `--scope`, personal
206
+ never graphs) and the interface is **CLI only** — the MCP surface stays at
207
+ thirteen tools. `graph lint` reports only (orphans / dangling / stale); an edge
208
+ endpoint that exists in *another* scope is a legitimate foreign link (a propose
209
+ copy's `derived_from`), so lint skips it — pass `loadAllMemoryIds()` as the
210
+ foreign set, never "fix" it by dropping the edge. The LLM half (semantic
211
+ insights, missing-page alerts) is still open in §18 and must propose new memories
212
+ through the normal flow, not write them.
213
+
189
214
  ## Design constraints — read the frozen design first
190
215
 
191
216
  `docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D88 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
package/CHANGELOG.md CHANGED
@@ -9,9 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ - The knowledge graph, deterministic half (D91 → design §20): an automatic, derivation-honest structural graph over project memories, plus a compiled outline injected at session start. `graph build` (`open-memex graph build`) extracts every edge it can *prove* — `relates-to` from `[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED), supersedes chains from the index, derived-from edges from propose copies, and shared-tag co-membership at a fixed confidence ladder (1 shared tag → low, 2 → medium, ≥3 → high, capped at `MAX_SHARED_TAG_EDGES_PER_NODE = 12` per node / 2000 nodes to bound hot-tag blowups) — stores it in `graph_edges`/`graph_meta` beside the rebuildable index, and stamps every edge `extracted` (structural fact) or `inferred` (heuristic) with its derivation receipt. Every mutating path (add/supersede/soft + hard forget on both hosts, keyword capture, propose, review promotion, CLI add/supersede/status/forget) refreshes the graph automatically; statuses are materialized into nodes so `retracted`/`archived` memories imply their edges without custom SQL. The new **`graph outline`** command renders the compiled outline — medium+ confidence components as `topic (n): titles...` lines, bounded by `graphOutlineLines` (default 10) with the cut disclosed — and `open-memex graph outline` output is also injected once at session start next to the working-state note (`graphOutline: false` disables it); outline components are joined **only by medium+ edges** so one universal tag cannot collapse the graph into one mega-topic (fixture-pinned). `graph neighbours <id> [--depth 1-6]` walks BFS with per-edge receipts, `graph path <a> <b>` prints the hop chain (depth 4 default), both failing honestly on unknown ids (D63: findings never invent nodes). `graph lint` reports orphans (active, in no topic, linked to nothing), dangling edges, and near-stale pairs (≥ 0.8 similarity, excluding chains) — reports only, nothing auto-resolved; this report is the input D78's pre-submit lint consumes later. The graph covers the cwd's project scope only (no `--scope` flag; `personal` never graphs). MCP stays at 13 tools — the interface is CLI-only per §20.6. Schema bump: the index gains a `derived_from` column (v10, rebuild-from-Markdown migration). New pure modules (`src/graph/{extract,outline,queries,lint}.ts`) + `src/store/graph.ts`; smoke + full-suite tested (154 pass). The LLM half (abstracted insights, missing-page alerts → new memories) stays open in §18.
13
+
14
+ ## [0.9.0-alpha.3] - 2026-11-04
15
+
16
+ - D77-L3: the reuse report — D77's third and final layer. `memory_status` (MCP) and `open-memex sync-status` now end with a **Reuse (D77)** block built from the `memory_usage` counters: per-scope `retrieved` / `useful` rates (personal + this project) with the **useful split shown separately** (`self` vs `team`, as D77 requires — the combined total drives the rate), the **top reused** memories, and **zombies** — retrieved at least once, never confirmed useful, i.e. the decay/prune candidates. Superseded/deprecated entries stay in the lists (their reuse was real) but carry a lifecycle tag like `[superseded]`, so historical data never reads to the agent as current guidance (a supersede itself ticks the old memory). The agent-facing tool result caps each list (cut disclosed, pointing at the CLI); the CLI prints them uncapped. Retracted/archived memories are excluded from both lists but still count toward the scope totals; an empty store gets an honest "no data yet" line instead of a silent section. Rendering is pure (`src/reuse-report.ts`, smoke-tested without SQLite); collection is one join query in `loadReuseReport`. The counters themselves stay local-only SQLite telemetry (D77).
17
+
12
18
  ## [0.9.0-alpha.2] - 2026-11-03
13
19
 
14
- - D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved), and a supersede. Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved). The D77-L3 reuse report (top reused, zero-reuse zombies, per-scope rates) remains open.
20
+ - D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved, or the `--local-approve` propose shortcut), and a supersede (recorded even when the index row is momentarily missing — the Markdown file is the source of truth). Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved). The D77-L3 reuse report (top reused, zero-reuse zombies, per-scope rates) remains open.
15
21
 
16
22
  ## [0.9.0-alpha.1] - 2026-11-03
17
23
 
package/README.md CHANGED
@@ -457,7 +457,7 @@ they only matter once you share memories through Git.
457
457
  | ● `memory_forget` | Delete a memory by id (`soft=true` hides it instead — retracted, one-way) |
458
458
  | ● `memory_workingstate` | Read/write/clear the per-project working-state note (§3.6, D89) — resumes an interrupted task; scratch state, never a memory |
459
459
  | ● `memory_useful` | Mark a memory as useful (D77) — explicit confirmation only; exposure is counted separately as `retrieved_count` |
460
- | `memory_status` | Show the sync queue: outbox drafts, repo review states, uncommitted files |
460
+ | `memory_status` | Show the sync queue (outbox drafts, repo review states, uncommitted files) plus the D77 reuse report |
461
461
  | `memory_submit` | Move named drafts into the repo memory dir (local branch + commit) |
462
462
  | `memory_propose` | Copy personal memories into the project scope as review candidates |
463
463
  | `memory_promote` | Advance `proposed → approved → published` (or reject / resubmit) |
@@ -478,8 +478,12 @@ confirms it paid off, a human approval at review, or a supersede. Passive
478
478
  exposure never counts as useful — a memory that merely showed up in results
479
479
  has shown nothing yet. Same-side CLI surface: `open-memex useful <id...>`.
480
480
  Counters live in the local SQLite index only (never in the Markdown files,
481
- never off this machine); the reuse report (top reused, zero-reuse zombies,
482
- per-scope rates) rides the D77-L3 follow-up.
481
+ never off this machine). The report rides `memory_status` (and
482
+ `open-memex sync-status`): per-scope retrieved/useful rates with the self/team
483
+ split shown separately, the most-reused memories, and the "zombies" —
484
+ retrieved but never confirmed useful, i.e. the decay/prune candidates
485
+ (D77-L3). Superseded/deprecated entries stay visible as reuse history but
486
+ carry a lifecycle tag, never presented as current guidance.
483
487
 
484
488
  ## Memory types
485
489
 
@@ -693,6 +697,8 @@ Defaults:
693
697
  "injectOnFirstTurn": true, // [OPEN-MEMEX] system-prompt block
694
698
  "keywordCaptureEnabled": true,
695
699
  "logLevel": "info", // info | debug
700
+ "graphOutline": true, // inject the compiled graph outline at session start
701
+ "graphOutlineLines": 10, // outline length cap (max 30)
696
702
  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
697
703
  }
698
704
  ```
@@ -704,10 +710,12 @@ setting after install:
704
710
  open-memex config set keywordCaptureEnabled false
705
711
  open-memex config set maxProjectMemories 12
706
712
  open-memex config set sync.autoPull true # best-effort pull at MCP session start
713
+ open-memex config set graphOutline false # stop injecting the graph outline
707
714
  ```
708
715
 
709
716
  Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
710
- `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
717
+ `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
718
+ `graphOutline`, `graphOutlineLines`, and `sync.autoPull` (a dotted
711
719
  key that writes into the nested `sync` object). Full design:
712
720
  [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
713
721
 
@@ -850,6 +858,8 @@ open-memex scopes # list project scopes with memory counts
850
858
  open-memex reindex # rebuild the SQLite index from markdown
851
859
  open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
852
860
  open-memex wstate # show the session working-state note (--clear deletes it)
861
+ open-memex graph build # rebuild the knowledge graph (structural edges only; runs automatically on writes)
862
+ open-memex graph lint # orphans, dangling edges, near-duplicate pairs (reports only)
853
863
  open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
854
864
  ```
855
865
 
@@ -877,6 +887,35 @@ open-memex wstate # show the note (age + expiry)
877
887
  open-memex wstate --clear # delete it
878
888
  ```
879
889
 
890
+ ## Knowledge graph
891
+
892
+ A derived, rebuildable graph over the **current project's** memories (D91, §20
893
+ deterministic half) — it answers "what is in memory and how is it connected"
894
+ without searching, and it never touches the Markdown source of truth. Structural
895
+ edges only, no LLM: `supersedes` chains, `derived-from` propose copies,
896
+ `[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED),
897
+ and shared-tag co-membership at a fixed
898
+ confidence ladder (1 tag → low, 2 → medium, ≥3 → high). Every edge is marked
899
+ `EXTRACTED` (structural fact) or `INFERRED` (heuristic) with its receipt.
900
+
901
+ The graph refreshes automatically on every memory write. A **compiled outline**
902
+ (medium+ confidence components, capped and cut-disclosed) is injected once at
903
+ session start next to the working-state note; disable it with
904
+ `config set graphOutline false`, tune its length with `graphOutlineLines`
905
+ (default 10, max 30). Personal scope is never graphed.
906
+
907
+ ```sh
908
+ open-memex graph build # rebuild now (writes do this automatically)
909
+ open-memex graph outline # the compiled outline, as injected
910
+ open-memex graph neighbours <id> [--depth 1-6] # BFS with per-edge provenance
911
+ open-memex graph path <a> <b> # shortest hop chain, with receipts
912
+ open-memex graph lint [--json] # orphans, dangling edges, near-stale pairs
913
+ ```
914
+
915
+ `lint` reports only — nothing is auto-resolved; a human decides. The same report
916
+ is the planned input for D78's pre-submit curation. The interface is CLI-only;
917
+ the MCP surface stays at its thirteen memory tools.
918
+
880
919
  ## MCP server
881
920
 
882
921
  The same memory tools over the Model Context Protocol, via a stdio server —
package/README.zh-CN.md CHANGED
@@ -297,7 +297,7 @@ MCP 服务器暴露十三个工具;opencode 原生插件暴露其中七个核
297
297
  | ● `memory_forget` | 按 id 删除一条记忆(`soft=true` 改为隐藏——retracted,单向) |
298
298
  | ● `memory_workingstate` | 读/写/清除每项目的工作状态笔记(§3.6,D89)——让被中断的任务得以续接;只是草稿状态,永远不会成为记忆 |
299
299
  | ● `memory_useful` | 确认一条记忆有用(D77)——只认显式确认;被动的搜索/列表出现只计入 `retrieved_count`,绝不算有用 |
300
- | `memory_status` | 显示同步队列:outbox 草稿、仓库评审状态、未提交文件 |
300
+ | `memory_status` | 显示同步队列(outbox 草稿、仓库评审状态、未提交文件),并附带 D77 复用报告 |
301
301
  | `memory_submit` | 把指定的草稿移进仓库记忆目录(本地分支 + 提交) |
302
302
  | `memory_propose` | 把个人记忆复制到项目作用域,作为评审候选 |
303
303
  | `memory_promote` | 推进 `proposed → approved → published`(或拒绝 / 重新提交) |
@@ -306,7 +306,7 @@ MCP 服务器暴露十三个工具;opencode 原生插件暴露其中七个核
306
306
 
307
307
  所以 MCP 接入的编辑器永远是全套;opencode 插件主攻捕获与回想,工作流类的事走 CLI 或 MCP 接入的编辑器。
308
308
 
309
- **有用性靠复用来衡量,不靠存储量(D77)。** 每条记忆带本地计数器:`retrieved_count`——它真正被递交给助手的次数(搜索结果、清单、会话开始注入);有用计数则拆成 `useful_self`(个人记忆、未评审的项目草稿)和 `useful_team`(approved/published 的项目记忆)。只有显式信号会抬升有用侧:`memory_useful`(人确认它帮上忙时)、评审中的人为 approve、或一次 supersede。被动曝光永远不算有用——记忆只是出现在结果里,还不能说明任何事。同侧的人用入口:`open-memex useful <id...>`。计数器只存在本地 SQLite 索引里(不进 Markdown 文件、不出这台机器);复用报告(复用最多、零复用的"僵尸"、各作用域复用率)由 D77-L3 后续跟进。
309
+ **有用性靠复用来衡量,不靠存储量(D77)。** 每条记忆带本地计数器:`retrieved_count`——它真正被递交给助手的次数(搜索结果、清单、会话开始注入);有用计数则拆成 `useful_self`(个人记忆、未评审的项目草稿)和 `useful_team`(approved/published 的项目记忆)。只有显式信号会抬升有用侧:`memory_useful`(人确认它帮上忙时)、评审中的人为 approve、或一次 supersede。被动曝光永远不算有用——记忆只是出现在结果里,还不能说明任何事。同侧的人用入口:`open-memex useful <id...>`。计数器只存在本地 SQLite 索引里(不进 Markdown 文件、不出这台机器)。复用报告挂在 `memory_status`(以及 `open-memex sync-status`)上:各作用域的 retrieved/useful 比率(self/team 分开显示)、复用最多的记忆,以及"僵尸"——被检索过却从未被确认有用、即衰减/清理候选项(D77-L3)。superseded/deprecated 的记忆仍作为复用历史出现,但带生命周期标记,不会被当成当前指引。
310
310
 
311
311
  ## 记忆类型
312
312
 
@@ -431,6 +431,8 @@ npm install -g open-memex@latest # 或 @alpha
431
431
  "injectOnFirstTurn": true, // [OPEN-MEMEX] 系统提示块
432
432
  "keywordCaptureEnabled": true,
433
433
  "logLevel": "info", // info | debug
434
+ "graphOutline": true, // 会话开始时注入图谱编译大纲
435
+ "graphOutlineLines": 10, // 大纲长度上限(最大 30)
434
436
  "memoryDir": ".ai/open-memex" // 仓库内项目记忆目录,相对于仓库根
435
437
  }
436
438
  ```
@@ -441,9 +443,10 @@ npm install -g open-memex@latest # 或 @alpha
441
443
  open-memex config set keywordCaptureEnabled false
442
444
  open-memex config set maxProjectMemories 12
443
445
  open-memex config set sync.autoPull true # MCP 会话开始时尽力而为地 pull
446
+ open-memex config set graphOutline false # 不再注入图谱大纲
444
447
  ```
445
448
 
446
- 可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
449
+ 可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`、`graphOutline`、`graphOutlineLines`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
447
450
 
448
451
  ## CLI 参考
449
452
 
@@ -564,6 +567,8 @@ open-memex scopes # 列出各项目作用域及记忆计数
564
567
  open-memex reindex # 从 markdown 重建 SQLite 索引
565
568
  open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链、过期的工作状态笔记
566
569
  open-memex wstate # 显示工作状态笔记(--clear 删除)
570
+ open-memex graph build # 重建知识图谱(仅结构边;写入时自动刷新)
571
+ open-memex graph lint # 孤立节点、悬空边、近重复对(只报告,不自动处理)
567
572
  open-memex migrate --to-v2 [--dry-run] # v1 数据 → v2(把 user 作用域改名为 personal)
568
573
  ```
569
574
 
@@ -578,6 +583,22 @@ open-memex wstate # 显示笔记(含年龄与到期)
578
583
  open-memex wstate --clear # 删除
579
584
  ```
580
585
 
586
+ ## 知识图谱
587
+
588
+ 一张派生、可重建的图谱,覆盖**当前项目作用域**的记忆(D91,§20 确定性那一半)——不用搜索就能回答"记忆里有什么、彼此怎么连",且永远不碰 Markdown 真源。只抽取结构边、不调用 LLM:`supersedes` 取代链、`derived-from` propose 副本、`[[wiki-link]]` 正文链接(EXTRACTED)与裸 ULID 提及(INFERRED),以及共享标签的固定置信阶梯(1 个标签 → low,2 个 → medium,≥3 个 → high)。每条边都标注 `EXTRACTED`(结构事实)或 `INFERRED`(启发式)并附推导凭据。
589
+
590
+ 图谱在每次写入记忆时自动刷新。一份**编译大纲**(medium+ 置信度的连通分量,带截断披露)会在会话开始时与工作状态笔记一起注入一次;用 `config set graphOutline false` 关闭,`graphOutlineLines` 调长度(默认 10,上限 30)。personal 作用域永不入图。
591
+
592
+ ```sh
593
+ open-memex graph build # 立即重建(写入会自动做)
594
+ open-memex graph outline # 编译后的大纲(即注入内容)
595
+ open-memex graph neighbours <id> [--depth 1-6] # BFS,带每条边的来源
596
+ open-memex graph path <a> <b> # 最短跳链,带凭据
597
+ open-memex graph lint [--json] # 孤立节点、悬空边、近陈旧对
598
+ ```
599
+
600
+ `lint` 只报告——不自动处理,由人决定。同一份报告就是 D78 提交前策展的既定输入。接口仅限 CLI;MCP 表面保持十三个记忆工具不变。
601
+
581
602
  ## MCP 服务器
582
603
 
583
604
  同一组记忆工具,走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
package/dist/.build-stamp CHANGED
@@ -1 +1 @@
1
- a8f61bc31b972df3523d0cebe5e6664a9adc28108162385725a004ee6b116656
1
+ 1a872598f56a092aab47264914caf532b86c553e96a92f73333742e4e0d9588b
package/dist/cli.js CHANGED
@@ -10,7 +10,8 @@ import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatR
10
10
  import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
11
11
  import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
12
12
  import { search, list, countList, hitStateLabel } from "./retrieve/search.js";
13
- import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage } from "./store/usage.js";
13
+ import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage, loadReuseReport } from "./store/usage.js";
14
+ import { formatReuseReport } from "./reuse-report.js";
14
15
  import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.js";
15
16
  import { formatInventoryLine, truncationNote } from "./retrieve/display.js";
16
17
  import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, } from "./store/markdown.js";
@@ -18,6 +19,9 @@ import { loadConfig, configSource } from "./config.js";
18
19
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
19
20
  import { redact } from "./redact.js";
20
21
  import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.js";
22
+ import { refreshGraph, refreshGraphQuiet, ensureGraph, loadGraphEdges, loadGraphNodes, loadAllMemoryIds } from "./store/graph.js";
23
+ import { graphNeighbours, shortestPath } from "./graph/queries.js";
24
+ import { lintGraph } from "./graph/lint.js";
21
25
  import { resolveMcpCommand } from "./init.js";
22
26
  import fs from "node:fs";
23
27
  import path from "node:path";
@@ -206,7 +210,9 @@ Examples:
206
210
  open-memex resolve 01ABC`,
207
211
  "sync-status": `Show the project memory sync pipeline: when the index last synced
208
212
  and what triggered it, drafts waiting in the outbox (appdata), memories in the
209
- repo awaiting review or published, and repo files not yet committed.
213
+ repo awaiting review or published, and repo files not yet committed. The
214
+ D77 reuse report follows: per-scope retrieved/useful rates, most-reused
215
+ memories, and "zombies" (retrieved but never confirmed useful).
210
216
 
211
217
  Usage: open-memex sync-status
212
218
 
@@ -418,6 +424,31 @@ Flags:
418
424
 
419
425
  Example:
420
426
  open-memex audit --scope both`,
427
+ graph: `Work with the compiled memory graph (§20, D88/D91) — a derived layer
428
+ of structural edges between memories, rebuilt from the Markdown source of
429
+ truth, never hand-edited.
430
+
431
+ Usage:
432
+ open-memex graph build rebuild edges + the compiled outline for this project
433
+ open-memex graph neighbours <id> [--depth N] neighbours via BFS (default 1, max 6)
434
+ open-memex graph path <idA> <idB> [--depth N] shortest path (default 4, max 6)
435
+ open-memex graph lint [--json] health check: orphans, dangling refs, stale chains
436
+ open-memex graph outline print the compiled outline as it is injected
437
+
438
+ Every hop reports its edge type, provenance and confidence — EXTRACTED
439
+ means the link was explicit in the source (a supersede chain, a
440
+ derived-from copy, or the body mentioning the other memory's id);
441
+ INFERRED means the system noticed it (shared tags). Inferred links are
442
+ suggestions, never facts that were in the source.
443
+
444
+ Writes (add / supersede / forget / propose / promote) refresh the graph
445
+ automatically; graph build is the manual repair. Lint only reports.
446
+
447
+ Examples:
448
+ open-memex graph build
449
+ open-memex graph neighbours 01ABC --depth 2
450
+ open-memex graph path 01ABC 01DEF
451
+ open-memex graph lint`,
421
452
  wstate: `Show the project's session working-state note (D89, §3.6) — the
422
453
  ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
423
454
  can resume. The file itself is plain Markdown and editable directly.
@@ -457,6 +488,7 @@ Usage:
457
488
  open-memex pr-status [--apply]
458
489
  open-memex reindex
459
490
  open-memex audit [--scope project|personal|both]
491
+ open-memex graph <build|neighbours <id>|path <a> <b>|lint|outline> [--depth N] [--json]
460
492
  open-memex wstate [--clear]
461
493
  open-memex scopes
462
494
  open-memex migrate [--from <key>] [--to <key>]
@@ -815,6 +847,135 @@ async function main() {
815
847
  }
816
848
  return;
817
849
  }
850
+ // D91: the graph surface (§20 deterministic half). Project scope only —
851
+ // the graph covers the cwd's project scope like every other command;
852
+ // no --scope flag exists because personal has no reader this iteration.
853
+ if (cmd === "graph") {
854
+ const sub = rest[0] ?? "";
855
+ const flags = parseFlags(rest.slice(1));
856
+ // --depth is opt-in per command: neighbours defaults to 1, path to 4,
857
+ // and an explicit flag is clamped to [1, 6]. Absent = undefined so the
858
+ // default reads cleanly where it is applied.
859
+ const depth = (() => {
860
+ if (flags.depth === undefined || flags.depth === "true")
861
+ return undefined;
862
+ const n = Number(flags.depth);
863
+ if (!Number.isInteger(n) || n < 1 || n > 6)
864
+ return undefined;
865
+ return n;
866
+ })();
867
+ const syncThen = (fn) => {
868
+ syncScope(project.key, "cli");
869
+ fn();
870
+ };
871
+ if (sub === "build") {
872
+ syncThen(() => {
873
+ const s = refreshGraph(project.key, cfg);
874
+ console.log(`graph built for ${s.scopeKey}: ${s.nodes} memories, ${s.edges} edges, ` +
875
+ `${s.topics} topic(s), outline ${s.outlineLines} line(s)`);
876
+ });
877
+ return;
878
+ }
879
+ if (sub === "neighbours") {
880
+ const id = rest[1];
881
+ if (!id)
882
+ usage();
883
+ syncThen(() => {
884
+ ensureGraph(project.key, cfg);
885
+ const nodes = loadGraphNodes(project.key);
886
+ if (!nodes.some((n) => n.id === id)) {
887
+ console.error(`neighbours: no memory with id ${id} in scope ${project.key} — graph findings never invent nodes.`);
888
+ process.exit(1);
889
+ }
890
+ const hits = graphNeighbours(id, loadGraphEdges(project.key), nodes.map((n) => n.id), {
891
+ maxDepth: depth ?? 1,
892
+ });
893
+ if (hits.length === 0) {
894
+ const status = nodes.find((n) => n.id === id).status;
895
+ console.log(status === "active"
896
+ ? `no structural neighbours within depth ${depth ?? 1} — this memory is currently an orphan (see \`graph lint\`).`
897
+ : `no structural neighbours within depth ${depth ?? 1} for this ${status} memory.`);
898
+ return;
899
+ }
900
+ for (const h of hits) {
901
+ const n = nodes.find((x) => x.id === h.id);
902
+ console.log(`- ${h.id} (depth ${h.depth}) ${h.via.type} ${h.via.provenance}/${h.via.confidence} (${h.via.via})` +
903
+ ` [${n.status}] ${n.body.replace(/\s+/g, " ").trim().slice(0, 120)}`);
904
+ }
905
+ });
906
+ return;
907
+ }
908
+ if (sub === "path") {
909
+ const a = rest[1];
910
+ const b = rest[2];
911
+ if (!a || !b)
912
+ usage();
913
+ syncThen(() => {
914
+ ensureGraph(project.key, cfg);
915
+ const nodes = loadGraphNodes(project.key);
916
+ for (const id of [a, b]) {
917
+ if (!nodes.some((n) => n.id === id)) {
918
+ console.error(`path: no memory with id ${id} in scope ${project.key}.`);
919
+ process.exit(1);
920
+ }
921
+ }
922
+ const p = shortestPath(a, b, loadGraphEdges(project.key), nodes.map((n) => n.id), {
923
+ maxDepth: depth ?? 4,
924
+ });
925
+ if (!p.found) {
926
+ console.log(`no path found between ${a} and ${b} within depth ${depth ?? 4}. Weaker links (single shared tags) exist outside the built edge cap — \`graph neighbours\` per side may still connect them.`);
927
+ return;
928
+ }
929
+ console.log(`${a} [${nodes.find((n) => n.id === a).status}]`);
930
+ for (const h of p.hops) {
931
+ console.log(` --(${h.type} ${h.provenance}/${h.confidence} via ${h.via})-->`);
932
+ console.log(`${h.to} [${nodes.find((n) => n.id === h.to).status}]`);
933
+ }
934
+ });
935
+ return;
936
+ }
937
+ if (sub === "lint") {
938
+ syncThen(() => {
939
+ ensureGraph(project.key, cfg);
940
+ // Cross-scope ids (e.g. a propose copy's personal original) are not
941
+ // findings — lint skips endpoints the store knows about.
942
+ const f = lintGraph(loadGraphNodes(project.key), loadGraphEdges(project.key), loadAllMemoryIds());
943
+ const counts = {
944
+ orphan: 0,
945
+ "dangling-edge": 0,
946
+ stale: 0,
947
+ };
948
+ for (const x of f)
949
+ counts[x.kind]++;
950
+ if (flags.json === "true") {
951
+ console.log(JSON.stringify({ findings: f, counts }, null, 2));
952
+ return;
953
+ }
954
+ console.log(`graph lint (${project.key}): ${f.length} finding(s) — orphans ${counts.orphan}, dangling ${counts["dangling-edge"]}, stale ${counts.stale}. Reports only — a human decides; nothing is auto-resolved.`);
955
+ for (const x of f) {
956
+ console.log(` [${x.kind}] ${x.id}${x.other ? ` ↔ ${x.other}` : ""}: ${x.detail}`);
957
+ }
958
+ if (f.length > 0) {
959
+ console.log(`feed these to the review flow when curating; D78's pre-submit lint consumes the same report later.`);
960
+ }
961
+ });
962
+ return;
963
+ }
964
+ if (sub === "outline") {
965
+ syncThen(() => {
966
+ const g = ensureGraph(project.key, cfg);
967
+ if (!g || !g.outline) {
968
+ console.log("no compiled outline for this scope yet — `graph build` creates one.");
969
+ return;
970
+ }
971
+ console.log(`outline built ${g.builtAt} (${g.nodes} memories / ${g.edges} edges):`);
972
+ for (const line of g.outline.split("\n"))
973
+ console.log(line);
974
+ });
975
+ return;
976
+ }
977
+ usage();
978
+ }
818
979
  // `config` prints the effective configuration (defaults + file). No DB needed.
819
980
  // `config set <key> <value>` persists a setting to the config file.
820
981
  if (cmd === "config") {
@@ -1078,6 +1239,8 @@ async function main() {
1078
1239
  const mf = readMemoryFile(filePath);
1079
1240
  if (mf)
1080
1241
  upsertFromFile(mf);
1242
+ // D91 ingest: refresh the project graph quietly (personal no-ops inside).
1243
+ refreshGraphQuiet(s.key, cfg);
1081
1244
  console.log(`saved ${fm.id} [${s.kind}] -> ${filePath}`);
1082
1245
  if (hadSecret) {
1083
1246
  console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
@@ -1111,6 +1274,7 @@ async function main() {
1111
1274
  });
1112
1275
  upsertFromFile(oldMf);
1113
1276
  upsertFromFile(newMf);
1277
+ refreshGraphQuiet(oldMf.fm.scope_key, cfg);
1114
1278
  console.log(`superseded ${oldMf.fm.id} → ${newMf.fm.id}`);
1115
1279
  if (hadSecret) {
1116
1280
  console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
@@ -1130,6 +1294,7 @@ async function main() {
1130
1294
  try {
1131
1295
  const mf = setStatus(id, st);
1132
1296
  upsertFromFile(mf);
1297
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1133
1298
  console.log(`status ${id} → ${mf.fm.status}`);
1134
1299
  }
1135
1300
  catch (e) {
@@ -1145,10 +1310,11 @@ async function main() {
1145
1310
  // D68: --soft hides (retracts) instead of deleting — same action as
1146
1311
  // the memory_forget tool's soft flag. One-way (D64).
1147
1312
  if (rest.includes("--soft")) {
1148
- const target = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
1313
+ const target = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id);
1149
1314
  try {
1150
1315
  const mf = setStatus(id, "retracted");
1151
1316
  upsertFromFile(mf);
1317
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1152
1318
  console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
1153
1319
  // D70: same honesty as the hard delete — a retraction of an in-repo
1154
1320
  // memory is a local working-tree edit until it is committed and pushed.
@@ -1162,7 +1328,7 @@ async function main() {
1162
1328
  }
1163
1329
  return;
1164
1330
  }
1165
- const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
1331
+ const row = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id);
1166
1332
  if (!row) {
1167
1333
  console.error("not found");
1168
1334
  process.exit(1);
@@ -1183,6 +1349,8 @@ async function main() {
1183
1349
  }
1184
1350
  }
1185
1351
  deleteFromIndex(id);
1352
+ // D91 ingest: the node left the graph — refresh its scope quietly.
1353
+ refreshGraphQuiet(row.scope_key);
1186
1354
  // D77-L2: hard forget prunes the usage row with the memory (the tool
1187
1355
  // path does the same); branch-switch removals go through syncScope and
1188
1356
  // keep counters for that reason.
@@ -1400,6 +1568,16 @@ async function main() {
1400
1568
  syncScope(PERSONAL_SCOPE.key, "cli");
1401
1569
  try {
1402
1570
  console.log(formatSyncStatus(getSyncStatus(), { cap: Number.POSITIVE_INFINITY }));
1571
+ // D77-L3: same reuse block as the memory_status tool, uncapped (a
1572
+ // human asked; the CLI is where the full list lives).
1573
+ const reuse = loadReuseReport([
1574
+ { scopeKey: project.key, label: "this project" },
1575
+ { scopeKey: PERSONAL_SCOPE.key, label: "personal" },
1576
+ ], { topLimit: Number.POSITIVE_INFINITY, zombieLimit: Number.POSITIVE_INFINITY });
1577
+ console.log("");
1578
+ for (const line of formatReuseReport(reuse, { entryCap: Number.POSITIVE_INFINITY })) {
1579
+ console.log(line);
1580
+ }
1403
1581
  }
1404
1582
  catch (e) {
1405
1583
  console.error(`sync-status failed: ${e.message}`);
package/dist/config.js CHANGED
@@ -9,6 +9,8 @@ export const DEFAULT_CONFIG = {
9
9
  captureAliases: true,
10
10
  workingStateEnabled: true,
11
11
  workingStateTtlDays: 7,
12
+ graphOutline: true,
13
+ graphOutlineLines: 10,
12
14
  keywordPatterns: [
13
15
  "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
14
16
  "^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -159,6 +161,15 @@ export const SETTABLE_KEYS = {
159
161
  throw new Error("must be a positive integer (days)");
160
162
  return n;
161
163
  },
164
+ graphOutline: toBool,
165
+ graphOutlineLines: (v) => {
166
+ const n = toNonNegInt(v);
167
+ if (n < 1)
168
+ throw new Error("must be a positive integer (topic lines)");
169
+ if (n > 30)
170
+ throw new Error("must be 30 or less — the injected outline stays compact");
171
+ return n;
172
+ },
162
173
  memoryDir: toRelativeDir,
163
174
  "sync.autoPull": toBool,
164
175
  logLevel: (v) => {