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/AGENTS.md +2 -2
- package/CHANGELOG.md +5 -1
- package/README.md +7 -3
- package/README.zh-CN.md +2 -2
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +15 -2
- package/dist/init.js +3 -1
- package/dist/mcp.js +3 -1
- package/dist/reuse-report.js +64 -0
- package/dist/review.js +7 -0
- package/dist/store/usage.js +142 -27
- package/dist/tools/ops.js +12 -11
- package/docs/V2-DESIGN.md +3 -1
- package/docs/design/decisions.md +1 -1
- package/package.json +66 -66
- package/scripts/smoke-mcp.ts +9 -0
- package/scripts/smoke-pure.ts +64 -0
- package/scripts/test-full.ts +124 -13
- package/skills/open-memex/SKILL.md +4 -0
- package/src/cli.ts +18 -2
- package/src/init.ts +3 -1
- package/src/mcp.ts +3 -1
- package/src/reuse-report.ts +119 -0
- package/src/review.ts +6 -0
- package/src/store/usage.ts +319 -178
- package/src/tools/ops.ts +12 -10
package/package.json
CHANGED
|
@@ -1,66 +1,66 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "open-memex",
|
|
3
|
-
"version": "0.9.0-alpha.
|
|
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
|
+
}
|
package/scripts/smoke-mcp.ts
CHANGED
|
@@ -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: {} });
|
package/scripts/smoke-pure.ts
CHANGED
|
@@ -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);
|
package/scripts/test-full.ts
CHANGED
|
@@ -866,24 +866,135 @@ ${body}
|
|
|
866
866
|
r.out.slice(0, 220),
|
|
867
867
|
);
|
|
868
868
|
|
|
869
|
-
//
|
|
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
|
-
|
|
873
|
-
|
|
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
|
-
//
|
|
876
|
-
//
|
|
877
|
-
|
|
878
|
-
|
|
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
|
-
"
|
|
881
|
-
/
|
|
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
|
|