open-memex 0.8.2 → 0.9.0-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +21 -5
- package/CHANGELOG.md +10 -0
- package/README.md +46 -13
- package/README.zh-CN.md +25 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +103 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +4 -2
- package/dist/index.js +6 -1
- package/dist/init.js +13 -3
- package/dist/mcp.js +28 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/retrieve/inject.js +6 -0
- package/dist/retrieve/search.js +13 -2
- package/dist/review.js +7 -0
- package/dist/store/audit.js +14 -0
- package/dist/store/db.js +19 -0
- package/dist/store/lifecycle.js +8 -0
- package/dist/store/usage.js +151 -0
- package/dist/tools/memory.js +21 -2
- package/dist/tools/ops.js +123 -1
- package/dist/working-state.js +118 -0
- package/docs/CONCEPTS.md +16 -0
- package/docs/CONCEPTS.zh-CN.md +13 -0
- package/docs/V2-DESIGN.md +42 -1039
- package/docs/design/decisions.md +1146 -0
- package/docs/design/knowledge-graph.md +86 -0
- package/package.json +66 -66
- package/scripts/smoke-mcp.ts +67 -4
- package/scripts/smoke-pure.ts +70 -0
- package/scripts/test-full.ts +83 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +19 -0
- package/src/cli.ts +111 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +4 -2
- package/src/index.ts +6 -0
- package/src/init.ts +13 -3
- package/src/mcp.ts +41 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/retrieve/inject.ts +7 -0
- package/src/retrieve/search.ts +19 -3
- package/src/review.ts +6 -0
- package/src/store/audit.ts +20 -0
- package/src/store/db.ts +20 -0
- package/src/store/lifecycle.ts +9 -0
- package/src/store/usage.ts +178 -0
- package/src/tools/memory.ts +26 -1
- package/src/tools/ops.ts +158 -1
- package/src/working-state.ts +153 -0
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–
|
|
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
|
|
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 |
|
|
519
|
-
| Cursor | MCP server + rules | ❌ no chat plugin API |
|
|
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 ✅ built 2026-11-03 (0.9.0-alpha.2): per-memory `retrieved_count`/`useful_count` (`useful_self` vs `useful_team`) + `memory_useful` tool, counters in a `memory_usage` table beside the rebuildable index. 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
|
-
-
|
|
589
|
-
|
|
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
|
|