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

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/package.json CHANGED
@@ -1,66 +1,66 @@
1
- {
2
- "name": "open-memex",
3
- "version": "0.9.0-alpha.2",
4
- "mcpName": "io.github.stoneskin/open-memex",
5
- "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
6
- "keywords": [
7
- "mcp",
8
- "model-context-protocol",
9
- "mcp-server",
10
- "opencode",
11
- "ai-agents",
12
- "agent-memory",
13
- "persistent-memory",
14
- "local-first",
15
- "sqlite",
16
- "fts5",
17
- "markdown",
18
- "memory",
19
- "copilot",
20
- "cursor",
21
- "claude-code",
22
- "vscode",
23
- "knowledge-management",
24
- "developer-tools",
25
- "synonyms"
26
- ],
27
- "type": "module",
28
- "license": "Apache-2.0",
29
- "repository": {
30
- "type": "git",
31
- "url": "git+https://github.com/stoneskin/open-memex.git"
32
- },
33
- "homepage": "https://github.com/stoneskin/open-memex#readme",
34
- "bugs": {
35
- "url": "https://github.com/stoneskin/open-memex/issues"
36
- },
37
- "main": "src/index.ts",
38
- "scripts": {
39
- "typecheck": "tsc --noEmit",
40
- "cli": "node --experimental-strip-types src/cli.ts",
41
- "mcp": "node --experimental-strip-types src/mcp.ts",
42
- "build": "tsc -p tsconfig.build.json && node scripts/build-stamp.mjs",
43
- "prepublishOnly": "npm run build",
44
- "postinstall": "node scripts/postinstall.js",
45
- "test-full": "node --experimental-strip-types scripts/test-full.ts"
46
- },
47
- "dependencies": {
48
- "@modelcontextprotocol/sdk": "^1.30.1",
49
- "better-sqlite3": "^13.0.3",
50
- "js-yaml": "^4.1.0",
51
- "zod": "^4.1.8"
52
- },
53
- "devDependencies": {
54
- "@opencode-ai/plugin": "^1.18.30",
55
- "@types/better-sqlite3": "^7.6.11",
56
- "@types/js-yaml": "^4.0.9",
57
- "@types/node": "^22.0.0",
58
- "typescript": "^5.6.0"
59
- },
60
- "bin": {
61
- "open-memex": "dist/cli.js"
62
- },
63
- "engines": {
64
- "node": ">=22.14.0"
65
- }
66
- }
1
+ {
2
+ "name": "open-memex",
3
+ "version": "0.9.0-alpha.3",
4
+ "mcpName": "io.github.stoneskin/open-memex",
5
+ "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
6
+ "keywords": [
7
+ "mcp",
8
+ "model-context-protocol",
9
+ "mcp-server",
10
+ "opencode",
11
+ "ai-agents",
12
+ "agent-memory",
13
+ "persistent-memory",
14
+ "local-first",
15
+ "sqlite",
16
+ "fts5",
17
+ "markdown",
18
+ "memory",
19
+ "copilot",
20
+ "cursor",
21
+ "claude-code",
22
+ "vscode",
23
+ "knowledge-management",
24
+ "developer-tools",
25
+ "synonyms"
26
+ ],
27
+ "type": "module",
28
+ "license": "Apache-2.0",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/stoneskin/open-memex.git"
32
+ },
33
+ "homepage": "https://github.com/stoneskin/open-memex#readme",
34
+ "bugs": {
35
+ "url": "https://github.com/stoneskin/open-memex/issues"
36
+ },
37
+ "main": "src/index.ts",
38
+ "scripts": {
39
+ "typecheck": "tsc --noEmit",
40
+ "cli": "node --experimental-strip-types src/cli.ts",
41
+ "mcp": "node --experimental-strip-types src/mcp.ts",
42
+ "build": "tsc -p tsconfig.build.json && node scripts/build-stamp.mjs",
43
+ "prepublishOnly": "npm run build",
44
+ "postinstall": "node scripts/postinstall.js",
45
+ "test-full": "node --experimental-strip-types scripts/test-full.ts"
46
+ },
47
+ "dependencies": {
48
+ "@modelcontextprotocol/sdk": "^1.30.1",
49
+ "better-sqlite3": "^13.0.3",
50
+ "js-yaml": "^4.1.0",
51
+ "zod": "^4.1.8"
52
+ },
53
+ "devDependencies": {
54
+ "@opencode-ai/plugin": "^1.18.30",
55
+ "@types/better-sqlite3": "^7.6.11",
56
+ "@types/js-yaml": "^4.0.9",
57
+ "@types/node": "^22.0.0",
58
+ "typescript": "^5.6.0"
59
+ },
60
+ "bin": {
61
+ "open-memex": "dist/cli.js"
62
+ },
63
+ "engines": {
64
+ "node": ">=22.14.0"
65
+ }
66
+ }
@@ -225,6 +225,15 @@ try {
225
225
  const forgetUseful = await req("tools/call", { name: "memory_forget", arguments: { id: savedId3 } });
226
226
  check("D77 probe memory cleaned up", (forgetUseful.result?.content?.[0]?.text ?? "").includes("Deleted"), (forgetUseful.result?.content?.[0]?.text ?? "").slice(0, 120));
227
227
 
228
+ // D77-L3: the reuse report rides memory_status, capped for agent results.
229
+ const status = await req("tools/call", { name: "memory_status", arguments: {} });
230
+ const statusText = status.result?.content?.[0]?.text ?? "";
231
+ check(
232
+ "memory_status carries the reuse report (D77-L3)",
233
+ /Reuse \(D77/.test(statusText) && /local counters/.test(statusText),
234
+ statusText.slice(-260),
235
+ );
236
+
228
237
  // §3.6 (D89): the working-state note round-trips, expires honestly, and
229
238
  // its file lives OUTSIDE memories/ so the index never picks it up.
230
239
  const wsRead0 = await req("tools/call", { name: "memory_workingstate", arguments: {} });
@@ -10,6 +10,7 @@ import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
10
10
  import { toFtsQuery } from "../src/retrieve/query.ts";
11
11
  import { expansionVariantsForDoc, MAX_AUTO_VARIANTS } from "../src/retrieve/synonyms.ts";
12
12
  import { BM25_WEIGHTS, DEFAULT_EXPANSIONS_WEIGHT } from "../src/retrieve/weights.ts";
13
+ import { formatReuseReport } from "../src/reuse-report.ts";
13
14
  import {
14
15
  planAliasExpansions,
15
16
  rewriteQueryOnce,
@@ -1035,5 +1036,68 @@ console.log("== D89 working-state note (§3.6) ==");
1035
1036
  }
1036
1037
  }
1037
1038
 
1039
+ console.log("== D77-L3 reuse report formatting ==")
1040
+ {
1041
+ const entry = (id: string, extra: Record<string, unknown> = {}) => ({
1042
+ id,
1043
+ scopeKey: "project__p__x",
1044
+ scopeLabel: "this project",
1045
+ type: "fact",
1046
+ reviewState: "draft",
1047
+ status: "active",
1048
+ retrieved: 3,
1049
+ useful: 1,
1050
+ usefulSelf: 1,
1051
+ usefulTeam: 0,
1052
+ snippet: `snippet ${id}`,
1053
+ ...extra,
1054
+ });
1055
+ const empty = formatReuseReport({
1056
+ scopes: [
1057
+ { label: "this project", scopeKey: "project__p__x", tracked: 0, retrieved: 0, useful: 0, usefulSelf: 0, usefulTeam: 0, rate: null },
1058
+ { label: "personal", scopeKey: "personal", tracked: 0, retrieved: 0, useful: 0, usefulSelf: 0, usefulTeam: 0, rate: null },
1059
+ ],
1060
+ top: [],
1061
+ topTotal: 0,
1062
+ zombies: [],
1063
+ zombieTotal: 0,
1064
+ tracked: 0,
1065
+ });
1066
+ ok("header always present", empty[0]?.startsWith("Reuse (D77") === true);
1067
+ ok("empty state explains how counters fill", empty.some((l) => l.includes("no data yet")));
1068
+ ok("empty state omits empty scope rows", !empty.some((l) => l.includes("retrieved 0")));
1069
+
1070
+ const report = {
1071
+ scopes: [
1072
+ { label: "this project", scopeKey: "project__p__x", tracked: 2, retrieved: 10, useful: 4, usefulSelf: 3, usefulTeam: 1, rate: 0.4 },
1073
+ { label: "personal", scopeKey: "personal", tracked: 1, retrieved: 5, useful: 0, usefulSelf: 0, usefulTeam: 0, rate: 0 },
1074
+ ],
1075
+ top: [entry("01TOP", { useful: 4, usefulSelf: 2, usefulTeam: 2 })],
1076
+ topTotal: 1,
1077
+ zombies: [entry("01Z1", { retrieved: 9, useful: 0, usefulSelf: 0, usefulTeam: 0, status: "superseded" }), entry("01Z2", { retrieved: 2, useful: 0, usefulSelf: 0, usefulTeam: 0 })],
1078
+ zombieTotal: 2,
1079
+ tracked: 3,
1080
+ };
1081
+ const lines = formatReuseReport(report, { entryCap: 1 });
1082
+ ok(
1083
+ "scope rate rendered as percent with the self/team split (D77)",
1084
+ lines.some((l) => l.includes("this project: retrieved 10, useful 4 (self 3, team 1) — 40%")),
1085
+ );
1086
+ ok("personal scope rendered", lines.some((l) => l.includes("personal: retrieved 5, useful 0 (self 0, team 0) — 0%")));
1087
+ ok(
1088
+ "top reused renders the split, not just the total",
1089
+ lines.some((l) => l.includes("01TOP") && l.includes("(self 2, team 2)")),
1090
+ );
1091
+ ok("cross-scope entries carry a scope tag", lines.some((l) => l.includes("[this project/fact]")));
1092
+ ok("non-active entries are lifecycle-tagged (superseded)", lines.some((l) => l.includes("01Z1") && l.includes("[superseded]")));
1093
+ ok("active entries carry no lifecycle tag", !lines.some((l) => l.includes("01TOP") && l.includes("[active]")));
1094
+ ok("zombie list rendered", lines.some((l) => l.includes("01Z1")));
1095
+ ok("capped list discloses the cut", lines.some((l) => l.includes("… and 1 more")));
1096
+ ok(
1097
+ "zombie count is the true total, not the shown slice",
1098
+ lines.some((l) => l.includes("never confirmed useful): 2")),
1099
+ );
1100
+ }
1101
+
1038
1102
  console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
1039
1103
  process.exit(fails === 0 ? 0 : 1);
@@ -866,24 +866,135 @@ ${body}
866
866
  r.out.slice(0, 220),
867
867
  );
868
868
 
869
- // Hard forget prunes the telemetry row (no phantom counters).
869
+ // Behavioral: --local-approve is a human approval too. It writes the copy
870
+ // straight to approved, bypassing promoteMemory, so the tick must be
871
+ // recorded by the propose path itself (submit preserves the state).
872
+ const localSrc = addMem(["fulltest D77 local-approve memory", "--scope", "personal"], d77Proj);
873
+ const localCopy = grabArrowId(cliRetry(["propose", localSrc, "--to", "project", "--local-approve"], d77Proj).out);
874
+ ok("local-approve propose works (setup)", !!localCopy);
875
+ r = cliRetry(["useful", localCopy], d77Proj);
876
+ // 1 tick from the local approval + 1 from this probe = 2.
877
+ ok(
878
+ "local-approve recorded useful_team (D77)",
879
+ /useful \(team\)/.test(r.out) && /useful_team: 2/.test(r.out),
880
+ r.out.slice(0, 220),
881
+ );
882
+
883
+ // Behavioral: supersede must not drop the tick when the index row is
884
+ // missing (schema rebuild pending / stale index). The file is the source
885
+ // of truth, so findMemoryFile's scan fallback still finds it.
886
+ const staleId = addMem(["fulltest D77 stale-index supersede target"], d77Proj);
887
+ {
888
+ const D = createRequire(import.meta.url)("better-sqlite3");
889
+ const conn = new D(dbPath);
890
+ conn.prepare("DELETE FROM memories WHERE id = ?").run(staleId);
891
+ conn.close();
892
+ }
893
+ r = cliRetry(["supersede", staleId, "fulltest D77 stale-index replacement"], d77Proj);
894
+ ok("supersede works with no index row (setup)", r.code === 0, (r.err || r.out).slice(0, 160));
895
+ {
896
+ const D = createRequire(import.meta.url)("better-sqlite3");
897
+ const conn = new D(dbPath, { readonly: true });
898
+ try {
899
+ const row = conn
900
+ .prepare("SELECT useful_self FROM memory_usage WHERE id = ?")
901
+ .get(staleId) as { useful_self: number } | undefined;
902
+ ok(
903
+ "supersede recorded useful even without the index row (D77)",
904
+ !!row && row.useful_self === 1,
905
+ JSON.stringify(row),
906
+ );
907
+ } finally {
908
+ conn.close();
909
+ }
910
+ }
911
+
912
+ // Hard forget prunes the telemetry row (no phantom counters). This must be
913
+ // asserted against memory_usage directly: a `useful` probe after forget
914
+ // fails on the missing memories row whether or not the usage row survived.
870
915
  const deadId = addMem(["fulltest D77 to-be-forgotten memory"], d77Proj);
916
+ cliRetry(["useful", deadId], d77Proj);
917
+ const usageRows = (id: string): number => {
918
+ const D = createRequire(import.meta.url)("better-sqlite3");
919
+ const conn = new D(dbPath, { readonly: true });
920
+ try {
921
+ const row = conn.prepare("SELECT COUNT(*) AS n FROM memory_usage WHERE id = ?").get(id) as { n: number };
922
+ return row.n;
923
+ } finally {
924
+ conn.close();
925
+ }
926
+ };
927
+ ok("seed: useful row exists before forget", usageRows(deadId) === 1);
871
928
  cliRetry(["forget", deadId], d77Proj);
872
- r = cliRetry(["useful", deadId], d77Proj);
873
- ok("forget pruned the usage row (D77-L2)", r.code !== 0 && /not found/.test(r.out + r.err), (r.out + r.err).slice(0, 120));
929
+ ok("forget pruned the usage row (D77-L2)", usageRows(deadId) === 0, `rows=${usageRows(deadId)}`);
930
+
931
+ // Counters survive a forced schema rebuild. `cli reindex` alone only runs
932
+ // syncScope and never invokes rebuildIndexSchema, so it cannot prove the
933
+ // promise — force an older user_version (the D87 fixture's trick) and let
934
+ // the next command's db() open rebuild the index, then inspect the table
935
+ // directly. memory_usage sits outside the rebuilt tables by design.
936
+ {
937
+ const D = createRequire(import.meta.url)("better-sqlite3");
938
+ const conn = new D(dbPath);
939
+ conn.exec("PRAGMA user_version = 8");
940
+ conn.close();
941
+ cliRetry(["list"], d77Proj); // opens db() -> rebuildIndexSchema -> syncScope
942
+ const after = new D(dbPath, { readonly: true });
943
+ try {
944
+ const ver = (after.prepare("PRAGMA user_version").get() as { user_version: number }).user_version;
945
+ const mem = after.prepare("SELECT COUNT(*) AS n FROM memories WHERE id = ?").get(uId) as { n: number };
946
+ const usage = after
947
+ .prepare("SELECT retrieved_count, useful_self, useful_team FROM memory_usage WHERE id = ?")
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}`);
950
+ ok("rebuild re-synced memories from Markdown", mem.n === 1, `memories=${mem.n}`);
951
+ ok(
952
+ "counters survive the schema rebuild (D77-L2)",
953
+ !!usage && usage.retrieved_count >= 2 && usage.useful_self === 2 && usage.useful_team === 0,
954
+ JSON.stringify(usage),
955
+ );
956
+ } finally {
957
+ after.close();
958
+ }
959
+ }
874
960
 
875
- // Counters survive a full schema rebuild (memory_usage sits outside the
876
- // rebuilt index tables; D77-L2 store design).
877
- cliRetry(["reindex"], d77Proj);
878
- r = cliRetry(["useful", uId], d77Proj);
961
+ // ---------- D77-L3: reuse report on the status surface ----------
962
+ // memory_status / `sync-status` gains per-scope rates, top reused, and
963
+ // zombies (retrieved, never confirmed useful).
964
+ console.log("== reuse report (D77-L3) ==");
965
+ const zombieId = addMem(["fulltest D77 zombie memory never confirmed"], d77Proj);
966
+ cliRetry(["search", "zombie memory never confirmed"], d77Proj);
967
+ r = cliRetry(["sync-status"], d77Proj);
968
+ ok("sync-status shows the reuse report (D77-L3)", /Reuse \(D77/.test(r.out), r.out.slice(0, 260));
969
+ // Scope every membership assertion to the reuse section: sync-status also
970
+ // lists the ids in its queue sections, so a bare `out.includes(id)` would
971
+ // pass even if the report itself dropped or mis-listed the entry.
972
+ const reuseBlock = r.out.slice(r.out.indexOf("Reuse (D77"));
973
+ ok(
974
+ "report shows per-scope rates with the self/team split (D77)",
975
+ /this project: retrieved \d+, useful \d+ \(self \d+, team \d+\) — \d+% over \d+ memor/.test(reuseBlock),
976
+ reuseBlock.slice(0, 300),
977
+ );
978
+ ok(
979
+ "report lists the most-reused memory in the top list",
980
+ /top reused: [1-9]/.test(reuseBlock) && reuseBlock.includes(uId),
981
+ reuseBlock.slice(0, 420),
982
+ );
983
+ ok(
984
+ "report lists the zombie in the zombie list and counts it",
985
+ /zombies \(retrieved, never confirmed useful\): [1-9]/.test(reuseBlock) &&
986
+ reuseBlock.includes(zombieId),
987
+ reuseBlock.slice(-360),
988
+ );
989
+ ok(
990
+ "historical reuse is lifecycle-labelled (superseded), not presented as current",
991
+ reuseBlock.includes(oldId) && /\[superseded\]/.test(reuseBlock),
992
+ reuseBlock.slice(0, 500),
993
+ );
879
994
  ok(
880
- "counters survive reindex",
881
- /retrieved: 2/.test(r.out) || /retrieved: 3/.test(r.out),
882
- r.out.slice(0, 160),
995
+ "report is local-only framed",
996
+ /local counters, never leave this machine/.test(reuseBlock),
883
997
  );
884
- // NOTE: the reindex section's useful tick bumps useful_self by 1 — that is
885
- // the probe itself, not persistence; the retrieved floor above is what
886
- // proves the table survived the rebuild.
887
998
 
888
999
  // JSON: no absolute local paths, and the format id records the change.
889
1000
  r = cliRetry(["inventory", "--format", "json"], PROJ);
@@ -121,6 +121,10 @@ open-memex sync-status # drafts waiting, repo review state, uncommitted file
121
121
  open-memex submit <id> # publish drafts to .ai/open-memex/ + local commit
122
122
  ```
123
123
 
124
+ `sync-status` also ends with the D77 reuse report — per-scope retrieved/useful
125
+ rates, the most-reused memories, and "zombies" (retrieved but never confirmed
126
+ useful). Show it when the user asks what memory is actually pulling its weight.
127
+
124
128
  If any command output reports drafts waiting in the project outbox, run
125
129
  `open-memex sync-status` and ask the user which drafts to sync. The user may
126
130
  also trigger this flow by saying "sync memory".
package/src/cli.ts CHANGED
@@ -10,7 +10,8 @@ import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatR
10
10
  import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.ts";
11
11
  import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.ts";
12
12
  import { search, list, countList, hitStateLabel } from "./retrieve/search.ts";
13
- import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage } from "./store/usage.ts";
13
+ import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage, loadReuseReport } from "./store/usage.ts";
14
+ import { formatReuseReport } from "./reuse-report.ts";
14
15
  import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.ts";
15
16
  import { formatInventoryLine, truncationNote } from "./retrieve/display.ts";
16
17
  import {
@@ -231,7 +232,9 @@ Examples:
231
232
 
232
233
  "sync-status": `Show the project memory sync pipeline: when the index last synced
233
234
  and what triggered it, drafts waiting in the outbox (appdata), memories in the
234
- repo awaiting review or published, and repo files not yet committed.
235
+ repo awaiting review or published, and repo files not yet committed. The
236
+ D77 reuse report follows: per-scope retrieved/useful rates, most-reused
237
+ memories, and "zombies" (retrieved but never confirmed useful).
235
238
 
236
239
  Usage: open-memex sync-status
237
240
 
@@ -1527,6 +1530,19 @@ function positionalArgs(argv: string[]): string[] {
1527
1530
  syncScope(PERSONAL_SCOPE.key, "cli");
1528
1531
  try {
1529
1532
  console.log(formatSyncStatus(getSyncStatus(), { cap: Number.POSITIVE_INFINITY }));
1533
+ // D77-L3: same reuse block as the memory_status tool, uncapped (a
1534
+ // human asked; the CLI is where the full list lives).
1535
+ const reuse = loadReuseReport(
1536
+ [
1537
+ { scopeKey: project.key, label: "this project" },
1538
+ { scopeKey: PERSONAL_SCOPE.key, label: "personal" },
1539
+ ],
1540
+ { topLimit: Number.POSITIVE_INFINITY, zombieLimit: Number.POSITIVE_INFINITY },
1541
+ );
1542
+ console.log("");
1543
+ for (const line of formatReuseReport(reuse, { entryCap: Number.POSITIVE_INFINITY })) {
1544
+ console.log(line);
1545
+ }
1530
1546
  } catch (e) {
1531
1547
  console.error(`sync-status failed: ${(e as Error).message}`);
1532
1548
  process.exit(2);
package/src/init.ts CHANGED
@@ -119,7 +119,9 @@ yet. Syncing them into the repo for review is an explicit, user-approved step:
119
119
  - When the user says "sync memory" (or "同步记忆"), run the sync
120
120
  flow above: call \`memory_status\`, summarize the outbox drafts, and ask which
121
121
  ones to sync. ALWAYS use the \`memory_status\` tool for this — never browse
122
- the memory data directory directly.
122
+ the memory data directory directly. That tool also carries the D77 reuse
123
+ report (per-scope rates, most-reused memories, and "zombies"): surface it
124
+ when the user asks what memory is actually being reused.
123
125
  - When the user approves, call \`memory_submit\` with the approved ids. It
124
126
  copies the drafts into the current project's \`.ai/open-memex/\` directory as
125
127
  \`proposed\` and commits locally on the CURRENT branch. It NEVER creates a
package/src/mcp.ts CHANGED
@@ -98,7 +98,9 @@ them by these full names.
98
98
  - When the user says "sync memory" (or "同步记忆"), call memory_status,
99
99
  summarize the outbox drafts (one line each), and ask which ones to sync.
100
100
  ALWAYS use the memory_status tool for this — never browse the memory data
101
- directory directly.
101
+ directory directly. memory_status also carries the D77 reuse report
102
+ (per-scope rates, most-reused, and never-used-but-retrieved "zombies") —
103
+ surface it when the user asks what memory is actually being reused.
102
104
  - After memory_submit, ask ONE follow-up: "want me to create a branch + push +
103
105
  open the PR, or will you handle it yourself?" NEVER create branches, push, or
104
106
  open PRs without the user's explicit approval. A "yes, you do it" covers the
@@ -0,0 +1,119 @@
1
+ /**
2
+ * D77-L3: the reuse report — pure types + rendering, no SQLite import (the
3
+ * data comes from `loadReuseReport` in store/usage.ts). Split like
4
+ * weights.ts so smoke-pure can test the formatting without a database.
5
+ *
6
+ * Report rules (D77):
7
+ * - per-scope reuse rate = useful / retrieved over tracked memories
8
+ * (counters exist per memory; scopes are personal vs the current project);
9
+ * - the useful side is shown split into self vs team — D77 requires reporting
10
+ * them separately so the team-knowledge claim stays honest (the combined
11
+ * total still drives ranking and the rate);
12
+ * - "top reused" = highest useful, then highest exposure;
13
+ * - "zombies" = retrieved at least once, never confirmed useful — the
14
+ * decay/prune candidates the D77 text calls out;
15
+ * - retracted/archived memories are excluded from the two lists (their
16
+ * counters still count toward the scope totals — history is history);
17
+ * - superseded/deprecated entries stay in the lists (their reuse is real)
18
+ * but carry a lifecycle tag, so historical data never reads as current
19
+ * guidance — supersede itself ticks the OLD memory's useful counter;
20
+ * - lists are capped and the cut is disclosed (D68 honesty rule).
21
+ */
22
+
23
+ export interface ReuseScopeStat {
24
+ /** Human label: "this project" / "personal". */
25
+ label: string;
26
+ scopeKey: string;
27
+ /** Memories in this scope that have a telemetry row. */
28
+ tracked: number;
29
+ retrieved: number;
30
+ useful: number;
31
+ /** D77: the useful split, reported separately from the combined total. */
32
+ usefulSelf: number;
33
+ usefulTeam: number;
34
+ /** useful / retrieved; null when nothing was ever retrieved. */
35
+ rate: number | null;
36
+ }
37
+
38
+ export interface ReuseEntry {
39
+ id: string;
40
+ scopeKey: string;
41
+ scopeLabel: string;
42
+ type: string;
43
+ reviewState: string;
44
+ /** Lifecycle status — non-active entries are tagged in the render. */
45
+ status: string;
46
+ retrieved: number;
47
+ useful: number;
48
+ usefulSelf: number;
49
+ usefulTeam: number;
50
+ snippet: string;
51
+ }
52
+
53
+ export interface ReuseReport {
54
+ scopes: ReuseScopeStat[];
55
+ top: ReuseEntry[];
56
+ topTotal: number;
57
+ zombies: ReuseEntry[];
58
+ zombieTotal: number;
59
+ /** Total memories with a telemetry row across the reported scopes. */
60
+ tracked: number;
61
+ }
62
+
63
+ export interface FormatReuseOptions {
64
+ /** Entries shown per list before the "and N more" line. Default 5. */
65
+ entryCap?: number;
66
+ }
67
+
68
+ function rateText(rate: number | null): string {
69
+ return rate === null ? "n/a" : `${Math.round(rate * 100)}%`;
70
+ }
71
+
72
+ /**
73
+ * Render the report as plain lines. Always emits the "Reuse (D77" header, so
74
+ * the section exists (with an honest empty-state line) even before any
75
+ * retrieval has been recorded — discoverability over silence.
76
+ */
77
+ export function formatReuseReport(
78
+ report: ReuseReport,
79
+ opts: FormatReuseOptions = {},
80
+ ): string[] {
81
+ const cap = opts.entryCap ?? 5;
82
+ const lines: string[] = ["Reuse (D77 — local counters, never leave this machine):"];
83
+ if (report.tracked === 0) {
84
+ lines.push(
85
+ " no data yet — search/list/session-start injection record exposure; memory_useful records usefulness.",
86
+ );
87
+ return lines;
88
+ }
89
+ for (const s of report.scopes) {
90
+ if (s.tracked === 0) continue;
91
+ lines.push(
92
+ ` ${s.label}: retrieved ${s.retrieved}, useful ${s.useful} (self ${s.usefulSelf}, team ${s.usefulTeam}) — ${rateText(s.rate)} over ${s.tracked} memor${s.tracked === 1 ? "y" : "ies"}`,
93
+ );
94
+ }
95
+ // Only disambiguate each entry's scope when both scopes have data — the
96
+ // single-scope case would just repeat the same tag on every line.
97
+ const multi = report.scopes.filter((s) => s.tracked > 0).length > 1;
98
+ const tag = (e: ReuseEntry) => (multi ? `[${e.scopeLabel}/${e.type}]` : `[${e.type}]`);
99
+ // Lifecycle tag: superseded/deprecated entries are historical reuse, not
100
+ // current guidance (a supersede ticks the old memory, so it can rank high).
101
+ const life = (e: ReuseEntry) => (e.status && e.status !== "active" ? ` [${e.status}]` : "");
102
+ lines.push(` top reused: ${report.topTotal}`);
103
+ for (const e of report.top.slice(0, cap)) {
104
+ lines.push(
105
+ ` · ${e.id} ${tag(e)}${life(e)} retrieved=${e.retrieved} useful=${e.useful} (self ${e.usefulSelf}, team ${e.usefulTeam}) — ${e.snippet}`,
106
+ );
107
+ }
108
+ if (report.topTotal > cap) {
109
+ lines.push(` … and ${report.topTotal - cap} more (full list: open-memex sync-status)`);
110
+ }
111
+ lines.push(` zombies (retrieved, never confirmed useful): ${report.zombieTotal}`);
112
+ for (const e of report.zombies.slice(0, cap)) {
113
+ lines.push(` · ${e.id} ${tag(e)}${life(e)} retrieved=${e.retrieved} — ${e.snippet}`);
114
+ }
115
+ if (report.zombieTotal > cap) {
116
+ lines.push(` … and ${report.zombieTotal - cap} more (full list: open-memex sync-status)`);
117
+ }
118
+ return lines;
119
+ }
package/src/review.ts CHANGED
@@ -138,6 +138,12 @@ function copyPersonalToProject(
138
138
  };
139
139
  const { filePath } = writeMemoryFile(fm, srcBody);
140
140
  upsertFromFile({ fm, body: srcBody, filePath, mtimeMs: Date.now() });
141
+ // D77-L2: a local approval is still a human approval at review, so it must
142
+ // record the same useful_team tick the promote path records. It bypasses
143
+ // promoteMemory by design (solo-dev shortcut) and submit preserves the
144
+ // approved state, so no later step would otherwise count it — and the
145
+ // later `approved → published` promote stays non-counting for both paths.
146
+ if (targetState === "approved") recordUseful(fm.id, "team", "promote");
141
147
  return { id: fm.id, filePath, reviewState: fm.review_state };
142
148
  }
143
149