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.
- package/AGENTS.md +18 -5
- package/CHANGELOG.md +6 -0
- package/README.md +32 -13
- package/README.zh-CN.md +22 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +54 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +3 -2
- package/dist/index.js +6 -1
- package/dist/init.js +8 -3
- package/dist/mcp.js +17 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/store/audit.js +14 -0
- package/dist/tools/memory.js +11 -2
- package/dist/tools/ops.js +68 -0
- package/dist/working-state.js +118 -0
- package/docs/CONCEPTS.md +16 -0
- package/docs/CONCEPTS.zh-CN.md +13 -0
- package/docs/V2-DESIGN.md +42 -1039
- package/docs/design/decisions.md +1146 -0
- package/docs/design/knowledge-graph.md +86 -0
- package/package.json +1 -1
- package/scripts/smoke-mcp.ts +29 -2
- package/scripts/smoke-pure.ts +70 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +10 -0
- package/src/cli.ts +60 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +3 -2
- package/src/index.ts +6 -0
- package/src/init.ts +8 -3
- package/src/mcp.ts +23 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/store/audit.ts +20 -0
- package/src/tools/memory.ts +13 -1
- package/src/tools/ops.ts +87 -0
- package/src/working-state.ts +153 -0
|
@@ -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.
|
|
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": [
|
package/scripts/smoke-mcp.ts
CHANGED
|
@@ -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
|
|
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
|
}
|
package/scripts/smoke-pure.ts
CHANGED
|
@@ -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.
|
|
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.
|
|
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
|
|
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,
|
|
441
|
-
|
|
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 (
|
|
510
|
-
the opencode plugin's
|
|
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 (
|
|
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
|
|
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
|
|
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\`, \`
|
|
67
|
-
\`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` —
|
|
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 /
|
|
7
|
-
* memory_promote / memory_resolve / memory_pr_status)
|
|
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,
|
|
83
|
-
memory_resolve, memory_pr_status — always call
|
|
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
|
}
|
package/src/opencode-v2.ts
CHANGED
|
@@ -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
|
|
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
|
|
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 });
|