open-memex 0.9.0-alpha.3 → 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.
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,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,6 +9,8 @@ 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
+
12
14
  ## [0.9.0-alpha.3] - 2026-11-04
13
15
 
14
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).
package/README.md CHANGED
@@ -697,6 +697,8 @@ Defaults:
697
697
  "injectOnFirstTurn": true, // [OPEN-MEMEX] system-prompt block
698
698
  "keywordCaptureEnabled": true,
699
699
  "logLevel": "info", // info | debug
700
+ "graphOutline": true, // inject the compiled graph outline at session start
701
+ "graphOutlineLines": 10, // outline length cap (max 30)
700
702
  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
701
703
  }
702
704
  ```
@@ -708,10 +710,12 @@ setting after install:
708
710
  open-memex config set keywordCaptureEnabled false
709
711
  open-memex config set maxProjectMemories 12
710
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
711
714
  ```
712
715
 
713
716
  Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
714
- `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
717
+ `keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
718
+ `graphOutline`, `graphOutlineLines`, and `sync.autoPull` (a dotted
715
719
  key that writes into the nested `sync` object). Full design:
716
720
  [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
717
721
 
@@ -854,6 +858,8 @@ open-memex scopes # list project scopes with memory counts
854
858
  open-memex reindex # rebuild the SQLite index from markdown
855
859
  open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
856
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)
857
863
  open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
858
864
  ```
859
865
 
@@ -881,6 +887,35 @@ open-memex wstate # show the note (age + expiry)
881
887
  open-memex wstate --clear # delete it
882
888
  ```
883
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
+
884
919
  ## MCP server
885
920
 
886
921
  The same memory tools over the Model Context Protocol, via a stdio server —
package/README.zh-CN.md CHANGED
@@ -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
- 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) => {