open-memex 0.9.0-alpha.3 → 0.9.0

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.
package/AGENTS.md CHANGED
@@ -39,6 +39,7 @@ npm run cli -- sync-status # last sync time/kin
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
@@ -186,11 +187,35 @@ 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
- `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:
216
+ `docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D91 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
192
217
  AGENTS.md answers "how should AI work here"; the design doc answers "why is it
193
- built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D88). Before changing
218
+ built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D91). Before changing
194
219
  architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
195
220
  schema, MCP tools, CLI contract), read the relevant design section — the decision
196
221
  log records what was already considered and rejected.
package/CHANGELOG.md CHANGED
@@ -9,17 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
- ## [0.9.0-alpha.3] - 2026-11-04
12
+ ## [0.9.0] - 2026-11-06
13
13
 
14
- - 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).
15
-
16
- ## [0.9.0-alpha.2] - 2026-11-03
14
+ - Session working-state note (D89 → D90, new minor line): one ephemeral per-project Markdown note for resuming an interrupted task — task summary, open files, last commands, where the work stands, next step. The agent writes it at wrap-up via the new **`memory_workingstate`** tool (now the **twelve** tools on both the opencode plugin and the MCP server), it surfaces once at session start next to the first-turn injection (framed as scratch, never knowledge), it never enters `memories/` or the retrieval index or the review ladder, and anything in it worth keeping goes through the normal propose-first flow. TTL defaults to 7 days (`workingStateTtlDays`; `workingStateEnabled` gates the whole feature — both flat keys, settable via `config set`). Expired notes stay silent at session start and are reported by `open-memex audit`; `open-memex wstate` (`--clear`) is the human surface. The write passes through `redact()` and `atomicWriteTextSync` like every path. One correction to D89's wording, recorded as D90: the opencode plugin API has no Stop hook, so the opencode write path is the instruction + tool branch (the agent refreshes the note when the user signals wrap-up); Claude Code's Stop hook waits for the Phase 2C native plugin.
17
15
 
18
- - 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.
16
+ - 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).
19
17
 
20
- ## [0.9.0-alpha.1] - 2026-11-03
18
+ - 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).
21
19
 
22
- - Session working-state note (D89 → D90, new minor line): one ephemeral per-project Markdown note for resuming an interrupted task — task summary, open files, last commands, where the work stands, next step. The agent writes it at wrap-up via the new **`memory_workingstate`** tool (now the **twelve** tools on both the opencode plugin and the MCP server), it surfaces once at session start next to the first-turn injection (framed as scratch, never knowledge), it never enters `memories/` or the retrieval index or the review ladder, and anything in it worth keeping goes through the normal propose-first flow. TTL defaults to 7 days (`workingStateTtlDays`; `workingStateEnabled` gates the whole feature — both flat keys, settable via `config set`). Expired notes stay silent at session start and are reported by `open-memex audit`; `open-memex wstate` (`--clear`) is the human surface. The write passes through `redact()` and `atomicWriteTextSync` like every path. One correction to D89's wording, recorded as D90: the opencode plugin API has no Stop hook, so the opencode write path is the instruction + tool branch (the agent refreshes the note when the user signals wrap-up); Claude Code's Stop hook waits for the Phase 2C native plugin.
20
+ - 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.
23
21
 
24
22
  ## [0.8.2] - 2026-10-28
25
23
 
package/README.md CHANGED
@@ -26,6 +26,10 @@ memory on your machine.
26
26
  a curated multilingual map of equivalents is indexed with every memory at
27
27
  write time, so no related wording misses the right answer. Deterministic
28
28
  and auditable, no embedding model required.
29
+ - **A map, not just search**: a derived knowledge graph connects your project
30
+ memories — supersedes chains, shared tags, explicit mentions — and injects
31
+ a compiled outline at session start, so the agent sees what's in memory
32
+ without searching. Structural edges only, no LLM.
29
33
 
30
34
  ![Terminal demo: two memories saved on Monday, recalled by search in a fresh session on Friday](./docs/assets/open-memex-demo.svg)
31
35
 
@@ -38,6 +42,7 @@ depth once you're up and running.
38
42
  - [Quick start](#quick-start)
39
43
  - [Core concepts](#core-concepts)
40
44
  - [Which editors, which features](#which-editors-which-features)
45
+ - [How it compares](#how-it-compares)
41
46
  - [Installation](#installation)
42
47
  - [Setting up your editor](#setting-up-your-editor)
43
48
  - [What `init` changes on your machine](#what-init-changes-on-your-machine)
@@ -52,6 +57,8 @@ depth once you're up and running.
52
57
  - [Storage layout](#storage-layout)
53
58
  - [Config](#config)
54
59
  - [CLI reference](#cli-reference)
60
+ - [Session working state](#session-working-state)
61
+ - [Knowledge graph](#knowledge-graph)
55
62
  - [MCP server](#mcp-server)
56
63
  - [Scopes, in detail](#scopes-in-detail)
57
64
  - [Troubleshooting](#troubleshooting)
@@ -697,6 +704,8 @@ Defaults:
697
704
  "injectOnFirstTurn": true, // [OPEN-MEMEX] system-prompt block
698
705
  "keywordCaptureEnabled": true,
699
706
  "logLevel": "info", // info | debug
707
+ "graphOutline": true, // inject the compiled graph outline at session start
708
+ "graphOutlineLines": 10, // outline length cap (max 30)
700
709
  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
701
710
  }
702
711
  ```
@@ -708,10 +717,12 @@ setting after install:
708
717
  open-memex config set keywordCaptureEnabled false
709
718
  open-memex config set maxProjectMemories 12
710
719
  open-memex config set sync.autoPull true # best-effort pull at MCP session start
720
+ open-memex config set graphOutline false # stop injecting the graph outline
711
721
  ```
712
722
 
713
723
  Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
714
- `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
724
+ `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
725
+ `graphOutline`, `graphOutlineLines`, and `sync.autoPull` (a dotted
715
726
  key that writes into the nested `sync` object). Full design:
716
727
  [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
717
728
 
@@ -854,6 +865,8 @@ open-memex scopes # list project scopes with memory counts
854
865
  open-memex reindex # rebuild the SQLite index from markdown
855
866
  open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
856
867
  open-memex wstate # show the session working-state note (--clear deletes it)
868
+ open-memex graph build # rebuild the knowledge graph (structural edges only; runs automatically on writes)
869
+ open-memex graph lint # orphans, dangling edges, near-duplicate pairs (reports only)
857
870
  open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
858
871
  ```
859
872
 
@@ -881,6 +894,35 @@ open-memex wstate # show the note (age + expiry)
881
894
  open-memex wstate --clear # delete it
882
895
  ```
883
896
 
897
+ ## Knowledge graph
898
+
899
+ A derived, rebuildable graph over the **current project's** memories (D91, §20
900
+ deterministic half) — it answers "what is in memory and how is it connected"
901
+ without searching, and it never touches the Markdown source of truth. Structural
902
+ edges only, no LLM: `supersedes` chains, `derived-from` propose copies,
903
+ `[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED),
904
+ and shared-tag co-membership at a fixed
905
+ confidence ladder (1 tag → low, 2 → medium, ≥3 → high). Every edge is marked
906
+ `EXTRACTED` (structural fact) or `INFERRED` (heuristic) with its receipt.
907
+
908
+ The graph refreshes automatically on every memory write. A **compiled outline**
909
+ (medium+ confidence components, capped and cut-disclosed) is injected once at
910
+ session start next to the working-state note; disable it with
911
+ `config set graphOutline false`, tune its length with `graphOutlineLines`
912
+ (default 10, max 30). Personal scope is never graphed.
913
+
914
+ ```sh
915
+ open-memex graph build # rebuild now (writes do this automatically)
916
+ open-memex graph outline # the compiled outline, as injected
917
+ open-memex graph neighbours <id> [--depth 1-6] # BFS with per-edge provenance
918
+ open-memex graph path <a> <b> # shortest hop chain, with receipts
919
+ open-memex graph lint [--json] # orphans, dangling edges, near-stale pairs
920
+ ```
921
+
922
+ `lint` reports only — nothing is auto-resolved; a human decides. The same report
923
+ is the planned input for D78's pre-submit curation. The interface is CLI-only;
924
+ the MCP surface stays at its thirteen memory tools.
925
+
884
926
  ## MCP server
885
927
 
886
928
  The same memory tools over the Model Context Protocol, via a stdio server —
package/README.zh-CN.md CHANGED
@@ -14,6 +14,7 @@
14
14
  - **本地优先**:记忆是纯 Markdown 文件(事实来源),外加一个可重建的 SQLite 关键词索引。除非你明确要分享,否则任何东西都不会离开你的机器。
15
15
  - **一份记忆,所有助手**:一条命令把几个编辑器都接上,它们共享同一份记忆,不再各存一份互不可见。
16
16
  - **精确的同义词检索**:`ship` 找得到 `deploy`,`单点登录` 找得到 `SSO`——一份多语言的精选同义词映射表在写入时展开进索引,任何相关词语都不会漏掉正确答案。确定性、可审计,不需要下载模型。
17
+ - **知识图谱,不只会搜**:一张派生图谱把项目记忆连起来(取代链、共享标签、显式引用),会话开始时注入一份编译大纲——不用搜索就知道记忆里有什么、彼此怎么连。只抽结构边,不调用 LLM。
17
18
 
18
19
  ![终端演示:周一存下的两条记忆,周五在新会话里被搜索召回](./docs/assets/open-memex-demo.svg)
19
20
 
@@ -24,6 +25,7 @@
24
25
  - [快速开始](#快速开始)
25
26
  - [核心概念](#核心概念)
26
27
  - [编辑器与功能对照](#编辑器与功能对照)
28
+ - [和别的方案比](#和别的方案比)
27
29
  - [安装](#安装)
28
30
  - [为你的编辑器做设置](#为你的编辑器做设置)
29
31
  - [init 到底改了你机器上的什么](#init-到底改了你机器上的什么)
@@ -38,6 +40,8 @@
38
40
  - [存储布局](#存储布局)
39
41
  - [配置](#配置)
40
42
  - [CLI 参考](#cli-参考)
43
+ - [工作状态笔记](#工作状态笔记)
44
+ - [知识图谱](#知识图谱)
41
45
  - [MCP 服务器](#mcp-服务器)
42
46
  - [作用域详解](#作用域详解)
43
47
  - [故障排查](#故障排查)
@@ -431,6 +435,8 @@ npm install -g open-memex@latest # 或 @alpha
431
435
  "injectOnFirstTurn": true, // [OPEN-MEMEX] 系统提示块
432
436
  "keywordCaptureEnabled": true,
433
437
  "logLevel": "info", // info | debug
438
+ "graphOutline": true, // 会话开始时注入图谱编译大纲
439
+ "graphOutlineLines": 10, // 大纲长度上限(最大 30)
434
440
  "memoryDir": ".ai/open-memex" // 仓库内项目记忆目录,相对于仓库根
435
441
  }
436
442
  ```
@@ -441,9 +447,10 @@ npm install -g open-memex@latest # 或 @alpha
441
447
  open-memex config set keywordCaptureEnabled false
442
448
  open-memex config set maxProjectMemories 12
443
449
  open-memex config set sync.autoPull true # MCP 会话开始时尽力而为地 pull
450
+ open-memex config set graphOutline false # 不再注入图谱大纲
444
451
  ```
445
452
 
446
- 可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
453
+ 可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`、`graphOutline`、`graphOutlineLines`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
447
454
 
448
455
  ## CLI 参考
449
456
 
@@ -564,6 +571,8 @@ open-memex scopes # 列出各项目作用域及记忆计数
564
571
  open-memex reindex # 从 markdown 重建 SQLite 索引
565
572
  open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链、过期的工作状态笔记
566
573
  open-memex wstate # 显示工作状态笔记(--clear 删除)
574
+ open-memex graph build # 重建知识图谱(仅结构边;写入时自动刷新)
575
+ open-memex graph lint # 孤立节点、悬空边、近重复对(只报告,不自动处理)
567
576
  open-memex migrate --to-v2 [--dry-run] # v1 数据 → v2(把 user 作用域改名为 personal)
568
577
  ```
569
578
 
@@ -578,6 +587,22 @@ open-memex wstate # 显示笔记(含年龄与到期)
578
587
  open-memex wstate --clear # 删除
579
588
  ```
580
589
 
590
+ ## 知识图谱
591
+
592
+ 一张派生、可重建的图谱,覆盖**当前项目作用域**的记忆(D91,§20 确定性那一半)——不用搜索就能回答"记忆里有什么、彼此怎么连",且永远不碰 Markdown 真源。只抽取结构边、不调用 LLM:`supersedes` 取代链、`derived-from` propose 副本、`[[wiki-link]]` 正文链接(EXTRACTED)与裸 ULID 提及(INFERRED),以及共享标签的固定置信阶梯(1 个标签 → low,2 个 → medium,≥3 个 → high)。每条边都标注 `EXTRACTED`(结构事实)或 `INFERRED`(启发式)并附推导凭据。
593
+
594
+ 图谱在每次写入记忆时自动刷新。一份**编译大纲**(medium+ 置信度的连通分量,带截断披露)会在会话开始时与工作状态笔记一起注入一次;用 `config set graphOutline false` 关闭,`graphOutlineLines` 调长度(默认 10,上限 30)。personal 作用域永不入图。
595
+
596
+ ```sh
597
+ open-memex graph build # 立即重建(写入会自动做)
598
+ open-memex graph outline # 编译后的大纲(即注入内容)
599
+ open-memex graph neighbours <id> [--depth 1-6] # BFS,带每条边的来源
600
+ open-memex graph path <a> <b> # 最短跳链,带凭据
601
+ open-memex graph lint [--json] # 孤立节点、悬空边、近陈旧对
602
+ ```
603
+
604
+ `lint` 只报告——不自动处理,由人决定。同一份报告就是 D78 提交前策展的既定输入。接口仅限 CLI;MCP 表面保持十三个记忆工具不变。
605
+
581
606
  ## MCP 服务器
582
607
 
583
608
  同一组记忆工具,走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
package/dist/.build-stamp CHANGED
@@ -1 +1 @@
1
- 507da63044e3c491b1ec5b7f077ccfbc492c986775ce97b77f172e5395fccca3
1
+ 1a872598f56a092aab47264914caf532b86c553e96a92f73333742e4e0d9588b
package/dist/cli.js CHANGED
@@ -19,6 +19,9 @@ import { loadConfig, configSource } from "./config.js";
19
19
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
20
20
  import { redact } from "./redact.js";
21
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";
22
25
  import { resolveMcpCommand } from "./init.js";
23
26
  import fs from "node:fs";
24
27
  import path from "node:path";
@@ -421,6 +424,31 @@ Flags:
421
424
 
422
425
  Example:
423
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`,
424
452
  wstate: `Show the project's session working-state note (D89, §3.6) — the
425
453
  ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
426
454
  can resume. The file itself is plain Markdown and editable directly.
@@ -460,6 +488,7 @@ Usage:
460
488
  open-memex pr-status [--apply]
461
489
  open-memex reindex
462
490
  open-memex audit [--scope project|personal|both]
491
+ open-memex graph <build|neighbours <id>|path <a> <b>|lint|outline> [--depth N] [--json]
463
492
  open-memex wstate [--clear]
464
493
  open-memex scopes
465
494
  open-memex migrate [--from <key>] [--to <key>]
@@ -818,6 +847,135 @@ async function main() {
818
847
  }
819
848
  return;
820
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
+ }
821
979
  // `config` prints the effective configuration (defaults + file). No DB needed.
822
980
  // `config set <key> <value>` persists a setting to the config file.
823
981
  if (cmd === "config") {
@@ -1081,6 +1239,8 @@ async function main() {
1081
1239
  const mf = readMemoryFile(filePath);
1082
1240
  if (mf)
1083
1241
  upsertFromFile(mf);
1242
+ // D91 ingest: refresh the project graph quietly (personal no-ops inside).
1243
+ refreshGraphQuiet(s.key, cfg);
1084
1244
  console.log(`saved ${fm.id} [${s.kind}] -> ${filePath}`);
1085
1245
  if (hadSecret) {
1086
1246
  console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
@@ -1114,6 +1274,7 @@ async function main() {
1114
1274
  });
1115
1275
  upsertFromFile(oldMf);
1116
1276
  upsertFromFile(newMf);
1277
+ refreshGraphQuiet(oldMf.fm.scope_key, cfg);
1117
1278
  console.log(`superseded ${oldMf.fm.id} → ${newMf.fm.id}`);
1118
1279
  if (hadSecret) {
1119
1280
  console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
@@ -1133,6 +1294,7 @@ async function main() {
1133
1294
  try {
1134
1295
  const mf = setStatus(id, st);
1135
1296
  upsertFromFile(mf);
1297
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1136
1298
  console.log(`status ${id} → ${mf.fm.status}`);
1137
1299
  }
1138
1300
  catch (e) {
@@ -1148,10 +1310,11 @@ async function main() {
1148
1310
  // D68: --soft hides (retracts) instead of deleting — same action as
1149
1311
  // the memory_forget tool's soft flag. One-way (D64).
1150
1312
  if (rest.includes("--soft")) {
1151
- 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);
1152
1314
  try {
1153
1315
  const mf = setStatus(id, "retracted");
1154
1316
  upsertFromFile(mf);
1317
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1155
1318
  console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
1156
1319
  // D70: same honesty as the hard delete — a retraction of an in-repo
1157
1320
  // memory is a local working-tree edit until it is committed and pushed.
@@ -1165,7 +1328,7 @@ async function main() {
1165
1328
  }
1166
1329
  return;
1167
1330
  }
1168
- 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);
1169
1332
  if (!row) {
1170
1333
  console.error("not found");
1171
1334
  process.exit(1);
@@ -1186,6 +1349,8 @@ async function main() {
1186
1349
  }
1187
1350
  }
1188
1351
  deleteFromIndex(id);
1352
+ // D91 ingest: the node left the graph — refresh its scope quietly.
1353
+ refreshGraphQuiet(row.scope_key);
1189
1354
  // D77-L2: hard forget prunes the usage row with the memory (the tool
1190
1355
  // path does the same); branch-switch removals go through syncScope and
1191
1356
  // keep counters for that reason.
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) => {