open-memex 0.8.2 → 0.9.0-alpha.2
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 +21 -5
- package/CHANGELOG.md +10 -0
- package/README.md +46 -13
- package/README.zh-CN.md +25 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +103 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +4 -2
- package/dist/index.js +6 -1
- package/dist/init.js +13 -3
- package/dist/mcp.js +28 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/retrieve/inject.js +6 -0
- package/dist/retrieve/search.js +13 -2
- package/dist/review.js +7 -0
- package/dist/store/audit.js +14 -0
- package/dist/store/db.js +19 -0
- package/dist/store/lifecycle.js +8 -0
- package/dist/store/usage.js +151 -0
- package/dist/tools/memory.js +21 -2
- package/dist/tools/ops.js +123 -1
- package/dist/working-state.js +118 -0
- package/docs/CONCEPTS.md +16 -0
- package/docs/CONCEPTS.zh-CN.md +13 -0
- package/docs/V2-DESIGN.md +42 -1039
- package/docs/design/decisions.md +1146 -0
- package/docs/design/knowledge-graph.md +86 -0
- package/package.json +66 -66
- package/scripts/smoke-mcp.ts +67 -4
- package/scripts/smoke-pure.ts +70 -0
- package/scripts/test-full.ts +83 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +19 -0
- package/src/cli.ts +111 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +4 -2
- package/src/index.ts +6 -0
- package/src/init.ts +13 -3
- package/src/mcp.ts +41 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/retrieve/inject.ts +7 -0
- package/src/retrieve/search.ts +19 -3
- package/src/review.ts +6 -0
- package/src/store/audit.ts +20 -0
- package/src/store/db.ts +20 -0
- package/src/store/lifecycle.ts +9 -0
- package/src/store/usage.ts +178 -0
- package/src/tools/memory.ts +26 -1
- package/src/tools/ops.ts +158 -1
- package/src/working-state.ts +153 -0
package/dist/mcp.js
CHANGED
|
@@ -3,8 +3,10 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Exposes the memory tools as the opencode plugin
|
|
5
5
|
* (memory_add / memory_search / memory_list / memory_supersede /
|
|
6
|
-
* memory_forget, plus
|
|
7
|
-
*
|
|
6
|
+
* memory_forget, plus memory_useful + memory_workingstate + memory_status /
|
|
7
|
+
* memory_submit / memory_propose / memory_promote / memory_resolve /
|
|
8
|
+
* memory_pr_status)
|
|
9
|
+
* over the Model Context Protocol, so any MCP client —
|
|
8
10
|
* VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
|
|
9
11
|
* without a host-specific plugin.
|
|
10
12
|
*
|
|
@@ -28,7 +30,7 @@ import { loadConfig } from "./config.js";
|
|
|
28
30
|
import { resolveProjectScope, PERSONAL_SCOPE } from "./scope.js";
|
|
29
31
|
import { db } from "./store/db.js";
|
|
30
32
|
import { syncScope } from "./store/sync.js";
|
|
31
|
-
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./tools/ops.js";
|
|
33
|
+
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, markMemoryUseful, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, workingStateMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, memoryWorkingStateArgs, memoryUsefulArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./tools/ops.js";
|
|
32
34
|
import { outboxDraftCount } from "./submit.js";
|
|
33
35
|
// Server version tracks package.json — never hardcode it here again.
|
|
34
36
|
// package.json sits two levels above this file in both layouts
|
|
@@ -52,8 +54,9 @@ const SERVER_VERSION = (() => {
|
|
|
52
54
|
*/
|
|
53
55
|
const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server.
|
|
54
56
|
Its tools are memory_add, memory_search, memory_list, memory_supersede,
|
|
55
|
-
memory_forget,
|
|
56
|
-
memory_resolve, memory_pr_status — always call
|
|
57
|
+
memory_forget, memory_useful, memory_workingstate, memory_status, memory_submit,
|
|
58
|
+
memory_propose, memory_promote, memory_resolve, memory_pr_status — always call
|
|
59
|
+
them by these full names.
|
|
57
60
|
|
|
58
61
|
- The server tells you when project outbox drafts are waiting for review —
|
|
59
62
|
in tool results, and in these session-start instructions. When it does,
|
|
@@ -102,6 +105,16 @@ memory_resolve, memory_pr_status — always call them by these full names.
|
|
|
102
105
|
about the user that hold across all projects. When a saved fact becomes
|
|
103
106
|
outdated, call memory_supersede (find the old memory's id with memory_search
|
|
104
107
|
first) instead of adding a duplicate.
|
|
108
|
+
- When the user signals the session or task is wrapping up, call
|
|
109
|
+
memory_workingstate (action=write) with a short note: task summary, open
|
|
110
|
+
files, last commands, where the work stands, next step — so an interrupted
|
|
111
|
+
task can resume. It is scratch state, not knowledge: do not save it as a
|
|
112
|
+
memory; durable conclusions still follow the propose-first flow above.
|
|
113
|
+
- When a person confirms a memory was useful, or accepted work that clearly
|
|
114
|
+
relied on one, call memory_useful on it. NEVER call memory_useful just
|
|
115
|
+
because a memory appeared in results or the session-start block — passive
|
|
116
|
+
exposure never counts as useful. (Superseding or approving a memory also
|
|
117
|
+
auto-records its useful signal; no need to duplicate those.)
|
|
105
118
|
`;
|
|
106
119
|
/** Adapt a framework-agnostic op result to an MCP tool response. */
|
|
107
120
|
function toMcp(p) {
|
|
@@ -186,6 +199,11 @@ export async function runMcpServer() {
|
|
|
186
199
|
inputSchema: z.object(memoryForgetArgs),
|
|
187
200
|
annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
|
|
188
201
|
}, withSync((args) => toMcp(withOutboxNote(getScope().key, forgetMemory(args), "call memory_status to review"))));
|
|
202
|
+
server.registerTool("memory_useful", {
|
|
203
|
+
description: TOOL_DESCRIPTIONS.memory_useful,
|
|
204
|
+
inputSchema: z.object(memoryUsefulArgs),
|
|
205
|
+
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
|
|
206
|
+
}, withSync((args) => toMcp(markMemoryUseful(args))));
|
|
189
207
|
server.registerTool("memory_status", {
|
|
190
208
|
description: TOOL_DESCRIPTIONS.memory_status,
|
|
191
209
|
inputSchema: z.object(memoryStatusArgs),
|
|
@@ -216,6 +234,11 @@ export async function runMcpServer() {
|
|
|
216
234
|
inputSchema: z.object(memoryPrStatusArgs),
|
|
217
235
|
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
|
|
218
236
|
}, withSync((args) => toMcp(prStatusOp(args))));
|
|
237
|
+
server.registerTool("memory_workingstate", {
|
|
238
|
+
description: TOOL_DESCRIPTIONS.memory_workingstate,
|
|
239
|
+
inputSchema: z.object(memoryWorkingStateArgs),
|
|
240
|
+
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
|
|
241
|
+
}, withSync((args) => toMcp(workingStateMemory(getScope, cfg, args))));
|
|
219
242
|
const transport = new StdioServerTransport();
|
|
220
243
|
await server.connect(transport);
|
|
221
244
|
}
|
package/dist/opencode-v2.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, } from "./plugin-core.js";
|
|
2
|
+
import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, surfaceWorkingStateOnce, } from "./plugin-core.js";
|
|
3
3
|
import { makeTools } from "./tools/memory.js";
|
|
4
|
-
/** Register the
|
|
4
|
+
/** Register the seven memory tools on a v2 host. */
|
|
5
5
|
async function registerTools(ctx, state) {
|
|
6
6
|
const tools = makeTools(() => state.scope, state.cfg);
|
|
7
7
|
await ctx.tool.transform((editor) => {
|
|
@@ -35,6 +35,10 @@ export const v2Plugin = {
|
|
|
35
35
|
injectOnce(sessionID, state, (block) => {
|
|
36
36
|
ev.system.push({ type: "text", text: block });
|
|
37
37
|
});
|
|
38
|
+
// D89: the working-state note rides the same one-time pass.
|
|
39
|
+
surfaceWorkingStateOnce(sessionID, state, (block) => {
|
|
40
|
+
ev.system.push({ type: "text", text: block });
|
|
41
|
+
});
|
|
38
42
|
// D73: tell the agent what the keyword hook already stored this turn.
|
|
39
43
|
const handoff = captureHandoff(sessionID, state);
|
|
40
44
|
if (handoff)
|
package/dist/plugin-core.js
CHANGED
|
@@ -5,6 +5,7 @@ import { syncScope, upsertFromFile } from "./store/sync.js";
|
|
|
5
5
|
import { scopeHasFiles } from "./store/migrate.js";
|
|
6
6
|
import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
|
|
7
7
|
import { buildContextBlock } from "./retrieve/inject.js";
|
|
8
|
+
import { workingStateBlock } from "./working-state.js";
|
|
8
9
|
import { detectKeywords } from "./capture/keywords.js";
|
|
9
10
|
import { formatHandoffBlock, freshCaptures, } from "./capture/handoff.js";
|
|
10
11
|
import { findDuplicates } from "./store/lifecycle.js";
|
|
@@ -45,7 +46,7 @@ export function bootstrapPlugin(root) {
|
|
|
45
46
|
catch (err) {
|
|
46
47
|
console.error("[open-memex] init failed:", err);
|
|
47
48
|
}
|
|
48
|
-
return { cfg, scope, injectedSessions: new Set(), captures: new Map() };
|
|
49
|
+
return { cfg, scope, injectedSessions: new Set(), workingStateSessions: new Set(), captures: new Map() };
|
|
49
50
|
}
|
|
50
51
|
/**
|
|
51
52
|
* Keyword capture (§ capture): scan one user message for "remember …"
|
|
@@ -181,3 +182,29 @@ export function injectOnce(sessionID, state, push) {
|
|
|
181
182
|
}
|
|
182
183
|
return false;
|
|
183
184
|
}
|
|
185
|
+
/**
|
|
186
|
+
* §3.6 (D89): surface the working-state note once per session, alongside
|
|
187
|
+
* the context injection. Scratch state, not knowledge — the block itself
|
|
188
|
+
* says what it is. Exactly-once uses the same in-memory Set discipline as
|
|
189
|
+
* `injectOnce` (not persisted; restarting the host re-surfaces). Expired
|
|
190
|
+
* or missing notes surface nothing.
|
|
191
|
+
*/
|
|
192
|
+
export function surfaceWorkingStateOnce(sessionID, state, push) {
|
|
193
|
+
const { cfg, scope } = state;
|
|
194
|
+
if (!cfg.workingStateEnabled)
|
|
195
|
+
return false;
|
|
196
|
+
if (state.workingStateSessions.has(sessionID))
|
|
197
|
+
return false;
|
|
198
|
+
state.workingStateSessions.add(sessionID);
|
|
199
|
+
try {
|
|
200
|
+
const block = workingStateBlock(scope.key, scope.projectName, cfg);
|
|
201
|
+
if (block) {
|
|
202
|
+
push(block);
|
|
203
|
+
return true;
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
catch (err) {
|
|
207
|
+
console.error("[open-memex] working-state surfacing failed:", err);
|
|
208
|
+
}
|
|
209
|
+
return false;
|
|
210
|
+
}
|
package/dist/retrieve/inject.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { list, hitStateLabel } from "./search.js";
|
|
2
|
+
import { recordRetrieved } from "../store/usage.js";
|
|
2
3
|
import { PERSONAL_SCOPE } from "../scope.js";
|
|
3
4
|
function oneLine(s, max = 240) {
|
|
4
5
|
const trimmed = s.replace(/\s+/g, " ").trim();
|
|
@@ -9,6 +10,11 @@ export function buildContextBlock(scope, cfg) {
|
|
|
9
10
|
const user = list(PERSONAL_SCOPE.key, { limit: cfg.maxProfileItems });
|
|
10
11
|
if (project.length === 0 && user.length === 0)
|
|
11
12
|
return null;
|
|
13
|
+
// D77-L2: the injection is a retrieval surface — the memories it puts in
|
|
14
|
+
// front of the agent were "returned", so they count as exposure. It must
|
|
15
|
+
// NOT touch the useful counters: passive surfacing never refreshes
|
|
16
|
+
// usefulness (D77).
|
|
17
|
+
recordRetrieved([...project.map((m) => m.id), ...user.map((m) => m.id)]);
|
|
12
18
|
const lines = ["[OPEN-MEMEX]"];
|
|
13
19
|
if (user.length > 0) {
|
|
14
20
|
lines.push("", "User profile / preferences:");
|
package/dist/retrieve/search.js
CHANGED
|
@@ -2,6 +2,7 @@ import { db } from "../store/db.js";
|
|
|
2
2
|
import { toFtsQuery } from "./query.js";
|
|
3
3
|
import { BM25_WEIGHTS } from "./weights.js";
|
|
4
4
|
import { loadAliasEntries, planAliasExpansions, mergeRounds, } from "./alias-memory.js";
|
|
5
|
+
import { recordRetrieved } from "../store/usage.js";
|
|
5
6
|
function toHit(r) {
|
|
6
7
|
const aliases = r.aliases ? r.aliases.split(",").map((a) => a.trim()).filter(Boolean) : [];
|
|
7
8
|
let snippet = r.snippet ?? "";
|
|
@@ -232,7 +233,12 @@ export function search(query, opts = {}) {
|
|
|
232
233
|
// without a user alias the query side stays a single FTS round.
|
|
233
234
|
if (opts.stats)
|
|
234
235
|
opts.stats.candidates = merged.length;
|
|
235
|
-
|
|
236
|
+
const hits = resolveVisible(merged, limit, opts.stats);
|
|
237
|
+
// D77-L2: record only the ids actually returned — the candidate pool is
|
|
238
|
+
// not an exposure, and #53 guarantees the cut below is the final result.
|
|
239
|
+
if (opts.record && hits.length > 0)
|
|
240
|
+
recordRetrieved(hits.map((h) => h.id));
|
|
241
|
+
return hits;
|
|
236
242
|
}
|
|
237
243
|
export function list(scopeKey, opts = {}) {
|
|
238
244
|
const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));
|
|
@@ -257,9 +263,14 @@ export function list(scopeKey, opts = {}) {
|
|
|
257
263
|
if (opts.include === "all") {
|
|
258
264
|
// D68: the audit view — every row as stored (superseded versions,
|
|
259
265
|
// retracted, archived), no chain collapsing, capped at limit.
|
|
266
|
+
// NOT an exposure (D77-L2): the audit view is inspection for pruning
|
|
267
|
+
// decisions; counting it would inflate memories the user never saw.
|
|
260
268
|
return raw.slice(0, limit).map(toHit);
|
|
261
269
|
}
|
|
262
|
-
|
|
270
|
+
const hits = resolveVisible(raw, limit);
|
|
271
|
+
if (opts.record && hits.length > 0)
|
|
272
|
+
recordRetrieved(hits.map((h) => h.id));
|
|
273
|
+
return hits;
|
|
263
274
|
}
|
|
264
275
|
/**
|
|
265
276
|
* True totals for the inventory's truncation disclosure (D68). Under
|
package/dist/review.js
CHANGED
|
@@ -26,6 +26,7 @@ import { resolveProjectScope } from "./scope.js";
|
|
|
26
26
|
import { parse as parseMemory, serialize, atomicWriteTextSync, ulid, writeMemoryFile, } from "./store/markdown.js";
|
|
27
27
|
import { findMemoryFile } from "./store/lifecycle.js";
|
|
28
28
|
import { upsertFromFile } from "./store/sync.js";
|
|
29
|
+
import { recordUseful } from "./store/usage.js";
|
|
29
30
|
/** Best-effort author identity: git user.name, else the OS user. */
|
|
30
31
|
export function currentAuthor() {
|
|
31
32
|
try {
|
|
@@ -202,6 +203,12 @@ export function promoteMemory(id, opts = {}) {
|
|
|
202
203
|
};
|
|
203
204
|
atomicWriteTextSync(mf.filePath, serialize(fm, mf.body));
|
|
204
205
|
upsertFromFile({ fm, body: mf.body, filePath: mf.filePath, mtimeMs: Date.now() });
|
|
206
|
+
// D77-L2: a human approve at review is exactly the "explicit confirmation"
|
|
207
|
+
// the D77 useful definition names. One tick per approve step — the later
|
|
208
|
+
// published transition passes through approved and does not re-count.
|
|
209
|
+
// Always useful_team: promoteMemory is project-only by contract above.
|
|
210
|
+
if (to === "approved")
|
|
211
|
+
recordUseful(id, "team", "promote");
|
|
205
212
|
return { id, from, to, history: fm.review_history };
|
|
206
213
|
}
|
|
207
214
|
/** Render a memory's audit trail as compact human-readable lines (D29). */
|
package/dist/store/audit.js
CHANGED
|
@@ -4,6 +4,7 @@ import { readMemoryFile, iterInRepoMemoryFiles, iterMemoryFiles, } from "./markd
|
|
|
4
4
|
import { similarity, NEAR_DUP_THRESHOLD } from "./lifecycle.js";
|
|
5
5
|
import { projectRoot } from "../paths.js";
|
|
6
6
|
import { loadConfig } from "../config.js";
|
|
7
|
+
import { readWorkingState, workingStatePath } from "../working-state.js";
|
|
7
8
|
// Memory health audit (D57). Read-only: reports, never mutates.
|
|
8
9
|
// Checks, per open question "retrieval explainability & memory health":
|
|
9
10
|
// - near-duplicate pairs among active memories (same dedup yardstick
|
|
@@ -90,6 +91,18 @@ export function runAudit(scopeKeys) {
|
|
|
90
91
|
filesNotIndexed++;
|
|
91
92
|
}
|
|
92
93
|
}
|
|
94
|
+
// D89: expired working-state notes. Reports only, never auto-deletes
|
|
95
|
+
// (D57 posture) — the next wrap-up write overwrites them.
|
|
96
|
+
const cfg = loadConfig();
|
|
97
|
+
const workingStateExpired = scopeKeys
|
|
98
|
+
.map((key) => ({ key, note: readWorkingState(key, cfg.workingStateTtlDays) }))
|
|
99
|
+
.filter((e) => Boolean(e.note?.expired))
|
|
100
|
+
.map((e) => ({
|
|
101
|
+
scopeKey: e.key,
|
|
102
|
+
filePath: workingStatePath(e.key),
|
|
103
|
+
ageDays: e.note.ageDays,
|
|
104
|
+
ttlDays: e.note.ttlDays,
|
|
105
|
+
}));
|
|
93
106
|
return {
|
|
94
107
|
totalMemories: inScope.length,
|
|
95
108
|
duplicatePairs: pairs,
|
|
@@ -97,5 +110,6 @@ export function runAudit(scopeKeys) {
|
|
|
97
110
|
brokenChains,
|
|
98
111
|
personalInRepo,
|
|
99
112
|
drift: { filesNotIndexed, rowsMissingFiles },
|
|
113
|
+
workingStateExpired,
|
|
100
114
|
};
|
|
101
115
|
}
|
package/dist/store/db.js
CHANGED
|
@@ -111,6 +111,24 @@ END;
|
|
|
111
111
|
`;
|
|
112
112
|
/** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
|
|
113
113
|
const SCHEMA_VERSION = 9;
|
|
114
|
+
// D77-L2: reuse counters live in their own table, keyed by memory id. It is
|
|
115
|
+
// created on every open (CREATE IF NOT EXISTS) and deliberately NOT part of
|
|
116
|
+
// the rebuildable index: `rebuildIndexSchema` drops memories/memories_fts
|
|
117
|
+
// and re-derives them from the Markdown files, but the counters are
|
|
118
|
+
// accumulated telemetry with no source-of-truth file to rebuild from — so
|
|
119
|
+
// they must survive a rebuild (ids are stable: the files carry them).
|
|
120
|
+
// No SCHEMA_VERSION bump: the table is additive with IF NOT EXISTS.
|
|
121
|
+
const USAGE_SCHEMA = `
|
|
122
|
+
CREATE TABLE IF NOT EXISTS memory_usage (
|
|
123
|
+
id TEXT PRIMARY KEY,
|
|
124
|
+
retrieved_count INTEGER NOT NULL DEFAULT 0,
|
|
125
|
+
useful_self INTEGER NOT NULL DEFAULT 0,
|
|
126
|
+
useful_team INTEGER NOT NULL DEFAULT 0,
|
|
127
|
+
last_retrieved_at TEXT NOT NULL DEFAULT '',
|
|
128
|
+
last_useful_at TEXT,
|
|
129
|
+
updated_at TEXT NOT NULL DEFAULT ''
|
|
130
|
+
);
|
|
131
|
+
`;
|
|
114
132
|
function userVersion(d) {
|
|
115
133
|
const row = d.prepare("PRAGMA user_version").get();
|
|
116
134
|
return row.user_version;
|
|
@@ -165,6 +183,7 @@ export function db() {
|
|
|
165
183
|
rebuildIndexSchema(d);
|
|
166
184
|
d.exec(TABLE_SCHEMA);
|
|
167
185
|
d.exec(FTS_SCHEMA);
|
|
186
|
+
d.exec(USAGE_SCHEMA);
|
|
168
187
|
if (userVersion(d) < SCHEMA_VERSION)
|
|
169
188
|
rebuildIndexSchema(d);
|
|
170
189
|
_db = d;
|
package/dist/store/lifecycle.js
CHANGED
|
@@ -6,6 +6,7 @@ import { paths, projectRoot, inRepoMemoriesDirPath, } from "../paths.js";
|
|
|
6
6
|
import { loadConfig } from "../config.js";
|
|
7
7
|
import { cjkIndexText } from "../retrieve/cjk.js";
|
|
8
8
|
import { isTurnEcho } from "../capture/handoff.js";
|
|
9
|
+
import { recordUseful, usefulKindFor } from "./usage.js";
|
|
9
10
|
import { parse, serialize, atomicWriteTextSync, ulid, msToRfc3339, } from "./markdown.js";
|
|
10
11
|
/**
|
|
11
12
|
* Dedup + lifecycle (V2-DESIGN §3.3, §3.4).
|
|
@@ -207,6 +208,10 @@ export function supersede(oldId, input) {
|
|
|
207
208
|
if (oldMf.fm.status !== "active") {
|
|
208
209
|
throw new Error(`cannot supersede memory with status '${oldMf.fm.status}' (id ${oldId}); only active memories can be superseded`);
|
|
209
210
|
}
|
|
211
|
+
// D77-L2: the replacement's chain pointer back to this memory is a
|
|
212
|
+
// behavioral useful signal — something here was worth carrying forward.
|
|
213
|
+
// Classified from the OLD memory's state (captured before any flips).
|
|
214
|
+
const usefulKind = usefulKindFor(oldMf.fm.scope, oldMf.fm.review_state);
|
|
210
215
|
const now = msToRfc3339(Date.now());
|
|
211
216
|
const newFm = {
|
|
212
217
|
...oldMf.fm,
|
|
@@ -250,6 +255,9 @@ export function supersede(oldId, input) {
|
|
|
250
255
|
oldMf.fm.superseded_by = newFm.id;
|
|
251
256
|
oldMf.fm.updated_at = now;
|
|
252
257
|
rewriteMemoryFile(oldMf);
|
|
258
|
+
// Behavioral useful (D77) — recorded after both aliases of the chain are
|
|
259
|
+
// settled, so a crash mid-supersede never half-records.
|
|
260
|
+
recordUseful(oldId, usefulKind, "supersede");
|
|
253
261
|
return { oldMf, newMf };
|
|
254
262
|
}
|
|
255
263
|
const SETTABLE_STATUSES = [
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* D77-L2: per-memory online reuse counters — `retrieved_count` (exposure:
|
|
3
|
+
* returned by search / list / first-turn injection) and useful counts,
|
|
4
|
+
* split into `useful_self` (the author's own reuse — personal memories and
|
|
5
|
+
* unpublished project drafts) and `useful_team` (reuse of reviewed project
|
|
6
|
+
* knowledge). Derived: reuse_rate = (useful_self + useful_team) /
|
|
7
|
+
* retrieved_count; "zombie memories" (retrieved, never useful) surface in
|
|
8
|
+
* the D77-L3 report.
|
|
9
|
+
*
|
|
10
|
+
* Counters live in SQLite, NOT in frontmatter (D77): they are volatile
|
|
11
|
+
* local telemetry, the Markdown source of truth never rewrites itself with
|
|
12
|
+
* every retrieval, and they never leave the machine. The table is keyed by
|
|
13
|
+
* memory id and deliberately sits OUTSIDE the rebuildable index schema —
|
|
14
|
+
* `rebuildIndexSchema` drops `memories`/`memories_fts` but must not touch
|
|
15
|
+
* counters (the ids survive a rebuild because the files carry them).
|
|
16
|
+
*
|
|
17
|
+
* Restraint rules (D77): useful only via explicit signal — `memory_useful`,
|
|
18
|
+
* a human approve at review, or a behavioral reference (supersede).
|
|
19
|
+
* Passive surfacing increments ONLY retrieved_count; unguarded exposure
|
|
20
|
+
* must never refresh usefulness (the self-reinforcing retrieval loop).
|
|
21
|
+
*
|
|
22
|
+
* `reuse_rate` is the useful/retrieved ratio, not a probability: an explicit
|
|
23
|
+
* confirmation does not require a matching recorded exposure in the same
|
|
24
|
+
* counter window (a human can confirm a memory that paid off before counters
|
|
25
|
+
* existed, or confirm the same payoff twice), so the ratio can exceed 1.0.
|
|
26
|
+
* Read it as signal strength, not a percentage.
|
|
27
|
+
*/
|
|
28
|
+
import { db } from "./db.js";
|
|
29
|
+
export function usefulKindFor(scope, reviewState) {
|
|
30
|
+
if (scope === "personal")
|
|
31
|
+
return "self";
|
|
32
|
+
// No identity system (D77): reviewed project knowledge reused = the team
|
|
33
|
+
// story; everything else still reads as the author's own utility.
|
|
34
|
+
if (reviewState === "approved" || reviewState === "published")
|
|
35
|
+
return "team";
|
|
36
|
+
return "self";
|
|
37
|
+
}
|
|
38
|
+
const INSERT_RETRIEVED_SQL = `
|
|
39
|
+
INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
|
|
40
|
+
VALUES (?, 1, 0, 0, ?, NULL, ?)
|
|
41
|
+
ON CONFLICT(id) DO UPDATE SET
|
|
42
|
+
retrieved_count = memory_usage.retrieved_count + 1,
|
|
43
|
+
last_retrieved_at = excluded.last_retrieved_at,
|
|
44
|
+
updated_at = excluded.updated_at
|
|
45
|
+
`;
|
|
46
|
+
function insertUsefulSql(self) {
|
|
47
|
+
const col = self ? "useful_self" : "useful_team";
|
|
48
|
+
return `
|
|
49
|
+
INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
|
|
50
|
+
VALUES (?, 0, ${self ? 1 : 0}, ${self ? 0 : 1}, '', ?, ?)
|
|
51
|
+
ON CONFLICT(id) DO UPDATE SET
|
|
52
|
+
${col} = memory_usage.${col} + 1,
|
|
53
|
+
last_useful_at = excluded.last_useful_at,
|
|
54
|
+
updated_at = excluded.updated_at
|
|
55
|
+
`;
|
|
56
|
+
}
|
|
57
|
+
function rfc(ms) {
|
|
58
|
+
return new Date(ms).toISOString().replace(/\.000Z$/, "Z");
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Count one exposure each for the ids actually returned to a caller
|
|
62
|
+
* (already limited/filtered — callers record the final hits, not the
|
|
63
|
+
* candidate pool). Unknown/id-side dupes are absorbed: ids arrive deduped
|
|
64
|
+
* (resolution collapses chains anyway); anything not in the index yet is
|
|
65
|
+
* still counted — a just-saved memory can be hit in the same query that
|
|
66
|
+
* created it only after upsert, so the index row exists by contract; a
|
|
67
|
+
* missing one gets a row with last_retrieved_at set and no harm done.
|
|
68
|
+
*/
|
|
69
|
+
export function recordRetrieved(ids, atMs = Date.now()) {
|
|
70
|
+
if (ids.length === 0)
|
|
71
|
+
return 0;
|
|
72
|
+
// No explicit transaction wrapper: both drivers' .transaction() returns a
|
|
73
|
+
// deferred callable (calling it must NOT execute), and the common surface
|
|
74
|
+
// here is stmt-exec only. Per-row autocommit on WAL is plenty for the
|
|
75
|
+
// ≤50 ids one retrieval returns.
|
|
76
|
+
const d = db();
|
|
77
|
+
const at = rfc(atMs);
|
|
78
|
+
const stmt = d.prepare(INSERT_RETRIEVED_SQL);
|
|
79
|
+
for (const id of ids)
|
|
80
|
+
stmt.run(id, at, at);
|
|
81
|
+
return new Set(ids).size;
|
|
82
|
+
}
|
|
83
|
+
export const VIA_VALUES = ["tool", "supersede", "promote"];
|
|
84
|
+
/**
|
|
85
|
+
* Count one explicit useful signal. Returns the updated row, or null when
|
|
86
|
+
* the id is not in the index (callers surface that as not-found — a useful
|
|
87
|
+
* tick for a memory nobody has must not create phantom telemetry).
|
|
88
|
+
*/
|
|
89
|
+
export function recordUseful(id, kind, _via, atMs = Date.now()) {
|
|
90
|
+
const d = db();
|
|
91
|
+
const mem = d.prepare(`SELECT id FROM memories WHERE id = ?`).get(id);
|
|
92
|
+
if (!mem)
|
|
93
|
+
return null;
|
|
94
|
+
const at = rfc(atMs);
|
|
95
|
+
d.prepare(insertUsefulSql(kind === "self")).run(id, at, at);
|
|
96
|
+
return getUsage(id);
|
|
97
|
+
}
|
|
98
|
+
export function getUsage(id) {
|
|
99
|
+
const row = db()
|
|
100
|
+
.prepare(`SELECT id, retrieved_count, useful_self, useful_team,
|
|
101
|
+
last_retrieved_at, last_useful_at, updated_at
|
|
102
|
+
FROM memory_usage WHERE id = ?`)
|
|
103
|
+
.get(id);
|
|
104
|
+
if (!row)
|
|
105
|
+
return null;
|
|
106
|
+
row.retrieved_count = Number(row.retrieved_count) || 0;
|
|
107
|
+
row.useful_self = Number(row.useful_self) || 0;
|
|
108
|
+
row.useful_team = Number(row.useful_team) || 0;
|
|
109
|
+
return row;
|
|
110
|
+
}
|
|
111
|
+
/** D77: useful_count = useful_self + useful_team — both count as useful. */
|
|
112
|
+
export function usefulCount(u) {
|
|
113
|
+
return u.useful_self + u.useful_team;
|
|
114
|
+
}
|
|
115
|
+
/** reuse_rate = useful / retrieved (0 when the memory was never retrieved). */
|
|
116
|
+
export function reuseRate(u) {
|
|
117
|
+
const n = usefulCount(u);
|
|
118
|
+
if (u.retrieved_count <= 0)
|
|
119
|
+
return null;
|
|
120
|
+
return n / u.retrieved_count;
|
|
121
|
+
}
|
|
122
|
+
/** D77-L3's selection helpers ride the same table scan for free. */
|
|
123
|
+
export function listUsage(scopeKey) {
|
|
124
|
+
const sql = scopeKey
|
|
125
|
+
? `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
|
|
126
|
+
u.last_retrieved_at, u.last_useful_at, u.updated_at
|
|
127
|
+
FROM memory_usage u JOIN memories m ON m.id = u.id
|
|
128
|
+
WHERE m.scope_key = ?`
|
|
129
|
+
: `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
|
|
130
|
+
u.last_retrieved_at, u.last_useful_at, u.updated_at
|
|
131
|
+
FROM memory_usage u`;
|
|
132
|
+
const args = scopeKey ? [scopeKey] : [];
|
|
133
|
+
const rows = db().prepare(sql).all(...args);
|
|
134
|
+
for (const r of rows) {
|
|
135
|
+
r.retrieved_count = Number(r.retrieved_count) || 0;
|
|
136
|
+
r.useful_self = Number(r.useful_self) || 0;
|
|
137
|
+
r.useful_team = Number(r.useful_team) || 0;
|
|
138
|
+
}
|
|
139
|
+
return rows;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Drop one memory's telemetry. ONLY the hard-forget path calls this (the
|
|
143
|
+
* memory is gone for good); plain index removal — which fires on a branch
|
|
144
|
+
* switch, when in-repo files transiently disappear — must NOT prune here,
|
|
145
|
+
* or switching branches would wipe counters the files will resurrect.
|
|
146
|
+
* Superseded/deprecated/retracted memories keep their rows: their history
|
|
147
|
+
* is part of the reuse story.
|
|
148
|
+
*/
|
|
149
|
+
export function deleteUsage(id) {
|
|
150
|
+
db().prepare(`DELETE FROM memory_usage WHERE id = ?`).run(id);
|
|
151
|
+
}
|
package/dist/tools/memory.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { PERSONAL_SCOPE } from "../scope.js";
|
|
2
2
|
import { syncScope } from "../store/sync.js";
|
|
3
|
-
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./ops.js";
|
|
3
|
+
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, markMemoryUseful, workingStateMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryUsefulArgs, memoryWorkingStateArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./ops.js";
|
|
4
4
|
// Local stand-in for the SDK's tool() helper — same signature, and the SDK
|
|
5
5
|
// function is a runtime identity (`return input`). Do NOT import it from
|
|
6
6
|
// @opencode-ai/plugin at runtime: that package is a devDependency, and when
|
|
@@ -72,5 +72,24 @@ export function makeTools(getScope, cfg) {
|
|
|
72
72
|
return withOutboxNote(getScope().key, forgetMemory(args));
|
|
73
73
|
},
|
|
74
74
|
});
|
|
75
|
-
|
|
75
|
+
// D77-L2: explicit useful confirmation. Needs a fresh index read to
|
|
76
|
+
// classify (scope/review_state), hence syncFirst like the mutators.
|
|
77
|
+
const memory_useful = tool({
|
|
78
|
+
description: TOOL_DESCRIPTIONS.memory_useful,
|
|
79
|
+
args: memoryUsefulArgs,
|
|
80
|
+
async execute(args) {
|
|
81
|
+
syncFirst();
|
|
82
|
+
return markMemoryUseful(args);
|
|
83
|
+
},
|
|
84
|
+
});
|
|
85
|
+
// §3.6 (D89): no scope/index work needed — the note lives beside the
|
|
86
|
+
// store, not in it.
|
|
87
|
+
const memory_workingstate = tool({
|
|
88
|
+
description: TOOL_DESCRIPTIONS.memory_workingstate,
|
|
89
|
+
args: memoryWorkingStateArgs,
|
|
90
|
+
async execute(args) {
|
|
91
|
+
return workingStateMemory(getScope, cfg, args);
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
return { memory_add, memory_search, memory_list, memory_forget, memory_supersede, memory_useful, memory_workingstate };
|
|
76
95
|
}
|