open-memex 0.8.2 → 0.9.0-alpha.1

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.
@@ -0,0 +1,86 @@
1
+ ## 20. Knowledge Graph & Compiled Wiki (v0.3 candidate)
2
+
3
+ *Status (2026-11-02): 未实现 — v0.3 candidate as a whole. §20.1–20.4, §20.6, §20.8 unbuilt; §20.5/§20.7 are no-change statements (confirmed, nothing to build).*
4
+ > v0.3 candidate (D88). Does not change the frozen v0.2 protocol; the graph/wiki is a derived layer (see §20.2). Sources: Karpathy's *LLM Wiki* (three layers / three operations) and Graphify (a working implementation of the same pattern on codebases, measured on muse-thinktank 2026-10-31: curated graph, 1029 nodes, edges tagged EXTRACTED/INFERRED with confidence). Both point to the same pattern: compile knowledge once, instead of re-deriving it on every query.
5
+
6
+ ### 20.1 Why add a graph (motivation)
7
+
8
+ Today open-memex is RAG-style retrieval: a query finds relevant fragments from memory and assembles an answer. Every query re-discovers knowledge from scratch — nothing accumulates. A question that synthesizes five memories forces the system to re-find and re-assemble them every time.
9
+
10
+ The alternative: between memories (raw) and terminal documents (docs / ADRs / AGENTS.md), add a layer of **compiled knowledge** — a knowledge graph plus a set of LLM-maintained wiki pages. When a new memory arrives, the system does not just store it for later retrieval; it reads it, extracts the key information, and merges it into the existing graph and wiki — updating entity and concept pages, flagging where new content contradicts old conclusions, strengthening or challenging emerging syntheses. Knowledge is **compiled once, then kept current**, not re-derived on every query.
11
+
12
+ This follows Design Principle 7 ("Memory is the entrance of knowledge, not its final form"): memory is the entrance, the graph/wiki is the compiled form, terminal documents are the final form. The §3 frontmatter currently has no `related` field (not in v0.2); this section supplies the graph edges — edges live in the graph layer first, and whether `related` enters the frontmatter is a v0.3 protocol decision.
13
+
14
+ ### 20.2 Three layers (Karpathy's raw / wiki / schema)
15
+
16
+ | Layer | In open-memex | Owned by | Mutable? |
17
+ |---|---|---|---|
18
+ | **Raw** | The memory files themselves (Markdown, one memory per file) + the docs they point at via `canonical_ref` | User / team | **Immutable** — the graph and wiki only read raw, never modify it; when something is wrong, trace back to the memory and the doc |
19
+ | **Wiki (compiled)** | Knowledge compiled from memories: entity pages, concept pages, comparisons, overviews, syntheses (Markdown files; the queryable graph is the same knowledge in another shape) | Maintained by the LLM, reviewed by humans | Mutable — updated when new memories arrive; it is a **derived layer**, rebuildable from raw if lost (echoes D1: Markdown is the source of truth, indexes are rebuildable) |
20
+ | **Schema (discipline)** | Capture rules + promotion rules + this section's conventions (what to record, how, what enters the graph, who may change it) | Co-written by human + LLM | Evolves — revised with practice, lives in the protocol doc and AGENTS.md |
21
+
22
+ Key point: **the wiki layer is derived, not a second source of truth.** Truth always lives in raw (the memory files). If the wiki is lost, wrong, or stale, it can be rebuilt or corrected from raw. This matches D1 (Markdown is the source of truth) and §12 ("Memory stores summaries and points at docs via `canonical_ref` — never copies them"): the wiki stores compiled summaries and links, not copies of the originals.
23
+
24
+ ### 20.3 Graph edges: typed edges with provenance
25
+
26
+ The §3 frontmatter currently has no `related` field (not in v0.2, see the note at the end of §3). This section introduces **typed edges with provenance** in the graph layer (edges are derived and rebuildable; they do not enter the frontmatter — whether `related` enters the frontmatter is a v0.3 protocol decision):
27
+
28
+ - **Edge types**: `relates-to`, `supports`, `contradicts`, `derived-from`, `supersedes` (already exists, see the supersede chain in §3.3).
29
+ - **Every edge carries provenance** (borrowing Graphify's practice): `EXTRACTED` (explicit in the source — e.g. memory A explicitly says "see memory B", or two memories share a `canonical_ref`) or `INFERRED` (system-inferred — e.g. similar content, shared tag/path), with a confidence (`confidence: high | medium | low`, reusing the confidence semantics already in §3).
30
+ - **Inferred edges are always marked**: in retrieval results they must be distinguishable (e.g. the recall receipt names the lane + edge type); an inferred link must never look like a fact that was in the source.
31
+
32
+ Why split EXTRACTED/INFERRED: this extends the trust model in §11 — a link with unclear provenance must not quietly become a "fact". An inferred edge is a suggestion, not an assertion.
33
+
34
+ ### 20.4 Three operations (Karpathy's ingest / query / lint)
35
+
36
+ #### Ingest: the graph updates when a memory is written / approved
37
+
38
+ - Trigger: a memory is created, updated, or its promotion state becomes approved (§5). Core triggers an incremental graph update on the write path (new nodes/edges, updates to the affected compiled pages) — not a separate background job.
39
+ - One ingest can touch several compiled pages (one memory can update an entity page, a concept page, and an overview). That is normal — the wiki's value is "one ingest, merged in many places".
40
+ - Ingest never changes the memory itself (raw is immutable); it only updates the derived graph and wiki.
41
+
42
+ #### Query: graph traversal becomes a third retrieval lane
43
+
44
+ - §7 today has two lanes: BM25/FTS5 and vector (optional). This section adds a third: **graph traversal** (a node's neighbours, the shortest path between two concepts, a community).
45
+ - Recall receipts (§7) gain a `graph` lane: each hit reports its lane (BM25 / vector / graph / recency); a graph hit reports which edge it travelled (type + EXTRACTED/INFERRED).
46
+ - A good answer from a graph query can be filed back into the wiki as a new page (a good comparison or analysis should not vanish into chat history). That is the compounding step.
47
+
48
+ #### Lint: a health check, run automatically before promotion
49
+
50
+ Lint runs **automatically before promotion** (decided 2026-10-31) and checks the graph/wiki for:
51
+
52
+ - Contradictions between memories (two memories asserting opposite facts)
53
+ - Stale claims superseded by newer memories (should have entered the supersede chain but hasn't)
54
+ - Orphan memories (written but never linked, in no compiled page)
55
+ - Important concepts mentioned but without their own page (missing pages)
56
+ - Missing cross-references
57
+
58
+ **Lint only discovers and reports; it never auto-resolves** (echoes Principle 5: Core never silently resolves semantic conflicts; and §9's conflict handling). The results go to a human (the curator / promotion reviewer) to decide. This is the input the §5 promotion flow needs: a list of "which memories contradict, which are stale, which are orphaned".
59
+
60
+ ### 20.5 Local-first & privacy (no change to the existing iron rules)
61
+
62
+ - **The graph is derived and stored locally**: compiled from local Markdown, stored locally (SQLite index + Markdown compiled pages), on the same machine as the memory files. Lost, it can be rebuilt.
63
+ - **Deterministic extraction needs no LLM**: structural edges (shared tag, shared path, shared `canonical_ref`, explicit links) are extracted by deterministic rules, on-machine, without an LLM (borrowing Graphify's tree-sitter idea: structure is extracted, not inferred).
64
+ - **Semantic extraction of docs is confirmed at init, on or off** (decided 2026-10-31): understanding document content semantically (not just structurally) needs an explicit LLM backend. Init asks the user whether to turn it on or off (echoes Principle 4: nothing leaves the machine without explicit user action) — off means no semantic extraction. Once on, the default backend is the API (most machines have no local model); to use a local model, change it in config (Ollama / LM Studio).
65
+ - **The personal scope never syncs** (D3): personal memories stay out of the graph's sync scope; the graph's sync follows the same scope/visibility rules as memory sync (§4), no separate scheme.
66
+ - **Iron rules unchanged**: a graph edge can never automatically become an instruction (iron rule 1's role gate still sits at the instruction-context entry); a personal memory's instruction never enters AGENTS.md (iron rule 2). The graph is a knowledge layer, not an authorization layer.
67
+
68
+ ### 20.6 Scope & phasing (v0.3 candidate, not in v0.2)
69
+
70
+ - **This section is a v0.3 candidate; it does not change the frozen v0.2 text.** v0.2 (Phases 0–2) proceeds as planned; the graph is a **parallel, benchmark-gated experiment** (same treatment as embeddings in Phase 2), not on the critical path.
71
+ - **Smallest closed loop first**: one domain (e.g. one project) → graph compiled from memories → neighbours and paths queryable → lint reporting contradictions and orphans. Expand only after that loop works.
72
+ - **Scale ceiling**: Karpathy's index pattern suffices at ~100 sources and a few hundred pages; before open-memex's memory count reaches that scale, the graph's index is "read the compiled pages first, then drill into the originals" — no embedding RAG infrastructure needed. Beyond that, add search/vector (reusing the §7 embeddings interface).
73
+
74
+ ### 20.7 What this section does not change
75
+
76
+ - **Data model unchanged**: one memory per file, Markdown is the source of truth, ULID is the filename (§3). The graph is a derived layer; it adds no memory field (edges live in the graph layer; whether `related` enters the frontmatter is a v0.3 protocol decision).
77
+ - **Iron rules unchanged** (§3.2): the instruction gate and the personal-scope guard apply as before.
78
+ - **Promotion flow unchanged** (§5): promotion stays explicit and human-reviewed; lint only supplies input to the reviewer, it does not decide for them.
79
+ - **Retrieval baseline unchanged** (§7): BM25/FTS5 + CJK remain the default; the graph is an added lane, not a replacement.
80
+
81
+ ### 20.8 Small amendments to §3 / §7 / §12 (land with this section, pending approval)
82
+
83
+ - **§3**: a v0.3 protocol revision will consider whether to add a `related` field (typed, with provenance); until then, edges live only in the graph layer, not in the frontmatter.
84
+ - **§7 Recall receipts**: add a `graph` lane; a graph hit reports its edge type and provenance.
85
+ - **§12 table**: add a sub-row under "OpenMemex" — "Compiled wiki/graph: knowledge compiled from memories (derived, rebuildable), between memories and terminal documents".
86
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "open-memex",
3
- "version": "0.8.2",
3
+ "version": "0.9.0-alpha.1",
4
4
  "mcpName": "io.github.stoneskin/open-memex",
5
5
  "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
6
6
  "keywords": [
@@ -80,9 +80,9 @@ try {
80
80
  const tools = await req("tools/list", {});
81
81
  const names = (tools.result?.tools ?? []).map((t: any) => t.name).sort();
82
82
  check(
83
- "tools/list has 11 memory tools",
83
+ "tools/list has 12 memory tools",
84
84
  JSON.stringify(names) ===
85
- JSON.stringify(["memory_add", "memory_forget", "memory_list", "memory_pr_status", "memory_promote", "memory_propose", "memory_resolve", "memory_search", "memory_status", "memory_submit", "memory_supersede"]),
85
+ JSON.stringify(["memory_add", "memory_forget", "memory_list", "memory_pr_status", "memory_promote", "memory_propose", "memory_resolve", "memory_search", "memory_status", "memory_submit", "memory_supersede", "memory_workingstate"]),
86
86
  names.join(","),
87
87
  );
88
88
  // D76: annotations must tell the truth — pr_status mutates with apply=true.
@@ -188,6 +188,33 @@ try {
188
188
 
189
189
  const search2 = await req("tools/call", { name: "memory_search", arguments: { query: "mcp e2e probe" } });
190
190
  check("memory gone after forget", !(search2.result?.content?.[0]?.text ?? "").includes(savedId));
191
+
192
+ // §3.6 (D89): the working-state note round-trips, expires honestly, and
193
+ // its file lives OUTSIDE memories/ so the index never picks it up.
194
+ const wsRead0 = await req("tools/call", { name: "memory_workingstate", arguments: {} });
195
+ const wsRead0Text = wsRead0.result?.content?.[0]?.text ?? "";
196
+ check("workingstate read reports none (D89)", wsRead0Text.includes("No working-state note"), wsRead0Text.slice(0, 120));
197
+
198
+ const wsWrite = await req("tools/call", {
199
+ name: "memory_workingstate",
200
+ arguments: { action: "write", content: "task: port the deploy script; next: run staging smoke" },
201
+ });
202
+ const wsWriteText = wsWrite.result?.content?.[0]?.text ?? "";
203
+ check("workingstate write works (D89)", wsWriteText.includes("written"), wsWriteText.slice(0, 160));
204
+
205
+ const wsRead = await req("tools/call", { name: "memory_workingstate", arguments: {} });
206
+ const wsReadText = wsRead.result?.content?.[0]?.text ?? "";
207
+ check("workingstate reads back (D89)", wsReadText.includes("run staging smoke"), wsReadText.slice(0, 160));
208
+
209
+ const wsFile = fs.readdirSync(path.join(HOME, "working-state")).find((f) => f.endsWith(".md"));
210
+ check("workingstate file outside memories/ (D89)", !!wsFile, `working-state/${wsFile}`);
211
+
212
+ const wsSearch = await req("tools/call", { name: "memory_search", arguments: { query: "staging smoke" } });
213
+ check("workingstate never enters the index (D89)", !(wsSearch.result?.content?.[0]?.text ?? "").includes("run staging smoke"), (wsSearch.result?.content?.[0]?.text ?? "").slice(0, 120));
214
+
215
+ const wsClear = await req("tools/call", { name: "memory_workingstate", arguments: { action: "clear" } });
216
+ check("workingstate clear works (D89)", (wsClear.result?.content?.[0]?.text ?? "").includes("deleted"), (wsClear.result?.content?.[0]?.text ?? "").slice(0, 120));
217
+
191
218
  } finally {
192
219
  child.kill();
193
220
  }
@@ -965,5 +965,75 @@ console.log("== D83 expansions BM25 weight + matchedVia ==");
965
965
  ok("body stays the strongest column", BM25_WEIGHTS[0] >= BM25_WEIGHTS[3], JSON.stringify(BM25_WEIGHTS));
966
966
  }
967
967
 
968
+ console.log("== D89 working-state note (§3.6) ==");
969
+ {
970
+ const {
971
+ workingStatePath,
972
+ writeWorkingState,
973
+ readWorkingState,
974
+ clearWorkingState,
975
+ workingStateBlock,
976
+ } = await import("../src/working-state.ts");
977
+ const savedHome = process.env.OPEN_MEMEX_HOME;
978
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "om-wstate-"));
979
+ process.env.OPEN_MEMEX_HOME = home;
980
+ const KEY = "project__wstatetest__abcdef123456";
981
+ const ttlCfg = { ...DEFAULT_CONFIG, workingStateTtlDays: 7 };
982
+ try {
983
+ // Read on a store that was never touched: no polluting directory.
984
+ ok("missing note → null", readWorkingState(KEY, 7) === null);
985
+ ok("read never creates the dir", !fs.existsSync(path.join(home, "working-state")));
986
+ // Write: redact applies (a pasted command secret is masked).
987
+ const w = writeWorkingState(
988
+ KEY,
989
+ "resume deploy; saw key=sk-1234567890abcdefghij1234 in logs",
990
+ 7,
991
+ DEFAULT_CONFIG.redactPatterns,
992
+ );
993
+ // NOTE: paths() caches the data root per process, and an earlier section
994
+ // in this file may already have pinned it to its own temp home. Assert
995
+ // the shape (…/working-state/<key>.md), not the absolute prefix.
996
+ ok(
997
+ "write landed under a working-state dir",
998
+ w.filePath.includes(path.join("working-state", `${KEY}.md`)),
999
+ w.filePath,
1000
+ );
1001
+ ok("secret masked", w.hadSecret && !fs.readFileSync(w.filePath, "utf8").includes("1234567890abcdefghij"));
1002
+ const note = readWorkingState(KEY, 7);
1003
+ ok("note reads back", note !== null && note.content.includes("resume deploy"));
1004
+ ok("ttl stamped from config", note?.ttlDays === 7);
1005
+ ok("fresh note not expired", note?.expired === false && note?.ageDays === 0);
1006
+ // Frontmatter edit override: the user's per-note ttl survives.
1007
+ const raw = fs.readFileSync(w.filePath, "utf8").replace("ttl_days: 7", "ttl_days: 3");
1008
+ fs.writeFileSync(w.filePath, raw, "utf8");
1009
+ const note2 = readWorkingState(KEY, 7);
1010
+ ok("per-note ttl override honored", note2?.ttlDays === 3);
1011
+ // Expiry: backdate updated_at past the ttl.
1012
+ const stale = fs.readFileSync(w.filePath, "utf8").replace(
1013
+ /^updated_at: .*$/m,
1014
+ `updated_at: ${new Date(Date.now() - 9 * 86_400_000).toISOString()}`,
1015
+ );
1016
+ fs.writeFileSync(w.filePath, stale, "utf8");
1017
+ const note3 = readWorkingState(KEY, 7);
1018
+ ok("aged note expired", note3?.expired === true && note3?.ttlDays === 3 && note3?.ageDays === 9, JSON.stringify(note3));
1019
+ // Expired notes never surface; a fresh one does, with the right framing.
1020
+ ok("expired note does not surface", workingStateBlock(KEY, "proj", ttlCfg) === null);
1021
+ writeWorkingState(KEY, "resume deploy; run smoke tests", 7, []);
1022
+ const block = workingStateBlock(KEY, "proj", ttlCfg);
1023
+ ok("fresh note surfaces", block !== null && block.includes("resume deploy"), String(block).slice(0, 40));
1024
+ ok("block frames it as scratch", block?.includes("not durable knowledge") === true);
1025
+ ok("block carries the wrap-up rule", block?.includes("memory_workingstate") === true);
1026
+ ok("disabled config never surfaces", workingStateBlock(KEY, "proj", { ...ttlCfg, workingStateEnabled: false }) === null);
1027
+ // Clear is honest: gone once, then reports gone.
1028
+ ok("clear deletes", clearWorkingState(KEY) === true);
1029
+ ok("clear on missing stays true", clearWorkingState(KEY) === true);
1030
+ ok("note gone", readWorkingState(KEY, 7) === null);
1031
+ } finally {
1032
+ if (savedHome === undefined) delete process.env.OPEN_MEMEX_HOME;
1033
+ else process.env.OPEN_MEMEX_HOME = savedHome;
1034
+ fs.rmSync(home, { recursive: true, force: true });
1035
+ }
1036
+ }
1037
+
968
1038
  console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
969
1039
  process.exit(fails === 0 ? 0 : 1);
package/server.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "io.github.stoneskin/open-memex",
4
4
  "title": "open-memex",
5
5
  "description": "Local-first memory for AI coding agents — Markdown + SQLite FTS5, shared across editors via MCP.",
6
- "version": "0.8.1",
6
+ "version": "0.8.2",
7
7
  "repository": {
8
8
  "url": "https://github.com/stoneskin/open-memex",
9
9
  "source": "github"
@@ -13,7 +13,7 @@
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "open-memex",
16
- "version": "0.8.1",
16
+ "version": "0.8.2",
17
17
  "runtimeHint": "npx",
18
18
  "packageArguments": [
19
19
  {
@@ -57,6 +57,16 @@ with the `memory_add` tool pass `source: "inference"` so the capture is marked
57
57
  as agent-proposed. Don't interrupt mid-task, and don't re-propose something
58
58
  the user already declined.
59
59
 
60
+ ## At wrap-up — refresh the working-state note
61
+
62
+ When the user signals the session or task is wrapping up (and the
63
+ `memory_workingstate` tool is available), write a short scratch note so an
64
+ interrupted task can resume in a fresh session: task summary (one paragraph),
65
+ open files, last commands, where the work stands, next step. It is **scratch
66
+ state, not knowledge** — never save it as a memory; anything here that
67
+ deserves to outlive the task goes through the propose flow above. The note
68
+ expires after 7 days; `open-memex wstate` shows it (`--clear` deletes it).
69
+
60
70
  ## Recall
61
71
 
62
72
  ```sh
package/src/cli.ts CHANGED
@@ -23,6 +23,7 @@ import {
23
23
  import { loadConfig, configSource } from "./config.ts";
24
24
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.ts";
25
25
  import { redact } from "./redact.ts";
26
+ import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.ts";
26
27
  import { resolveMcpCommand } from "./init.ts";
27
28
  import fs from "node:fs";
28
29
  import path from "node:path";
@@ -428,7 +429,7 @@ Example:
428
429
  doctor: `Environment health check: Node version, config source, scope resolution,
429
430
  storage writability, VS Code MCP enablement (settings.json + system policy),
430
431
  then boots a real MCP server and runs initialize + tools/list against it —
431
- all eleven tools must show up.
432
+ all twelve tools must show up.
432
433
 
433
434
  Usage: open-memex doctor
434
435
 
@@ -437,8 +438,8 @@ Example:
437
438
 
438
439
  audit: `Memory health audit (read-only, reports never mutates): near-duplicate
439
440
  pairs among active memories, stale actives untouched for 90+ days, broken
440
- supersede chains, personal files found inside the repo memory dir, and
441
- index/file drift.
441
+ supersede chains, personal files found inside the repo memory dir, index/file
442
+ drift, and expired working-state notes (D89).
442
443
 
443
444
  Usage: open-memex audit [--scope project|personal|both]
444
445
 
@@ -447,6 +448,19 @@ Flags:
447
448
 
448
449
  Example:
449
450
  open-memex audit --scope both`,
451
+
452
+ wstate: `Show the project's session working-state note (D89, §3.6) — the
453
+ ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
454
+ can resume. The file itself is plain Markdown and editable directly.
455
+
456
+ Usage: open-memex wstate [--clear]
457
+
458
+ Flags:
459
+ --clear delete the note (no tombstone — it is scratch, not knowledge)
460
+
461
+ Examples:
462
+ open-memex wstate
463
+ open-memex wstate --clear`,
450
464
  };
451
465
 
452
466
  function usage(exitCode = 1): never {
@@ -474,6 +488,7 @@ Usage:
474
488
  open-memex pr-status [--apply]
475
489
  open-memex reindex
476
490
  open-memex audit [--scope project|personal|both]
491
+ open-memex wstate [--clear]
477
492
  open-memex scopes
478
493
  open-memex migrate [--from <key>] [--to <key>]
479
494
  [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -506,8 +521,8 @@ first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs nev
506
521
  \`open-memex config set <key> <value>\` changes those settings after install.
507
522
 
508
523
  Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
509
- available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
510
- the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
524
+ available directly: \`open-memex mcp\` starts the stdio MCP server (12 tools, a superset of
525
+ the opencode plugin's six memory_* tools); \`open-memex mcp --print-config <client>\`
511
526
  prints a copy-paste MCP client config snippet.
512
527
 
513
528
  Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -733,6 +748,40 @@ async function main() {
733
748
  const cfg = loadConfig();
734
749
  const project = resolveProjectScope(process.cwd());
735
750
 
751
+ // §3.6 (D89): human convenience surface for the working-state note —
752
+ // print it (with age/expiry) or delete it on request. The file itself is
753
+ // always editable directly; audit reports expired notes either way.
754
+ if (cmd === "wstate") {
755
+ const flags = parseFlags(rest);
756
+ if (flags["clear"] === "true") {
757
+ const gone = clearWorkingState(project.key);
758
+ console.log(
759
+ gone
760
+ ? `working-state note cleared (${project.key})`
761
+ : "nothing to clear — the note is still on disk; delete it manually if it exists",
762
+ );
763
+ return;
764
+ }
765
+ const note = readWorkingState(project.key, cfg.workingStateTtlDays);
766
+ if (!note) {
767
+ console.log(`no working-state note for ${project.key} — the agent writes one at wrap-up (memory_workingstate); you can edit the file directly`);
768
+ return;
769
+ }
770
+ if (!cfg.workingStateEnabled) {
771
+ console.log("(working state is disabled in config — workingStateEnabled=false)");
772
+ }
773
+ console.log(
774
+ note.expired
775
+ ? `EXPIRED — ${note.ageDays} day(s) old, ttl ${note.ttlDays} (ignored at session start; ` +
776
+ `audit keeps reporting it until the next wrap-up write or 'wstate --clear')`
777
+ : `updated ${note.ageDays} day(s) ago — expires after ${note.ttlDays} day(s)`,
778
+ );
779
+ console.log();
780
+ console.log(note.content || "(empty note)");
781
+ console.log(`\nfile: ${workingStatePath(project.key)}`);
782
+ return;
783
+ }
784
+
736
785
  // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
737
786
  // before the index is opened so it also works where the DB driver
738
787
  // isn't available.
@@ -840,6 +889,11 @@ async function main() {
840
889
  console.log(
841
890
  ` index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`,
842
891
  );
892
+ // D89: expired working-state notes — reports only, never auto-deletes.
893
+ console.log(` expired working-state notes: ${r.workingStateExpired.length}`);
894
+ for (const w of r.workingStateExpired) {
895
+ console.log(` ${w.filePath} — ${w.ageDays} days old (ttl ${w.ttlDays}); 'wstate --clear' or the next wrap-up write refreshes`);
896
+ }
843
897
  return;
844
898
  }
845
899
 
@@ -920,7 +974,7 @@ async function main() {
920
974
  return;
921
975
  }
922
976
 
923
- // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
977
+ // `mcp` starts the stdio MCP server (12 tools; the opencode plugin exposes 6).
924
978
  // Branched before db() — runMcpServer() does its own init, and stdout must
925
979
  // stay clean for the MCP protocol.
926
980
  if (cmd === "mcp") {
package/src/config.ts CHANGED
@@ -15,6 +15,14 @@ export interface MyOMemoryConfig {
15
15
  * at init, default on; off = aliases passed by agents are dropped.
16
16
  */
17
17
  captureAliases: boolean;
18
+ /**
19
+ * D89: session working state note. `enabled` gates both the tool write
20
+ * path and the session-start surfacing; `ttlDays` is the default TTL the
21
+ * note's frontmatter stamps at write time (per-note `ttl_days` edits
22
+ * survive config changes afterwards).
23
+ */
24
+ workingStateEnabled: boolean;
25
+ workingStateTtlDays: number;
18
26
  /** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
19
27
  keywordPatterns: string[];
20
28
  /** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
@@ -43,6 +51,8 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
43
51
  injectOnFirstTurn: true,
44
52
  keywordCaptureEnabled: true,
45
53
  captureAliases: true,
54
+ workingStateEnabled: true,
55
+ workingStateTtlDays: 7,
46
56
  keywordPatterns: [
47
57
  "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
48
58
  "^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -183,6 +193,12 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
183
193
  injectOnFirstTurn: toBool,
184
194
  keywordCaptureEnabled: toBool,
185
195
  captureAliases: toBool,
196
+ workingStateEnabled: toBool,
197
+ workingStateTtlDays: (v) => {
198
+ const n = toNonNegInt(v);
199
+ if (n < 1) throw new Error("must be a positive integer (days)");
200
+ return n;
201
+ },
186
202
  memoryDir: toRelativeDir,
187
203
  "sync.autoPull": toBool,
188
204
  logLevel: (v) => {
package/src/doctor.ts CHANGED
@@ -24,7 +24,7 @@ interface Check {
24
24
  detail: string;
25
25
  }
26
26
 
27
- // D64: the MCP server exposes eleven tools; checking only the five the
27
+ // D64: the MCP server exposes twelve tools; checking only the six the
28
28
  // opencode plugin carries let a half-registered server pass as healthy.
29
29
  const EXPECTED_TOOLS = [
30
30
  "memory_add",
@@ -32,6 +32,7 @@ const EXPECTED_TOOLS = [
32
32
  "memory_list",
33
33
  "memory_supersede",
34
34
  "memory_forget",
35
+ "memory_workingstate",
35
36
  "memory_status",
36
37
  "memory_submit",
37
38
  "memory_propose",
@@ -412,7 +413,7 @@ function opencodePluginCheck(): Check {
412
413
  }
413
414
  }
414
415
 
415
- /** Spawn the real MCP server, handshake, and verify the five tools list. */
416
+ /** Spawn the real MCP server, handshake, and verify the twelve tools list. */
416
417
  function mcpCheck(): Promise<Check> {
417
418
  const name = "mcp";
418
419
  return new Promise((resolve) => {
package/src/index.ts CHANGED
@@ -5,6 +5,7 @@ import {
5
5
  captureFromText,
6
6
  captureHandoff,
7
7
  injectOnce,
8
+ surfaceWorkingStateOnce,
8
9
  } from "./plugin-core.ts";
9
10
  import { pickScopeRoot } from "./scope.ts";
10
11
  import { makeTools } from "./tools/memory.ts";
@@ -43,6 +44,11 @@ const server: Plugin = async ({ worktree, directory }) => {
43
44
  injectOnce(sessionID, state, (block) => {
44
45
  output.system.push(block);
45
46
  });
47
+ // D89: the working-state note rides the same one-time pass — with a
48
+ // fresh note it surfaces even when the memory lists are empty.
49
+ surfaceWorkingStateOnce(sessionID, state, (block) => {
50
+ output.system.push(block);
51
+ });
46
52
  // D73: runs on every request, so the note lands on the very turn whose
47
53
  // message the hook just captured. Delivered once per capture.
48
54
  const handoff = captureHandoff(sessionID, state);
package/src/init.ts CHANGED
@@ -63,9 +63,9 @@ const INSTRUCTIONS = `${MARKER}
63
63
 
64
64
  You have a local memory MCP server (\`open-memex\`). Its tools are
65
65
  \`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`,
66
- \`memory_forget\`, \`memory_status\`, \`memory_submit\`, \`memory_propose\`,
67
- \`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` — always call them by
68
- these full names.
66
+ \`memory_forget\`, \`memory_workingstate\`, \`memory_status\`, \`memory_submit\`,
67
+ \`memory_propose\`, \`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` —
68
+ always call them by these full names.
69
69
 
70
70
  - The server tells you when project outbox drafts are waiting for review — in
71
71
  tool results. When it does (or when the user asks), call \`memory_status\`
@@ -97,6 +97,11 @@ these full names.
97
97
  about the user that hold across all projects. When a saved fact becomes
98
98
  outdated, call \`memory_supersede\` (find the old memory's id with
99
99
  \`memory_search\` first) instead of adding a duplicate.
100
+ - When the user signals the session or task is wrapping up, refresh the
101
+ working-state note: call \`memory_workingstate\` (action=write) with a short
102
+ note — task summary, open files, last commands, where the work stands, next
103
+ step — so an interrupted task can resume in a fresh session. It is scratch
104
+ state, not durable knowledge: never save it as a memory.
100
105
 
101
106
  ## Syncing project memories for review (D26)
102
107
 
package/src/mcp.ts CHANGED
@@ -3,8 +3,9 @@
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_workingstate + memory_status / memory_submit /
7
+ * memory_propose / memory_promote / memory_resolve / memory_pr_status)
8
+ * over the Model Context Protocol, so any MCP client —
8
9
  * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
9
10
  * without a host-specific plugin.
10
11
  *
@@ -40,6 +41,7 @@ import {
40
41
  promoteMemoryOp,
41
42
  resolveMemoryOp,
42
43
  prStatusOp,
44
+ workingStateMemory,
43
45
  memoryAddArgs,
44
46
  memorySearchArgs,
45
47
  memoryListArgs,
@@ -51,6 +53,7 @@ import {
51
53
  memoryPromoteArgs,
52
54
  memoryResolveArgs,
53
55
  memoryPrStatusArgs,
56
+ memoryWorkingStateArgs,
54
57
  TOOL_DESCRIPTIONS,
55
58
  withOutboxNote,
56
59
  type ToolResult,
@@ -79,8 +82,9 @@ const SERVER_VERSION: string = (() => {
79
82
  */
80
83
  const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server.
81
84
  Its tools are memory_add, memory_search, memory_list, memory_supersede,
82
- memory_forget, memory_status, memory_submit, memory_propose, memory_promote,
83
- memory_resolve, memory_pr_status — always call them by these full names.
85
+ memory_forget, memory_workingstate, memory_status, memory_submit,
86
+ memory_propose, memory_promote, memory_resolve, memory_pr_status — always call
87
+ them by these full names.
84
88
 
85
89
  - The server tells you when project outbox drafts are waiting for review —
86
90
  in tool results, and in these session-start instructions. When it does,
@@ -129,6 +133,11 @@ memory_resolve, memory_pr_status — always call them by these full names.
129
133
  about the user that hold across all projects. When a saved fact becomes
130
134
  outdated, call memory_supersede (find the old memory's id with memory_search
131
135
  first) instead of adding a duplicate.
136
+ - When the user signals the session or task is wrapping up, call
137
+ memory_workingstate (action=write) with a short note: task summary, open
138
+ files, last commands, where the work stands, next step — so an interrupted
139
+ task can resume. It is scratch state, not knowledge: do not save it as a
140
+ memory; durable conclusions still follow the propose-first flow above.
132
141
  `;
133
142
 
134
143
  /** Adapt a framework-agnostic op result to an MCP tool response. */
@@ -314,6 +323,16 @@ export async function runMcpServer() {
314
323
  withSync((args) => toMcp(prStatusOp(args))),
315
324
  );
316
325
 
326
+ server.registerTool(
327
+ "memory_workingstate",
328
+ {
329
+ description: TOOL_DESCRIPTIONS.memory_workingstate,
330
+ inputSchema: z.object(memoryWorkingStateArgs),
331
+ annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
332
+ },
333
+ withSync((args) => toMcp(workingStateMemory(getScope, cfg, args))),
334
+ );
335
+
317
336
  const transport = new StdioServerTransport();
318
337
  await server.connect(transport);
319
338
  }
@@ -5,6 +5,7 @@ import {
5
5
  captureFromText,
6
6
  captureHandoff,
7
7
  injectOnce,
8
+ surfaceWorkingStateOnce,
8
9
  type PluginState,
9
10
  } from "./plugin-core.ts";
10
11
  import { makeTools } from "./tools/memory.ts";
@@ -30,7 +31,7 @@ import { makeTools } from "./tools/memory.ts";
30
31
  * verified on 2.0.1): by default the host exposes plugin tools only
31
32
  * through an `execute` meta-tool that runs model-written JS, and a model
32
33
  * that calls the tool by name instead gets "Unknown tool" — flaky,
33
- * model-dependent behavior. With the opt-out the five tools are plain
34
+ * model-dependent behavior. With the opt-out the six tools are plain
34
35
  * function calls, same as on v1 and MCP.
35
36
  */
36
37
 
@@ -70,7 +71,7 @@ interface V2ContextEvent {
70
71
  system: unknown[];
71
72
  }
72
73
 
73
- /** Register the five memory tools on a v2 host. */
74
+ /** Register the six memory tools on a v2 host. */
74
75
  async function registerTools(ctx: V2PluginContext, state: PluginState): Promise<void> {
75
76
  const tools = makeTools(() => state.scope, state.cfg);
76
77
  await ctx.tool.transform((editor) => {
@@ -111,6 +112,10 @@ export const v2Plugin = {
111
112
  injectOnce(sessionID, state, (block) => {
112
113
  ev.system.push({ type: "text", text: block });
113
114
  });
115
+ // D89: the working-state note rides the same one-time pass.
116
+ surfaceWorkingStateOnce(sessionID, state, (block) => {
117
+ ev.system.push({ type: "text", text: block });
118
+ });
114
119
  // D73: tell the agent what the keyword hook already stored this turn.
115
120
  const handoff = captureHandoff(sessionID, state);
116
121
  if (handoff) ev.system.push({ type: "text", text: handoff });