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/src/store/db.ts CHANGED
@@ -127,6 +127,25 @@ END;
127
127
  /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
128
128
  const SCHEMA_VERSION = 9;
129
129
 
130
+ // D77-L2: reuse counters live in their own table, keyed by memory id. It is
131
+ // created on every open (CREATE IF NOT EXISTS) and deliberately NOT part of
132
+ // the rebuildable index: `rebuildIndexSchema` drops memories/memories_fts
133
+ // and re-derives them from the Markdown files, but the counters are
134
+ // accumulated telemetry with no source-of-truth file to rebuild from — so
135
+ // they must survive a rebuild (ids are stable: the files carry them).
136
+ // No SCHEMA_VERSION bump: the table is additive with IF NOT EXISTS.
137
+ const USAGE_SCHEMA = `
138
+ CREATE TABLE IF NOT EXISTS memory_usage (
139
+ id TEXT PRIMARY KEY,
140
+ retrieved_count INTEGER NOT NULL DEFAULT 0,
141
+ useful_self INTEGER NOT NULL DEFAULT 0,
142
+ useful_team INTEGER NOT NULL DEFAULT 0,
143
+ last_retrieved_at TEXT NOT NULL DEFAULT '',
144
+ last_useful_at TEXT,
145
+ updated_at TEXT NOT NULL DEFAULT ''
146
+ );
147
+ `;
148
+
130
149
  function userVersion(d: AnyDatabase): number {
131
150
  const row = d.prepare("PRAGMA user_version").get() as { user_version: number };
132
151
  return row.user_version;
@@ -181,6 +200,7 @@ export function db(): AnyDatabase {
181
200
  if (hasTable && userVersion(d) < SCHEMA_VERSION) rebuildIndexSchema(d);
182
201
  d.exec(TABLE_SCHEMA);
183
202
  d.exec(FTS_SCHEMA);
203
+ d.exec(USAGE_SCHEMA);
184
204
  if (userVersion(d) < SCHEMA_VERSION) rebuildIndexSchema(d);
185
205
  _db = d;
186
206
  return d;
@@ -10,6 +10,7 @@ import {
10
10
  import { loadConfig } from "../config.ts";
11
11
  import { cjkIndexText } from "../retrieve/cjk.ts";
12
12
  import { isTurnEcho } from "../capture/handoff.ts";
13
+ import { recordUseful, usefulKindFor } from "./usage.ts";
13
14
  import {
14
15
  parse,
15
16
  serialize,
@@ -282,6 +283,10 @@ export function supersede(
282
283
  `cannot supersede memory with status '${oldMf.fm.status}' (id ${oldId}); only active memories can be superseded`,
283
284
  );
284
285
  }
286
+ // D77-L2: the replacement's chain pointer back to this memory is a
287
+ // behavioral useful signal — something here was worth carrying forward.
288
+ // Classified from the OLD memory's state (captured before any flips).
289
+ const usefulKind = usefulKindFor(oldMf.fm.scope, oldMf.fm.review_state);
285
290
 
286
291
  const now = msToRfc3339(Date.now());
287
292
  const newFm: Frontmatter = {
@@ -329,6 +334,10 @@ export function supersede(
329
334
  oldMf.fm.updated_at = now;
330
335
  rewriteMemoryFile(oldMf);
331
336
 
337
+ // Behavioral useful (D77) — recorded after both aliases of the chain are
338
+ // settled, so a crash mid-supersede never half-records.
339
+ recordUseful(oldId, usefulKind, "supersede");
340
+
332
341
  return { oldMf, newMf };
333
342
  }
334
343
 
@@ -0,0 +1,178 @@
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.ts";
29
+
30
+ export type UsefulKind = "self" | "team";
31
+
32
+ export interface MemoryUsage {
33
+ id: string;
34
+ retrieved_count: number;
35
+ useful_self: number;
36
+ useful_team: number;
37
+ last_retrieved_at: string; // RFC 3339, "" when never
38
+ last_useful_at: string | null; // RFC 3339
39
+ updated_at: string; // RFC 3339
40
+ }
41
+
42
+ export function usefulKindFor(scope: unknown, reviewState: unknown): UsefulKind {
43
+ if (scope === "personal") return "self";
44
+ // No identity system (D77): reviewed project knowledge reused = the team
45
+ // story; everything else still reads as the author's own utility.
46
+ if (reviewState === "approved" || reviewState === "published") return "team";
47
+ return "self";
48
+ }
49
+
50
+ const INSERT_RETRIEVED_SQL = `
51
+ INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
52
+ VALUES (?, 1, 0, 0, ?, NULL, ?)
53
+ ON CONFLICT(id) DO UPDATE SET
54
+ retrieved_count = memory_usage.retrieved_count + 1,
55
+ last_retrieved_at = excluded.last_retrieved_at,
56
+ updated_at = excluded.updated_at
57
+ `;
58
+
59
+ function insertUsefulSql(self: boolean): string {
60
+ const col = self ? "useful_self" : "useful_team";
61
+ return `
62
+ INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
63
+ VALUES (?, 0, ${self ? 1 : 0}, ${self ? 0 : 1}, '', ?, ?)
64
+ ON CONFLICT(id) DO UPDATE SET
65
+ ${col} = memory_usage.${col} + 1,
66
+ last_useful_at = excluded.last_useful_at,
67
+ updated_at = excluded.updated_at
68
+ `;
69
+ }
70
+
71
+ function rfc(ms: number): string {
72
+ return new Date(ms).toISOString().replace(/\.000Z$/, "Z");
73
+ }
74
+
75
+ /**
76
+ * Count one exposure each for the ids actually returned to a caller
77
+ * (already limited/filtered — callers record the final hits, not the
78
+ * candidate pool). Unknown/id-side dupes are absorbed: ids arrive deduped
79
+ * (resolution collapses chains anyway); anything not in the index yet is
80
+ * still counted — a just-saved memory can be hit in the same query that
81
+ * created it only after upsert, so the index row exists by contract; a
82
+ * missing one gets a row with last_retrieved_at set and no harm done.
83
+ */
84
+ export function recordRetrieved(ids: readonly string[], atMs: number = Date.now()): number {
85
+ if (ids.length === 0) return 0;
86
+ // No explicit transaction wrapper: both drivers' .transaction() returns a
87
+ // deferred callable (calling it must NOT execute), and the common surface
88
+ // here is stmt-exec only. Per-row autocommit on WAL is plenty for the
89
+ // ≤50 ids one retrieval returns.
90
+ const d = db();
91
+ const at = rfc(atMs);
92
+ const stmt = d.prepare(INSERT_RETRIEVED_SQL);
93
+ for (const id of ids) stmt.run(id, at, at);
94
+ return new Set(ids).size;
95
+ }
96
+
97
+ export const VIA_VALUES = ["tool", "supersede", "promote"] as const;
98
+ export type UsefulVia = (typeof VIA_VALUES)[number];
99
+
100
+ /**
101
+ * Count one explicit useful signal. Returns the updated row, or null when
102
+ * the id is not in the index (callers surface that as not-found — a useful
103
+ * tick for a memory nobody has must not create phantom telemetry).
104
+ */
105
+ export function recordUseful(
106
+ id: string,
107
+ kind: UsefulKind,
108
+ _via: UsefulVia,
109
+ atMs: number = Date.now(),
110
+ ): MemoryUsage | null {
111
+ const d = db();
112
+ const mem = d.prepare(`SELECT id FROM memories WHERE id = ?`).get(id) as
113
+ | { id: string }
114
+ | undefined;
115
+ if (!mem) return null;
116
+ const at = rfc(atMs);
117
+ d.prepare(insertUsefulSql(kind === "self")).run(id, at, at);
118
+ return getUsage(id);
119
+ }
120
+
121
+ export function getUsage(id: string): MemoryUsage | null {
122
+ const row = db()
123
+ .prepare(
124
+ `SELECT id, retrieved_count, useful_self, useful_team,
125
+ last_retrieved_at, last_useful_at, updated_at
126
+ FROM memory_usage WHERE id = ?`,
127
+ )
128
+ .get(id) as MemoryUsage | undefined;
129
+ if (!row) return null;
130
+ row.retrieved_count = Number(row.retrieved_count) || 0;
131
+ row.useful_self = Number(row.useful_self) || 0;
132
+ row.useful_team = Number(row.useful_team) || 0;
133
+ return row;
134
+ }
135
+
136
+ /** D77: useful_count = useful_self + useful_team — both count as useful. */
137
+ export function usefulCount(u: Pick<MemoryUsage, "useful_self" | "useful_team">): number {
138
+ return u.useful_self + u.useful_team;
139
+ }
140
+
141
+ /** reuse_rate = useful / retrieved (0 when the memory was never retrieved). */
142
+ export function reuseRate(u: MemoryUsage): number | null {
143
+ const n = usefulCount(u);
144
+ if (u.retrieved_count <= 0) return null;
145
+ return n / u.retrieved_count;
146
+ }
147
+
148
+ /** D77-L3's selection helpers ride the same table scan for free. */
149
+ export function listUsage(scopeKey?: string): MemoryUsage[] {
150
+ const sql = scopeKey
151
+ ? `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
152
+ u.last_retrieved_at, u.last_useful_at, u.updated_at
153
+ FROM memory_usage u JOIN memories m ON m.id = u.id
154
+ WHERE m.scope_key = ?`
155
+ : `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
156
+ u.last_retrieved_at, u.last_useful_at, u.updated_at
157
+ FROM memory_usage u`;
158
+ const args = scopeKey ? [scopeKey] : [];
159
+ const rows = db().prepare(sql).all(...(args as unknown[])) as MemoryUsage[];
160
+ for (const r of rows) {
161
+ r.retrieved_count = Number(r.retrieved_count) || 0;
162
+ r.useful_self = Number(r.useful_self) || 0;
163
+ r.useful_team = Number(r.useful_team) || 0;
164
+ }
165
+ return rows;
166
+ }
167
+
168
+ /**
169
+ * Drop one memory's telemetry. ONLY the hard-forget path calls this (the
170
+ * memory is gone for good); plain index removal — which fires on a branch
171
+ * switch, when in-repo files transiently disappear — must NOT prune here,
172
+ * or switching branches would wipe counters the files will resurrect.
173
+ * Superseded/deprecated/retracted memories keep their rows: their history
174
+ * is part of the reuse story.
175
+ */
176
+ export function deleteUsage(id: string): void {
177
+ db().prepare(`DELETE FROM memory_usage WHERE id = ?`).run(id);
178
+ }
@@ -10,11 +10,15 @@ import {
10
10
  listMemories,
11
11
  supersedeMemory,
12
12
  forgetMemory,
13
+ markMemoryUseful,
14
+ workingStateMemory,
13
15
  memoryAddArgs,
14
16
  memorySearchArgs,
15
17
  memoryListArgs,
16
18
  memorySupersedeArgs,
17
19
  memoryForgetArgs,
20
+ memoryUsefulArgs,
21
+ memoryWorkingStateArgs,
18
22
  TOOL_DESCRIPTIONS,
19
23
  withOutboxNote,
20
24
  } from "./ops.ts";
@@ -100,5 +104,26 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
100
104
  },
101
105
  });
102
106
 
103
- return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };
107
+ // D77-L2: explicit useful confirmation. Needs a fresh index read to
108
+ // classify (scope/review_state), hence syncFirst like the mutators.
109
+ const memory_useful = tool({
110
+ description: TOOL_DESCRIPTIONS.memory_useful,
111
+ args: memoryUsefulArgs,
112
+ async execute(args) {
113
+ syncFirst();
114
+ return markMemoryUseful(args);
115
+ },
116
+ });
117
+
118
+ // §3.6 (D89): no scope/index work needed — the note lives beside the
119
+ // store, not in it.
120
+ const memory_workingstate = tool({
121
+ description: TOOL_DESCRIPTIONS.memory_workingstate,
122
+ args: memoryWorkingStateArgs,
123
+ async execute(args) {
124
+ return workingStateMemory(getScope, cfg, args);
125
+ },
126
+ });
127
+
128
+ return { memory_add, memory_search, memory_list, memory_forget, memory_supersede, memory_useful, memory_workingstate };
104
129
  }
package/src/tools/ops.ts CHANGED
@@ -25,11 +25,24 @@ import {
25
25
  import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
26
26
  import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.ts";
27
27
  import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.ts";
28
+ import {
29
+ getUsage,
30
+ recordUseful,
31
+ reuseRate,
32
+ usefulKindFor,
33
+ usefulCount,
34
+ deleteUsage,
35
+ } from "../store/usage.ts";
28
36
  import { db } from "../store/db.ts";
29
37
  import { redact } from "../redact.ts";
30
38
  import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.ts";
31
39
  import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.ts";
32
40
  import { isInRepoMemoryFile } from "../paths.ts";
41
+ import {
42
+ writeWorkingState,
43
+ readWorkingState,
44
+ clearWorkingState,
45
+ } from "../working-state.ts";
33
46
  import {
34
47
  proposeMemories,
35
48
  promoteMemory,
@@ -87,6 +100,10 @@ export const TOOL_DESCRIPTIONS = {
87
100
  "List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved. Run it when a git pull or merge leaves memory files conflicted; the merged file is written in place (undo with git if the merge is wrong). For PR review state rather than file conflicts, use memory_pr_status. (MCP server and the `open-memex resolve` CLI; the opencode native plugin does not expose this tool.)",
88
101
  memory_pr_status:
89
102
  "Read the current branch's GitHub PR and map its review state onto each in-repo memory: merged PR → published, PR approval → approved (approved_by = reviewer), changes-requested → suggestion only. Report by default — that mode changes nothing; apply=true writes the mapped transitions to the local files (still no push). (MCP server and the `open-memex pr-status` CLI; the opencode native plugin does not expose this tool.)",
103
+ memory_workingstate:
104
+ "Read, write, or clear the one ephemeral per-project working-state note (§3.6, D89): where an interrupted task stands, so a fresh session can resume. Scratch state, NOT durable knowledge — it never enters memory retrieval or a review ladder; any conclusion here that should outlive the task goes through the normal memory_add/checkpoint-proposal path instead. WRITE it (action=write, content required) when the user signals the session or task is wrapping up — body rubric: task summary (one paragraph), open files, last commands, where the work stands, next step; short by design, a scratch note, not a transcript. READ it when resuming work or when the user asks what they were doing. CLEAR it on the user's request only. The note lives outside memories/, the user can edit the plain file directly, and it expires after ttl_days (default 7) — expired notes are ignored and `audit` reports them.",
105
+ memory_useful:
106
+ "Mark an existing memory as useful (D77): record that it demonstrably paid off. Call it ONLY on an explicit signal — the user confirmed it helped ('that was the one', 'saved me again'), or your completed/accepted work clearly relied on that memory and the user saw the result. NEVER call it because a memory appeared in memory_search results, a memory_list inventory, or the session-start block: passive exposure never refreshes usefulness. Exposure is counted automatically under retrieved_count; the useful buckets increment only through this tool, a human approval at review, or a supersede. Useful is split automatically: useful_self for personal memories and unpublished project drafts (the author's own utility), useful_team for approved/published project memories (team knowledge reused) — pass kind only to override. Returns the cumulative counts and reuse_rate (useful / retrieved). The counters live in the local SQLite index, not in the Markdown source of truth, and never leave this machine.",
90
107
  } as const;
91
108
 
92
109
  /** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
@@ -263,6 +280,36 @@ export const memoryPrStatusArgs = {
263
280
  };
264
281
  export type MemoryPrStatusArgs = z.infer<z.ZodObject<typeof memoryPrStatusArgs>>;
265
282
 
283
+ export const memoryWorkingStateArgs = {
284
+ action: z
285
+ .enum(["read", "write", "clear"])
286
+ .default("read")
287
+ .describe(
288
+ "read = show the current note (empty when none); write = create or refresh it; clear = delete it.",
289
+ ),
290
+ content: z
291
+ .string()
292
+ .optional()
293
+ .describe(
294
+ "Note body, Markdown, short by design (required for write). Rubric: task summary (one paragraph), open files, last commands, where the work stands, next step. A scratch note, not a transcript.",
295
+ ),
296
+ };
297
+ export type MemoryWorkingStateArgs = z.infer<z.ZodObject<typeof memoryWorkingStateArgs>>;
298
+
299
+ export const memoryUsefulArgs = {
300
+ id: z
301
+ .string()
302
+ .min(1)
303
+ .describe("ID of the memory being confirmed useful (memory_search / memory_list return ids)."),
304
+ kind: z
305
+ .enum(["self", "team"])
306
+ .optional()
307
+ .describe(
308
+ "Which useful counter. Default: auto — personal memories and unpublished project drafts count useful_self; approved/published project memories count useful_team. Pass only to override the auto split.",
309
+ ),
310
+ };
311
+ export type MemoryUsefulArgs = z.infer<z.ZodObject<typeof memoryUsefulArgs>>;
312
+
266
313
  function resolveScope(
267
314
  getScope: () => Scope,
268
315
  kind?: "project" | "personal",
@@ -400,10 +447,12 @@ export async function searchMemories(
400
447
  : args.scope === "project"
401
448
  ? [project.key]
402
449
  : [project.key, PERSONAL_SCOPE.key];
450
+ // D77-L2: every surface that hands hits to a caller counts as exposure.
403
451
  const hits = search(args.query, {
404
452
  scopeKeys,
405
453
  limit: args.limit,
406
454
  type: args.type,
455
+ record: true,
407
456
  });
408
457
  if (hits.length === 0) {
409
458
  return {
@@ -431,7 +480,7 @@ export async function listMemories(
431
480
  // #3" names exactly one memory. A per-section counter emitted two "#1"s.
432
481
  let seq = 0;
433
482
  const render = (scopeKey: string) => {
434
- const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
483
+ const hits = list(scopeKey, { type: args.type, limit: args.limit, include, record: true });
435
484
  const total = countList(scopeKey, { type: args.type, include });
436
485
  const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
437
486
  const note = truncationNote(hits.length, total);
@@ -569,6 +618,10 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
569
618
  }
570
619
  }
571
620
  deleteFromIndex(args.id);
621
+ // D77-L2: the memory is gone for good — its telemetry has no subject left.
622
+ // Only the hard path prunes the usage row; status flips and index removal
623
+ // (branch switches remove in-repo files transiently) keep it.
624
+ deleteUsage(args.id);
572
625
  // D64: forgetting an in-repo memory deletes a file inside the user's
573
626
  // git working tree. Say so — the deletion should ride a commit, or the
574
627
  // file silently diverges from what teammates have.
@@ -586,6 +639,46 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
586
639
  // sync loop: status → ask user → submit → push/PR on approval).
587
640
  // ---------------------------------------------------------------------------
588
641
 
642
+ /**
643
+ * D77-L2: the explicit confirmation route to the useful counters. The
644
+ * restraint rules live in the tool description and the MCP handshake —
645
+ * an unguarded call path here would create the self-reinforcing retrieval
646
+ * loop D77 warns about, so nothing silently routes exposure into useful.
647
+ * Classification proxy (no identity system): personal scope / unreviewed
648
+ * project draft → useful_self; approved/published project memory → useful_team.
649
+ */
650
+ export async function markMemoryUseful(
651
+ args: MemoryUsefulArgs,
652
+ ): Promise<ToolResult> {
653
+ const row = db()
654
+ .prepare(`SELECT scope, review_state FROM memories WHERE id = ?`)
655
+ .get(args.id) as { scope: string; review_state: string } | undefined;
656
+ if (!row) {
657
+ return {
658
+ title: "memory: useful not found",
659
+ output: `No memory with id ${args.id} in the index — memory_search or memory_list returns current ids.`,
660
+ };
661
+ }
662
+ const kind = args.kind ?? usefulKindFor(row.scope, row.review_state);
663
+ const after = recordUseful(args.id, kind, "tool");
664
+ // recordUseful re-checks existence; both branches above agree on not-found.
665
+ if (!after) {
666
+ return {
667
+ title: "memory: useful not found",
668
+ output: `No memory with id ${args.id} in the index.`,
669
+ };
670
+ }
671
+ const u = getUsage(args.id)!;
672
+ const rate = reuseRate(u);
673
+ const useful = usefulCount(u);
674
+ return {
675
+ title: `memory: useful (${kind}) ${args.id}`,
676
+ output:
677
+ `Marked useful (${kind}). retrieved: ${u.retrieved_count}, useful_self: ${u.useful_self}, useful_team: ${u.useful_team}, reuse_rate: ${rate === null ? "n/a (never retrieved)" : rate.toFixed(2)}.` +
678
+ `\nA supersede or a human approval also counts — no need to duplicate those with an explicit call.`,
679
+ };
680
+ }
681
+
589
682
  export async function statusMemories(): Promise<ToolResult> {
590
683
  const st = getSyncStatus();
591
684
  const n =
@@ -682,3 +775,67 @@ export async function prStatusOp(args: MemoryPrStatusArgs): Promise<ToolResult>
682
775
  }
683
776
  return { title: "memory: pr-status", output: lines.join("\n") };
684
777
  }
778
+
779
+ /**
780
+ * §3.6 (D89): the one ephemeral per-project working-state note. Scratch
781
+ * state, not knowledge — it never enters the review ladder or the
782
+ * retrieval index; durable conclusions still go through memory_add (agent
783
+ * proposes, user approves). The tool description and the session-start
784
+ * block must keep saying the same thing on this.
785
+ */
786
+ export async function workingStateMemory(
787
+ getScope: () => Scope,
788
+ cfg: MyOMemoryConfig,
789
+ args: MemoryWorkingStateArgs,
790
+ ): Promise<ToolResult> {
791
+ if (!cfg.workingStateEnabled) {
792
+ return {
793
+ title: "memory: working-state",
794
+ output:
795
+ "The working-state note is disabled (config workingStateEnabled=false). Enable it in the config file, or record durable facts with memory_add instead.",
796
+ };
797
+ }
798
+ const scope = getScope();
799
+ if (args.action === "clear") {
800
+ const gone = clearWorkingState(scope.key);
801
+ return {
802
+ title: "memory: working-state",
803
+ output: gone
804
+ ? `Working-state note for ${scope.projectName} deleted.`
805
+ : "Failed to delete the working-state note — it may still be on disk.",
806
+ };
807
+ }
808
+ if (args.action === "write") {
809
+ const content = (args.content ?? "").trim();
810
+ if (!content) {
811
+ return {
812
+ title: "memory: working-state",
813
+ output:
814
+ "Refusing an empty working-state note: pass content (task summary, open files, last commands, where the work stands, next step).",
815
+ };
816
+ }
817
+ const r = writeWorkingState(scope.key, content, cfg.workingStateTtlDays, cfg.redactPatterns);
818
+ const secretNote = r.hadSecret
819
+ ? `\n[open-memex: a secret was masked in place (${r.matchedPattern}) before saving]`
820
+ : "";
821
+ return {
822
+ title: "memory: working-state",
823
+ output:
824
+ `Working-state note written to ${r.filePath}. Surfaces at session start; expires after ${cfg.workingStateTtlDays} day${cfg.workingStateTtlDays === 1 ? "" : "s"} or at the next write.${secretNote}`,
825
+ };
826
+ }
827
+ const note = readWorkingState(scope.key, cfg.workingStateTtlDays);
828
+ if (!note) {
829
+ return {
830
+ title: "memory: working-state",
831
+ output: `No working-state note for ${scope.projectName}. Write one at wrap-up (action=write) so an interrupted task can resume.`,
832
+ };
833
+ }
834
+ const status = note.expired
835
+ ? `EXPIRED (${note.ageDays} day${note.ageDays === 1 ? "" : "s"} old, ttl ${note.ttlDays}) — stale until a write refreshes it`
836
+ : `updated ${note.ageDays} day${note.ageDays === 1 ? "" : "s"} ago, ttl ${note.ttlDays} day${note.ttlDays === 1 ? "" : "s"}`;
837
+ return {
838
+ title: "memory: working-state",
839
+ output: `[${status}]\n\n${note.content}`,
840
+ };
841
+ }
@@ -0,0 +1,153 @@
1
+ /**
2
+ * D89 / §3.6 — session working state note.
3
+ *
4
+ * One ephemeral Markdown note per project scope, at
5
+ * `working-state/<scope_key>.md` under the data root — beside the store,
6
+ * never inside `memories/`, never committed to a repo. The note is written
7
+ * or refreshed by the agent at wrap-up, surfaced at session start alongside
8
+ * the §7 injection, and never enters the review ladder: it is scratch
9
+ * state, not knowledge. Worth-keeping content routes through the D61
10
+ * checkpoint-proposal flow — the note is raw material, the ladder is the
11
+ * gate. Expired notes are reported by `audit` (reports only, never
12
+ * auto-deletes — the D57 posture); the next wrap-up write overwrites.
13
+ *
14
+ * Hermetic on purpose: only fs, paths and config types are imported, no
15
+ * sqlite — scripts/smoke-pure.ts keeps its no-sqlite guarantee.
16
+ */
17
+ import fs from "node:fs";
18
+ import path from "node:path";
19
+ import { paths } from "./paths.ts";
20
+ import { redact } from "./redact.ts";
21
+ import { atomicWriteTextSync } from "./store/markdown.ts";
22
+ import type { MyOMemoryConfig } from "./config.ts";
23
+
24
+ const DAY_MS = 86_400_000;
25
+
26
+ export interface WorkingStateFile {
27
+ content: string;
28
+ /** Filesystem write time in ms (the note's own age anchor). */
29
+ updatedAtMs: number;
30
+ /** TTL days effective for this note (frontmatter `ttl_days`, falling
31
+ * back to the given default). */
32
+ ttlDays: number;
33
+ /** Whole-day age of the note. */
34
+ ageDays: number;
35
+ /** True when ageDays > ttlDays — ignored by surfacing, reported by audit. */
36
+ expired: boolean;
37
+ }
38
+
39
+ export interface WriteWorkingStateResult {
40
+ filePath: string;
41
+ hadSecret: boolean;
42
+ matchedPattern: string | null;
43
+ }
44
+
45
+ /** Read-only path helper — never creates the directory (D70 discipline;
46
+ * contrast the write path below, which mkdirs on demand). */
47
+ export function workingStatePath(scopeKey: string): string {
48
+ return path.join(paths().root, "working-state", `${scopeKey}.md`);
49
+ }
50
+
51
+ /**
52
+ * Write or refresh the note. The agent composes the body (task summary /
53
+ * open files / last commands / where the work stands / next step). Content
54
+ * passes through `redact()` so command paste-through from an interrupted
55
+ * session cannot park a readable secret in storage. TTL days is stamped
56
+ * into frontmatter so the user's per-note edit survives config changes.
57
+ */
58
+ export function writeWorkingState(
59
+ scopeKey: string,
60
+ content: string,
61
+ defaultTtlDays: number,
62
+ redactPatterns: string[],
63
+ ): WriteWorkingStateResult {
64
+ const { content: redacted, hadSecret, matchedPattern } = redact(content, redactPatterns);
65
+ const filePath = workingStatePath(scopeKey);
66
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
67
+ const ttlDays = Number.isInteger(defaultTtlDays) && defaultTtlDays > 0 ? defaultTtlDays : 7;
68
+ const text =
69
+ "---\n" +
70
+ "schema: working-state\n" +
71
+ `updated_at: ${new Date().toISOString()}\n` +
72
+ `ttl_days: ${ttlDays}\n` +
73
+ "---\n" +
74
+ redacted.trimEnd() +
75
+ "\n";
76
+ atomicWriteTextSync(filePath, text);
77
+ return { filePath, hadSecret, matchedPattern };
78
+ }
79
+
80
+ /**
81
+ * Read the note and compute expiry. Missing file → null. A note older than
82
+ * its TTL is marked expired (surfacing ignores it; audit reports it).
83
+ */
84
+ export function readWorkingState(
85
+ scopeKey: string,
86
+ defaultTtlDays: number,
87
+ ): WorkingStateFile | null {
88
+ const filePath = workingStatePath(scopeKey);
89
+ let raw: string;
90
+ try {
91
+ raw = fs.readFileSync(filePath, "utf8");
92
+ } catch {
93
+ return null;
94
+ }
95
+ const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
96
+ if (!m) return null;
97
+ const fm = m[1] ?? "";
98
+ const updatedAt = /^updated_at:\s*(.+)$/m.exec(fm)?.[1]?.trim() ?? "";
99
+ const t = Date.parse(updatedAt);
100
+ if (Number.isNaN(t)) return null;
101
+ const ttlDaysRaw = /^ttl_days:\s*(\d+)\s*$/m.exec(fm)?.[1];
102
+ const ttlDays = ttlDaysRaw
103
+ ? Number.parseInt(ttlDaysRaw, 10)
104
+ : Number.isInteger(defaultTtlDays) && defaultTtlDays > 0
105
+ ? defaultTtlDays
106
+ : 7;
107
+ const ageDays = Math.max(0, Math.floor((Date.now() - t) / DAY_MS));
108
+ return {
109
+ content: raw.slice(m[0].length).trimEnd(),
110
+ updatedAtMs: t,
111
+ ttlDays,
112
+ ageDays,
113
+ expired: ageDays > ttlDays,
114
+ };
115
+ }
116
+
117
+ /**
118
+ * Delete the note. Honest delete (D63 spirit): true — deleted or already
119
+ * gone; false — the unlink failed (keeps reporting to worry about).
120
+ */
121
+ export function clearWorkingState(scopeKey: string): boolean {
122
+ const filePath = workingStatePath(scopeKey);
123
+ try {
124
+ fs.unlinkSync(filePath);
125
+ return true;
126
+ } catch (err) {
127
+ return (err as NodeJS.ErrnoException).code === "ENOENT";
128
+ }
129
+ }
130
+
131
+ /**
132
+ * D89: surfaced at session start, outside the review ladder. Returns null
133
+ * when nothing should surface: the feature is off, or no note exists, or
134
+ * the note has expired (audit is the reporter; silence at session start).
135
+ */
136
+ export function workingStateBlock(
137
+ scopeKey: string,
138
+ projectName: string,
139
+ cfg: MyOMemoryConfig,
140
+ ): string | null {
141
+ if (!cfg.workingStateEnabled) return null;
142
+ const note = readWorkingState(scopeKey, cfg.workingStateTtlDays);
143
+ if (!note || note.expired || !note.content) return null;
144
+ return (
145
+ `[OPEN-MEMEX WORKING STATE — ${projectName}]\n` +
146
+ "Scratch state from an interrupted task, not durable knowledge; do not save it as a memory.\n" +
147
+ note.content +
148
+ "\n\n" +
149
+ "This is the user's own recent work state, for resuming where the work stands. " +
150
+ "If something in it deserves to outlive the task, propose it as a distilled memory — the checkpoint-proposal flow is the gate, the note never enters a review ladder. " +
151
+ "When the user signals the session or task is wrapping up, refresh this note via `memory_workingstate` (action=write) before finishing: task summary, open files, last commands, where the work stands, next step."
152
+ );
153
+ }