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/tools/ops.js CHANGED
@@ -15,11 +15,13 @@ import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOM
15
15
  import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
16
16
  import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.js";
17
17
  import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.js";
18
+ import { getUsage, recordUseful, reuseRate, usefulKindFor, usefulCount, deleteUsage, } from "../store/usage.js";
18
19
  import { db } from "../store/db.js";
19
20
  import { redact } from "../redact.js";
20
21
  import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.js";
21
22
  import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.js";
22
23
  import { isInRepoMemoryFile } from "../paths.js";
24
+ import { writeWorkingState, readWorkingState, clearWorkingState, } from "../working-state.js";
23
25
  import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory, } from "../review.js";
24
26
  /**
25
27
  * D53: push, don't poll. Append the project-outbox pending count to mutating
@@ -49,6 +51,8 @@ export const TOOL_DESCRIPTIONS = {
49
51
  memory_promote: "Advance a project memory one step up the review ladder (proposed → approved → published), or reject it with a note. Rejected memories are never deleted — they can be revised and resubmitted. One step per call; an unknown id or a memory already published errors. Pass `by` to record the reviewer when it should differ from the default (e.g. approving on the strength of someone else's review). For brand-new outbox drafts, memory_submit is the entry point. (MCP server and the `open-memex promote` CLI; the opencode native plugin does not expose this tool.)",
50
52
  memory_resolve: "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.)",
51
53
  memory_pr_status: "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.)",
54
+ memory_workingstate: "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.",
55
+ memory_useful: "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.",
52
56
  };
53
57
  /** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
54
58
  export const scopeArg = z
@@ -174,6 +178,26 @@ export const memoryPrStatusArgs = {
174
178
  .optional()
175
179
  .describe("Perform the mapped review transitions locally (no push). Default: report only."),
176
180
  };
181
+ export const memoryWorkingStateArgs = {
182
+ action: z
183
+ .enum(["read", "write", "clear"])
184
+ .default("read")
185
+ .describe("read = show the current note (empty when none); write = create or refresh it; clear = delete it."),
186
+ content: z
187
+ .string()
188
+ .optional()
189
+ .describe("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."),
190
+ };
191
+ export const memoryUsefulArgs = {
192
+ id: z
193
+ .string()
194
+ .min(1)
195
+ .describe("ID of the memory being confirmed useful (memory_search / memory_list return ids)."),
196
+ kind: z
197
+ .enum(["self", "team"])
198
+ .optional()
199
+ .describe("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."),
200
+ };
177
201
  function resolveScope(getScope, kind) {
178
202
  return kind === "personal" ? PERSONAL_SCOPE : getScope();
179
203
  }
@@ -282,10 +306,12 @@ export async function searchMemories(getScope, args) {
282
306
  : args.scope === "project"
283
307
  ? [project.key]
284
308
  : [project.key, PERSONAL_SCOPE.key];
309
+ // D77-L2: every surface that hands hits to a caller counts as exposure.
285
310
  const hits = search(args.query, {
286
311
  scopeKeys,
287
312
  limit: args.limit,
288
313
  type: args.type,
314
+ record: true,
289
315
  });
290
316
  if (hits.length === 0) {
291
317
  return {
@@ -306,7 +332,7 @@ export async function listMemories(getScope, args) {
306
332
  // #3" names exactly one memory. A per-section counter emitted two "#1"s.
307
333
  let seq = 0;
308
334
  const render = (scopeKey) => {
309
- const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
335
+ const hits = list(scopeKey, { type: args.type, limit: args.limit, include, record: true });
310
336
  const total = countList(scopeKey, { type: args.type, include });
311
337
  const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
312
338
  const note = truncationNote(hits.length, total);
@@ -429,6 +455,10 @@ export async function forgetMemory(args) {
429
455
  }
430
456
  }
431
457
  deleteFromIndex(args.id);
458
+ // D77-L2: the memory is gone for good — its telemetry has no subject left.
459
+ // Only the hard path prunes the usage row; status flips and index removal
460
+ // (branch switches remove in-repo files transiently) keep it.
461
+ deleteUsage(args.id);
432
462
  // D64: forgetting an in-repo memory deletes a file inside the user's
433
463
  // git working tree. Say so — the deletion should ride a commit, or the
434
464
  // file silently diverges from what teammates have.
@@ -444,6 +474,42 @@ export async function forgetMemory(args) {
444
474
  // 2B/D26: review workflow ops (also exposed over MCP so agents can drive the
445
475
  // sync loop: status → ask user → submit → push/PR on approval).
446
476
  // ---------------------------------------------------------------------------
477
+ /**
478
+ * D77-L2: the explicit confirmation route to the useful counters. The
479
+ * restraint rules live in the tool description and the MCP handshake —
480
+ * an unguarded call path here would create the self-reinforcing retrieval
481
+ * loop D77 warns about, so nothing silently routes exposure into useful.
482
+ * Classification proxy (no identity system): personal scope / unreviewed
483
+ * project draft → useful_self; approved/published project memory → useful_team.
484
+ */
485
+ export async function markMemoryUseful(args) {
486
+ const row = db()
487
+ .prepare(`SELECT scope, review_state FROM memories WHERE id = ?`)
488
+ .get(args.id);
489
+ if (!row) {
490
+ return {
491
+ title: "memory: useful not found",
492
+ output: `No memory with id ${args.id} in the index — memory_search or memory_list returns current ids.`,
493
+ };
494
+ }
495
+ const kind = args.kind ?? usefulKindFor(row.scope, row.review_state);
496
+ const after = recordUseful(args.id, kind, "tool");
497
+ // recordUseful re-checks existence; both branches above agree on not-found.
498
+ if (!after) {
499
+ return {
500
+ title: "memory: useful not found",
501
+ output: `No memory with id ${args.id} in the index.`,
502
+ };
503
+ }
504
+ const u = getUsage(args.id);
505
+ const rate = reuseRate(u);
506
+ const useful = usefulCount(u);
507
+ return {
508
+ title: `memory: useful (${kind}) ${args.id}`,
509
+ output: `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)}.` +
510
+ `\nA supersede or a human approval also counts — no need to duplicate those with an explicit call.`,
511
+ };
512
+ }
447
513
  export async function statusMemories() {
448
514
  const st = getSyncStatus();
449
515
  const n = st.outbox.length +
@@ -537,3 +603,59 @@ export async function prStatusOp(args) {
537
603
  }
538
604
  return { title: "memory: pr-status", output: lines.join("\n") };
539
605
  }
606
+ /**
607
+ * §3.6 (D89): the one ephemeral per-project working-state note. Scratch
608
+ * state, not knowledge — it never enters the review ladder or the
609
+ * retrieval index; durable conclusions still go through memory_add (agent
610
+ * proposes, user approves). The tool description and the session-start
611
+ * block must keep saying the same thing on this.
612
+ */
613
+ export async function workingStateMemory(getScope, cfg, args) {
614
+ if (!cfg.workingStateEnabled) {
615
+ return {
616
+ title: "memory: working-state",
617
+ output: "The working-state note is disabled (config workingStateEnabled=false). Enable it in the config file, or record durable facts with memory_add instead.",
618
+ };
619
+ }
620
+ const scope = getScope();
621
+ if (args.action === "clear") {
622
+ const gone = clearWorkingState(scope.key);
623
+ return {
624
+ title: "memory: working-state",
625
+ output: gone
626
+ ? `Working-state note for ${scope.projectName} deleted.`
627
+ : "Failed to delete the working-state note — it may still be on disk.",
628
+ };
629
+ }
630
+ if (args.action === "write") {
631
+ const content = (args.content ?? "").trim();
632
+ if (!content) {
633
+ return {
634
+ title: "memory: working-state",
635
+ output: "Refusing an empty working-state note: pass content (task summary, open files, last commands, where the work stands, next step).",
636
+ };
637
+ }
638
+ const r = writeWorkingState(scope.key, content, cfg.workingStateTtlDays, cfg.redactPatterns);
639
+ const secretNote = r.hadSecret
640
+ ? `\n[open-memex: a secret was masked in place (${r.matchedPattern}) before saving]`
641
+ : "";
642
+ return {
643
+ title: "memory: working-state",
644
+ output: `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}`,
645
+ };
646
+ }
647
+ const note = readWorkingState(scope.key, cfg.workingStateTtlDays);
648
+ if (!note) {
649
+ return {
650
+ title: "memory: working-state",
651
+ output: `No working-state note for ${scope.projectName}. Write one at wrap-up (action=write) so an interrupted task can resume.`,
652
+ };
653
+ }
654
+ const status = note.expired
655
+ ? `EXPIRED (${note.ageDays} day${note.ageDays === 1 ? "" : "s"} old, ttl ${note.ttlDays}) — stale until a write refreshes it`
656
+ : `updated ${note.ageDays} day${note.ageDays === 1 ? "" : "s"} ago, ttl ${note.ttlDays} day${note.ttlDays === 1 ? "" : "s"}`;
657
+ return {
658
+ title: "memory: working-state",
659
+ output: `[${status}]\n\n${note.content}`,
660
+ };
661
+ }
@@ -0,0 +1,118 @@
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.js";
20
+ import { redact } from "./redact.js";
21
+ import { atomicWriteTextSync } from "./store/markdown.js";
22
+ const DAY_MS = 86_400_000;
23
+ /** Read-only path helper — never creates the directory (D70 discipline;
24
+ * contrast the write path below, which mkdirs on demand). */
25
+ export function workingStatePath(scopeKey) {
26
+ return path.join(paths().root, "working-state", `${scopeKey}.md`);
27
+ }
28
+ /**
29
+ * Write or refresh the note. The agent composes the body (task summary /
30
+ * open files / last commands / where the work stands / next step). Content
31
+ * passes through `redact()` so command paste-through from an interrupted
32
+ * session cannot park a readable secret in storage. TTL days is stamped
33
+ * into frontmatter so the user's per-note edit survives config changes.
34
+ */
35
+ export function writeWorkingState(scopeKey, content, defaultTtlDays, redactPatterns) {
36
+ const { content: redacted, hadSecret, matchedPattern } = redact(content, redactPatterns);
37
+ const filePath = workingStatePath(scopeKey);
38
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
39
+ const ttlDays = Number.isInteger(defaultTtlDays) && defaultTtlDays > 0 ? defaultTtlDays : 7;
40
+ const text = "---\n" +
41
+ "schema: working-state\n" +
42
+ `updated_at: ${new Date().toISOString()}\n` +
43
+ `ttl_days: ${ttlDays}\n` +
44
+ "---\n" +
45
+ redacted.trimEnd() +
46
+ "\n";
47
+ atomicWriteTextSync(filePath, text);
48
+ return { filePath, hadSecret, matchedPattern };
49
+ }
50
+ /**
51
+ * Read the note and compute expiry. Missing file → null. A note older than
52
+ * its TTL is marked expired (surfacing ignores it; audit reports it).
53
+ */
54
+ export function readWorkingState(scopeKey, defaultTtlDays) {
55
+ const filePath = workingStatePath(scopeKey);
56
+ let raw;
57
+ try {
58
+ raw = fs.readFileSync(filePath, "utf8");
59
+ }
60
+ catch {
61
+ return null;
62
+ }
63
+ const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
64
+ if (!m)
65
+ return null;
66
+ const fm = m[1] ?? "";
67
+ const updatedAt = /^updated_at:\s*(.+)$/m.exec(fm)?.[1]?.trim() ?? "";
68
+ const t = Date.parse(updatedAt);
69
+ if (Number.isNaN(t))
70
+ return null;
71
+ const ttlDaysRaw = /^ttl_days:\s*(\d+)\s*$/m.exec(fm)?.[1];
72
+ const ttlDays = ttlDaysRaw
73
+ ? Number.parseInt(ttlDaysRaw, 10)
74
+ : Number.isInteger(defaultTtlDays) && defaultTtlDays > 0
75
+ ? defaultTtlDays
76
+ : 7;
77
+ const ageDays = Math.max(0, Math.floor((Date.now() - t) / DAY_MS));
78
+ return {
79
+ content: raw.slice(m[0].length).trimEnd(),
80
+ updatedAtMs: t,
81
+ ttlDays,
82
+ ageDays,
83
+ expired: ageDays > ttlDays,
84
+ };
85
+ }
86
+ /**
87
+ * Delete the note. Honest delete (D63 spirit): true — deleted or already
88
+ * gone; false — the unlink failed (keeps reporting to worry about).
89
+ */
90
+ export function clearWorkingState(scopeKey) {
91
+ const filePath = workingStatePath(scopeKey);
92
+ try {
93
+ fs.unlinkSync(filePath);
94
+ return true;
95
+ }
96
+ catch (err) {
97
+ return err.code === "ENOENT";
98
+ }
99
+ }
100
+ /**
101
+ * D89: surfaced at session start, outside the review ladder. Returns null
102
+ * when nothing should surface: the feature is off, or no note exists, or
103
+ * the note has expired (audit is the reporter; silence at session start).
104
+ */
105
+ export function workingStateBlock(scopeKey, projectName, cfg) {
106
+ if (!cfg.workingStateEnabled)
107
+ return null;
108
+ const note = readWorkingState(scopeKey, cfg.workingStateTtlDays);
109
+ if (!note || note.expired || !note.content)
110
+ return null;
111
+ return (`[OPEN-MEMEX WORKING STATE — ${projectName}]\n` +
112
+ "Scratch state from an interrupted task, not durable knowledge; do not save it as a memory.\n" +
113
+ note.content +
114
+ "\n\n" +
115
+ "This is the user's own recent work state, for resuming where the work stands. " +
116
+ "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. " +
117
+ "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.");
118
+ }
package/docs/CONCEPTS.md CHANGED
@@ -175,6 +175,22 @@ outbox drafts — drafts stay findable, but never pose as vetted.
175
175
  - **personal never enters git** (§1) — not by `submit`, not by `export`
176
176
  defaults, not ever.
177
177
 
178
+ ## 8. The working-state note: resuming an interrupted task (D89, §3.6)
179
+
180
+ Durable knowledge answers "what is true here"; a scheduled task also needs
181
+ "where am I in it". One ephemeral Markdown note per project lives under
182
+ `<data root>/working-state/<scope key>.md` — outside `memories/`, outside git,
183
+ off the retrieval index. The agent writes it at wrap-up via the
184
+ `memory_workingstate` tool (opencode has no Stop hook, so wrap-up means the
185
+ user signaling the task is ending); the content rubric is task summary, open
186
+ files, last commands, where the work stands, next step. The note surfaces at
187
+ session start next to the first-turn injection, framed as scratch state; it
188
+ never enters the review ladder — if something here deserves to outlive the
189
+ task, the normal propose-first flow turns it into a memory. TTL defaults to 7
190
+ days (`config set workingStateTtlDays`); expired notes stay silent at session
191
+ start and are reported by `audit`. `open-memex wstate` reads/clears it; edit
192
+ the plain file directly if you like.
193
+
178
194
  ---
179
195
 
180
196
  *Design record: `docs/V2-DESIGN.md` (append-only decision log). Per-scope
@@ -157,6 +157,19 @@ draft 找得到,但绝不冒充已审。
157
157
  - **personal 永不进 git**(§1)——`submit` 不行、`export` 默认不行、
158
158
  任何方式都不行。
159
159
 
160
+ ## 8. 工作状态笔记:续接被中断的任务(D89,§3.6)
161
+
162
+ 耐久知识回答"这里什么是真的";过了一天的任务还要回答"我做到哪了"。
163
+ 每个项目一份临时 Markdown 笔记,存放在 `<数据根>/working-state/<作用域键>.md`
164
+ ——在 `memories/` 之外、git 之外、检索索引之外。助手在收尾时通过
165
+ `memory_workingstate` 工具写(opencode 没有 Stop 钩子,所以"收尾"指用户发出
166
+ 任务结束的信号);正文骨架是任务摘要、打开的文件、最后的命令、进度在哪、
167
+ 下一步。笔记在会话开始时随首轮注入一起浮现,并被明确定位为草稿状态;它
168
+ 永不进入评审阶梯——若其中有值得留下的内容,走正常的先提议流程转成记忆。
169
+ TTL 默认 7 天(`config set workingStateTtlDays`);过期笔记在会话开始时
170
+ 保持沉默、由 `audit` 报告。`open-memex wstate` 读取/清除;文件本身是纯文本,
171
+ 想直接编辑也行。
172
+
160
173
  ---
161
174
 
162
175
  *设计记录:`docs/V2-DESIGN.md`(只追加的决策日志)。按作用域的细节: