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.
@@ -36,6 +36,10 @@ import { z } from "zod";
36
36
  import { memoryAddArgs } from "../src/tools/ops.ts";
37
37
  import { dataRootPath, homeOverride } from "../src/paths.ts";
38
38
  import { configFilePath, loadConfig, stripJsonComments } from "../src/config.ts";
39
+ import { extractEdges, sharedTagConfidence } from "../src/graph/extract.ts";
40
+ import { renderOutline } from "../src/graph/outline.ts";
41
+ import { graphNeighbours, shortestPath } from "../src/graph/queries.ts";
42
+ import { lintGraph } from "../src/graph/lint.ts";
39
43
 
40
44
  console.log("== jsonc parsing + config invariants (P0) ==");
41
45
  {
@@ -1099,5 +1103,204 @@ console.log("== D77-L3 reuse report formatting ==")
1099
1103
  );
1100
1104
  }
1101
1105
 
1106
+ console.log("== D91 graph: extract / outline / queries / lint ==");
1107
+ {
1108
+ // Deterministic twenty-six-char Crockford ids (no I, L, O, U) so test
1109
+ // bodies can embed real id mentions.
1110
+ const ID_A = "01AAAAAAAAAAAAAAAAAAAAAAAA";
1111
+ const ID_B = "01BBBBBBBBBBBBBBBBBBBBBBBB";
1112
+ const ID_C = "01CCCCCCCCCCCCCCCCCCCCCCCC";
1113
+ const ID_D = "01DDDDDDDDDDDDDDDDDDDDDDDD";
1114
+ const ID_E = "01EEEEEEEEEEEEEEEEEEEEEEEE";
1115
+ const node = (over: Partial<Parameters<typeof extractEdges>[0][number]> & { id: string }) => ({
1116
+ status: "active",
1117
+ type: "fact",
1118
+ tags: [] as string[],
1119
+ body: "",
1120
+ supersedes: null,
1121
+ derived_from: null,
1122
+ ...over,
1123
+ });
1124
+
1125
+ ok("confidence ladder: 1→low, 2→medium, ≥3→high (fixed by D91)",
1126
+ sharedTagConfidence(1) === "low" && sharedTagConfidence(2) === "medium" && sharedTagConfidence(3) === "high" && sharedTagConfidence(9) === "high");
1127
+
1128
+ {
1129
+ const edges = extractEdges([
1130
+ node({ id: ID_B, supersedes: ID_A }),
1131
+ node({ id: ID_A }),
1132
+ node({ id: ID_C, derived_from: ID_A }),
1133
+ ]);
1134
+ ok("supersedes edge new→old EXTRACTED/high",
1135
+ edges.some((e) => e.from === ID_B && e.to === ID_A && e.type === "supersedes" && e.provenance === "EXTRACTED" && e.confidence === "high"));
1136
+ ok("derived-from edge EXTRACTED/high",
1137
+ edges.some((e) => e.from === ID_C && e.to === ID_A && e.type === "derived-from" && e.provenance === "EXTRACTED"));
1138
+ }
1139
+
1140
+ {
1141
+ const edges = extractEdges([
1142
+ node({ id: ID_A, body: `see [[${ID_B}]] for the checklist` }),
1143
+ node({ id: ID_B, tags: ["deploy", "ci"] }),
1144
+ node({ id: ID_C, tags: ["deploy", "ci"] }),
1145
+ node({ id: ID_D, tags: ["deploy"] }),
1146
+ ]);
1147
+ ok("[[wiki-link]] mention is EXTRACTED/high relates-to",
1148
+ edges.some((e) => e.from === ID_A && e.to === ID_B && e.provenance === "EXTRACTED" && e.confidence === "high" && e.via === "wiki-link"));
1149
+ ok("two shared tags → INFERRED/medium, canonical pair order",
1150
+ edges.some((e) => e.from === ID_B && e.to === ID_C && e.provenance === "INFERRED" && e.confidence === "medium" && e.via === "shared-tag:ci,deploy"));
1151
+ ok("one shared tag → INFERRED/low",
1152
+ edges.some((e) => ((e.from === ID_B && e.to === ID_D) || (e.from === ID_C && e.to === ID_D)) && e.provenance === "INFERRED" && e.confidence === "low"));
1153
+ }
1154
+
1155
+ {
1156
+ // A bare ULID in prose is an INFERRED edge (D91/§20.3): the writer
1157
+ // typed an id but did not mark it as a link, so it is never presented
1158
+ // as evidence the source stated a relationship.
1159
+ const edges = extractEdges([
1160
+ node({ id: ID_A, body: `follow up ${ID_B} when parser lands` }),
1161
+ node({ id: ID_B }),
1162
+ ]);
1163
+ ok("bare ULID mention is INFERRED/high relates-to",
1164
+ edges.some((e) => e.from === ID_A && e.to === ID_B && e.type === "relates-to" && e.provenance === "INFERRED" && e.confidence === "high" && e.via === "body-mention"),
1165
+ JSON.stringify(edges));
1166
+ }
1167
+
1168
+ {
1169
+ // Exhaustive collapse: an EXTRACTED body-mention wins the pair over
1170
+ // the INFERRED shared-tag edge.
1171
+ const edges = extractEdges([
1172
+ node({ id: ID_A, body: `as in [[${ID_B}]], deploy first`, tags: ["deploy", "ci", "ops"] }),
1173
+ node({ id: ID_B, tags: ["deploy", "ci", "ops"] }),
1174
+ ]);
1175
+ const rel = edges.filter((e) => e.type === "relates-to");
1176
+ ok("one relates-to per pair, EXTRACTED wins",
1177
+ rel.length === 1 && rel[0]!.from === ID_A && rel[0]!.to === ID_B && rel[0]!.provenance === "EXTRACTED",
1178
+ JSON.stringify(rel));
1179
+ }
1180
+
1181
+ {
1182
+ const edges = extractEdges([
1183
+ node({ id: ID_A, body: `self ${ID_A} ignore` }),
1184
+ node({ id: ID_B, status: "superseded", empty: undefined } as never),
1185
+ ]);
1186
+ ok("self-mention not extracted", !edges.some((e) => e.type === "relates-to" && e.from === ID_A));
1187
+ ok("superseded memory contributes no tag inference", edges.every((e) => e.provenance !== "INFERRED"));
1188
+ }
1189
+
1190
+ {
1191
+ // Crockford excludes L (as well as I/O/U): a 26-char all-caps word
1192
+ // containing L is a word, not an id — it must never become EXTRACTED
1193
+ // evidence. Regression for the [0-9A-HJ-NP-TV-Z] class bug.
1194
+ const edges = extractEdges([
1195
+ node({ id: ID_A, body: "FLATBATTERYWELLSXXQZABCDEF flagged" }),
1196
+ node({ id: ID_B }),
1197
+ ]);
1198
+ ok(
1199
+ "L-containing 26-char word is not a body mention",
1200
+ !edges.some((e) => e.type === "relates-to" && e.from === ID_A),
1201
+ JSON.stringify(edges),
1202
+ );
1203
+ }
1204
+
1205
+ {
1206
+ // Determinism: the same build twice must agree byte for byte.
1207
+ const input = [
1208
+ node({ id: ID_A, tags: ["a", "b"], body: `ref ${ID_B}` }),
1209
+ node({ id: ID_B, tags: ["a", "b"] }),
1210
+ node({ id: ID_C, tags: ["b"] }),
1211
+ ];
1212
+ ok("two builds over the same data sort identically",
1213
+ JSON.stringify(extractEdges(input)) === JSON.stringify(extractEdges([...input].reverse())));
1214
+ }
1215
+
1216
+ console.log(" == outline: no universal-tag collapse ==");
1217
+ {
1218
+ // Five active memories all tagged "legacy" (a universal tag — every
1219
+ // pair shares exactly ONE tag, so every inferred pair edge is low);
1220
+ // plus two real topics via extra tags. Result: the store must NOT
1221
+ // fuse into one "legacy (5)" topic.
1222
+ const outlineNodes = [
1223
+ node({ id: ID_A, tags: ["legacy", "deploy", "ci"], body: "deploy is ci-gated", snippet: "deploy is ci-gated" }),
1224
+ node({ id: ID_B, tags: ["legacy", "deploy", "ci"], body: "deploy is manual", snippet: "deploy is manual" }),
1225
+ node({ id: ID_C, tags: ["legacy", "editor", "parser"], body: "editor parsing", snippet: "editor parsing" }),
1226
+ node({ id: ID_D, tags: ["legacy", "editor", "parser"], body: "parser rewrite", snippet: "parser rewrite" }),
1227
+ // Legacy-only: one shared tag is the low band, which never joins topics.
1228
+ node({ id: ID_E, tags: ["legacy"], body: `shared ${ID_B}` }),
1229
+ ];
1230
+ const outlineEdges = extractEdges(outlineNodes);
1231
+ ok("universal-tag pairs stay in the low band",
1232
+ outlineEdges
1233
+ .filter((e) => e.type === "relates-to" && e.via === "shared-tag:legacy")
1234
+ .every((e) => e.confidence === "low"),
1235
+ JSON.stringify(outlineEdges.filter((e) => e.provenance === "INFERRED").map((e) => e.via)));
1236
+ const r = renderOutline(outlineNodes, outlineEdges, { maxLines: 10 });
1237
+ ok("two distinct topics survive the universal tag",
1238
+ r.topics.length === 2 && r.topics.every((t) => t.name !== "legacy"),
1239
+ JSON.stringify(r.topics.map((t) => t.name)));
1240
+ ok("no topic spans five memories (the store did not fuse)",
1241
+ r.topics.every((t) => t.size === 2), r.lines.join("\n"));
1242
+ ok("legacy-only memory is outside every topic and disclosed",
1243
+ r.outsideCount === 1 && r.lines.some((l) => l.includes("1 memory not in any topic")),
1244
+ r.lines.join("\n"));
1245
+ ok("topic lines carry truncated one-liners", r.lines.some((l) => l.includes("deploy is manual")));
1246
+ ok("outline is capped in units of memory-not-topic disclosure",
1247
+ r.exposureIds.length > 0 && r.exposureIds.every((id) => r.topics.some((t) => t.snippetIds.includes(id))));
1248
+ }
1249
+
1250
+ console.log(" == outline: cap and disclosure ==");
1251
+ {
1252
+ const nodes: ReturnType<typeof node>[] = [];
1253
+ const edges: Parameters<typeof renderOutline>[1] = [];
1254
+ for (let i = 0; i < 4; i++) {
1255
+ const a = `${i}AAAAAAA${ID_A.slice(8)}`;
1256
+ const b = `${i}BBBBBBB${ID_B.slice(8)}`;
1257
+ nodes.push(node({ id: a, tags: [`t${i}`], body: "" }));
1258
+ nodes.push(node({ id: b, tags: [`t${i}`], body: "" }));
1259
+ edges.push({ from: a, to: b, type: "relates-to", provenance: "INFERRED", confidence: "medium", via: `shared-tag:t${i}` });
1260
+ }
1261
+ const r = renderOutline(nodes, edges, { maxLines: 2 });
1262
+ ok("cap respected", r.lines.length === 3); // 2 topics + the cut disclosure
1263
+ ok("cut disclosed", r.lines.some((l) => l.includes("2 more topics not shown")));
1264
+ }
1265
+
1266
+ console.log(" == queries ==");
1267
+ {
1268
+ const nodeIds = [ID_A, ID_B, ID_C, ID_D];
1269
+ const edges: Parameters<typeof graphNeighbours>[1] = [
1270
+ { from: ID_A, to: ID_B, type: "relates-to", provenance: "EXTRACTED", confidence: "high", via: "body-mention" },
1271
+ { from: ID_B, to: ID_C, type: "relates-to", provenance: "INFERRED", confidence: "medium", via: "shared-tag:deploy" },
1272
+ { from: ID_C, to: ID_E as never, type: "relates-to", provenance: "EXTRACTED", confidence: "high", via: "body-mention" },
1273
+ ];
1274
+ const nb = graphNeighbours(ID_A, edges, nodeIds, { maxDepth: 1 });
1275
+ ok("depth-1 neighbour traversal", nb.length === 1 && nb[0]!.id === ID_B && nb[0]!.via.provenance === "EXTRACTED");
1276
+ const nb2 = graphNeighbours(ID_A, edges, nodeIds, { maxDepth: 2 });
1277
+ ok("depth-2 reaches two hops", nb2.length === 2 && nb2[1]!.id === ID_C && nb2[1]!.via.provenance === "INFERRED");
1278
+ const p = shortestPath(ID_A, ID_C, edges, nodeIds);
1279
+ ok("shortest path found through the chain with edge receipts",
1280
+ p.found && p.hops.length === 2 && p.hops[0]!.from === ID_A && p.hops[1]!.to === ID_C,
1281
+ JSON.stringify(p));
1282
+ const miss = shortestPath(ID_A, "01ZZZZZZZZZZZZZZZZZZZZZZZZ", edges, nodeIds);
1283
+ ok("path to a node outside the set fails cleanly", !miss.found && miss.hops.length === 0);
1284
+ const dangling = graphNeighbours(ID_A, edges, nodeIds, { maxDepth: 3 });
1285
+ ok("traversal never crosses into a missing node", !dangling.some((h) => h.id === ID_E));
1286
+ }
1287
+
1288
+ console.log(" == lint ==");
1289
+ {
1290
+ const nodeIds: Parameters<typeof lintGraph>[0] = [
1291
+ node({ id: ID_A, body: "deploy checklist: build, sign, upload" }),
1292
+ node({ id: ID_B, status: "superseded", body: "deploy checklist: build, sign, upload" }),
1293
+ node({ id: ID_C }),
1294
+ ];
1295
+ const edges: Parameters<typeof lintGraph>[1] = [
1296
+ { from: ID_C, to: "01FFFFFFFFFFFFFFFFFFFFFFFF", type: "relates-to", provenance: "EXTRACTED", confidence: "high", via: "body-mention" },
1297
+ ];
1298
+ const f = lintGraph(nodeIds, edges);
1299
+ ok("orphan reported for the active, unlinked memory", f.some((x) => x.kind === "orphan" && x.id === ID_A));
1300
+ ok("dangling edge reported with the missing id", f.some((x) => x.kind === "dangling-edge" && x.other === "01FFFFFFFFFFFFFFFFFFFFFFFF"));
1301
+ ok("stale detected: active near-duplicate of superseded", f.some((x) => x.kind === "stale" && x.id === ID_A && x.other === ID_B));
1302
+ }
1303
+ }
1304
+
1102
1305
  console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
1103
1306
  process.exit(fails === 0 ? 0 : 1);
@@ -460,8 +460,8 @@ ok("migrate personal→project runs", r.code === 0, (r.err || r.out).slice(0, 15
460
460
  const ver = (after.prepare("PRAGMA user_version").get() as { user_version: number }).user_version;
461
461
  const cols = (after.prepare("PRAGMA table_info(memories)").all() as { name: string }[]).map((c) => c.name);
462
462
  after.close();
463
- ok("D87: stale store migrates to schema v9", ver === 9, `user_version=${ver}`);
464
- ok("D87: migrated table has alias/target/expansions", ["alias", "target", "expansions"].every((c) => cols.includes(c)), cols.join(","));
463
+ ok("D87: stale store migrates to current schema (v10 since D91)", ver === 10, `user_version=${ver}`);
464
+ ok("D87: migrated table has alias/target/expansions/derived_from", ["alias", "target", "expansions", "derived_from"].every((c) => cols.includes(c)), cols.join(","));
465
465
  }
466
466
 
467
467
  // ---------- 10. capture / doctor / mcp --print-config / init ----------
@@ -936,7 +936,7 @@ ${body}
936
936
  {
937
937
  const D = createRequire(import.meta.url)("better-sqlite3");
938
938
  const conn = new D(dbPath);
939
- conn.exec("PRAGMA user_version = 8");
939
+ conn.exec("PRAGMA user_version = 9"); // stale only vs the current v10 (D91)
940
940
  conn.close();
941
941
  cliRetry(["list"], d77Proj); // opens db() -> rebuildIndexSchema -> syncScope
942
942
  const after = new D(dbPath, { readonly: true });
@@ -946,7 +946,7 @@ ${body}
946
946
  const usage = after
947
947
  .prepare("SELECT retrieved_count, useful_self, useful_team FROM memory_usage WHERE id = ?")
948
948
  .get(uId) as { retrieved_count: number; useful_self: number; useful_team: number } | undefined;
949
- ok("forced schema rebuild happened (v8 -> v9)", ver === 9, `user_version=${ver}`);
949
+ ok("forced schema rebuild happened (v9 -> v10)", ver === 10, `user_version=${ver}`);
950
950
  ok("rebuild re-synced memories from Markdown", mem.n === 1, `memories=${mem.n}`);
951
951
  ok(
952
952
  "counters survive the schema rebuild (D77-L2)",
@@ -1010,6 +1010,78 @@ ${body}
1010
1010
  "inventory json counts hidden without the entries",
1011
1011
  invJson2.hidden !== undefined && !("hiddenEntries" in invJson2),
1012
1012
  );
1013
+
1014
+ // ---------- D91: graph (§20 deterministic half) ----------
1015
+ // graph build / neighbours / path / lint / outline on a scratch project:
1016
+ // shared tags → one medium edge, a supersedes pair, an orphan, and the
1017
+ // write-path refresh (a later add lands in the graph with no rebuild).
1018
+ console.log("== graph (D91) ==");
1019
+ const graphProj = mkproj("graphproj");
1020
+ const gTagA = addMem(["graph D91 deploy checklist runs on Fridays", "--tag", "deploy,ci"], graphProj);
1021
+ const gTagB = addMem(["graph D91 ci gates every deploy", "--tag", "deploy,ci"], graphProj);
1022
+ const gOrphan = addMem(["graph D91 unrelated editor parser note", "--tag", "editor"], graphProj);
1023
+ ok("graph fixture: three project memories", gTagA && gTagB && gOrphan);
1024
+
1025
+ r = cli(["graph", "build"], graphProj);
1026
+ ok("graph build reports nodes/edges", /graph built for project__.*: 3 memories/.test(r.out) && /1 edges/.test(r.out), r.out.slice(0, 200));
1027
+
1028
+ r = cli(["graph", "neighbours", gTagB], graphProj);
1029
+ ok(
1030
+ "shared-tag edge shows with provenance and confidence",
1031
+ r.out.includes(gTagA) && /relates-to INFERRED\/medium \(shared-tag:ci,deploy\)/.test(r.out),
1032
+ r.out.slice(0, 300),
1033
+ );
1034
+
1035
+ r = cli(["graph", "neighbours", gOrphan], graphProj);
1036
+ ok(
1037
+ "orphan explains itself with the lint pointer",
1038
+ r.code === 0 && /currently an orphan/.test(r.out) && /graph lint/.test(r.out),
1039
+ (r.out + r.err).slice(0, 200),
1040
+ );
1041
+ // D63-style honesty for an unknown node.
1042
+ r = cli(["graph", "neighbours", "01AAAAAAAAAAAAAAAAAAAAAAAA"], graphProj);
1043
+ ok("neighbours fails on an invented id", r.code !== 0 && /no memory with id/.test(r.out + r.err), (r.out + r.err).slice(0, 150));
1044
+
1045
+ // Supersede one — the chain becomes an EXTRACTED edge via the write path.
1046
+ // One attempt; a missing match fails the subsequent assertions with a
1047
+ // clear message instead of quietly superseding the fixture five times.
1048
+ const gSup = cli(["supersede", gTagA, "graph D91 deploy checklist runs on Thursdays now"], graphProj);
1049
+ const gNewA = (gSup.out.match(/superseded [A-Z0-9]{26} → ([A-Z0-9]{26})/) ?? [])[1] ?? "";
1050
+ ok("supersede of the shared-tag memory returns the new id", gNewA.length === 26, gSup.out.slice(0, 200));
1051
+ r = cli(["graph", "neighbours", gNewA, "--depth", "1"], graphProj);
1052
+ ok(
1053
+ "supersede auto-refreshed the graph: chain edge EXTRACTED/high",
1054
+ r.out.includes(gTagA) && /supersedes EXTRACTED\/high/.test(r.out),
1055
+ r.out.slice(0, 300),
1056
+ );
1057
+
1058
+ r = cli(["graph", "lint"], graphProj);
1059
+ ok("lint reports the orphan and nothing dangling", /\borphans 1\b/.test(r.out) && /dangling 0\b/.test(r.out), r.out.slice(0, 300));
1060
+ ok("lint states the reports-only posture", /nothing is auto-resolved/.test(r.out));
1061
+
1062
+ r = cli(["graph", "lint", "--json"], graphProj);
1063
+ ok(
1064
+ "lint --json emits structured findings",
1065
+ /"findings"/.test(r.out) && new RegExp(`"id": "${gOrphan}"`).test(r.out),
1066
+ r.out.slice(0, 200),
1067
+ );
1068
+
1069
+ r = cli(["graph", "outline"], graphProj);
1070
+ ok("outline prints topics with the cap disclosure", /deploy|ci/.test(r.out), r.out.slice(0, 300));
1071
+
1072
+ // Path: two hops through a live body mention added after the last build
1073
+ // (write-path refresh must keep the graph current without `graph build`).
1074
+ const gTail = addMem([`graph D91 follow up [[${gOrphan}]] when parser lands`, "--tag", "followup"], graphProj);
1075
+ r = cli(["graph", "path", gOrphan, gTail], graphProj);
1076
+ ok(
1077
+ "path builds the hop chain from a wiki-link edge",
1078
+ r.out.includes(gOrphan) && r.out.includes(gTail) && /relates-to EXTRACTED\/high/.test(r.out),
1079
+ r.out.slice(0, 300),
1080
+ );
1081
+
1082
+ // Unknown scope id on both sides still escapes clearly.
1083
+ r = cli(["graph", "path", gTagB, "01BBBBBBBBBBBBBBBBBBBBBBBB"], graphProj);
1084
+ ok("path fails on a missing endpoint", r.code !== 0 && /no memory with id/.test(r.out + r.err));
1013
1085
  }
1014
1086
 
1015
1087
  console.log("\n================ SUMMARY ================");
package/server.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "io.github.stoneskin/open-memex",
4
4
  "title": "open-memex",
5
5
  "description": "Local-first memory for AI coding agents — Markdown + SQLite FTS5, shared across editors via MCP.",
6
- "version": "0.8.2",
6
+ "version": "0.9.0",
7
7
  "repository": {
8
8
  "url": "https://github.com/stoneskin/open-memex",
9
9
  "source": "github"
@@ -13,7 +13,7 @@
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "open-memex",
16
- "version": "0.8.2",
16
+ "version": "0.9.0",
17
17
  "runtimeHint": "npx",
18
18
  "packageArguments": [
19
19
  {
@@ -112,6 +112,23 @@ open-memex forget <id> # delete (permanent)
112
112
  open-memex forget <id> --soft # hide (retracted, one-way)
113
113
  ```
114
114
 
115
+ ## Structure: the knowledge graph
116
+
117
+ The project's memories form a derived graph (D91) — what is connected to
118
+ what, without searching. Use it when the user asks how memories relate, what
119
+ an entry links to, or what is orphaned:
120
+
121
+ ```sh
122
+ open-memex graph outline # topics + titles (also injected at session start)
123
+ open-memex graph neighbours <id> # what links to / from this memory, with provenance
124
+ open-memex graph path <a> <b> # how two memories connect
125
+ open-memex graph lint # orphans, dangling edges, near-stale pairs (reports only)
126
+ ```
127
+
128
+ Edges are `EXTRACTED` (structural fact) or `INFERRED` (heuristic) — quote
129
+ that distinction when reporting. `lint` never fixes anything; a human decides.
130
+ The graph is rebuilt automatically on writes; `graph build` forces it.
131
+
115
132
  ## Project outbox → repo (the sync flow)
116
133
 
117
134
  New project memories land in a local outbox (not in git). Review and publish:
package/src/cli.ts CHANGED
@@ -26,6 +26,9 @@ import { loadConfig, configSource } from "./config.ts";
26
26
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.ts";
27
27
  import { redact } from "./redact.ts";
28
28
  import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.ts";
29
+ import { refreshGraph, refreshGraphQuiet, ensureGraph, loadGraphEdges, loadGraphNodes, loadAllMemoryIds } from "./store/graph.ts";
30
+ import { graphNeighbours, shortestPath } from "./graph/queries.ts";
31
+ import { lintGraph } from "./graph/lint.ts";
29
32
  import { resolveMcpCommand } from "./init.ts";
30
33
  import fs from "node:fs";
31
34
  import path from "node:path";
@@ -465,6 +468,32 @@ Flags:
465
468
  Example:
466
469
  open-memex audit --scope both`,
467
470
 
471
+ graph: `Work with the compiled memory graph (§20, D88/D91) — a derived layer
472
+ of structural edges between memories, rebuilt from the Markdown source of
473
+ truth, never hand-edited.
474
+
475
+ Usage:
476
+ open-memex graph build rebuild edges + the compiled outline for this project
477
+ open-memex graph neighbours <id> [--depth N] neighbours via BFS (default 1, max 6)
478
+ open-memex graph path <idA> <idB> [--depth N] shortest path (default 4, max 6)
479
+ open-memex graph lint [--json] health check: orphans, dangling refs, stale chains
480
+ open-memex graph outline print the compiled outline as it is injected
481
+
482
+ Every hop reports its edge type, provenance and confidence — EXTRACTED
483
+ means the link was explicit in the source (a supersede chain, a
484
+ derived-from copy, or the body mentioning the other memory's id);
485
+ INFERRED means the system noticed it (shared tags). Inferred links are
486
+ suggestions, never facts that were in the source.
487
+
488
+ Writes (add / supersede / forget / propose / promote) refresh the graph
489
+ automatically; graph build is the manual repair. Lint only reports.
490
+
491
+ Examples:
492
+ open-memex graph build
493
+ open-memex graph neighbours 01ABC --depth 2
494
+ open-memex graph path 01ABC 01DEF
495
+ open-memex graph lint`,
496
+
468
497
  wstate: `Show the project's session working-state note (D89, §3.6) — the
469
498
  ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
470
499
  can resume. The file itself is plain Markdown and editable directly.
@@ -505,6 +534,7 @@ Usage:
505
534
  open-memex pr-status [--apply]
506
535
  open-memex reindex
507
536
  open-memex audit [--scope project|personal|both]
537
+ open-memex graph <build|neighbours <id>|path <a> <b>|lint|outline> [--depth N] [--json]
508
538
  open-memex wstate [--clear]
509
539
  open-memex scopes
510
540
  open-memex migrate [--from <key>] [--to <key>]
@@ -914,6 +944,146 @@ async function main() {
914
944
  return;
915
945
  }
916
946
 
947
+ // D91: the graph surface (§20 deterministic half). Project scope only —
948
+ // the graph covers the cwd's project scope like every other command;
949
+ // no --scope flag exists because personal has no reader this iteration.
950
+ if (cmd === "graph") {
951
+ const sub = rest[0] ?? "";
952
+ const flags = parseFlags(rest.slice(1));
953
+ // --depth is opt-in per command: neighbours defaults to 1, path to 4,
954
+ // and an explicit flag is clamped to [1, 6]. Absent = undefined so the
955
+ // default reads cleanly where it is applied.
956
+ const depth = (() => {
957
+ if (flags.depth === undefined || flags.depth === "true") return undefined;
958
+ const n = Number(flags.depth);
959
+ if (!Number.isInteger(n) || n < 1 || n > 6) return undefined;
960
+ return n;
961
+ })();
962
+
963
+ const syncThen = (fn: () => void) => {
964
+ syncScope(project.key, "cli");
965
+ fn();
966
+ };
967
+
968
+ if (sub === "build") {
969
+ syncThen(() => {
970
+ const s = refreshGraph(project.key, cfg);
971
+ console.log(
972
+ `graph built for ${s.scopeKey}: ${s.nodes} memories, ${s.edges} edges, ` +
973
+ `${s.topics} topic(s), outline ${s.outlineLines} line(s)`,
974
+ );
975
+ });
976
+ return;
977
+ }
978
+
979
+ if (sub === "neighbours") {
980
+ const id = rest[1];
981
+ if (!id) usage();
982
+ syncThen(() => {
983
+ ensureGraph(project.key, cfg);
984
+ const nodes = loadGraphNodes(project.key);
985
+ if (!nodes.some((n) => n.id === id)) {
986
+ console.error(`neighbours: no memory with id ${id} in scope ${project.key} — graph findings never invent nodes.`);
987
+ process.exit(1);
988
+ }
989
+ const hits = graphNeighbours(id, loadGraphEdges(project.key), nodes.map((n) => n.id), {
990
+ maxDepth: depth ?? 1,
991
+ });
992
+ if (hits.length === 0) {
993
+ const status = nodes.find((n) => n.id === id)!.status;
994
+ console.log(
995
+ status === "active"
996
+ ? `no structural neighbours within depth ${depth ?? 1} — this memory is currently an orphan (see \`graph lint\`).`
997
+ : `no structural neighbours within depth ${depth ?? 1} for this ${status} memory.`,
998
+ );
999
+ return;
1000
+ }
1001
+ for (const h of hits) {
1002
+ const n = nodes.find((x) => x.id === h.id)!;
1003
+ console.log(
1004
+ `- ${h.id} (depth ${h.depth}) ${h.via.type} ${h.via.provenance}/${h.via.confidence} (${h.via.via})` +
1005
+ ` [${n.status}] ${n.body.replace(/\s+/g, " ").trim().slice(0, 120)}`,
1006
+ );
1007
+ }
1008
+ });
1009
+ return;
1010
+ }
1011
+
1012
+ if (sub === "path") {
1013
+ const a = rest[1];
1014
+ const b = rest[2];
1015
+ if (!a || !b) usage();
1016
+ syncThen(() => {
1017
+ ensureGraph(project.key, cfg);
1018
+ const nodes = loadGraphNodes(project.key);
1019
+ for (const id of [a, b]) {
1020
+ if (!nodes.some((n) => n.id === id)) {
1021
+ console.error(`path: no memory with id ${id} in scope ${project.key}.`);
1022
+ process.exit(1);
1023
+ }
1024
+ }
1025
+ const p = shortestPath(a, b, loadGraphEdges(project.key), nodes.map((n) => n.id), {
1026
+ maxDepth: depth ?? 4,
1027
+ });
1028
+ if (!p.found) {
1029
+ console.log(
1030
+ `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.`,
1031
+ );
1032
+ return;
1033
+ }
1034
+ console.log(`${a} [${nodes.find((n) => n.id === a)!.status}]`);
1035
+ for (const h of p.hops) {
1036
+ console.log(` --(${h.type} ${h.provenance}/${h.confidence} via ${h.via})-->`);
1037
+ console.log(`${h.to} [${nodes.find((n) => n.id === h.to)!.status}]`);
1038
+ }
1039
+ });
1040
+ return;
1041
+ }
1042
+ if (sub === "lint") {
1043
+ syncThen(() => {
1044
+ ensureGraph(project.key, cfg);
1045
+ // Cross-scope ids (e.g. a propose copy's personal original) are not
1046
+ // findings — lint skips endpoints the store knows about.
1047
+ const f = lintGraph(loadGraphNodes(project.key), loadGraphEdges(project.key), loadAllMemoryIds());
1048
+ const counts = {
1049
+ orphan: 0,
1050
+ "dangling-edge": 0,
1051
+ stale: 0,
1052
+ };
1053
+ for (const x of f) counts[x.kind]++;
1054
+ if (flags.json === "true") {
1055
+ console.log(JSON.stringify({ findings: f, counts }, null, 2));
1056
+ return;
1057
+ }
1058
+ console.log(
1059
+ `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.`,
1060
+ );
1061
+ for (const x of f) {
1062
+ console.log(` [${x.kind}] ${x.id}${x.other ? ` ↔ ${x.other}` : ""}: ${x.detail}`);
1063
+ }
1064
+ if (f.length > 0) {
1065
+ console.log(`feed these to the review flow when curating; D78's pre-submit lint consumes the same report later.`);
1066
+ }
1067
+ });
1068
+ return;
1069
+ }
1070
+
1071
+ if (sub === "outline") {
1072
+ syncThen(() => {
1073
+ const g = ensureGraph(project.key, cfg);
1074
+ if (!g || !g.outline) {
1075
+ console.log("no compiled outline for this scope yet — `graph build` creates one.");
1076
+ return;
1077
+ }
1078
+ console.log(`outline built ${g.builtAt} (${g.nodes} memories / ${g.edges} edges):`);
1079
+ for (const line of g.outline.split("\n")) console.log(line);
1080
+ });
1081
+ return;
1082
+ }
1083
+
1084
+ usage();
1085
+ }
1086
+
917
1087
  // `config` prints the effective configuration (defaults + file). No DB needed.
918
1088
  // `config set <key> <value>` persists a setting to the config file.
919
1089
  if (cmd === "config") {
@@ -1201,6 +1371,8 @@ async function main() {
1201
1371
  const { filePath } = writeMemoryFile(fm, red);
1202
1372
  const mf = readMemoryFile(filePath);
1203
1373
  if (mf) upsertFromFile(mf);
1374
+ // D91 ingest: refresh the project graph quietly (personal no-ops inside).
1375
+ refreshGraphQuiet(s.key, cfg);
1204
1376
  console.log(`saved ${fm.id} [${s.kind}] -> ${filePath}`);
1205
1377
  if (hadSecret) {
1206
1378
  console.log(
@@ -1241,6 +1413,7 @@ async function main() {
1241
1413
  });
1242
1414
  upsertFromFile(oldMf);
1243
1415
  upsertFromFile(newMf);
1416
+ refreshGraphQuiet(oldMf.fm.scope_key, cfg);
1244
1417
  console.log(`superseded ${oldMf.fm.id} → ${newMf.fm.id}`);
1245
1418
  if (hadSecret) {
1246
1419
  console.log(
@@ -1261,6 +1434,7 @@ async function main() {
1261
1434
  try {
1262
1435
  const mf = setStatus(id, st as "active" | "deprecated" | "retracted" | "archived");
1263
1436
  upsertFromFile(mf);
1437
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1264
1438
  console.log(`status ${id} → ${mf.fm.status}`);
1265
1439
  } catch (e) {
1266
1440
  console.error(`status failed: ${(e as Error).message}`);
@@ -1275,12 +1449,13 @@ async function main() {
1275
1449
  // D68: --soft hides (retracts) instead of deleting — same action as
1276
1450
  // the memory_forget tool's soft flag. One-way (D64).
1277
1451
  if (rest.includes("--soft")) {
1278
- const target = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id) as
1279
- | { file_path: string }
1452
+ const target = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id) as
1453
+ | { file_path: string; scope_key: string }
1280
1454
  | undefined;
1281
1455
  try {
1282
1456
  const mf = setStatus(id, "retracted");
1283
1457
  upsertFromFile(mf);
1458
+ refreshGraphQuiet(mf.fm.scope_key, cfg);
1284
1459
  console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
1285
1460
  // D70: same honesty as the hard delete — a retraction of an in-repo
1286
1461
  // memory is a local working-tree edit until it is committed and pushed.
@@ -1295,8 +1470,8 @@ async function main() {
1295
1470
  }
1296
1471
  return;
1297
1472
  }
1298
- const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id) as
1299
- | { file_path: string }
1473
+ const row = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id) as
1474
+ | { file_path: string; scope_key: string }
1300
1475
  | undefined;
1301
1476
  if (!row) {
1302
1477
  console.error("not found");
@@ -1317,6 +1492,8 @@ async function main() {
1317
1492
  }
1318
1493
  }
1319
1494
  deleteFromIndex(id);
1495
+ // D91 ingest: the node left the graph — refresh its scope quietly.
1496
+ refreshGraphQuiet(row.scope_key);
1320
1497
  // D77-L2: hard forget prunes the usage row with the memory (the tool
1321
1498
  // path does the same); branch-switch removals go through syncScope and
1322
1499
  // keep counters for that reason.
package/src/config.ts CHANGED
@@ -23,6 +23,14 @@ export interface MyOMemoryConfig {
23
23
  */
24
24
  workingStateEnabled: boolean;
25
25
  workingStateTtlDays: number;
26
+ /**
27
+ * D91: the compiled project memory map (§20.4). `graphOutline` gates the
28
+ * session-start injection of the outline; `graphOutlineLines` caps its
29
+ * size (the injection-cost discipline — topics stay compact, details
30
+ * stay on-demand via graph neighbours/search).
31
+ */
32
+ graphOutline: boolean;
33
+ graphOutlineLines: number;
26
34
  /** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
27
35
  keywordPatterns: string[];
28
36
  /** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
@@ -53,6 +61,8 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
53
61
  captureAliases: true,
54
62
  workingStateEnabled: true,
55
63
  workingStateTtlDays: 7,
64
+ graphOutline: true,
65
+ graphOutlineLines: 10,
56
66
  keywordPatterns: [
57
67
  "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
58
68
  "^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -199,6 +209,13 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
199
209
  if (n < 1) throw new Error("must be a positive integer (days)");
200
210
  return n;
201
211
  },
212
+ graphOutline: toBool,
213
+ graphOutlineLines: (v) => {
214
+ const n = toNonNegInt(v);
215
+ if (n < 1) throw new Error("must be a positive integer (topic lines)");
216
+ if (n > 30) throw new Error("must be 30 or less — the injected outline stays compact");
217
+ return n;
218
+ },
202
219
  memoryDir: toRelativeDir,
203
220
  "sync.autoPull": toBool,
204
221
  logLevel: (v) => {