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/docs/V2-DESIGN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OpenMemex — Design Document (protocol v0.2)
2
2
 
3
- **Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D79 are settled; open questions are tracked at the end of this document.
3
+ **Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D90 are settled (log: [docs/design/decisions.md](design/decisions.md)); open questions are tracked at the end of this document.
4
4
  **Author:** Stone, with 小沐
5
5
  **Changelog vs v1:** incorporates round-3 review from Perplexity, Grok, Gemini, ChatGPT, DeepSeek.
6
6
  Key changes: Design Principles section; `role` separated from `type`; two iron rules;
@@ -230,6 +230,15 @@ second-brain target: store the note as user-authored content, preserve the body,
230
230
  and keep the same scope/privacy rules. The distinction is intent: implicit/model-suggested capture
231
231
  distills; explicit "save this note" may preserve long-form text.
232
232
 
233
+ ### 3.6 Session working state
234
+
235
+ open-memex stores durable knowledge, not the state of an interrupted task. A fresh session resuming mid-task currently re-derives "where the work stands" from the agent's own reading — the gap memryzed names as its third layer (per-repository session state). The working-state note closes it without turning scratch state into knowledge:
236
+
237
+ - **One ephemeral note per project.** A single Markdown file per project scope, at `working-state/<scope_key>.md` under the storage root — beside the store, never inside `memories/`, never committed to a repo. Frontmatter: `updated_at`, `ttl_days` (default 7, configurable). Body, short by design: task summary (one paragraph), open files (paths), last commands, where the work stands, next step. A scratch note, not a transcript.
238
+ - **Written at wrap-up, by the agent.** The agent writes or refreshes it when a session wraps up — via the host's Stop hook where one exists (opencode, Claude Code), otherwise on an explicit user command. The human can edit it directly; it is a plain file. *(D90 correction, 2026-11-03: the opencode plugin API has no Stop hook — implement opencode's write path as the "explicit user command" branch via instruction + tool (the surfaced block teaches the agent to refresh on the user's wrap-up signal); Claude Code's Stop hook arrives with the Phase 2C native plugin.)*
239
+ - **Surfaced at session start, outside the review ladder.** The note is shown alongside the §7 compact summary at session start. It is scratch state, not knowledge: it never enters the review ladder, never becomes a memory on its own, and the §7 Core disclaimer does not apply to it (it is the user's own recent work state, not retrieved historical knowledge). If something in it is worth keeping, the normal checkpoint-proposal flow (D61) proposes it as a distilled-memory candidate — that rule resolves the overlap with retrospective distillation: the note is the raw material, the ladder is the gate.
240
+ - **Expiry.** A note older than its TTL is ignored at session start. Expired notes are reported by `audit` (reports only, never auto-deletes — the D57 posture); the next wrap-up write overwrites.
241
+
233
242
  ---
234
243
 
235
244
  ## 4. Scopes, Visibility & Namespaces
@@ -335,6 +344,7 @@ instructions are never candidates.)
335
344
  - **Injection policy (concrete):**
336
345
  - Session start: compact summary only, ≤800 tokens default (configurable). Selection: `status:
337
346
  active`, then `importance` × recency × relevance to cwd/branch/open files. Query-aware, not newest-N.
347
+ - Session start also surfaces the project's working-state note (§3.6) alongside the compact summary — scratch state, not knowledge; the Core disclaimer does not apply to it.
338
348
  - On demand: agent calls `memory_search` → 3–10 hits.
339
349
  - Proactive nudge: attach a `warning`-type memory automatically only when the trigger is
340
350
  specific — tag hit **plus** content similarity above threshold, or `paths` match with the
@@ -355,6 +365,7 @@ instructions are never candidates.)
355
365
  | Explicit tools | `memory_add/update/forget` (soft delete) · `search/get/list/status` · `propose/promote` · `resolve`. Write tools confirm with the user; read tools are open. |
356
366
  | Keyword triggers | `remember …`, `note that …`, `TIL …`, `save this: …` + Chinese `记住` `记得` `保存一下` … |
357
367
  | Implicit (opt-in) | end-of-session "should I remember X?"; implicit captures default to `confidence: low` and appear in a separate list view for batch cleanup (regret window). |
368
+ | Wrap-up | agent writes/refreshes the §3.6 working-state note at session wrap-up (Stop hook where supported, else explicit user command); human-editable plain file. *(D90, 2026-11-03: shipped — opencode write path is the instruction + tool branch since the plugin API has no Stop hook; surfaced at session start, `audit` expiry report, `wstate` CLI.)* |
358
369
  | Redaction (hard) | `<private>…</private>` stripped; secret patterns are **masked in place** (first 4 chars kept, rest → `x`) and the write proceeds (D14); pre-commit hook scans shared scopes. |
359
370
 
360
371
  **Scope routing on capture:** when the user says "save", "remember", or "note this" without an
@@ -493,30 +504,35 @@ Zero-config is survival for an open-source project. The opencode plugin remains
493
504
 
494
505
  - **Phase 0 — Design freeze + validation (now).** Freeze this doc (protocol v0.2). Verify: company
495
506
  VS Code MCP-server support; corporate Copilot local-tool support. **Hard gate before Phase 2.**
507
+ *Status (2026-11-02): 部分实现 — design frozen; VS Code validation evidenced, corporate-Copilot validation has no recorded artifact.*
496
508
  - **Phase 1 — Local hardening (1–2 wks).** CJK default (bigram+FTS5) · v1→v2 migration · dedup +
497
509
  lifecycle · redaction hardening · scope docs. No external dependencies.
510
+ *Status (2026-11-02): 已实现 — all five items shipped (0.3.0–0.8.1).*
498
511
  - **Phase 2A — MCP server (shipped 2026-09-27, D15).** Core/adapters split
499
- (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all eleven memory tools —
512
+ (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all twelve memory tools —
500
513
  read-only-first phasing dropped per D15 · query-aware injection stays host-side.
501
514
  Ships in **`0.3.0-alpha`** (with bin/npx user-friendliness polish per §17 adoption path).
515
+ *Status (2026-11-02): 已实现 — shipped 2026-09-27 (0.3.0).*
502
516
  - **Phase 2B — Team sync.** GitProvider · `propose/promote/resolve` · in-repo dir · 1–2 colleague pilot
503
517
  (pilot project selection is maintainer-private, not tracked in this doc).
504
518
  Ships in **`0.4.0`** (was labeled `0.3.0-beta` before 0.3.0 shipped as stable).
505
519
  Embeddings/rerank run as a **parallel benchmark-gated experiment**, not on the critical path.
520
+ *Status (2026-11-02): 部分实现 — mechanisms shipped in 0.4.0; the 1–2 colleague pilot has no completion evidence (TEST-PLAN §G unchecked).*
506
521
  - **Phase 2C — Native agent plugins (candidates, not committed).** Claude Code plugin and/or
507
522
  Codex plugin as hook-enhanced paths over the same MCP tool surface (`SessionStart` →
508
523
  context injection, `UserPromptSubmit` → keyword-triggered search, `Stop`/`PostToolUse` →
509
524
  capture); per D16, no host-specific extraction intelligence — opencode is likewise
510
525
  supported as a plain MCP consumer. Gated on real-world signal from 0.3.0-alpha MCP
511
526
  dogfooding.
527
+ *Status (2026-11-02): 未实现 — candidate, not committed; Claude Code / Codex have only the MCP-consumer path.*
512
528
 
513
529
  ### Agent integration matrix
514
530
 
515
531
  | Agent | Integration path | Native hooks? | Status |
516
532
  |---|---|---|---|
517
533
  | opencode | native plugin (`src/index.ts`) | ✅ keyword capture + first-turn injection | shipped (Phase 1) |
518
- | VS Code Copilot | MCP server + `.github/copilot-instructions.md` | ❌ — VS Code extension API cannot intercept Copilot Chat (researched 2026-09-27); an extension would add no hook capability, so not worth building | ships `0.3.0-alpha` |
519
- | Cursor | MCP server + rules | ❌ no chat plugin API | ships `0.3.0-alpha` |
534
+ | VS Code Copilot | MCP server + `.github/copilot-instructions.md` | ❌ — VS Code extension API cannot intercept Copilot Chat (researched 2026-09-27); an extension would add no hook capability, so not worth building | shipped (0.3.0) |
535
+ | Cursor | MCP server + rules | ❌ no chat plugin API | shipped (0.3.0) |
520
536
  | Claude Code | MCP server today; plugin + hooks candidate | ✅ `SessionStart` / `UserPromptSubmit` / `PostToolUse` | Phase 2C candidate |
521
537
  | Codex (CLI/IDE) | MCP server (`[mcp_servers]` in config.toml / `codex mcp add`) today; plugin + hooks + marketplace candidate | ✅ hooks mirror Claude Code's | Phase 2C candidate |
522
538
 
@@ -526,6 +542,8 @@ Coding-agent memory is crowded; open-memex's wedge is **zero-cloud, zero-account
526
542
  zero-embedding-download**, with repo-native markdown as source of truth (maintainer
527
543
  requirement: personal data never touches third-party services). Benchmarks to track:
528
544
 
545
+ *Note (2026-11-02): figures below are a Sep 2026 snapshot and already stale in places (e.g. Mem0 ~50k+★ then, ~68k★ by 2026-10-28) — re-verify before quoting publicly.*
546
+
529
547
  | Product | Scale / backing (Sep 2026) | Shape | Gap vs open-memex |
530
548
  |---|---|---|---|
531
549
  | Mem0 | ~50k+★, $24M Series A (YC) | universal memory SDK/API, vector+graph, cloud-first | cloud dependency; not repo-native for coding agents |
@@ -562,7 +580,7 @@ requirement: personal data never touches third-party services). Benchmarks to tr
562
580
  - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
563
581
  sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
564
582
  for enterprise knowledge systems.
565
- - **Near-term backlog — committed direction, not yet built (2026-10-07).** Stone's rule: anything said as "later" is written down here. D77-L2: per-memory `retrieved_count`/`useful_count` (`useful_self` vs `useful_team`) + `memory_useful` tool. D77-L3: `memory_status` reuse report (top reused, zero-reuse, per-scope reuse rate) feeding the Spark Tank pilot metrics. D77: external bench — LongMemEval-S run 2026-10-07 (`scripts/bench-longmemeval.ts`, 470 questions, recall_any@k: R@5 97.0% / MRR 0.909 per-question, R@5 40.6% on a pooled 22k corpus; ahead of agentmemory’s BM25-only, level with their BM25+vector). MemoryAgentBench still open as a second external data point. D79 follow-up SUPERSEDED → built as **D80** (2026-10-07): index-time synonym/translation expansion shipped; 41-query fixture recall@5 0.854 → 0.976, MRR 0.791 → 0.859. Embedding-model configurability (Stone 2026-10-07): the multilingual model is his personal need (EN↔ZH), not everyone’s — the model must be user-configurable. Timing: (1) NOW in the bench only — a `--model` flag to measure the multilingual tax (multilingual vs English-only on English data), which decides the DEFAULT. (2) AT SHIP TIME — `embedding.model` in `MyOMemoryConfig` + `SETTABLE_KEYS`, model-agnostic storage from day one (dim + model id stored with vectors, cache dir), download UX and `doctor` checks. Not before the gate passes: building config UX for a layer we haven’t decided to ship is premature. If multilingual tax ≈ 0, default multilingual (covers everyone); else default English-only with a docs note.D78: curate+submit — pre-submit lint, then confidence-tier auto-curation (auto-apply / batch-confirm / explicit human). D79 follow-ups: feedback-weighted ranking once D77 counters land; embeddings gate decision against the published baseline; reranker evaluation. Cross-lingual embedding rerank (Stone 2026-10-16, from obsidian-mind comparison): ablation showed multilingual vectors beat BM25 by +12pp R@5 on the cross-lingual slice — the one gap lexical can't cover. Design as opt-in rerank for EN↔ZH queries only, not a default path; local stays BM25-first per the retrieval split above. TDQS nit (separate PR): tighten search/list `type` to `z.enum`. Retrieval eval: grow the fixture (project-scope tier cases) as retrieval logic evolves. Retrieval split — local vs share server (Stone 2026-10-07): the two environments emphasize different mechanisms. Local (personal machine): BM25 + curated index-time expansion as the primary — deterministic, zero model download (D7), fast on CPU, index bloat bounded by the small corpus; embeddings opt-in only. Share server (team/org, enterprise): embeddings + ANN + reranker as the primary — server-grade compute with models resident, corpus too large and multi-author for any curated map; the curated map stays as a precision layer plus org glossary. The server additionally aggregates D77 useful_count across users into feedback-weighted ranking (already in D79 follow-ups) — a signal a single machine can never have. Bottom-up loop: curated pairs that many users converge on locally become org-glossary candidates. Economics flip: N users each downloading a model vs one model amortized on the server. OptMem lessons (Stone 2026-10-16, from kafkaup's OptMem post): three friction-reduction ideas worth stealing from the minimalist end of the spectrum. (1) **Token cost as spec** — measure and publish open-memex's prompt/token overhead in the README, the way OptMem advertises its "426-token prompt"; acquisition copy, not just engineering. (2) **`wake` convention** — document a session-start ritual (one `memory_recall` call at the beginning of every session), mirroring OptMem's `memo wake`; the MCP tools exist but the habit isn't specified. (3) **Capture length nudge** — a soft length cap or conciseness hint at capture time, inspired by OptMem's 280-byte hard cap; forces conciseness at write time, cheap to implement, aligned with the distill-to-AGENTS.md direction (D40). Three-tier memory zones (Stone 2026-10-18, from Westenberg "I Deleted My Second Brain" + his own reflection): the second brain should have zones like cache vs database, not "keep everything" vs "delete everything". **Hot** (active zone, cache-like: small, curated, always in context — D81 aliases, WHAT-level) · **Warm** (compost/incubation: not active but not cold; periodic review, rotted items deleted — this is "forget on purpose" as engineering) · **Cold** (full archive, searchable, not resident). The hard part is the **promotion/demotion policy** — what moves between zones, when, by what rule (the cache-replacement problem for knowledge; "useful" ≠ "recently used"). Capture restraint is a separate gate: not everything deserves to enter even cold storage. Spec the policy before building the zones. Auto-capture design brief (Stone 2026-10-19, from ai-memory comparison): open-memex wants auto-capture but under the restraint philosophy (not ai-memory's capture-everything). Five design questions: (1) **End-session trigger** — what hooks does opencode actually expose? (check before designing; ai-memory built finalize-session fallback for harnesses without SessionEnd); candidates: native hook / idle timeout / explicit command / context-near-full. (2) **Distillation** — rules first (what happened: git diff, tool calls, decision sentences; zero LLM), interpretation layer (what it means) left to human/LLM. (3) **Save-value triage** — three tiers: clearly valuable → save; clearly noise → drop; ambiguous → ask human. Boundary principle: **rather over-ask than over-save** (polluted retrieval costs more than a missed memory). (4) **Routing** — four exits: project memory / personal memory / AGENTS.md proposal (distill-agents exists) / discard; keep v1 routing rules simple. (5) **Human interaction** — one batch confirmation at session end ("save these 3? [y/n/edit]"), never per-item popups. Relations: D73 keyword capture is turn-level (no conflict); `wake` convention is session-start (this is session-end — the other bookend); three-tier zones govern where auto-captured items land. Cross-agent study (Stone 2026-10-19): open-memex has cross-agent on the roadmap — study how ai-memory does it (handoff claim-once semantics, lifecycle hooks per harness, VSCode support via MCP-only) before designing ours; borrow the semantics, not the push-injection behavior (discoverability > injection). Injection cost discipline (Stone 2026-10-19, from Harness² paper arXiv:2610.14224): "ALWAYS-ON PROSE IS THE EXPENSIVE OPTION" — every always-on word competes with the agent's output budget. Current session-start injection (8 project + 5 personal) is the expensive path; direction: move "important but not needed every turn" memories to on-demand (tool/skill-triggered loading), keep only truly every-turn items resident. Tolerable now, better not to tolerate. Component cost ladder for reference: SKILL (default, zero-cost until invoked) > SCRIPT > SUBAGENT > PLUGIN ("prose can be skipped, a hook cannot") > ALWAYS-ON TEXT (last resort). Read-less compression (Stone 2026-10-19, from caveman https://github.com/JuliusBrussee/caveman): the execution layer of injection cost discipline — compress what the agent READS before it reaches context, not just what we inject. Caveman's measured numbers: 33.2% fewer input tokens per session (CSV 98.9%, logs 98.5%, YAML 99.1%, JSON 98.5% per-file; HTML has no compressor yet). Direction for open-memex: a pre-retrieval compression pass on tool outputs and retrieved passages (structured data → compact form), originals stay on disk and pullable on demand. Two design principles borrowed: (1) never compress the user's own prompt/input (Adobe CAVEWOMAN finding: cavemanning user prompts makes answers worse); (2) leave code/tool calls/payloads verbatim — compress the wrapper, not the payload. Caveats: caveman's own rules cost ~1,160 input tokens fixed; per-request billing (Copilot-style) nullifies the saving — compression pays off on per-token billing only. Knowledge upkeep as a first-class direction (Stone 2026-10-23; external validation: Hedy Zhang's FDE field retrospective on enterprise AI knowledge bases, X article 2026-10-22 — enterprise knowledge bases die on unowned upkeep, not on retrieval: stale answers served silently, conflicts with no owner, updates nobody owns after delivery). The mechanisms already exist (supersede chains, lifecycle states, `audit` health check, curator convention); the direction is driving the human cost of upkeep toward zero: (1) staleness signals — age, contradiction with newer captures, D77 zero-reuse counters — feeding a standing review queue instead of waiting for someone to remember to run `audit`; (2) a conflict inbox — semantic conflicts and broken chains as a persistent todo; (3) the endgame is D78 confidence-tier auto-curation (auto-apply the safe tier, batch-confirm the rest). Success metric: the base stays trustworthy on minutes-per-week of human attention, not a curator shift. README pitches the shipped half of this as core concept 4 (Knowledge stays current) plus a "When facts change" comparison row.
583
+ - **Near-term backlog — committed direction, not yet built (2026-10-07).** Stone's rule: anything said as "later" is written down here. D77-L2: per-memory `retrieved_count`/`useful_count` (`useful_self` vs `useful_team`) + `memory_useful` tool. D77-L3: `memory_status` reuse report (top reused, zero-reuse, per-scope reuse rate) feeding the Spark Tank pilot metrics. D77: external bench — LongMemEval-S run 2026-10-07 (`scripts/bench-longmemeval.ts`, 470 questions, recall_any@k: R@5 97.0% / MRR 0.909 per-question, R@5 40.6% on a pooled 22k corpus; ahead of agentmemory’s BM25-only, level with their BM25+vector). MemoryAgentBench still open as a second external data point. D79 follow-up SUPERSEDED → built as **D80** (2026-10-07): index-time synonym/translation expansion shipped; 41-query fixture recall@5 0.854 → 0.976, MRR 0.791 → 0.859. Embedding-model configurability (Stone 2026-10-07): the multilingual model is his personal need (EN↔ZH), not everyone’s — the model must be user-configurable. Timing: (1) NOW in the bench only — a `--model` flag to measure the multilingual tax (multilingual vs English-only on English data), which decides the DEFAULT. (2) AT SHIP TIME — `embedding.model` in `MyOMemoryConfig` + `SETTABLE_KEYS`, model-agnostic storage from day one (dim + model id stored with vectors, cache dir), download UX and `doctor` checks. Not before the gate passes: building config UX for a layer we haven’t decided to ship is premature. If multilingual tax ≈ 0, default multilingual (covers everyone); else default English-only with a docs note.D78: curate+submit — pre-submit lint, then confidence-tier auto-curation (auto-apply / batch-confirm / explicit human). D79 follow-ups: feedback-weighted ranking once D77 counters land; embeddings gate decision against the published baseline; reranker evaluation. Cross-lingual embedding rerank (Stone 2026-10-16, from obsidian-mind comparison): ablation showed multilingual vectors beat BM25 by +12pp R@5 on the cross-lingual slice — the one gap lexical can't cover. Design as opt-in rerank for EN↔ZH queries only, not a default path; local stays BM25-first per the retrieval split above. TDQS nit (separate PR): tighten search/list `type` to `z.enum`. Retrieval eval: grow the fixture (project-scope tier cases) as retrieval logic evolves. Retrieval split — local vs share server (Stone 2026-10-07): the two environments emphasize different mechanisms. Local (personal machine): BM25 + curated index-time expansion as the primary — deterministic, zero model download (D7), fast on CPU, index bloat bounded by the small corpus; embeddings opt-in only. Share server (team/org, enterprise): embeddings + ANN + reranker as the primary — server-grade compute with models resident, corpus too large and multi-author for any curated map; the curated map stays as a precision layer plus org glossary. The server additionally aggregates D77 useful_count across users into feedback-weighted ranking (already in D79 follow-ups) — a signal a single machine can never have. Bottom-up loop: curated pairs that many users converge on locally become org-glossary candidates. Economics flip: N users each downloading a model vs one model amortized on the server. OptMem lessons (Stone 2026-10-16, from kafkaup's OptMem post): three friction-reduction ideas worth stealing from the minimalist end of the spectrum. (1) **Token cost as spec** — measure and publish open-memex's prompt/token overhead in the README, the way OptMem advertises its "426-token prompt"; acquisition copy, not just engineering. (2) **`wake` convention** — document a session-start ritual (one `memory_recall` call at the beginning of every session), mirroring OptMem's `memo wake`; the MCP tools exist but the habit isn't specified. (3) **Capture length nudge** — a soft length cap or conciseness hint at capture time, inspired by OptMem's 280-byte hard cap; forces conciseness at write time, cheap to implement, aligned with the distill-to-AGENTS.md direction (D40). Three-tier memory zones (Stone 2026-10-18, from Westenberg "I Deleted My Second Brain" + his own reflection): the second brain should have zones like cache vs database, not "keep everything" vs "delete everything". **Hot** (active zone, cache-like: small, curated, always in context — D81 aliases, WHAT-level) · **Warm** (compost/incubation: not active but not cold; periodic review, rotted items deleted — this is "forget on purpose" as engineering) · **Cold** (full archive, searchable, not resident). The hard part is the **promotion/demotion policy** — what moves between zones, when, by what rule (the cache-replacement problem for knowledge; "useful" ≠ "recently used"). Capture restraint is a separate gate: not everything deserves to enter even cold storage. Spec the policy before building the zones. Auto-capture design brief (Stone 2026-10-19, from ai-memory comparison): open-memex wants auto-capture but under the restraint philosophy (not ai-memory's capture-everything). Five design questions: (1) **End-session trigger** — what hooks does opencode actually expose? (check before designing; ai-memory built finalize-session fallback for harnesses without SessionEnd); candidates: native hook / idle timeout / explicit command / context-near-full. (2) **Distillation** — rules first (what happened: git diff, tool calls, decision sentences; zero LLM), interpretation layer (what it means) left to human/LLM. (3) **Save-value triage** — three tiers: clearly valuable → save; clearly noise → drop; ambiguous → ask human. Boundary principle: **rather over-ask than over-save** (polluted retrieval costs more than a missed memory). (4) **Routing** — four exits: project memory / personal memory / AGENTS.md proposal (distill-agents exists) / discard; keep v1 routing rules simple. (5) **Human interaction** — one batch confirmation at session end ("save these 3? [y/n/edit]"), never per-item popups. Relations: D73 keyword capture is turn-level (no conflict); `wake` convention is session-start (this is session-end — the other bookend); three-tier zones govern where auto-captured items land. Cross-agent study (Stone 2026-10-19): open-memex has cross-agent on the roadmap — study how ai-memory does it (handoff claim-once semantics, lifecycle hooks per harness, VSCode support via MCP-only) before designing ours; borrow the semantics, not the push-injection behavior (discoverability > injection). Injection cost discipline (Stone 2026-10-19, from Harness² paper arXiv:2610.14224): "ALWAYS-ON PROSE IS THE EXPENSIVE OPTION" — every always-on word competes with the agent's output budget. Current session-start injection (8 project + 5 personal) is the expensive path; direction: move "important but not needed every turn" memories to on-demand (tool/skill-triggered loading), keep only truly every-turn items resident. Tolerable now, better not to tolerate. Component cost ladder for reference: SKILL (default, zero-cost until invoked) > SCRIPT > SUBAGENT > PLUGIN ("prose can be skipped, a hook cannot") > ALWAYS-ON TEXT (last resort). Read-less compression (Stone 2026-10-19, from caveman https://github.com/JuliusBrussee/caveman): the execution layer of injection cost discipline — compress what the agent READS before it reaches context, not just what we inject. Caveman's measured numbers: 33.2% fewer input tokens per session (CSV 98.9%, logs 98.5%, YAML 99.1%, JSON 98.5% per-file; HTML has no compressor yet). Direction for open-memex: a pre-retrieval compression pass on tool outputs and retrieved passages (structured data → compact form), originals stay on disk and pullable on demand. Two design principles borrowed: (1) never compress the user's own prompt/input (Adobe CAVEWOMAN finding: cavemanning user prompts makes answers worse); (2) leave code/tool calls/payloads verbatim — compress the wrapper, not the payload. Caveats: caveman's own rules cost ~1,160 input tokens fixed; per-request billing (Copilot-style) nullifies the saving — compression pays off on per-token billing only. Knowledge upkeep as a first-class direction (Stone 2026-10-23; external validation: Hedy Zhang's FDE field retrospective on enterprise AI knowledge bases, X article 2026-10-22 — enterprise knowledge bases die on unowned upkeep, not on retrieval: stale answers served silently, conflicts with no owner, updates nobody owns after delivery). The mechanisms already exist (supersede chains, lifecycle states, `audit` health check, curator convention); the direction is driving the human cost of upkeep toward zero: (1) staleness signals — age, contradiction with newer captures, D77 zero-reuse counters — feeding a standing review queue instead of waiting for someone to remember to run `audit`; (2) a conflict inbox — semantic conflicts and broken chains as a persistent todo; (3) the endgame is D78 confidence-tier auto-curation (auto-apply the safe tier, batch-confirm the rest). Success metric: the base stays trustworthy on minutes-per-week of human attention, not a curator shift. README pitches the shipped half of this as core concept 4 (Knowledge stays current) plus a "When facts change" comparison row. Session working state note (D89, 2026-11-02) → BUILT, shipped 2026-11-03 as D90: 12th tool `memory_workingstate` on both hosts, session-start surfacing, `audit` expiry report, `wstate` CLI; opencode write path is instruction + tool (plugin API has no Stop hook).
566
584
 
567
585
  - **Phase 5 — Candidates recorded 2026-10-04 (not committed).** From the competitor scan (D75): an offline FTS5 retrieval eval with a published recall number (gates any semantic-layer decision) [promoted to next build, D77] · per-client trust levels on the review ladder · cold-start Markdown import into outbox drafts · `doctor` check that each editor's MCP registration points at the intended data root (mis-rooted servers are a real failure mode elsewhere). Sequencing and scope TBD per candidate.
568
586
  - **Phase 5 — Candidates recorded 2026-10-11 (not committed).** From the XERJ review (xerj-org/xerj, Apache-2.0; founder Ivan N requested open-memex D81 for the XERJ Corpus Hub — agreed 2026-10-11, attribution + repo link): schema-first querying (`xerj_map` — agent fetches the field map before writing query DSL; candidate: a schema/describe helper ahead of `memory_search` to cut dead queries) · token-budgeted MCP results (their `token_budget.rs` — truncate to a token budget, not a fixed row limit) · hybrid retrieval as the scale answer (BM25 + vector kNN with fused ranking, e.g. RRF — the reference pattern for the eventual embedding layer; our lexical ceiling is already measured at R@5 40.6% pooled) · NL-to-validated-query planning (`xerj_plan` — natural language in, validated query out; candidate: a query lint/validate step before search executes) · evidence-carrying memory links (typed links with evidence + confidence, soft-retire never hard-delete — same spirit as our review-state ladder; prior art for a future memory-graph direction) · honest isolation docs (state what a namespace guarantees and does NOT — query-level vs trust boundary; same spirit as our Limitations section) · cost-accounted evals (report tokens + dollars per approach, as in their case studies — the format for proving "memory makes agents cheaper"). Sequencing and scope TBD per candidate.
@@ -583,1067 +601,52 @@ requirement: personal data never touches third-party services). Benchmarks to tr
583
601
 
584
602
  ---
585
603
 
604
+ ## 20. Knowledge Graph & Compiled Wiki (v0.3 candidate)
605
+
606
+ > v0.3 candidate (D88). Does not change the frozen v0.2 protocol; the graph/wiki is a derived layer. Full text: [docs/design/knowledge-graph.md](design/knowledge-graph.md).
607
+
608
+ *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).*
609
+
610
+ ---
611
+
586
612
  ## Decisions (append-only)
587
613
 
588
- - **D1** — Markdown as source of truth, index rebuildable. *Rationale: human-editable, git-friendly,
589
- no lock-in; the single decision that makes team sharing trivial.*
590
- - **D2** — Instruction/data separation via `role` gate (iron rule 1). *Rationale: the #1 failure mode
591
- of memory systems is history being mistaken for current rules.*
592
- - **D3** — `personal` scope never syncs. *Rationale: the trust anchor of the whole project.*
593
- - **D4** — MCP is an interface, not the product identity. *Rationale: transports evolve; the protocol
594
- must outlive them.*
595
- - **D5** — Git is transport, local index is query layer. *Rationale: answers the "git can't do
596
- semantic search" objection by separating the two layers.*
597
- - **D6** — Promotion is explicit, never automatic. *Rationale: personal → shared is a governance
598
- decision, not a sync event.*
599
- - **D7** — Embeddings are an optional capability, BM25+CJK is the default. *Rationale: zero-setup
600
- default; no mandatory 100MB download or native dependency.*
601
- - **D8** — Contested choices become **configurable with a popular default**, not hard-coded.
602
- Applies to: in-repo dir name (default `.ai/open-memex/` per D23), CJK tokenizer (default bigram),
603
- embeddings model (default `multilingual-e5-small`). *Rationale: the five-AI review split on all
604
- three; maintainers shouldn't burn decision capital where config suffices.*
605
- - **D9** — The LAN reference server lives at `examples/remote-server/`. *Rationale: maintainer decision
606
- 2026-09-26; "lan" is noise for OSS users, "remote-server" names what it proves (RemoteProvider).*
607
- - **D10** — Project renamed to **OpenMemex** (npm `open-memex`, repo `stoneskin/open-memex`).
608
- *Rationale: `my-o-memory` was opencode-specific; the Memory Protocol positioning needs a broader name.
609
- Fresh repo with no company-account commit history (see migration checklist 2026-09-26); old repo
610
- archived with a pointer. Trademark check on "Memex"/"OpenMemex" required before public launch
611
- (flagged in round-4 review).*
612
- - **D13** — Rename cascade (implements D10 in this doc, 2026-09-26): npm package `open-memex`,
613
- CLI `open-memex` (e.g. `open-memex pull`), config dir `~/.open-memex/`, in-repo dir default
614
- `.open-memex/` (**amends D8's** `.my-o-memory/` default). MCP tool name `memory_search` unchanged.
615
- v1→v2 migration moves legacy `.my-o-memory/` dirs and `~/.my-o-memory/` config to the new paths
616
- (with backup, explicit via `open-memex migrate`). *Rationale: one name everywhere; the old default
617
- was set before the rename decision.*
618
- - **D11** — `type` and `role` remain separate. `type` describes what a memory IS; `role`
619
- (`knowledge` | `instruction`, default `knowledge`) describes how it may be USED. `role: instruction`
620
- is an explicit, reviewable exception and may enter instruction context only when iron rule 1
621
- (`role` + `instruction_state: approved` + `trust_level`) passes. *Rationale: content classification
622
- and behavior authorization are separate concerns — the risky action is entering instruction
623
- context, not the content's wording. Unanimous 5/5 in round-4 AI review, 2026-09-26.*
624
- - **D12** — Pull is explicit by default. Session start never pulls, never blocks on network, and
625
- shows a staleness indicator instead. `sync.autoPull` is configurable, default `false`; even with
626
- `autoPull: true`, a failed pull never blocks the session and every pull emits a receipt.
627
- *Rationale: a memory pull can change agent behavior, so it must be a deliberate, visible act —
628
- predictable offline-first beats silent freshness. Unanimous 5/5 in round-4 AI review, 2026-09-26.*
629
- - **D14** — Secret detection masks instead of refusing. A write-path secret hit is **masked in
630
- place** (first 4 characters kept, the rest replaced with `x`, length-preserving) and the write
631
- proceeds with a notice; `<private>…</private>` spans are still stripped to `[REDACTED]`.
632
- Amends the v0.2 rule "secret patterns refuse the write" (§8, §11). *Rationale: a refused write
633
- loses the surrounding context the user asked to remember; a prefix-masked secret stays
634
- recognizable (which key it was) while the credential itself is not recoverable from the file.
635
- Supersedes the refusal behavior; applies to every write path (tools, keyword capture, CLI).
636
- 2026-09-27.*
637
- - **D15** — Phase 2A MCP server ships with all five tools, not read-only first. The MCP server
638
- (`src/mcp.ts`, stdio) exposes `memory_add` / `memory_search` / `memory_list` /
639
- `memory_supersede` / `memory_forget` — amends the §18 roadmap's "Read-only MCP" phasing.
640
- *Rationale: the write path is the same Core (redact/D14, dedup, lifecycle) already shipped and
641
- dogfooded in the opencode plugin, so a separate read-only stage adds process cost without
642
- reducing risk. Core/adapters split implemented as `src/tools/ops.ts` (host-agnostic logic +
643
- shared zod schemas); the opencode plugin and the MCP server are thin adapters over it.
644
- Query-aware injection stays host-side: MCP is request/response and offers no hooks, so
645
- proactive memory use depends on the host's agent instructions. 2026-09-27.*
646
- - **D16** — No separate LLM extraction pass; memory intelligence lives in model-driven tool
647
- calls. A dedicated post-session extraction (opencode `session.idle` hook → hidden session
648
- → host model) was evaluated and rejected: the model's own decision to call `memory_add`
649
- *is* the LLM judgment of "worth remembering", so a second pass is redundant and
650
- host-specific. Investment goes into the shared layer instead — `TOOL_DESCRIPTIONS` in
651
- `src/tools/ops.ts` and each host's agent instructions — so every host benefits at once.
652
- Native plugins (opencode now; Claude Code / Codex as Phase 2C candidates) remain as
653
- hook-enhanced paths, but opencode is also supported as a plain MCP consumer of
654
- `open-memex mcp`, keeping one unified tool surface. 2026-09-27.
655
- - **D17** — `open-memex init` resolves the MCP server command at init time. A durable
656
- `open-memex` on PATH (outside npm's ephemeral `_npx` cache) → `command: "open-memex"`;
657
- otherwise (one-shot `npx open-memex@alpha init`) → `command: "npx", args: ["-y",
658
- "open-memex@alpha", "mcp"]` plus a hint to `npm i -g` + re-run `init --force`.
659
- `mcp --print-config` uses the same resolution. *Rationale: a one-shot npx run leaves
660
- no bin behind, so writing `command: "open-memex"` would produce a dead MCP server on
661
- the next editor launch; the npx fallback keeps the one-command setup actually
662
- one-command. 2026-09-27.*
663
-
664
- - **D18** — Keyword scope routing: 我 → personal, 我们 → project. Chinese capture
665
- keywords are split into two pattern lists: personal patterns (`记住我`/`替我记`/
666
- `我觉得`/`我喜欢`, plus legacy `remember for me`/`记住(个人)`) route to the personal
667
- scope, while project patterns (`我们认为`/`我们决定`/`帮我们记住`, and the generic
668
- `记住…` for `记住我们的…`) route to the current project scope. Personal patterns are
669
- scanned first and *claim* the line so the generic `记住…` pattern cannot double-fire;
670
- `记住我` uses a `(?!们)` guard so it never swallows `记住我们…`. *Rationale: the
671
- user's own rule — "我" is personal, "我们" is the current project — stated 2026-09-27;
672
- scanning user messages (never assistant output) with personal-first claim keeps one
673
- utterance to one memory. README + repo AGENTS.md keyword sections updated in the same
674
- commit. 2026-09-27.*
675
- - **D19** — `open-memex init` asks setup questions; `open-memex config set` edits settings
676
- after install. `init` prompts on a TTY (editor: vscode/cursor/opencode; keyword
677
- auto-capture on/off; first-turn injection on/off), `--yes` accepts all defaults, and
678
- non-terminal runs never prompt (scripts keep the historical vscode default).
679
- Non-default answers persist to the JSONC config file; `open-memex config set <key>
680
- <value>` changes them later (validated keys: `maxProjectMemories`, `maxProfileItems`,
681
- `injectOnFirstTurn`, `keywordCaptureEnabled`, `logLevel`). `init --client opencode`
682
- merges a `type: "local"` MCP entry into project-level `opencode.jsonc` (v1 format).
683
- *Rationale: install time is the only moment the user's attention is guaranteed, and a
684
- print-only `config` left no path to change settings afterwards. 2026-09-27.*
685
- - **D20** — `init` / `mcp --print-config` support Visual Studio. Writes solution-level
686
- `.mcp.json` with the `"servers"` section (`{ "type": "stdio", "command", "args" }`),
687
- per Microsoft Learn (VS 2022 17.14+ / VS 2026, Windows-only). `.github/copilot-
688
- instructions.md` is still written — VS's Copilot reads it too. Note VS also
689
- auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so repos already set up for
690
- VS Code get VS support for free; the explicit `.mcp.json` is the source-controllable
691
- option. 2026-09-27.*
692
- - **D21** — The published npm package ships pre-compiled JS (`tsc -p tsconfig.build.json`
693
- → `dist/`, via `prepublishOnly`; bin points at `dist/cli.js`). *Rationale: Node's
694
- `--experimental-strip-types` refuses files under `node_modules`
695
- (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the old launcher
696
- (`bin/open-memex.js` re-execing `src/cli.ts`) crashed on every global install —
697
- reported 2026-09-27 on Node v22.12.0. Development stays build-free (`npm run cli`
698
- / `npm run mcp` run `src/` directly); `doctor`'s MCP self-check resolves its server
699
- entry the same way it is running (`dist/mcp.js` vs `src/mcp.ts`). The opencode
700
- native plugin still loads `src/index.ts` (Bun strips types anywhere). 2026-09-27.*
701
- - **D22** — `init` writes the Copilot memory instructions to the **user level** by
702
- default (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-
703
- instructions.md` for Visual Studio 2026) instead of the repo-level
704
- `.github/copilot-instructions.md`. *Rationale: the repo-level file is checked in,
705
- so teammates without open-memex get Copilot errors about missing `memory_*`
706
- tools. The user-level location is GitHub's official personal-instructions slot
707
- (highest priority, all projects, never in a repo). `--instructions project`
708
- keeps the old repo-level behavior for teams where everyone uses open-memex.
709
- The instructions carry a guard clause ("ignore this section when the
710
- `open-memex` MCP server is not available") as cheap insurance. 2026-09-27.*
711
- - **D23** — Default in-repo memory dir is `.ai/open-memex/` (configurable via
712
- `memoryDir`; rejects absolute paths and `..`). *Rationale: `.ai/` is the
713
- emerging convention for AI-local project state; the `open-memex/` leaf keeps
714
- brand clarity and avoids collisions with other tools' `.ai/` content.
715
- 2026-09-27.*
716
- - **D24** — Project-scope markdown lives in the repo: writes with
717
- `scope: project` go to `<projectRoot>/<memoryDir>/` (D23 default
718
- `.ai/open-memex/`); `personal` never leaves appdata. Legacy appdata project
719
- files are lazily migrated on first write/`syncScope` — the move is guarded by
720
- the appdata dir name (which *is* the scope key), so it can only ever migrate
721
- the current scope's files. The index's `file_path` is the single locator for
722
- reads/deletes (`findMemoryFile`, `forget`); on the near-impossible id
723
- collision between locations, the in-repo copy wins. *Rationale: one home per
724
- scope, no silent data loss, no repo pollution before first use.* 2026-09-27.*
725
- - **D25** — Review workflow semantics (`propose` / `promote` / `resolve`,
726
- `src/review.ts`): (1) `review_state` frontmatter field
727
- (`draft → proposed → approved/rejected → published`, default `draft`) plus
728
- `proposed_by` / `approved_by` / `derived_from` / `review_note` provenance;
729
- the SQLite index carries `review_state` (schema v6, rebuilt from markdown —
730
- D1). (2) `propose` **copies** personal → project (new id, never moves — the
731
- personal original stays private); one call takes several ids (one branch,
732
- one PR; all-or-nothing — a bad id aborts the whole batch);
733
- `--local-approve` skips the PR for solo
734
- devs. (3) `promote` advances exactly one step up the ladder
735
- (`proposed → approved → published`), `--reject`s with a note (also from
736
- `approved`, withdrawing approval before merge), or `--resubmit`s a rejected
737
- memory back to `proposed` for another round; `draft` and terminal states
738
- refuse. (4) `resolve` lists conflicted memory files, or
739
- attempts a field-level 3-way merge from git stages 1/2/3 (`tags` union,
740
- `updated_at` takes latest, body merged only when one side changed); semantic
741
- conflicts (same field / body changed differently on both sides) are reported
742
- and the file is left untouched — **never auto-resolved**. (5) A rejection
743
- never deletes anything: the file stays on the author's branch; the human
744
- accepts (close PR, delete branch), revises + `--resubmit`s, or keeps it as
745
- a `[rejected]` record. (6) No git
746
- automation anywhere in the workflow: no branch creation, no commits, no PRs —
747
- the commands print the exact next steps for the human. Org-level promotion is
748
- Phase 4. *Rationale: the review ladder must be explicit and auditable; the
749
- tool assists merging but a human always decides meaning.* 2026-09-27.*
750
- - **D26** — **Supersedes D24.** Project-scope markdown has two homes, one per
751
- lifecycle stage — never silently moved between them. (1) `memory_add` /
752
- `memory_propose` with `scope: project` write to the **appdata outbox**
753
- (`memories/<project_key>/<id>.md`, `review_state: draft`); the outbox is
754
- git-invisible and branch-independent. The D24 lazy migration is deleted —
755
- appdata project files are legitimate drafts, not legacy. (2) `open-memex
756
- submit <id...>` / `memory_submit` moves user-named drafts into the repo's
757
- `<memoryDir>/` (D23), flipping `review_state` to `proposed`: the file now
758
- follows branches and PRs. `sync-status` / `memory_status` shows both sides
759
- (outbox drafts, repo review states, uncommitted repo files). (3) The move is
760
- one-stage-one-place: copy → verify hash → local commit → verify → delete
761
- outbox original; re-running is idempotent (identical content skips, different
762
- content aborts). `search` prefers the repo copy when both exist; conflicts
763
- (same id, different content; push rejected) stop and ask the human — never
764
- overwrite. *Rationale: an AI agent drafts constantly; the repo should only
765
- ever see what the human explicitly approved for review. The outbox is the
766
- agent's desk, the repo dir is the shared table. Approved 2026-09-28.*
767
- - **D27** — **Revises D25 §6 (no git automation).** `submit` automates the
768
- *local* half of the git workflow: create `mem/sync-<timestamp>` (or
769
- `--onto` the current branch for code+memory PRs), copy, `git add` only the
770
- memory files, local commit, verify. It prints the push + `gh pr create`
771
- commands for the human — but an agent that already holds the user's Yes for
772
- this sync carries through push and PR creation without re-asking (each step
773
- is not a separate approval). Batch submit is all-or-nothing; an empty-branch
774
- abort rolls the branch back. *Rationale: the old "no git automation" rule
775
- assumed a human at the keyboard; the agent-driven flow needs local mechanics
776
- automated while push/PR stay under the user's explicit per-sync Yes/No.
777
- Approved 2026-09-28.*
778
- - **D28** — Memory PR base defaults to the **current branch**; the user may
779
- redirect to `main` or the project's integration branch (`--base`). A
780
- standalone memory PR and a code+memory PR are both supported — the agent asks
781
- which one each time; on "with code" it uses `--onto` and never commits
782
- unrelated staged changes. *Rationale: memory usually reviews against the work
783
- it describes (current branch); the integration branch is the exception, not
784
- the default. Approved 2026-09-28.*
785
- - **D29** — Every review transition is written to a per-memory audit trail
786
- (`review_history`: at/by/from/to/note) — reject / resubmit / approve /
787
- publish all append, never overwrite; `propose` and `submit` seed it; merge
788
- conflict resolution unions both sides' histories. *Rationale: review is a
789
- decision log, not a flag — "who rejected this and why" must be answerable
790
- months later. Approved 2026-09-28.*
791
- - **D30** — Retrieval ranks by review state: approved/published project
792
- memories outrank unreviewed content; project drafts/rejected sink to the
793
- bottom and are visibly tagged `[draft]` in search/list/inject output, while
794
- personal memories (always draft by design) are never demoted or tagged.
795
- Explicit search still finds drafts — they are deprioritized, not hidden.
796
- *Rationale: reviewed knowledge should win the context window; drafts stay
797
- discoverable but never masquerade as vetted. Approved 2026-09-28.*
798
- - **D31** — Every index sync records when it ran, what triggered it
799
- (`session` / `request` / `cli` / `submit`) and its stats, in
800
- `<appdata>/sync-state.json`; `sync-status` shows the last sync first.
801
- *Rationale: "is my index fresh?" must be answerable without guessing —
802
- especially across branch switches where the in-repo dir changes underneath.
803
- Approved 2026-09-28.*
804
- - **D32** — The branch PR's GitHub state maps back onto each in-repo
805
- memory's review_state via `pr-status` / `memory_pr_status`: merged PR →
806
- published, PR approval → approved with `approved_by` = reviewer login,
807
- changes-requested → suggestion only (never auto-rejects). Report by
808
- default; `--apply` performs the mapped transitions locally (no push —
809
- inside the D27 line). Each memory keeps its own state: a human `rejected`
810
- is never overridden by a PR signal. *Rationale: the PR is where the team
811
- actually reviews — the mapping closes the loop without inventing new
812
- review UI. Approved 2026-09-28.*
813
- - **D34** — The MCP server sends session-start guidance in the handshake
814
- `instructions`: call `memory_status` at session start (and at work
815
- checkpoints); if the outbox has drafts, summarize and ask the user which to
816
- sync; proactive `memory_add`; `memory_search` before asking about the past;
817
- personal never leaves the machine. *Rationale: the init-written instruction
818
- files only exist if the user ran `init --client` — the handshake reaches
819
- every MCP client at connect time. Still advisory: no MCP consumer offers a
820
- hard session-start hook, and we do not claim otherwise. Approved 2026-09-28.*
821
- - **D35** — "sync memory" (or "同步记忆") is a natural-language trigger for the
822
- sync flow: the agent calls `memory_status`, summarizes the outbox drafts, and
823
- asks the user which ones to sync — same flow as the session-start proposal,
824
- but user-initiated. Taught in the MCP handshake instructions, the
825
- init-written instruction files, and the `memory_status` tool description.
826
- *Rationale: the user should not have to remember command names to sync;
827
- saying it in words must work. Approved 2026-09-28.*
828
- - **D36** — `submit` never creates a branch on its own (revises D26/D27): it
829
- copies the named drafts into `.ai/open-memex/`, commits locally on the
830
- CURRENT branch, and prints next-step commands. Branch creation is the human's
831
- call — or the agent's, only with explicit approval for the full chain, via
832
- `submit --branch <name>` / `memory_submit(branch=...)`. *Rationale: an
833
- auto-created branch strands the user on it — they forget to switch back.
834
- After a submit the agent asks ONE follow-up ("want me to create a branch +
835
- push + open the PR, or will you handle it yourself?") instead of branching
836
- silently. Checkpoints that trigger `memory_status`: session start, end of a
837
- work chunk, after the user commits, and after any memory_* action.
838
- The "sync memory" trigger ALWAYS goes through the `memory_status` tool —
839
- never by browsing the appdata directory directly. Approved 2026-09-28.*
840
- - **D33** — Every CLI command answers `open-memex <command> --help` (and `-h`)
841
- with its own usage, flags, and examples; checked before config/DB load so
842
- help works even in a broken environment. Unknown commands with `--help`
843
- fall back to the global usage. *Rationale: AI assistants discover the CLI
844
- through --help first — a command that silently swallows --help as a flag
845
- teaches the agent nothing. Approved 2026-09-28.*
846
- - **D37** — Conversation distillation is the memory unit; transcript storage is
847
- not the default. Capture should preserve the useful conclusion from a human/AI
848
- session — what was learned, what resolved the issue, what should be avoided,
849
- and where the authoritative doc lives — as a short reviewable memory. If the
850
- knowledge already exists in docs, store a `reference` memory with
851
- `canonical_ref` instead of duplicating the doc. Tags are retrieval hints, not
852
- content kinds: `type` classifies the memory, tags describe topics/tools/paths.
853
- *Rationale: full chat logs are noisy, harder to review, and riskier for
854
- privacy; the value is remembering the right conclusion at the right scope,
855
- with enough context for the next human or AI session. Approved 2026-09-28.*
856
- - **D38** — OpenMemex supports a Markdown second-brain use case while keeping
857
- distillation as the default for implicit/model-suggested capture. If the user
858
- explicitly asks to save a long note, meeting summary, troubleshooting record,
859
- or write-up, preserve it as user-authored Markdown with tags and normal
860
- scope/privacy rules. Git/GitHub sync is the default team-sharing provider, not
861
- the product boundary: future export/import archives and API-backed providers
862
- may move the same markdown memories to other computers, applications, or
863
- enterprise systems. For generic "save/remember/note this" requests, the agent
864
- routes project-specific knowledge to `project`, personal or repo-unrelated
865
- knowledge to `personal`, and asks one clarification if ambiguous; `org` remains
866
- curated/future, never a direct single-user chat write. *Rationale: users also
867
- want a local AI-assisted second brain, but portability and ownership must stay
868
- explicit; sharing mechanisms should be provider choices over the same memory
869
- model, not the identity of the product. Approved 2026-09-28.*
870
- - **D39** — `type` and `tags` are complementary axes, not alternatives. `type` is
871
- single-valued: what the memory IS — it drives behavior (lifecycle, review,
872
- rendering, retrieval: a `todo` can be completed, a `reference` resolves
873
- `canonical_ref`, a `decision` participates in supersede chains). `tags` are
874
- multi-valued: what the memory is ABOUT — pure retrieval hints
875
- (topics, tools, subsystems, paths, incidents). *Rationale: without type the
876
- system cannot tell "a todo I must do" from "a fact I must know" even when both
877
- are tagged `auth`; without tags, cross-cutting retrieval ("everything about
878
- onboarding") would need a combinatorial type explosion. Type answers "how do I
879
- handle this?", tags answer "how do I find this?". Approved 2026-09-28.*
880
- - **D40** — `open-memex export` excludes `visibility: private` memories by
881
- default; `--all` / `-a` includes everything, for a full personal migration to
882
- a new machine. *Rationale: the safe default protects privacy; the escape hatch
883
- keeps the "no walled garden" promise — the user can always take everything
884
- with them. Approved 2026-09-28.*
885
- - **D42** — §3.5 checkpoint distillation is taught in the MCP handshake
886
- instructions (`src/mcp.ts` `SERVER_INSTRUCTIONS`) and the `init`-written
887
- instruction files (`src/init.ts` `INSTRUCTIONS`): at checkpoints the agent
888
- DISTILLs the session and proposes 1–3 short memories (conclusion, not
889
- transcript); nothing is saved without user approval. Approved captures are
890
- saved via `memory_add` with the new optional `source` param set to
891
- `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
892
- the design's capture loop now reaches the agent. Implemented 2026-09-29.*
893
- - **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
894
- footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
895
- at checkpoints; save nothing without approval; prefer `reference` over
896
- copying). *Rationale: double insurance for opencode users, who never see the
897
- MCP handshake instructions or the `init`-written instruction files — but
898
- opencode reads AGENTS.md natively, so the distilled snippet teaches the
899
- checkpoint habit wherever it lands. Approved 2026-09-29.*
900
- - **D44** — `migrate --to-v2` hotfix (issue #7, 0.4.1): (1) `--dry-run` now
901
- previews the legacy `my-o-memory` files in place — per-file conversion plans
902
- without moving anything (previously it scanned only the new, still-empty
903
- root and always reported "0 files", making the preview useless); (2) dry-run
904
- no longer prints the false "legacy data dir merged" line; (3) the Windows
905
- EPERM on the legacy-dir backup rename is caught and rethrown as an actionable
906
- message (close the program holding the folder — e.g. a running MCP server —
907
- and re-run; nothing was deleted), and the CLI prints it as `Error: …` with
908
- exit 1 instead of a raw syscall stack; (4) `parseFlags` accepts `--key=value`
909
- in addition to `--key value` (the `=` form was silently misparsed before,
910
- dropping the flag — which can turn a `--dry-run` into a real run).
911
- *Rationale: a preview that shows nothing is worse than no preview — the user
912
- cannot confirm what the real run will do; and a destructive-path failure must
913
- speak in user terms. Shipped as 0.4.1 hotfix on the stable line. Approved
914
- 2026-09-29.*
915
- - **D45** — `init --global` (0.5.0-alpha.1): one-time user-level MCP wiring for
916
- VS Code / Cursor. Writes the open-memex server entry to the editor's
917
- user-level `mcp.json` (`%APPDATA%\Code\User\mcp.json` on Windows,
918
- `~/Library/Application Support/Code/User/mcp.json` on macOS,
919
- `~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
920
- instead of the project's `.vscode/mcp.json` — init once, the server starts
921
- in every project. The entry keeps `cwd: "${workspaceFolder}"` so VS Code
922
- substitutes it per window and project-scope resolution keeps working;
923
- a per-project config still wins when present. Merge semantics are shared
924
- with project-level init (merge, never clobber; `--force` overwrites).
925
- Interactive `init` now asks per-project vs user-level for vscode/cursor
926
- (default: per-project, preserving old behavior); `--global` skips the
927
- question. For opencode, `--global` is a no-op that prints the native-plugin
928
- one-liner (already global, and strictly more capable than plain-MCP mode);
929
- Visual Studio stays solution-level by design. *Rationale: per-project init
930
- is a paper cut that compounds — the data layer already needs zero per-project
931
- setup (scope is derived from cwd), so the editor wiring should be able to
932
- match. Approved 2026-09-29.*
933
- - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
934
- (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
935
- `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,
936
- `workflow`→`howto`, `incident`→`lesson` (incident id goes in `tags`),
937
- `architecture`→`knowledge` (tag `architecture`). *Rationale: a type earns its
938
- place only if the system treats it differently (lifecycle, retrieval,
939
- rendering); otherwise it is a tag. Fifteen types blur classification and hurt
940
- agent accuracy — eleven keeps each type's behavioral slot distinct. `lesson`
941
- is deliberately broader than `incident`: a postmortem's shape (timeline, root
942
- cause, actions) is a template concern, not a type. Code
943
- `MEMORY_TYPE_TAXONOMY` updated to match. Approved 2026-09-28.*
944
- - **D46** — `init` with no `--client` auto-detects installed editors and wires
945
- them all (0.5.0-alpha.2). Detection: VS Code via `code` on `PATH`, well-known
946
- install locations, or an existing user-level `mcp.json`; Cursor via `cursor`
947
- on `PATH` or `~/.cursor`; opencode via `opencode` on `PATH` or its global
948
- config dir; Visual Studio only when the project has a `.sln` (solution-scoped
949
- by design). Auto mode always wires user-level where the editor supports it —
950
- VS Code / Cursor MCP entry (D45), and for opencode the native plugin entry is
951
- now *actually merged* into `~/.config/opencode/opencode.json` (replacing D45's
952
- hint-only `--global`), so one init covers every editor and every project.
953
- A config file with comments (JSONC) is never rewritten — init prints the
954
- manual one-liner instead. Interactive `init` shows the detected editors and
955
- confirms wiring all of them (declining falls back to the single-editor
956
- prompt); non-interactive (`--yes`) wires all detected with no prompts.
957
- An explicit `--client` keeps the old single-editor behavior, including the
958
- per-project default for vscode/cursor. *Rationale: Stone's two hats — he
959
- writes code in several editors himself, and new users / pilot colleagues
960
- should not have to learn `--client` to get started. The help text already
961
- promised "default: auto-detect"; D46 makes the code keep that promise.
962
- Approved 2026-09-29.*
963
- - **D47** — when `init` refuses to touch a config file that isn't valid JSON
964
- (usually JSONC with comments — VS Code / Cursor / opencode all accept them),
965
- it now prints the exact snippet to add by hand: the section key plus the
966
- `"open-memex"` entry, pretty-printed. Covers all three MCP-writing paths —
967
- vscode/cursor (user + project level), opencode project-level `opencode.jsonc`,
968
- and Visual Studio `.mcp.json` — matching the manual hint the opencode
969
- `--global` plugin path already printed (D46). The file is still never
970
- rewritten; the hint just makes "fix it manually" actionable. Triggered by
971
- Stone's real Windows run: his user-level `mcp.json` had comments, init
972
- correctly left it alone, but the old message gave him nothing to paste.
973
- *Rationale: a refusal without a remedy is a dead end; the entry shape is
974
- already computed, so printing it costs nothing. Approved 2026-09-29.*
975
- - **D48** — new `open-memex uninstall` command, the reverse of `init`
976
- (0.5.0-alpha.4). Removes the MCP server entry / opencode native plugin line /
977
- Copilot instructions section that `init` wrote; memory data is never touched.
978
- Client resolution mirrors `init` (explicit `--client`, else auto-detect with
979
- an interactive confirm). Without `--global` it cleans both project-level and
980
- user-level files — init may have written either, and a leftover entry at the
981
- other level would be a surprise; `--global` restricts to user-level. Empty
982
- sections/arrays are pruned; an instructions file that only held the
983
- open-memex section is deleted. Non-JSON (JSONC) configs are left untouched
984
- with the manual step, same D47 treatment as the init write path.
985
- *Rationale: Stone asked "有 uninstall 吗" while testing init on Windows —
986
- every write deserves an undo. Approved 2026-09-29.*
987
- - **D49** — empty config files are no longer treated as corrupt (0.5.0-alpha.5).
988
- Stone's real Windows run: his user-level `mcp.json` existed but was empty,
989
- and `init` refused it with "not valid JSON — left untouched", because
990
- `JSON.parse("")` throws. New `parseJsonConfig` helper: empty or
991
- whitespace-only content parses as `{}` — there is nothing to preserve, so
992
- writers safely populate it; genuinely unparseable content (JSONC comments)
993
- or non-objects still return null and keep the D47 leave-untouched + manual
994
- hint behavior. Applied to all five config file touch points: the three init
995
- writers (vscode/cursor MCP, opencode `opencode.jsonc`, Visual Studio
996
- `.mcp.json`) and the two uninstall removers (empty file = nothing to remove).
997
- *Rationale: an empty file is the safest write target, not a corrupt file;
998
- refusing it sent the user down a manual path for no reason. Triggered by
999
- Stone's report 2026-09-29.*
1000
- - **D50** — close the install→init gap (0.6.0-alpha.1). `npm install -g`
1001
- only puts the CLI on PATH; the editor wiring is `init`'s job, and a clean
1002
- reinstall wipes it — Stone hit exactly this on 2026-09-30 (fresh opencode
1003
- reinstall + `npm i -g open-memex`, then no open-memex in `opencode.jsonc`).
1004
- Two changes, both CI-safe: (1) a `postinstall` script that **prints**
1005
- `Run \`open-memex init\`…` — postinstall must never prompt, it runs in CI /
1006
- Docker / `npm ci` where stdin isn't a terminal; (2) bare `open-memex` on a
1007
- machine where init never completed **offers** to run it (default yes) when
1008
- stdin+stdout are TTYs, otherwise prints usage exactly as before. Asked-state
1009
- is a `.init.json` marker at the data root — init writes it on success, a
1010
- declined offer writes it too, so the question is asked once; `uninstall`
1011
- removes it (unwiring is the reverse of init, so the next bare run offers to
1012
- wire again). The marker is a dotfile and export builds from DB rows, so it
1013
- can't leak into bundles. The offer re-execs `open-memex init` as a child
1014
- with inherited stdio rather than calling init in-process — the offer's own
1015
- readline already consumed stdin's buffer, and a second readline on the same
1016
- stream would see EOF on burst input (verified with a pty test).
1017
- *Rationale: install ≠ setup, and the gap only shows up on a fresh machine —
1018
- exactly when the user has the least context. A printed hint covers the
1019
- install moment; the interactive offer covers the first-run moment; neither
1020
- can hang a pipeline. Approved 2026-09-30.*
1021
- - **D51** — close the init→first-use gap (0.6.0-alpha.2). D50 gets the user to
1022
- a wired editor; a first-time user then stops at "it's wired" with no idea
1023
- what to do next. `init` now ends with one concrete next step:
1024
- ``Next step: `open-memex add "standup is at 9:30"` — then ask your agent what
1025
- it remembers.`` One line, printed unconditionally — the cheapest possible
1026
- onboarding after wiring. *Rationale: the CLI is editor-independent, so the
1027
- hint works no matter which client was wired; `add` + recall is the smallest
1028
- loop that proves the whole system works. Approved 2026-09-30.*
1029
-
1030
- - **D52** — agent-prompt clarity rewrite (0.6.0-alpha.3). Both agent-facing
1031
- prompts (MCP `initialize` instructions in `src/mcp.ts`, init instruction
1032
- template in `src/init.ts`) are rewritten to fix ambiguities found on review:
1033
- (1) the proactive-save vs approval-gate contradiction is resolved by naming
1034
- the two cases — facts the user *states* are saved proactively, conclusions
1035
- the agent *infers* are proposed first and saved only on approval;
1036
- (2) `memory_status`/`memory_search` are excluded from the "after any
1037
- memory_* action" checkpoint trigger (self-trigger loop);
1038
- (3) tool names use the full `memory_*` form in both prompts;
1039
- (4) the four checkpoints are defined once as "Checkpoints" and referenced,
1040
- with an operational heuristic ("a task the user would describe in one
1041
- sentence") replacing "meaningful chunk of work";
1042
- (5) empty outbox → do nothing; "the user commits" → "any git commit in this
1043
- session"; `type "reference"` named explicitly; PR-base mechanics spelled out
1044
- per D28. *Rationale: these prompts are the product's UI for agents — a
1045
- literal-minded agent must execute them correctly without guessing.
1046
- Approved 2026-10-01.*
1047
-
1048
- - **D53** — push-not-poll outbox: the checkpoint mechanism is retired; code
1049
- pushes state to the agent instead (0.6.0-alpha.4). `src/submit.ts` gains
1050
- `outboxDraftCount()` (one indexed SQLite COUNT on the current scope's outbox,
1051
- no git I/O); `src/tools/ops.ts` gains `withOutboxNote()`, which appends
1052
- `[open-memex: N draft(s) waiting in the project outbox — call memory_status
1053
- to review]` to mutating tool results, only when N > 0. It is wired into the
1054
- five MCP mutating tools (`memory_add`, `memory_supersede`, `memory_forget`,
1055
- `memory_submit`, `memory_propose`) and the three opencode-plugin mutating
1056
- tools (`memory_add`, `memory_supersede`, `memory_forget` — there the note
1057
- stays generic because the plugin has no `memory_status`). The MCP server
1058
- also appends the live draft count to the `initialize` instructions when N >
1059
- 0 (stdio servers start fresh per session, so construction-time state is
1060
- session-start state). Both agent-facing prompts drop the Checkpoints section
1061
- and the post-`memory_submit`/`memory_propose` status checks; the sync rule
1062
- becomes one line ("when the server reports drafts waiting, call
1063
- `memory_status`") plus the existing "sync memory" trigger. The static init
1064
- template keeps one explicit session-start `memory_status` call, since a
1065
- static file cannot carry live state. An anti-nag clause is added: if the
1066
- agent already asked about these drafts this session, it does not ask again.
1067
- *Rationale: the server knows the outbox state; making the agent poll for it
1068
- on a timer wastes tool calls and teaches a habit that scales badly. The note
1069
- is silent when the outbox is empty, so the common case costs nothing.
1070
- `memory_submit` drains the outbox, so its own note is naturally silent.
1071
- Approved 2026-10-01.*
1072
-
1073
- - **F28** — install→init reminder was invisible (0.6.0-alpha.5). The D50
1074
- postinstall pointer never reaches the user: npm runs lifecycle scripts in
1075
- the background and swallows their stdout unless `--foreground-scripts` is
1076
- passed (reproduced on npm 10.9.4 — the script ran with code 0, its output
1077
- never displayed). The install-time channel is therefore best-effort only.
1078
- Fix: every CLI entry point now prints a one-line nudge on stderr until init
1079
- has run or been declined (`open-memex init` wires editors), gated by the
1080
- existing `.init.json` first-run marker — stderr keeps the MCP stdio protocol
1081
- (stdout) intact, so even `open-memex mcp` spawned by an editor carries it
1082
- safely. `init`/`uninstall` are excluded. The bare-`open-memex` interactive
1083
- offer on a TTY (D50) is unchanged. *Rationale: the reminder must live in a
1084
- channel the project controls — the CLI — not in npm script output.
1085
- Reported 2026-10-01.*
1086
-
1087
- - **F29** — Copilot review fixes on PR #11 (0.6.0-alpha.7). (a) The lockfile
1088
- carried a stray `"version": "0.6.0-alpha.1"` key as a direct child of
1089
- `packages` (left by the D50 version bump; hand-edited bumps preserved it) —
1090
- `npm ls --package-lock-only` failed on it. Removed; version bumps now go
1091
- through `npm pkg set` so npm owns the lockfile format. (b) D53 missed the
1092
- shared `TOOL_DESCRIPTIONS.memory_status`: it still told agents to call the
1093
- tool "at session start and at task checkpoints" — the polling this change
1094
- retires. Now: session start, server-reported drafts, or explicit "sync
1095
- memory". Same staleness removed from the `source` field hint. (c) Onboarding
1096
- strings (postinstall note, first-run nudge, bare-CLI offer) now mention
1097
- Visual Studio auto-detection for solution projects instead of listing only
1098
- three editors. *Lesson: never hand-edit version fields in package-lock.json.
1099
- Reported 2026-10-01.*
1100
-
1101
- - **D54** — Agent Skills support (0.6.0-alpha.8). Ship a bundled
1102
- `open-memex` skill (`skills/open-memex/SKILL.md`: frontmatter + CLI guide —
1103
- proactive save, search, scope routing, outbox→submit flow) inside the npm
1104
- package. `init` copies it (not symlinks — Windows needs no Developer Mode)
1105
- into each wired editor's user-level skills dir: VS Code →
1106
- `~/.copilot/skills/open-memex/`, Cursor → `~/.cursor/skills/open-memex/`,
1107
- opencode → `~/.config/opencode/skills/open-memex/`; Visual Studio has no
1108
- skills concept and is skipped. User-level by design (D46: init once). An
1109
- existing skill is never clobbered silently — kept unless `--force`.
1110
- `uninstall` removes only the `open-memex` skill directory. The skill tells
1111
- agents to prefer MCP tools (`memory_add` etc.) when available and fall back
1112
- to the CLI otherwise (with the `npx -y open-memex@latest` prefix when the
1113
- CLI isn't on PATH). *Rationale: skill-aware agents get memory with zero MCP
1114
- configuration; the skill is the CLI-shaped complement to the MCP server.
1115
- Requested by Stone 2026-10-01 after the Agent Skills ecosystem suggestion.*
1116
-
1117
- - **F30** — Sweep pre-rename `my-o-memory` leftovers (0.6.0-alpha.9). The
1118
- my-o-memory → open-memex rename left editor configs behind that still load
1119
- the OLD plugin/server, which writes to the OLD data dir — silently splitting
1120
- the user's memories in two (found live on Stone's work machine 2026-10-01:
1121
- the old opencode plugin sat above the new one in `opencode.json`, so
1122
- opencode and the CLI wrote to different data roots). `init` now drops stale
1123
- `my-o-memory` plugin entries and `my-o-memory` MCP server keys wherever it
1124
- touches a config (opencode global plugin list, per-project `opencode.jsonc`,
1125
- `.mcp.json`, VS Code/Cursor `mcp.json` incl. `--global`), even on the
1126
- "kept" path; JSONC files it can't parse get a manual-removal hint.
1127
- `uninstall` sweeps the same leftovers. `doctor` gains a read-only
1128
- `legacy my-o-memory` check: fails when a legacy data dir exists next to the
1129
- data root, when a user-level config still references `my-o-memory`, or when
1130
- `MY_O_MEMORY_HOME` points at a pre-rename dir. *Lesson: a package rename
1131
- must clean up its own old wiring — the old entry and the new entry are never
1132
- both valid. Reported 2026-10-01.*
1133
-
1134
- - **D55** — opencode's native plugin supersedes the Agent Skill
1135
- (0.6.0-alpha.10). Real-world feedback (Stone 2026-10-01): with both the
1136
- native plugin's `memory_*` tools and the D54 skill installed, opencode's
1137
- agent turned chatty — two overlapping instruction sets plus a "use MCP or
1138
- CLI?" choice on every memory action. No data corruption (identical saves
1139
- dedupe), but the UX regressed from "one tool call and done" to narration.
1140
- `init` no longer installs the skill for opencode when the native plugin is
1141
- wired (`--global`), and removes a previously installed one; the per-project
1142
- plain-MCP mode keeps the skill as the no-tools fallback. VS Code/Cursor
1143
- keep the skill — their MCP wiring is more fragile (server-start failures,
1144
- policy blocks), so the fallback still earns its keep, and the skill already
1145
- tells agents to prefer MCP tools when available. *Lesson: don't ship two
1146
- overlapping integrations for the same editor — the agent pays the
1147
- duplication cost in chatter. Reported 2026-10-01.*
1148
- - **D56** — question-shaped searches and host parity, said out loud
1149
- (0.6.1-alpha.1). Two-persona review (Stone 2026-10-03) converged on small,
1150
- honest fixes rather than new machinery. (1) Retrieval already OR-ed terms
1151
- and ranked with bm25, but fed whole questions ("how do we configure…",
1152
- "中文记忆怎么检索") straight into FTS — question words matched everything
1153
- and diluted ranking. Query construction now filters a small EN/CJK
1154
- function-word set, dedupes, and caps terms at 24 per side, with a
1155
- never-empty fallback (query.ts; partially answers the retrieval-robustness
1156
- open question — layers 2 agent-side expansion / 3 capture-time aliasing
1157
- remain open, embeddings stay reserved). (2) The plugin(5)/MCP(11) tool
1158
- asymmetry is now stated in the six MCP-only tool descriptions themselves,
1159
- with the CLI equivalent named, so an agent looking for `memory_status`
1160
- inside opencode finds the answer instead of assuming breakage (the
1161
- host-parity open question's "document it" option; true parity undecided).
1162
- (3) `init`'s closing lines gain a one-line privacy statement at the moment
1163
- of maximum doubt: memories live only on this machine, personal ones never
1164
- leave it, nothing is uploaded.
1165
-
1166
- - **D57** — explainable search, a memory audit, and the concurrency posture
1167
- written down (0.6.1-alpha.2; addresses most of the retrieval-explainability
1168
- / memory-health open question and establishes the concurrent-sessions
1169
- behavior it asked for). (1) `open-memex search --explain` prints the
1170
- constructed FTS expression, per-hit bm25 score, and how many matches
1171
- lifecycle hid (superseded vs retracted/archived), so a miss is diagnosable
1172
- — bad query, stale memory, or chain-hidden — without reading the index.
1173
- (2) New `open-memex audit` (read-only; doctor checks the environment, this
1174
- checks the memories): near-duplicate active pairs (same ≥ 0.8 Jaccard as
1175
- write-time dedup), actives untouched for 90+ days, broken supersede chains,
1176
- personal files found inside the in-repo memory dir (iron-rule breach), and
1177
- index/file drift. Reports only; fixes stay with `supersede` / `forget` by
1178
- hand. (3) Concurrency, measured: every process opens its own connection to
1179
- one WAL index; memory files are per-memory ULIDs, so concurrent writes to
1180
- *different* memories never collide on disk. SQLite was the gap — no
1181
- `busy_timeout` was set, so better-sqlite3 silently tolerated 5s while
1182
- bun:sqlite (opencode plugin) timed out at 0 and failed instantly under any
1183
- overlapping write. Now unified at `PRAGMA busy_timeout = 5000` in `db()`.
1184
- Past the timeout the CLI prints one plain line ("store is busy … nothing
1185
- was lost") instead of a stack trace — and nothing *is* lost: the memory
1186
- file is written before the index update, so the next sync reconciles it
1187
- (verified end-to-end: a write blocked 8s still lands once the lock frees).
1188
- Memory file writes are tmp+rename, so a concurrent reader never sees a
1189
- torn file. Same-memory concurrent edits remain last-writer-wins (accepted:
1190
- different processes editing the same memory simultaneously is a human
1191
- conflict, not a storage one). `doctor` reports the live locking settings.
1192
-
1193
- - **D58** — the opencode plugin must never runtime-import the host SDK
1194
- (0.6.1-alpha.3). Field report: after a global `npm i -g open-memex`, the
1195
- plugin was configured in `~/.config/opencode/opencode.jsonc` but silently
1196
- inactive — no memory tools, no error, nothing in opencode's log. Bisected
1197
- with the real host (opencode 1.18.34) and a minimal plugin: a bare
1198
- `file://` entry loads fine; adding `import { tool } from
1199
- "@opencode-ai/plugin/tool"` makes opencode skip the plugin without a
1200
- trace. That import only ever resolved from a source checkout (where
1201
- `npm install` provides the devDependency); from a global install's
1202
- location nothing provides the module and the host does not resolve it
1203
- for file:// plugins. The helper is a runtime identity (`return input`),
1204
- so the fix is a local same-signature stand-in in `tools/memory.ts` —
1205
- types still come from the SDK (type-only imports erase at runtime), and
1206
- the plugin now depends only on real runtime dependencies. Verified in
1207
- the real host against a global-install-shaped tree: all five tools
1208
- register. Rule going forward: plugin code imports host SDK types only;
1209
- runtime imports must resolve from the package's own dependencies.
1210
-
1211
- - **D59** — `doctor` patrols the plugin entry it used to take on faith
1212
- (0.6.2-alpha.1). D58's failure was invisible to every existing check:
1213
- `doctor` verified the MCP server end-to-end but never looked at the
1214
- opencode plugin entry, so a configured-but-dead plugin passed all
1215
- checks. The new `opencode plugin` check reads the user-level opencode
1216
- configs (`opencode.json` + `opencode.jsonc`), attributes entries to
1217
- this plugin by package path or the `[open-memex]` marker (source
1218
- checkouts live anywhere), and fails when (a) the entry's target file
1219
- does not exist — with the `init --force` re-point command named — or
1220
- (b) the entry's relative-import closure runtime-imports
1221
- `@opencode-ai/plugin`, the exact D58 death. It checks only what can be
1222
- attributed; per-project and MCP wiring are out of scope.
1223
-
1224
- - **D60** — one plugin serves both opencode generations (0.7.0-alpha.1).
1225
- Opencode 2 changes the plugin contract end to end: config reads
1226
- `plugins` (directories or `{package}` objects) instead of v1's
1227
- `plugin` file entries, a v1-style file entry only earns a log warning
1228
- ("configured plugin path must be a directory") and is silently skipped
1229
- — the D58 death in a new shape; and the plugin value itself is a
1230
- structurally decoded `{ id, setup(ctx) }` rather than the v1 server
1231
- factory. A single `open-memex init --client opencode --global` now
1232
- writes both keys (`plugin` file URL and `plugins` directory): each
1233
- host loads from its own key — verified: opencode 1.18.34 ignores the
1234
- `plugins` array with a config-normalization warning, and opencode 2
1235
- warns per `plugin` file entry but loads the directory entry — so users on either generation get a
1236
- working plugin from the same install. `src/index.ts` default-exports
1237
- `{ id, setup, server }`: v2 calls `setup`, v1 calls `server`, the
1238
- shared logic (bootstrap, keyword capture, one-time injection) lives in
1239
- `src/plugin-core.ts`. Cost of the bridge on the v1 side: v1 hosts
1240
- older than 1.18.29 only invoke function default exports and would
1241
- skip this object; 1.18.29+ accepts it — the README states the new
1242
- minimum. The v2 adapter (src/opencode-v2.ts) obeys D58's rule — no
1243
- runtime `@opencode/plugin` import (a devDependency again); the
1244
- context is duck-typed from the 2.0 surface, tool arg shapes compile
1245
- from the same zod shapes via `z.toJSONSchema`, and hooks map
1246
- one-to-one (session `prompt` → keyword capture, session `context` →
1247
- first-turn injection). One registration subtlety cost real debugging
1248
- time and is worth recording: on 2.0.1 a plugin tool added without
1249
- options is exposed to the model only in code mode — callable through
1250
- an `execute` meta-tool that runs model-written JS
1251
- (`tools.memory_search(...)`) — and a model that instead calls the
1252
- tool by name gets a host-side "Unknown tool" error, so whether the
1253
- memory tools work at all depends on the model's calling style. Each
1254
- tool therefore registers with `options: { codemode: false }`, which
1255
- restores plain function calling (verified: direct calls execute
1256
- first try). The D59 doctor check extends to both keys:
1257
- v2 entries are checked for an existing, resolvable entry file and the
1258
- closure scan now covers `@opencode/plugin` too, plus a generation
1259
- advisory — when the installed host and the config point at different
1260
- generations, doctor fails and names the fix (`init --force`; package-
1261
- name entries installed via `opencode plugin add` are recorded but not
1262
- path-checked). Field-verified on real hosts 1.18.34 and 2.0.1.
1263
-
1264
- - **D61 — proactive capture cluster: propose posture, a shared
1265
- memorability rubric, and capture-time aliasing (retrieval layer 3).**
1266
- Builds on the "proactive capture" open question below and the
1267
- CHECKPOINT_PROACTIVITY / MEMORY_VISIBILITY notes. Three pieces,
1268
- shipped together because they are one user-visible behavior — the
1269
- agent capturing well without being asked each time:
1270
- (1) **Posture: propose, not auto-draft.** When the agent finishes a
1271
- task the user would describe in one sentence, it proposes 1–3 short
1272
- candidate memories in the conversation and saves only what the user
1273
- approves (approved inferences are saved with `source: "inference"`,
1274
- the §3.5 convention). The guidance is text, not mechanism — the same
1275
- rubric written into the bundled skill, the AGENTS.md memory-hygiene
1276
- footer, the MCP handshake instructions, the `memory_add` tool
1277
- description, and a one-line summary in the injected context block —
1278
- with throttling rules (task end / decision / gotcha moments only, no
1279
- mid-task interruptions, never re-propose a declined candidate). The
1280
- auto-draft posture (write first, surface later in bulk) is deferred
1281
- until memory visibility ships: without an inventory the user can
1282
- read, silent drafting reads as surveillance, so D61 deliberately
1283
- does not build it.
1284
- (2) **Rubric.** One memorability standard, shared by this live
1285
- capture path and the future retrospective-distillation group:
1286
- worth saving — decisions and their reasons, preferences,
1287
- conventions, gotchas, approaches tried and abandoned, and
1288
- `reference` memories pointing at authoritative docs; not worth
1289
- saving — one-off task details and anything re-derivable from the
1290
- code. Retrieval robustness layer 2 (agent-side query expansion:
1291
- decompose into concepts, 2–3 phrasings each, cross-language, check
1292
- the other scope) ships as guidance in the same texts, on top of the
1293
- D56 server-side layer 1.
1294
- (3) **Capture-time aliases (layer 3).** When a memory is saved, the
1295
- agent attaches up to 4 aliases — alternate phrasings, synonyms,
1296
- equivalents in the user's other language — stored in a new optional
1297
- frontmatter field `aliases` (additive; files without it parse
1298
- unchanged, `schema_version` stays 2) and indexed in their own FTS
1299
- column (index schema 6→7, rebuilt from markdown automatically).
1300
- Gated by a new `captureAliases` config flag (init asks once, default
1301
- on, `config set captureAliases off` opts out): when off, aliases
1302
- passed by agents are dropped and the alias guidance disappears from
1303
- the MCP handshake. Turning it off never rewrites existing memory
1304
- files — aliases already stored stay stored and searchable, and
1305
- supersede keeps carrying them forward; the flag gates new captures
1306
- only (no silent data destruction). Aliases pass through the same
1307
- secret redaction as memory content before they are stored, and a
1308
- malformed alias list (blanks, more than 4) is normalized silently —
1309
- never a tool-call error.
1310
- Keyword capture (no agent in the loop) leaves
1311
- aliases empty rather than inventing them; `supersede` carries
1312
- aliases forward unless the caller replaces them. Aliases are
1313
- normalized (trim, case-insensitive dedupe, cap 4) and bad ones cost
1314
- nothing — they rank as bm25 noise, never an error. Retrospective
1315
- distillation over host transcripts stays its own group; it will
1316
- reuse this rubric.
1317
-
1318
- - **D62 — environment variable names grow current-name aliases.** The
1319
- data-root and config-path overrides predate the rename and kept the
1320
- old package's name (`MY_O_MEMORY_HOME`, `MY_O_MEMORY_CONFIG`) — a
1321
- stale-looking name is a trap for users and agents scripting against
1322
- the current one. `OPEN_MEMEX_HOME` / `OPEN_MEMEX_CONFIG` are now the
1323
- preferred names; the legacy names still work as fallbacks (new name
1324
- wins when both are set), so existing setups and scripts never break.
1325
- The data root itself does not move — only the variable names change.
1326
- `doctor`'s storage check notes when the root arrived via the legacy
1327
- variable, and its pre-rename-dir leftovers check reads whichever
1328
- variable is in effect.
1329
-
1330
- - **D63 — correctness fixes from a whole-project external review.** Six
1331
- verified silent-wrong-answer bugs, fixed as one batch: (1) VS init
1332
- dropped the parsed `.mcp.json` instead of merging it, wiping other
1333
- servers; (2) forget reported success when unlink failed — only ENOENT
1334
- is success now, both in the tool op and the CLI; (3) the config
1335
- loader's regex comment-stripper was not string-aware and corrupted
1336
- redact patterns (`src/**/secrets` → `srcsecrets`) — replaced with a
1337
- string-aware scanner now shared with doctor (one parser, not two);
1338
- (4) `loadConfig` enforces the `memoryDir` no-escape invariant on
1339
- hand-edited files, falling back to the default with a warning;
1340
- (5) `migrate` rewrites `scope`/`visibility` with the key, and
1341
- conflict resolution compares parsed timestamps (lexicographic
1342
- RFC-3339 order breaks at fractional seconds); (6) bundle import
1343
- enforces staging-dir containment (resolve + realpath), rejecting
1344
- `../` and symlink escapes. Rule going forward: any behavior that can
1345
- fail must fail loudly in its return value; "already gone" is the only
1346
- swallowed delete error.
1347
-
1348
- - **D64 — second batch from the same review: stale answers, stranded
1349
- files, and holes between surfaces.** (1) The opencode plugin hosts
1350
- synced the index only at bootstrap, so memories written by the CLI or
1351
- another client stayed invisible all session (and exact duplicates
1352
- accumulated); plugin tool calls now reconcile from disk first,
1353
- mirroring the MCP server's per-call sync. (2) Superseding a published
1354
- memory reset `review_state` to `draft` in the repo, where submit
1355
- could not reach it and promote refuses drafts — the replacement now
1356
- re-enters at `proposed` whenever the old memory had entered review.
1357
- (3) Every memory-file rewrite now goes through the atomic
1358
- tmp+rename helper (D57 covered creates only); a torn read mid-rewrite
1359
- previously parsed as a deletion. (4) `setStatus` refuses
1360
- `retracted → active`: retraction is one-way through this path, or
1361
- withdrawn content silently returns to recall. (5) Propose copies get
1362
- `visibility: internal` instead of inheriting `private`, which export
1363
- excludes by default — the team copy no longer vanishes from bundles.
1364
- (6) `opencodeGlobalConfigPath` resolves whichever of `.json`/`.jsonc`
1365
- actually exists, as init's writer does; uninstall no longer reports
1366
- "nothing to remove" while leaving the plugin entry behind.
1367
- (7) `doctor` now checks all eleven MCP tool names (it checked the
1368
- plugin's five) and flags v1 memories stranded under `memories/user/`,
1369
- which v2 read paths cannot see. (8) `memory_status` output is capped
1370
- per section with an "… and N more" line; `memory_list` accepts
1371
- `scope: both`; `forget` says when the deleted file lived in the repo
1372
- (commit the deletion); the Copilot instructions and the MCP handshake
1373
- now tell the agent the same thing about when to call
1374
- `memory_status`; the AGENTS.md distillation footer teaches
1375
- `source: "inference"` like every other surface; `where` prints the
1376
- config path it always promised. Standing rule reinforced: any surface
1377
- that answers a question must be reading current truth, and every
1378
- workflow state must have a next step.
1379
-
1380
- - **D65 — keyword capture: natural phrasings fell through.** Default-pattern
1381
- fixes found while verifying a review claim: (1) `帮我记住…` — arguably the
1382
- most natural Chinese phrasing — matched no pattern at all; it now captures
1383
- to personal, following the established 我-rule (same as 替我记), while
1384
- `帮我们记住…` still routes project. (2) A leading `请` defeated every
1385
- 记住-led pattern (`请记住我…`, `请记住:…`, `请记住(个人)…`); the
1386
- `(?:请)?` prefix the 记一下 patterns already had is now uniform.
1387
- (3) English `remember to …` left a stray leading "to" in the captured
1388
- body; the pattern consumes it (with backtracking verified so
1389
- "remember Toronto…" is not mangled). Patterns are code defaults, so
1390
- upgrades pick these up automatically unless the user customized the
1391
- pattern lists. Deliberately NOT changed: multi-line paste triggering
1392
- and the secret-masking windows stay as they are — narrowing them is a
1393
- capture-recall tradeoff that needs an explicit decision, not a drive-by.
1394
-
1395
- - **D66 — follow-up review of the D63–D65 stack.** (1) The 帮/替
1396
- keyword family is rebuilt around full verb phrases: an optional `请`,
1397
- `记` + optional `住|录` + optional `一下`, then a separator boundary —
1398
- `请帮我记住:…` captures (D65's new pattern lacked its own `请`),
1399
- `帮我记录一下:…` saves `周五不发布` instead of the mid-word garbage
1400
- `录一下:…`, and `帮我记得…` does not fire. `help me remember: …`
1401
- joins the personal patterns. Still deliberately unchanged: shortening
1402
- the ≥3-char content floor (it eats `记一下这个`-type captures, but
1403
- lowering it invites junk) and adding narrative triggers like `记得…` /
1404
- `remind me to…` (imperative-vs-narration ambiguity) — both need an
1405
- explicit decision. (2) `sync-status` CLI shows the full list; the
1406
- 20-line cap binds only agent renders, whose "… and N more" line names
1407
- the CLI. `list --scope both` reaches CLI parity with the tool, and
1408
- `status --help` documents the retracted one-way door. (3) The test
1409
- suite is Windows-safe (probe imports are `file://` URLs, the uninstall
1410
- test sets `USERPROFILE` since `os.homedir()` ignores `HOME` there)
1411
- and refuses to run against a stale `dist/`. (4) Sync-error posture is
1412
- now a stated asymmetry: the MCP adapter lets pre-call sync errors
1413
- propagate as tool errors; the plugin adapter logs them at debug and
1414
- answers from a possibly-stale index rather than taking the tools
1415
- down. (5) §19's legacy-paths text now names the shipped locations;
1416
- historical decision entries keep their as-decided wording.
1417
-
1418
- - **D67 — keyword capture: a trigger must be a statement to the store.**
1419
- Three rulings, all from the D66 review's open items plus one bug D66
1420
- introduced. (1) **The boundary guard guards the bare verb only.** D66 put
1421
- a separator requirement *after* the whole verb phrase, which killed the
1422
- commonest Chinese form — `帮我记一下这个配置`, `帮我记住这个配置`,
1423
- `替我记一下我住在杭州`, `帮我们记一下这个约定` all stopped matching, because
1424
- the noun follows 记一下/记住 directly. The guard now applies only to a
1425
- bare 记: `记` + (`住`|`录`, never followed by a verb continuation like
1426
- 得/着) + optional `一下`, or a separator. So mid-word garbage (`帮我记得带伞`
1427
- → `带伞`) is still impossible while the natural form captures. (2) **The
1428
- ≥3-char body floor stays, but stops being silent.** A trigger that yields
1429
- `这个` or `OK` is a match on the trigger, not a memory, and a 2-char memory
1430
- is noise in every later injection — so the floor is deliberately *not*
1431
- lowered (a script-aware floor is the escape hatch if short Latin bodies
1432
- ever matter). What changed is honesty: `capture --dry-run` prints the
1433
- rejection with the reason, and `logLevel: debug` logs it, so "nothing
1434
- happened" is never a mystery. A rejected **personal** match also keeps
1435
- its line claimed — otherwise `记住我:OK` fell through to the generic
1436
- 记住 and was saved as the nonsense project memory `我:OK`. (3) **Narrative
1437
- forms are not triggers.** `记得…`, `remind me to…`, `I always forget to…`
1438
- stay out: they are imperatives aimed at the agent, they are the most
1439
- frequent sentences in any conversation that mentions memory, and a false
1440
- trigger writes permanent state nobody reviewed — while a missed trigger
1441
- costs one sentence. The asymmetry is deliberate: precision over recall.
1442
- For the two ambiguous forms already in the list, an explicit marker now
1443
- separates narration from instruction: `别忘了:…` / `don't forget: …` /
1444
- `don't forget that …` capture; bare `别忘了带伞` / `don't forget the wifi
1445
- password` do not. The `note` family is untouched — `note the API is v2`
1446
- was never ambiguous. (4) Test/tooling honesty: `test-full.ts` guards the
1447
- built `dist/` with a content fingerprint (`scripts/build-stamp.mjs`)
1448
- rather than mtimes — `git checkout` rewrites mtimes, so a branch switch
1449
- could leave an older-branch dist looking fresh — and the agent-facing
1450
- `memory_status` cap is pinned again (20 entries per section plus a
1451
- "full list: open-memex sync-status" pointer) after D66's CLI-parity test
1452
- had dropped that coverage.
1453
-
1454
- - **D68 — memory visibility: the inventory is a protocol surface.** Group 3-C
1455
- (design: `docs/memory-visibility-design.md` v2). `memory_list` output
1456
- becomes a numbered, structured inventory (`[type] id=… created=…
1457
- source=…`, state tags for project scopes; `created=` is when the fact
1458
- was learned, `updated=` shown only when it moved materially later). The
1459
- raw enums stay in the data; plain-language renderings live in the
1460
- guidance surfaces (tool descriptions, MCP handshake, SKILL.md,
1461
- distill-agents footer) so agents rephrase in the conversation's
1462
- language. New input `include: "active" | "all"` (default `active`) —
1463
- a deliberate behavior change: superseded versions and retracted /
1464
- archived memories leave the default listing (audit view via `all`).
1465
- Every listing states its true total; truncation is disclosed, never
1466
- silent (the D66 lesson applied to this surface). `open-memex
1467
- inventory` renders the same data layer as text (default) or JSON
1468
- (`open-memex-inventory/1`); a report containing personal memories
1469
- refuses to be written inside a git working tree without
1470
- `--allow-personal`. `memory_forget` gains `soft` (CLI `forget
1471
- --soft`): retraction as a first-class tool action — hidden from lists
1472
- and search, file kept, still one-way per D64 (restoring the fact means
1473
- saving it again; no un-hide, no undo, no recycle bin). Deletion stays
1474
- a confirmed conversation: agents re-list before acting on a number
1475
- (numbers are only valid for the listing just produced) and read the
1476
- entry back before deleting. The HTML rendering of the same data layer
1477
- follows as a separate change; auto-draft stays gated on the unlock
1478
- conditions in the design doc.
1479
- - **D74 — the Node floor is 22.14, because the driver sets it, not us.** D72
1480
- moved the Node driver to `better-sqlite3` 13 (the N-API rewrite) to stop the
1481
- Node 24.19+ exit-path abort. That upgrade carried an unstated requirement:
1482
- v13 is compiled against **Node-API 10**, and Node only gained Node-API 10 in
1483
- **22.14.0**. Below that floor `require("better-sqlite3")` succeeds and then
1484
- `new Database()` segfaults the process — no message, no stack, exit 139 on
1485
- macOS/Linux, `0xC0000005` on Windows. Measured on win32-x64: Node 22.12.0
1486
- dies on the first open, Node 22.23.3 and 24.20.0 work; Node 20 can never work
1487
- with v13, since Node-API 10 never landed on that line (EoL regardless). This
1488
- is upstream and still open — WiseLibs/better-sqlite3#1514, plus #1516 for the
1489
- separate `npm ci` gyp problem on Windows, where `gypfile: false` does not stop
1490
- npm from shelling out to node-gyp. `engines.node` had been `>=22.6`, which was
1491
- the `--experimental-strip-types` floor — a real but *different* constraint
1492
- that predated the driver bump; leaving it would have shipped a package whose
1493
- declared support window crashes on its own dependency. Three changes:
1494
- (1) `engines.node` is `>=22.14.0`, and the two floors are documented as two
1495
- floors rather than merged into one number; (2) `loadDatabase` refuses below
1496
- the new floor and throws the actionable message (upgrade Node, or pin
1497
- `better-sqlite3@^12.11.1` — v12 is unaffected), because a crash no in-process
1498
- `try`/`catch` can report is the worst possible failure mode for a CLI;
1499
- (3) `doctor` reports the floor *and* probes the driver in a **child process**,
1500
- since a segfault cannot be caught in-process — the probe resolves the driver
1501
- from this package's own directory, because `doctor` routinely runs with cwd
1502
- set to a user project where a bare `require` finds nothing. The version
1503
- comparison lives in `src/runtime-floor.ts`, pure and unit-tested, because the
1504
- boundary is a fact to be tested (22.13.9 below, 22.14.0 exactly at, 22.23.3
1505
- and 24.20.0 above) rather than a constant to be trusted. Deliberately NOT
1506
- done: pinning back to v12 (that re-opens D72's Node 24 abort), or attempting
1507
- to fix either upstream bug here.
1508
-
1509
- - **D73 — one user statement, one memory: the keyword hook hands off to the
1510
- agent.** The keyword hook and the agent are two writers for one user turn,
1511
- and only one of them knows the sentence is already stored. Observed
1512
- 2026-10-04: a single `remember this folder is for my spark tank ideas …
1513
- shared memory across agents and employees` produced **three** memories — one
1514
- `source: keyword` verbatim capture plus two `source: tool` paraphrases the
1515
- agent wrote because it could see the chat transcript but not the store. The
1516
- existing §3.4 guard could not catch it: token Jaccard scored those
1517
- paraphrases 0.21–0.38 against the capture, below the 0.8 near-dup bar, and
1518
- `open-memex audit` reported zero near-dup pairs, so the store looked healthy
1519
- while holding three copies of one statement (retrieval then returns all
1520
- three). Two mechanisms, deliberately layered:
1521
- **(a) hand-off note** — `captureFromText` records each capture against the
1522
- host session id (`chat.message` / v2 `prompt`, both of which carry one), and
1523
- the system-context hook (`experimental.chat.system.transform` / v2
1524
- `context`) pushes a short block naming what was already stored, delivered
1525
- once per capture and pruned after the turn window. The agent can now avoid
1526
- the duplicate write it had no way to see. In-memory only, like
1527
- `injectedSessions`: never persisted, gone on restart.
1528
- **(b) turn-echo guard** — `memory_add` additionally refuses a write that
1529
- overlaps a `source: keyword`/`user` memory created in the same scope within
1530
- the last 10 minutes, returning the stored id and pointing at
1531
- `memory_supersede`. This is the deterministic backstop for the case where
1532
- (a) is ignored. It is deliberately scoped and high-barred, because lexical
1533
- overlap **cannot** separate an agent's gloss from a genuinely new fact: in
1534
- the same measured set, the agent's gloss scored 0.211 and a distinct fact
1535
- the same sentence happened to contain scored 0.214. So the bar sits at
1536
- 0.28 — wholesale re-saves of the captured sentence measure 0.29–0.36 and are
1537
- refused; anything below is left to (a) and the agent's judgment, and a
1538
- refusal always names the stored id so the caller can rephrase to the new
1539
- part or supersede. Agent-authored `source: tool` saves keep the old 0.8
1540
- near-dup *notice* and are never refused. The refused case is recoverable by
1541
- construction (supersede, or a follow-up add carrying only the new
1542
- information), and no D14-style masking, dedup, or lifecycle rule changes.
1543
- What is deliberately NOT done: no fuzzy-matching upgrade (D73 measures why a
1544
- better metric still cannot decide "new information"), no auto-merging of the
1545
- agent's gloss into the capture, and no transcript store (the replay-distillation
1546
- open question owns that).
1547
-
1548
- - **D72 — the Node SQLite driver moves to the N-API line.** The D70 suite was stable on Windows and failed in shifting clusters on Linux under Node 24.20: individual CLI processes intermittently died with `SIGABRT` in `Statement::~Statement()` (`RemoveEnvironmentCleanupHook ... Assertion failed: (env) != nullptr`) and lost their stdout, so unrelated supersede / submit / inventory checks failed depending on which process the GC reaped. The work itself had always landed; only the exit path was broken. Root cause is upstream: Node 24.19 changed `node::ObjectWrap` cleanup-hook registration, and `better-sqlite3` <13 (raw `node::ObjectWrap`) can finalize a prepared statement from a GC callback with no Environment entered. `better-sqlite3` 13 is the N-API rewrite and removes that path; it still supports Node ≥22, and every API this repo uses (`Database`, `prepare`, `exec`, `pragma`-style PRAGMAs, `close`) is unchanged. The suite's crash-retry shim stays as belt-and-braces for older installs, but the shipped driver no longer needs it on current Node. Verified: three consecutive Linux `test-full` runs at 114/114 plus a 40-command add/list/search loop with zero aborts (was ~50% per process).
1549
-
1550
- - **D71 — the scope seed is the folder opened, never a filesystem root.**
1551
- OpenCode v1 hands the plugin two roots: `worktree` (the repo root — but
1552
- the filesystem root itself, `C:\` or `/`, when the opened folder is not a
1553
- git repo) and `directory` (the folder actually opened). The v1 adapter
1554
- preferred `worktree`, so every non-git folder on a drive seeded its scope
1555
- on the drive root and collapsed into one shared
1556
- `project__workspace__<hash of the root>` bucket — a `c:\temp` project
1557
- landing in `project__workspace__3dc8472eaebe` (seed `c:\`) is what
1558
- surfaced it. `pickScopeRoot` (src/scope.ts) now takes `worktree` only when
1559
- it is a real directory below the filesystem root, else `directory`. The
1560
- repo-root behavior is unchanged: a real worktree still wins, so opening a
1561
- repo subfolder keeps the repo's scope. Memories already written under a
1562
- root-seeded key stay where they are (no auto-migration, per the existing
1563
- rule); `open-memex scopes` shows the stray bucket and
1564
- `open-memex migrate --from <old-key>` moves them. The v2 adapter already
1565
- seeded on the opened directory and is unaffected.
1566
-
1567
- - **D70 — visibility follow-ups: one number, one guard, one truth.** The
1568
- 3-C review of D68/D69 found the surfaces honest individually and
1569
- inconsistent with each other. (1) **Every visibility surface discloses
1570
- truncation.** `memory_list` did; `open-memex list` — the command a
1571
- sceptical user runs first — silently showed 20 of 25. It now renders
1572
- the same structured line as the tool and states how many entries it
1573
- dropped, naming the command that shows everything. (2) **Numbers are
1574
- unique within a listing.** Ordinals ran per scope, so a single
1575
- `scope: both` output contained two `#1`s and "delete #3" was a guess;
1576
- the counter now runs across every section of one listing (tool, CLI and
1577
- the text report). (3) **A correction that touches the repo says so.**
1578
- The hard delete already did (D64); the soft hide did not, so a
1579
- retraction of an in-repo memory read as "hidden" while it was only a
1580
- local working-tree edit — the team still had the memory. Both surfaces
1581
- now name the commit and push. (4) **The report guard fails closed and
1582
- exists once.** `isInsideWorkTree` ran `git -C` on the output's parent
1583
- directory, so a not-yet-created directory made the check throw and
1584
- report "not in a worktree" — a fail-open on the one path where personal
1585
- memories would ride a commit; it now resolves the nearest existing
1586
- ancestor, reports a missing directory as itself, and both formats share
1587
- a single refusal helper instead of two copies. (5) **`open-memex-inventory/2`**
1588
- drops the absolute `file` path: the JSON renderer exists to be handed to
1589
- an agent, i.e. pasted into a cloud conversation, and it carried the
1590
- user's home directory. (6) Smaller honesty fixes: an empty scope is
1591
- reported as `(0)` instead of vanishing; only the HTML audit view loads
1592
- the hidden rows themselves (text/json pay for counts); the page's
1593
- "no network requests" claim is now enforced by a `default-src 'none'`
1594
- CSP rather than asserted; and `countList`'s comment states its one known
1595
- divergence (a self-healed dangling chain pointer) instead of claiming
1596
- equivalence. Deliberately NOT done, pending a decision: HTML i18n and a
1597
- size cap for very large stores.
1598
-
1599
- - **D75 — closed questions leave the list; competitor-inspired directions enter it (2026-10-04).** The Open Questions section is a working list, not an archive: the entries decided in D56 (host parity), D57 (retrieval explainability / memory health), D61 (checkpoint proactivity, capture criteria, retrieval layers 2–3), and D68 (memory visibility), plus the retrieval-robustness entry whose three cheap layers all shipped, are removed; the decisions remain the record. A same-day scan of five Glama-listed memory servers (auxly-memory-cli, agent-memory, remnic, Agent-Memory-Bridge, memtomem, memryzed) confirmed the current wedge — proactive in-session capture + one memory shared across editors + PR-based team sharing — appears in none of them whole. Borrowable directions are recorded instead: four new open questions (retrieval evaluation gate, per-client trust levels, cold-start import, session working state) and one roadmap candidate (`doctor` mis-registration check). Nothing here commits implementation; each direction needs its own design pass.
1600
-
1601
- - **D76 — tool annotations must tell the truth (2026-10-05).** `memory_pr_status` declared `readOnlyHint: true` while `apply=true` writes local review states (caught by Glama's TDQS evaluation of v0.7.2, 4.0/5). Structured hints are part of the protocol surface: all 11 tools now declare read-only / destructive / open-world hints that match their behavior, descriptions route between sibling tools instead of leaving agents to guess, and `scripts/smoke-mcp.ts` guards the pr_status combination. Description honesty is held to the same standard as behavior: ranking claims, defaults, and error semantics in tool text must match the code.
1602
-
1603
- - **D77 — measure usefulness by reuse, not storage (2026-10-07).** The Spark Tank submission commits the metric: "measured by reuse — fewer repeated questions, less context-prep time, approved memories reused by non-authors — not by memory count." Three layers, in build order: (1) **Offline retrieval eval.** A synthetic fixture (memories + queries with gold ids) run against the FTS5 baseline; publish recall@k/MRR in the README. This also answers the D75 "retrieval evaluation gate" open question — the number gates any future semantic-layer decision (reference points: agentmemory's published LongMemEval-S R@5 95.2%; lotargo/memory_plugin's BM25-only vs hybrid table). Later, run the MemoryAgentBench harness for directly comparable numbers (Knowl 90 / Mem0 18 / MIRIX 14 / Zep 7). (2) **Online reuse counters.** Per memory: `retrieved_count` (returned by search/list/first-turn injection) and `useful_count`, split into `useful_self` (author's own reuse — the personal-utility story) and `useful_team` (reuse of published project memories across sessions — the Spark Tank "reused by non-authors" story; no identity system needed: published state plus session diversity is the proxy). Both count as useful; reporting them separately keeps the team-knowledge claim honest. Explicit confirmation: a `memory_useful` tool call, human approve at review; behavioral: supersede/promote referencing it. Passive surfacing must never refresh usefulness — the opencode-memory lesson: unguarded exposure creates a self-reinforcing retrieval loop. Derived: `reuse_rate = useful / retrieved`; "zombie memories" (retrieved but never confirmed useful) surface in `memory_status` as decay/prune candidates. Counters live in SQLite, not frontmatter; local-only. (3) **Status surfaces.** `memory_status` gains a reuse report: top reused, zero-reuse list, per-scope reuse rate — feeding the Spark Tank pilot metrics. Moat note: competitors' "useful" is agent self-reported; our review ladder gives a human-grounded signal — approved/published means a human already said it is worth sharing. **Priority: this is the next build after 0.7.3** — fixture eval first (1–2 days, publishable number), then counters + `memory_useful`, then the status report, then the external bench.
1604
-
1605
- - **D78 — pre-submit curation: human-on-the-loop, not in-the-loop (2026-10-07).** Fragmented captures must be organized before submit, but the submitter's patience is the scarce resource — every manual gate lowers the submit rate, so curation defaults to automatic and the human handles exceptions. Confidence tiers: **auto-apply** (exact duplicates, trivial fragments, inferred type/tags, title normalization); **batch-confirm** (semantic merges, splits — one summary screen, one tap to accept or undo, never per-item approval); **explicit human decision** (dropping substantive content, and submit itself — the D-hard boundary "project scope never auto-submits" stands: automation covers organizing, sharing stays human). The safety net is the supersede chain: every auto-merge preserves provenance and is undoable, so pre-approval is replaced by reversibility (undo-send, not confirm-dialog). Trigger: no new step to remember — `submit` becomes curate+submit in one command, with the curation summary attached to the PR description; session wrap-up is the alternative hook (batch-silent, per the D61 checkpoint posture). Closed loop: human undos feed back into confidence thresholds, consuming the D77 `useful_count` signals. This revises the earlier review-ladder instinct of per-item approval: the human moves from in-the-loop to on-the-loop.
1606
-
1607
- - **D79 — query-time synonym expansion with a second-chance round (2026-10-07).** Fourth retrieval layer after D56 (query construction) and D61 (agent-side expansion guidance, capture-time aliases): a curated, checked-in synonym map (`src/retrieve/synonyms.ts` — EN dev-domain groups plus ZH groups, bidirectional) applied at query time. `search()` runs round one unchanged; when it returns fewer candidates than requested, round two re-runs with synonym variants OR-ed in and fills only the gaps — round-one ids and scores are never diluted by the expansion. Deliberately not embeddings and not an LLM call: deterministic, auditable, zero dependencies; a bad synonym is a visible line in the file, not a silent vector. `SearchStats.secondRound` records whether the round ran (surfaced in `search --explain`). Eval proof: 3 synonym-only fixture queries are unanswerable in round one by construction (their words appear in no memory); round two answers 2 of 3 at rank –2. Baseline with the round: recall@1 0.81, recall@5 0.95, MRR 0.87 over 37 queries. Follow-ups, not in this change: feedback-weighted ranking once D77 counters land; the embeddings gate decision against these numbers; reranker evaluation. **Update (2026-10-07, LongMemEval-S):** measured on 470 questions (recall_any@k protocol, per-question isolated corpora): R@1 86.0% / R@5 97.0% / R@10 98.3% / MRR 0.909 — ahead of agentmemory’s published BM25-only (86.2% / 94.6% / 0.715) and level with their BM25+vector (95.2% / 98.6% / 0.882). But the second round fired on **0 of 470** queries: the `raw.length < limit` trigger never trips once the corpus fills the page — the round as designed is a thin-corpus fallback, not a scale answer. A pooled 22k-memory stress run drops R@5 to 40.6% (the lexical ceiling, now measured instead of asserted). Consequence: the trigger needs a redesign (score/coverage-based, or always-expand-with-fusion) before the round can claim the scale story; the pooled number is the baseline an embedding layer must beat. **Ablation (2026-10-07, same bench):** OFAT over the lexical factors, limit=10, effect on MRR: OR semantics **+0.652** (AND collapses to 0.257 — the load-bearing wall); prefix matching **-0.010** (disabling it lifts R@1 86.0%→87.9% — mildly harmful, needs a second dataset before acting); stopword filtering **+0.005** (keep: cheap, principled); synonym round **0.000** at every limit and scale tested. Limit sweep: R@1 is invariant to limit (86.0% at 1–50); returns flatten at limit 5 (R@5 97.0%, +1.3pp to go to 50); round-2 fired 10/470 at limit=50 and rescued nothing (identical to no-synonyms). Pooled 22k at limit=50: R@5 still 40.6%, round-2 fired 0. Reading: the lexical lemon is squeezed — OR does the work, the rest is ±0.01. The next gains must come from ranking under distractors (embedding/reranker layer), not more lexical tweaks. Rescue experiment (same day): fallback-append vs always-expand+RRF-fusion, 470q, stratified by query–gold overlap — **zero rescues** under either design, at either scale; not one question changes outcome. The 8 residual misses are reasoning problems (preference/multi-hop/temporal), not vocabulary gaps. The round’s value lives in a mismatch slice the public data barely contains (proven on constructed queries: 2 of 3 rescued). Keep the curated map; stop spending design budget on the trigger. (Superseded same day: index-time expansion, see backlog.)
1608
- - **D80 — index-time synonym/translation expansion (2026-10-07).** Supersedes D79's query-time second round (removed from `search()`; `SearchStats.secondRound` gone): the curated map (`src/retrieve/synonyms.ts` — EN dev-domain groups, ZH groups and EN↔ZH translation pairs merged into one bidirectional group list) is applied at sync/index time. `writeRow` expands each memory's keywords via `expansionVariantsForDoc()` and appends the variants to the indexed `aliases` column (FTS and CJK-bigram columns both pick them up), so any related word matches in a plain round-1 query. Query side: single FTS round, no trigger, no second chance. Keyword-centric per Stone ("重要的是关键词"): Latin content terms (same stopword filter as the query builder, so both sides agree on what a keyword is) + CJK substring matching + multi-word Latin phrases (`regression test`); variants already present in the text are skipped; capped at 32 per memory to bound index growth. Derived at sync time — the Markdown file stays the source of truth; a map update needs a reindex to backfill. *Rationale: the precise slice (exact EN↔ZH pairs like 单点登录/SSO) must never be missed, and embeddings are fuzzy where the map is exact; paying the cost once at write time keeps every query simple and trigger-free.* Eval on the 41-query cross-lingual fixture: recall@1 0.732 → 0.756, recall@5 0.854 → **0.976**, MRR 0.791 → **0.859** — all 5 EN↔ZH vocabulary misses rescued at rank 1–3. Known trade-off: a single-keyword query can rank an aliases-only hit below shorter docs sharing the variant (`how do we ship`: rank 2 → 8 — its hit is 1 of 15 variants on a long aliases field); accepted, the old rank depended on the fragile thin-corpus trigger. `expandQueryWithSynonyms` kept as a bench-only export.
1609
- - **D81 — user-defined alias vocabulary as query-time expansion (2026-10-07).** Stone: an alias should be a *kind of memory* — defined once, remembered forever. Any memory type may carry `alias:` (the nickname, e.g. 香蕉计划) and `target:` (what it refers to, e.g. 支付系统重构项目) frontmatter; the alias memory defines vocabulary once per scope. At query time (`src/retrieve/alias-memory.ts`), query terms are looked up against the alias registry — one cheap `SELECT` per `search()` call over rows with non-empty alias+target (trigger A: exact registry hit, never a count heuristic; the D79 0/470 trigger is not repeated). On a hit the query is rewritten with the other side of the relation — bidirectional (alias→target and target→alias), depth < 3, cycle-safe — and re-run as round 2 (round 3 for chains). Rounds merge by normalized-max (`mergeRounds`): each round's BM25 scores are divided by that round's best (raw cross-round scores are incomparable — °C vs °F), then final = max, so an alias-side champion competes evenly with a literal-side champion — alias hits are never down-weighted for coming from a later round. Merged pool is re-ranked then cut to [1.5K, 2K] (Stone) — never back to K, or round-2 hits would be starved the way D79's slice-to-K starved them. No reindex when an alias changes (query-time). Scope-aware: a project codename stays in its project. *Rationale: D80's curated map is static and shared — personal vocabulary (小宝贝, 香蕉计划) doesn't belong in it; per-memory D61 aliases don't propagate to new memories. Alias memories close the gap: user-defined, scope-aware, effective immediately.* v1: user-explicit creation only (`memory_add` alias/target params, CLI `--alias`/`--target`, frontmatter edit); agent-proposed aliases deferred. D81 also rewords the init `captureAliases` prompt (it is not the synonym switch — D80's expansion always applies). Eval: 3 new fixture queries (香蕉计划↔支付系统重构项目 both directions + the alias memory itself), 44 queries total: recall@1 0.750, recall@5 **0.977** (43/44), MRR 0.857 — the single miss remains `how do we ship` (known D80 trade-off).
1610
-
1611
-
1612
- - **D82 — closed `type` taxonomy on search/list (2026-10-07).** Follow-up deferred from the TDQS pass (#50), closes issue #51: `memory_search` / `memory_list` `type` is now `z.enum(MEMORY_TYPE_TAXONOMY)` instead of `z.string()` — a misspelled type (`"decisions"`) is rejected at the schema (MCP -32602) instead of returning zero results the agent can't distinguish from "no memories of that type". Hard rejection, not a soft "no matches" message: closed taxonomy + fail-fast. Existing rows with non-taxonomy types are possible (the frontmatter parser only coerces the v1 `instruction` → `knowledge` case) and are unaffected — they still surface in unfiltered search/list, they just can't be addressed by a type filter. The opencode plugin shares the same args objects, so both surfaces tighten together; `scripts/smoke-mcp.ts` guards the rejection. `memory_submit` keeps `destructiveHint: false` — settled in the #50 review (the outbox unlink happens after the repo copy is committed and hash-verified, so it's recoverable from git); recorded here so it isn't re-litigated.
1613
-
1614
- - **D83 — D80 expansions get their own index column (2026-10-07).** Design follow-up to issue #56 (deferred from the D80 review): the curated index-time variants (`expansionVariantsForDoc`) move out of the `aliases` column into a dedicated `expansions` column — on `memories`, on `memories_fts`, and in the ai/ad/au triggers. `writeRow` stores user/authored aliases in `aliases` and derived variants in `expansions` (still filtered against the supplied set, still never written to Markdown); the `cjk` bigram column keeps covering body + tags + aliases + expansions so CJK variants stay substring-searchable. Retrieval: the FTS MATCH set gains the column with its own bm25 weight (at or below `aliases` — the fixture is the gate, tune don't guess); `SearchHit.aliases` and the `(aka: …)` attribution surface only user-authored aliases; `search --explain` reports which column matched (alias vs expansion). Migration: `SCHEMA_VERSION` 8 → 9; the bump triggers `rebuildIndexSchema`, which repopulates from Markdown — safe because expansions are derived and Markdown is untouched.
1615
- *Update (2026-10-07, implemented and measured):* the `how do we ship` rank did **not** improve (still 8) — the dilution for expansion-column matches is inherent to per-column BM25 length norm (32 variants in their own column dilute about as much as 36 did in the shared one), not to the mixing. What the split fixed is provenance (`(aka:)` / `SearchHit.aliases` are user-authored again) and the dilution of deliberate user aliases (a ≤4-term column now scores cleanly). Regression gate passed: `retrieval-eval` R@1 0.750 / R@5 0.977 / MRR 0.857, identical to pre-split; v8→v9 migration verified on a scratch DB (merged aliases re-split correctly, `user_version` 9). *Rationale: an agent reading `(aka: …)` must be able to trust it means "alternate phrasings someone attached to this memory", and a 32-variant derived list must not dilute the weight of 4 deliberate ones.*
1616
- - **D84 — `limit` is a cap on the return, never a hint (2026-10-07).** Correction to D81's cut rule, raised by the review of #52. D81 widened the merged alias pool to `[1.5K, 2K]` and passed that widened value to `resolveVisible` as the slice — so when an alias round fired, `search()` returned up to **2× `limit`** rows to every caller (`memory_search`, the MCP tool, `cli search`), with nothing in `--explain` saying so. The pool stays wider than `limit` — each round already over-fetches by `fetchLimit`, and the starvation D79's slice-to-K caused is real and still prevented — but the *return* is cut to `limit`. (D81's `1.5K` line was also dead: `max(min(pool,2K), min(pool,1.5K))` is always `min(pool,2K)`, so the documented band never existed; it is gone.) No ranking change — the merge sorts before any cut, so top-k is byte-identical; `scripts/retrieval-eval.ts` unchanged at R@1 0.750 / R@5 0.977 / MRR 0.857. *Rationale: `limit` is a contract on what a caller receives. Headroom belongs inside the ranking, not in the result set — an agent paying 2× the tool-result tokens on alias-touching queries has no way to see that it happened.*
1617
- - **D86 — the `expansions` BM25 weight, set by the fixture (2026-10-07).** Closes the two D83 clauses that were written into the decision log but never landed in code (`00c4d2d` shipped `bm25(memories_fts)` with no weight vector, and left `--explain` reporting only `fts:` / `candidates:` / `alias rounds:`). (1) **Weight vector** — `bm25(memories_fts, …)` now takes an explicit `[content, tags, aliases, expansions, type, cjk]`, with `expansions` at **0.75** (`src/retrieve/weights.ts`, kept out of `search.ts` so `smoke-pure.ts` keeps its no-sqlite guarantee). The measurement that sets it: on equal-length docs at weight 1.0, a direct body match and an expansion-only match score **identically** (`-3.983` vs `-3.983`) — the preference was being decided by tiebreak, not by the ranking function. Any weight < 1.0 breaks that tie toward the body. `0.75` is the *highest* weight the checked-in fixture cannot distinguish from 1.0 (sweep: 1.0 / 0.9 / 0.75 all yield R@1 0.750 / R@5 0.977 / MRR 0.857; 0.5 already costs MRR; below 0.35 R@5 breaks), so the ordering guarantee is free and the fixture remains the gate — retune by re-running the sweep, never by intuition. `SearchHit.matchedVia` (`body` | `alias` | `expansion` | `other`) is computed from the same per-column highlights the attribution already used. (2) **`--explain` attribution** — prints `matched via: body=N alias=N expansion=N other=N` alongside the active weights, so a surprising rank is traceable to the column that caused it. *Rationale: D83 promised the split would make the two columns distinguishable; on equal-weight columns they were not distinguishable at all, so the split bought provenance without buying ranking. This is the missing half.* **Explicit non-goal:** this does *not* repair D80's `how do we ship` rank-8 case — that is per-column length norm (one variant among many in a long `expansions` field), not a weighting problem. Fixing that means narrowing *what* lands in the column, not re-weighting it. Fixture unchanged: R@1 0.750 / R@5 0.977 / MRR 0.857.
1618
- - **D85 — the alias registry is indexed, not cached (2026-10-07).** From the same review (#55). D81's `loadAliasEntries` runs on **every** `search()` call over `alias <> '' AND target <> ''` — a full table scan on a corpus that may be tens of thousands. Added `idx_memories_alias ON memories(scope_key) WHERE alias <> '' AND target <> ''` to `TABLE_SCHEMA`. Two deliberate choices: (1) **no `SCHEMA_VERSION` bump** — `TABLE_SCHEMA` executes on every db open, not only on rebuild, so `CREATE INDEX IF NOT EXISTS` is idempotent and existing installs pick it up on next open with no rebuild; this also keeps the bump free for D83's 8 → 9 schema change. (2) **No result cache** — the registry must be re-read per query so a newly saved alias memory applies on the very next query (D81's freshness property). An index accelerates the lookup without caching results; those two concerns are separable and this resolves only the first. Measured at 5k memories: 971ms → 39ms per 2000 scoped lookups (~25×), `EXPLAIN QUERY PLAN` confirms `SEARCH memories USING INDEX idx_memories_alias`. Note the *unscoped* variant of the query still prefers `idx_memories_status`; `search()` always passes `scopeKeys`, so the partial index is what ships. *Rationale: the alias table is tiny by construction — one row per defined nickname per scope — so its lookup cost must be proportional to aliases defined, not to store size.*
1619
- - **D87 — stale stores migrate before the schema is created (2026-10-28).** D85's "no `SCHEMA_VERSION` bump" reasoning was wrong for one population: stores created before D81 (`SCHEMA_VERSION` 7, ≤0.7.x) have no `alias`/`target` columns, and `CREATE TABLE IF NOT EXISTS` adds no columns to an existing table — so `CREATE INDEX IF NOT EXISTS idx_memories_alias ... WHERE alias <> ''` throws `no such column: alias` inside `db()` before the `userVersion < SCHEMA_VERSION` rebuild check ever runs, wedging every open (CLI, MCP, plugin) on that store. Reproduced with a faithful v7 fixture: current code throws exactly that error. Fix, ordering only: in `db()`, when the `memories` table exists but the version is old, `rebuildIndexSchema()` runs *before* `TABLE_SCHEMA`/`FTS_SCHEMA` are executed (the table exists, so rebuild's `DELETE` is valid); fresh stores still fall through to creation and the existing post-create version check is unchanged. No version bump — the guard is ordered before creation, so version 9 still covers the migration, and no new mechanism was needed. Regression test in `test-full.ts` §9 builds a v7 store and asserts the open succeeds, `user_version = 9`, and the three columns are present. The D85 comment in `db.ts` carries a correction note. *Rationale: the wipe-and-repopulate migration only works if it runs before the schema that assumes its result; the bug was ordering, not a missing mechanism.*
614
+ The decision log lives in [docs/design/decisions.md](design/decisions.md). Append-only — new decisions append there with the next D-number; never rewrite history, never renumber.
615
+
1620
616
 
1621
617
  ## Open Questions
1622
618
 
1623
619
  _Pruned 2026-10-04 (D75): entries decided in D56/D57/D61/D68 and the shipped layers of the retrieval-robustness question were removed — the decisions are the record. What remains below is genuinely open._
1624
620
 
1625
621
  - **Non-programmer users: PMs, BAs, and entry points (open, 2026-10-03):** the current experience assumes a programmer's toolchain — terminal, npm install, editor plugin, git branches, PR review. Project managers and BAs have none of that, and their most likely entry points are not the VS Code chat window: at most an agentic CLI (opencode, Claude Code), more probably Teams chat, MS Copilot, or another chat surface calling the same MCP server. The mechanics must hide behind two confirmations ("remember this?" / "share with the team?") — scope/promote/supersede/outbox vocabulary is a programmer dialect they should never have to learn. Three roles to design for, in increasing order of build cost: (1) **sources** — their meetings and decisions are the highest-value project memory, captured by someone else's agent with attribution in `source`; needs nothing new. (2) **curators** — "is this true? is it safe to share?" is business-truth review, which BAs are often better placed to do than programmers; GitHub's web PR review is the only existing no-CLI door, and CURATOR.md would need a plain-language path for reviewers who have never touched git. (3) **direct users** — capture sources shift from chat commands to meeting transcripts, email, and tickets; and without git there is no courier: a shared-folder transport is mechanically easy (memories are Markdown files) but has no PR-equivalent review step, so a substitute review flow has to be designed. Also weigh: stakeholder/customer facts carry PII and retention weight that code conventions never do, so "is it safe to share" becomes a compliance question, not a hygiene one. If a company ever gives every employee one unified agent entry point (a work buddy / AI team mate), most of this audience split dissolves — the question is what open-memex should assume until then: heterogeneous entry points, one memory service behind them.
622
+ *Status (2026-11-02): 未实现 — only the sources role needs nothing new; curators and direct users unbuilt, no Teams/M365 entry.*
1626
623
 
1627
624
  - **Retrospective distillation: mining host transcripts after the fact (open, 2026-10-03):** open-memex captures only in-session (keyword triggers, explicit `memory_add`) and keeps **no transcript** — so anything not captured during the conversation is gone once it ends. Hosts with durable memory (e.g. Muse) avoid this loss with two layers open-memex skipped: full transcript retention plus background distillation. The gap is architectural, not a timing detail: the raw material for a second chance does not exist on our side. But the hosts themselves already retain it — opencode persists sessions and messages in its local store; Claude Code keeps JSONL transcripts under `~/.claude/projects/`; VS Code Copilot's chat state is locked in workspace storage (readable, fragile, not a first target). Candidate direction: a "replay distillation" flow that exports a past session's transcript and has an agent mine it in a dedicated review session, with every extracted candidate landing as an **outbox draft** for human review — never a direct save. Boundaries that keep this inside the existing design: open-memex builds no transcript store of its own (borrow the host's), mining judgment is the agent's LLM work (we provide the export and the queue, not an extractor), fully local, mined drafts carry their provenance (`source` marks them as distilled, from which session). Open sub-questions: host adapters per tool (opencode store format, Claude Code JSONL), how the user picks sessions to mine (by date? by project? "everything since last sync"?), and whether the proactive-capture criteria (open question above) should be the mining rubric verbatim — likely yes.
625
+ *Status (2026-11-02): 未实现 — no transcript replay/mining flow; open-memex keeps no transcript by design.*
1628
626
 
1629
627
  - **Novice experience: the 60-second magic moment and the plain-language layer (open, 2026-10-03; trimmed 2026-10-04):** the privacy model is now stated in plain words at init (D56). Still open: init offering to save one sample memory and immediately having the user's agent answer a question with it — the user *sees* recall work before being asked to trust it — and a plain-language layer over the review ladder ("saved on this computer" / "shared with the team") with outbox/submit/promote vocabulary becoming the advanced view. This is the same vocabulary wall the PM/BA question above hits from the other side.
628
+ *Status (2026-11-02): 部分实现 — init privacy statement (D56) and one-line hint (D51) shipped; the 60-second magic moment and plain-language review ladder unbuilt.*
1630
629
 
1631
630
  - **Retrieval evaluation: measure recall before choosing a semantic layer (open, 2026-10-04):** the retrieval-robustness question closed with all three cheap layers shipped (D56 query construction; D61 agent-side expansion + capture-time aliases), and embeddings stayed deferred *by judgment, without numbers*. A comparable project (agent-memory) publishes an offline recall@5 of 0.98 and wears it as a badge. open-memex should build the same kind of small, fixed eval — a query set over a seeded store, recall@k / MRR for the current FTS5 pipeline — and publish the number. The semantic-layer decision then gets a gate: if FTS5 + aliases is good enough, embeddings stay deferred; if a query class measurably fails, that class defines what an optional local-embedding layer must beat. Eval first, architecture second. **Update (2026-10-07):** the eval shipped (D77, `scripts/retrieval-eval.ts`, baseline recall@1 0.81 / recall@5 0.95 / MRR 0.87); query-time synonym expansion landed as retrieval layer 4 (D79) — embeddings stay deferred, now with numbers behind the judgment.
631
+ *Update (2026-11-02): fixture numbers have since moved to R@1 0.750 / R@5 0.977 / MRR 0.857 (D80/D81/D83); the conclusion (eval shipped, embeddings deferred on numbers) still holds.*
632
+ *Status (2026-11-02): 部分实现 — eval harness shipped (D77 layer 1) and embeddings deferred on numbers; MemoryAgentBench second data point still open.*
1632
633
 
1633
634
  - **Per-client trust levels (open, 2026-10-04):** the review ladder is currently global: every host's writes face the same gates. A comparable tool (auxly) sets a trust level per agent — one agent's writes land immediately, another's queue for approval, a third is read-only. That maps naturally onto open-memex, since the ladder already exists; the open questions are the config surface (per host? per MCP client name? how does the server learn the client's identity reliably?), the default for unknown clients, and whether trust should also gate *reads* of the personal scope. Signal to watch: one user running several agents with different autonomy expectations.
635
+ *Status (2026-11-02): 未实现 — no per-client trust config; the review ladder is global.*
1634
636
 
1635
637
  - **Cold-start import: index what the user already has (open, 2026-10-04):** adoption today starts from an empty store. Comparable tools index the user's existing notes (memtomem) or import other memory systems' exports (remnic: mem0 / ChatGPT / Claude). Candidate first steps, cheapest first: (1) import a folder of plain Markdown notes as personal-scope outbox drafts — never direct saves, the review gate stays the front door; (2) named-export importers once (1) proves the pipeline. Open sub-questions: chunking policy for long notes (one file ≠ one memory), dedup against existing memories, and provenance marking (`source: import`).
1636
-
1637
- - **Session working state: resume where you left off (open, 2026-10-04):** open-memex stores durable knowledge, not the state of an interrupted task. memryzed's third layer — per-repository session state (open files, last commands, where the work stands) so a fresh session resumes mid-task — names the gap. Candidate shape, if pursued: an ephemeral per-project working-state note, agent-written at wrap-up and surfaced at session start alongside memory injection, *outside* the review ladder (it is scratch state, not knowledge) with a short TTL. Open questions: what belongs in it (task summary? file list? next step?), who writes it (agent at Stop? user command?), and the overlap with the retrospective-distillation and checkpoint-proactivity threads. Defer until there is signal that users lose work context, not just facts.
638
+ *Status (2026-11-02): 部分实现 — bundle import/export shipped (0.4.0); importing a folder of plain Markdown notes as outbox drafts unbuilt.*
1638
639
 
1639
640
  - **The three Copilots: three integration surfaces (open, 2026-10-05):** "Copilot" is three different products with three different extension models, and open-memex's posture differs per surface. (Stone's machines: home has all three; the work machine has no Microsoft Copilot app.)
1640
641
  - **GitHub Copilot (editor, developer) — decided / shipped:** `open-memex init --client vscode|cursor|…` writes the MCP server entry; all 11 tools via MCP; the Agent Skill + instruction files drive proactive capture. This is the production path today.
1641
642
  - **Microsoft Copilot (Windows consumer app; formerly "Windows Copilot") — open, unverified:** the app itself claims MCP registration via `%LocalAppData%\Microsoft\Copilot\mcp\mcp.json` (a `servers` array with `id` / `type: "stdio"` / `command` / `args` / `cwd`), but no public documentation exists for this path, and it is not the same thing as the OS-level On-Device Agent Registry (ODR, `odr.exe` + MSIX manifest) — the documented mechanism, still in public preview. Two verified technical constraints for any implementation: (1) on Windows the npm global bin is `open-memex.cmd`, which cannot be spawned without a shell — the entry must be `cmd /c open-memex mcp` (or `node` pointed at `dist/mcp.js`); (2) the MCP server resolves project scope from the process cwd, so a global assistant config needs a deliberate "home base" `cwd`, not a source checkout. No Skills/instructions layer loads here (Copilot Studio Skills packages are M365-only), so proactive capture degrades to "save when asked". Deferred until verified on a real machine (write file → restart app → tools appear in the tool list); if verified, implement as a new `init --client windows-copilot` target.
1642
643
  - **Microsoft 365 Copilot (enterprise) — open, reframed 2026-10-05:** extension runs through Copilot Studio (agents, Skills packages, declarative agents, Graph connectors) — tenant-cloud surfaces, not local stdio — and this is where the non-programmer audience actually lives (the "MS Copilot" named in the non-programmer question above meant the consumer app; in practice, company non-programmers are on M365 Copilot, so this surface is not optional if we want that audience). The question is no longer *whether* but *how*: personal memory stays local-first and never touches the tenant; team/project memory — shared by design — is served by a company-hosted team-tier endpoint that Copilot Studio agents call as a remote MCP server (Copilot Studio supports MCP over URL). Pointing tenant agents at individual laptops is a non-starter (laptops aren't servers) and an IP mess under Roper-style assignment terms — work memory belongs on the company side, personal memory never leaves the machine, and that split is the clean story. Until the team tier exists, the no-new-infrastructure path is asymmetric participation: non-programmers contribute as attributed sources (captured by others' agents) and review as curators on GitHub web, reading via inventory reports.
644
+ *Status (2026-11-02): 部分实现 — GitHub Copilot shipped; Microsoft Copilot unverified, M365 team-tier endpoint does not exist.*
1643
645
 
1644
646
  - **Enterprise / pro edition: team server + remote MCP (open, 2026-10-05):** the M365 question above reframes the enterprise surface as a *team-tier* endpoint: personal memory stays local-first, team/project memory is served company-hosted and called by Copilot Studio agents as a remote MCP server. The packaging question is whether that team tier ships as an open-memex "enterprise/pro" edition (hosted service or deployable server + remote MCP) or stays a documented deployment pattern companies run themselves. Adoption insight from large-company anecdotes: internally-built programmer tools get pulled in by BAs/QAs/POs on their own — the wedge is developers, and the non-programmer entry point may not need to be built up front; it arrives via the team surface (M365/Teams) once the team server exists. Open: packaging and monetization model (Stone's current goal for open-memex is personal influence, not user count or revenue — an enterprise edition is a support burden, so timing and shape need a deliberate decision); hosting and auth model for the team server; how the personal/team split is enforced at the protocol level.
1645
647
  - *Refinement (2026-10-05): the entry point is not built, it is placed.* Employees already live in team chat — asking questions, getting work done. A team-chat AI agent (e.g. a Copilot Studio agent in Teams backed by the team memory server) becomes the entry point by standing where the questions already get asked. Adoption is pull, not push: the agent answers and does work in the chat, and usage follows. This dissolves the "non-programmer entry point" problem rather than solving it — there is no separate door to build.
1646
648
  - *Interface constraint (2026-10-16, from tool/skill/MCP boundary audit):* design the MCP interface for dual use from the start — internal agents and external agents (Copilot Studio, team chat) consume the same tools. Reserve org scope alongside project/personal; the review ladder's single-reviewer assumption will need multi-reviewer semantics. No code changes now; the constraint is recorded so the team tier doesn't require an interface rework later.
649
+ *Status (2026-11-02): 未实现 — no team server; packaging, hosting/auth, and protocol split all undecided.*
1647
650
 
1648
651
  ---
1649
652