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.
Files changed (52) hide show
  1. package/AGENTS.md +21 -5
  2. package/CHANGELOG.md +10 -0
  3. package/README.md +46 -13
  4. package/README.zh-CN.md +25 -11
  5. package/dist/.build-stamp +1 -1
  6. package/dist/cli.js +103 -6
  7. package/dist/config.js +9 -0
  8. package/dist/doctor.js +4 -2
  9. package/dist/index.js +6 -1
  10. package/dist/init.js +13 -3
  11. package/dist/mcp.js +28 -5
  12. package/dist/opencode-v2.js +6 -2
  13. package/dist/plugin-core.js +28 -1
  14. package/dist/retrieve/inject.js +6 -0
  15. package/dist/retrieve/search.js +13 -2
  16. package/dist/review.js +7 -0
  17. package/dist/store/audit.js +14 -0
  18. package/dist/store/db.js +19 -0
  19. package/dist/store/lifecycle.js +8 -0
  20. package/dist/store/usage.js +151 -0
  21. package/dist/tools/memory.js +21 -2
  22. package/dist/tools/ops.js +123 -1
  23. package/dist/working-state.js +118 -0
  24. package/docs/CONCEPTS.md +16 -0
  25. package/docs/CONCEPTS.zh-CN.md +13 -0
  26. package/docs/V2-DESIGN.md +42 -1039
  27. package/docs/design/decisions.md +1146 -0
  28. package/docs/design/knowledge-graph.md +86 -0
  29. package/package.json +66 -66
  30. package/scripts/smoke-mcp.ts +67 -4
  31. package/scripts/smoke-pure.ts +70 -0
  32. package/scripts/test-full.ts +83 -0
  33. package/server.json +2 -2
  34. package/skills/open-memex/SKILL.md +19 -0
  35. package/src/cli.ts +111 -6
  36. package/src/config.ts +16 -0
  37. package/src/doctor.ts +4 -2
  38. package/src/index.ts +6 -0
  39. package/src/init.ts +13 -3
  40. package/src/mcp.ts +41 -4
  41. package/src/opencode-v2.ts +7 -2
  42. package/src/plugin-core.ts +32 -1
  43. package/src/retrieve/inject.ts +7 -0
  44. package/src/retrieve/search.ts +19 -3
  45. package/src/review.ts +6 -0
  46. package/src/store/audit.ts +20 -0
  47. package/src/store/db.ts +20 -0
  48. package/src/store/lifecycle.ts +9 -0
  49. package/src/store/usage.ts +178 -0
  50. package/src/tools/memory.ts +26 -1
  51. package/src/tools/ops.ts +158 -1
  52. 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 memory_status / memory_submit / memory_propose /
7
- * memory_promote / memory_resolve / memory_pr_status) over the Model Context Protocol, so any MCP client —
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, memory_status, memory_submit, memory_propose, memory_promote,
56
- memory_resolve, memory_pr_status — always call them by these full names.
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
  }
@@ -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 five memory tools on a v2 host. */
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)
@@ -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
+ }
@@ -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:");
@@ -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
- return resolveVisible(merged, limit, opts.stats);
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
- return resolveVisible(raw, limit);
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). */
@@ -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;
@@ -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
+ }
@@ -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
- return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };
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
  }