open-memex 0.6.2 → 0.7.0-alpha.11

package/docs/V2-DESIGN.md

@@ -1,6 +1,6 @@
 # OpenMemex — Design Document (protocol v0.2)
 
-**Status:** FROZEN — protocol v0.2 (2026-09-26). Zero open questions.
+**Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D70 are settled; open questions are tracked at the end of this document.
 **Author:** Stone, with 小沐
 **Changelog vs v1:** incorporates round-3 review from Perplexity, Grok, Gemini, ChatGPT, DeepSeek.
 Key changes: Design Principles section; `role` separated from `type`; two iron rules;
@@ -39,7 +39,7 @@ Decisions log; Prior Art; solo-dev adoption path.
 **OpenMemex is an open, local-first memory layer and interoperable protocol for AI coding agents.**
 
 - **Tagline:** *"Capture knowledge once, make it available to every AI agent."*
-- **Local-first, open source (MIT).** No cloud SaaS, no account, no mandatory network calls.
+- **Local-first, open source (Apache-2.0).** No cloud SaaS, no account, no mandatory network calls.
 - **The pain it kills:** every developer's AI learns in isolation. Dev A spends three days debugging an
   environment quirk with AI help; dev B rediscovers it next week. Hard-won knowledge should flow
   **personal → team → organization** instead of evaporating with each session.
@@ -109,36 +109,35 @@ One memory = one file. `id` = filename = ULID. No other ID scheme.
 ```yaml
 id: 01K6AB3XZQ7WVD9J1M2N4P5Q6R7
 schema_version: 2
-revision: 1
 scope: project            # personal | project | org  (ownership: WHO owns it)
                           # team, public → schema enum REJECTS writes (reserved)
+scope_key: project__my-repo__9f2c1a4b8e3d   # storage identity (repo-derived, or "personal")
 visibility: internal      # private | internal | shared (read access: WHO may read)
+project_name: my-repo
 type: decision            # content kind: what the memory IS (§3.2)
 role: knowledge           # knowledge | instruction — how it may be USED (§3.3)
-importance: normal         # low | normal | high (ranking hint; replaces 1–10 priority)
-instruction_state: null   # draft | approved | revoked — only when role=instruction
-trust_level: reviewed     # untrusted | reviewed | trusted
+importance: normal        # low | normal | high (ranking hint; replaces 1–10 priority)
 status: active            # active | superseded | deprecated | retracted | archived
-review_state: approved    # draft | proposed | approved | rejected | published (promotion)
+tags: [auth, oauth]
+aliases: ["oauth login flow"]   # optional: capture-time phrasing variants (D61)
 source: user              # provenance: user | tool | keyword | inference | import
-confidence: high          # high | medium | low — describes the CONTENT, not the author
-created_by: github:stoneskin   # namespaced identity: local:… | github:… | oidc:…:…
-promoted_by: null
-approved_by: null
-via: cli                  # mcp | copilot | opencode | cli | import (cross-agent provenance)
 created_at: "2026-09-26T12:00:00Z"   # RFC 3339, never bare epoch
 updated_at: "2026-09-26T12:00:00Z"
-supersedes: 01K69Z…       # on the NEW memory → points BACK to what it replaces
+supersedes: null          # on the NEW memory → points BACK to what it replaces
 superseded_by: null       # on the OLD memory → points FORWARD to its replacement
-expires_at: null
-repo_id: git-origin-sha256:9f2c…     # namespace: cross-machine project identity
-language: zh                         # detected or declared; drives tokenizer choice
-tags: [auth, oauth]
-paths: ["src/auth/**"]               # repo-relative globs; mismatch ⇒ downrank, not filter
-related: [01K6AC…]                   # light links between memories (no knowledge graph yet)
-canonical_ref: docs/adr-003.md       # memory holds a SUMMARY; the doc is canonical
+review_state: approved    # draft | proposed | approved | rejected | published (promotion)
+proposed_by: stoneskin
+approved_by: stoneskin
+derived_from: null        # for propose-copies: the personal memory this came from
+review_note: null
+review_history: []        # append-only [{at, by, from, to, note}] audit trail
 ```
 
+Field set as implemented (`src/store/markdown.ts`). Earlier drafts of this
+example listed aspirational fields (`revision`, `trust_level`, `confidence`,
+`via`, `expires_at`, `paths`, `related`, `canonical_ref`) that never shipped;
+they are not part of protocol v0.2.
+
 ### 3.1 Type taxonomy (content kind)
 
 `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto` `gotcha`
@@ -240,14 +239,17 @@ distills; explicit "save this note" may preserve long-form text.
 | Scope      | Owner | Lives where | Synced? |
 |------------|-------|-------------|---------|
 | `personal` | you | this machine only | **never** |
-| `project`  | repo collaborators | `<repo>/.open-memex/` | via git (opt-in per repo) |
+| `project`  | repo collaborators | `<repo>/.ai/open-memex/` | via git (opt-in per repo) |
 | `org`      | org members | dedicated org memory repo | via git |
 
 Legal combinations: `personal/*` (any visibility, stays local); `project/{internal,shared}`;
-`org/{internal,shared}`. `visibility: private` inside a shared scope is **physically isolated**:
-private memories are written to a local-only cache directory and never land under `.open-memex/`
-— never relying on `.gitignore` or filename conventions alone. (Pre-commit scanning is defense in
-depth, not the boundary.)
+`org/{internal,shared}`. `visibility: private` inside a shared scope is a logical boundary
+today, not a physical one: `export` excludes private memories by default (D40), and the
+`personal` scope never leaves the machine — but a private file placed under
+`<repo>/.ai/open-memex/` still travels with git, so review before you push. Physical
+isolation of private memories into a local-only cache directory remains planned
+(see docs/SCOPES.md); `.gitignore` and pre-commit scanning are defense in depth, not
+the boundary.
 
 **Namespace:** `repo_id` (`git-origin-sha256:…`, falling back to a normalized cwd hash) identifies
 the same project across machines — carried over from v1's scope-key design.
@@ -567,8 +569,10 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 - Times: epoch ms → RFC 3339. `priority: N` → `importance: low|normal|high` (1–3 low, 4–7 normal, 8–10 high).
 - `type: instruction` (if any v1 memory used it) → `type: <content-kind>` + `role: instruction`.
 - Index is discarded and rebuilt from markdown files. `open-memex migrate --dry-run` previews everything.
-- Legacy paths: v1 `.my-o-memory/` repo dirs and `~/.my-o-memory/` config are moved to `.open-memex/` /
-  `~/.open-memex/` during migration (originals kept as backup until the user confirms).
+- Legacy paths: v1 `.my-o-memory/` repo dirs and `~/.my-o-memory/` config are moved to the
+  v2 locations (in-repo `.ai/open-memex/`; data root per §4/paths — `OPEN_MEMEX_HOME`, else
+  `%APPDATA%\open-memex` or `$XDG_DATA_HOME/open-memex`) by `open-memex migrate --to-v2`,
+  with the pre-migration tree kept as a dated backup.
 
 ---
 
@@ -1210,13 +1214,312 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   `@opencode-ai/plugin`, the exact D58 death. It checks only what can be
   attributed; per-project and MCP wiring are out of scope.
 
-## Open Questions
+- **D60** — one plugin serves both opencode generations (0.7.0-alpha.1).
+  Opencode 2 changes the plugin contract end to end: config reads
+  `plugins` (directories or `{package}` objects) instead of v1's
+  `plugin` file entries, a v1-style file entry only earns a log warning
+  ("configured plugin path must be a directory") and is silently skipped
+  — the D58 death in a new shape; and the plugin value itself is a
+  structurally decoded `{ id, setup(ctx) }` rather than the v1 server
+  factory. A single `open-memex init --client opencode --global` now
+  writes both keys (`plugin` file URL and `plugins` directory): each
+  host loads from its own key — verified: opencode 1.18.34 ignores the
+  `plugins` array with a config-normalization warning, and opencode 2
+  warns per `plugin` file entry but loads the directory entry — so users on either generation get a
+  working plugin from the same install. `src/index.ts` default-exports
+  `{ id, setup, server }`: v2 calls `setup`, v1 calls `server`, the
+  shared logic (bootstrap, keyword capture, one-time injection) lives in
+  `src/plugin-core.ts`. Cost of the bridge on the v1 side: v1 hosts
+  older than 1.18.29 only invoke function default exports and would
+  skip this object; 1.18.29+ accepts it — the README states the new
+  minimum. The v2 adapter (src/opencode-v2.ts) obeys D58's rule — no
+  runtime `@opencode/plugin` import (a devDependency again); the
+  context is duck-typed from the 2.0 surface, tool arg shapes compile
+  from the same zod shapes via `z.toJSONSchema`, and hooks map
+  one-to-one (session `prompt` → keyword capture, session `context` →
+  first-turn injection). One registration subtlety cost real debugging
+  time and is worth recording: on 2.0.1 a plugin tool added without
+  options is exposed to the model only in code mode — callable through
+  an `execute` meta-tool that runs model-written JS
+  (`tools.memory_search(...)`) — and a model that instead calls the
+  tool by name gets a host-side "Unknown tool" error, so whether the
+  memory tools work at all depends on the model's calling style. Each
+  tool therefore registers with `options: { codemode: false }`, which
+  restores plain function calling (verified: direct calls execute
+  first try). The D59 doctor check extends to both keys:
+  v2 entries are checked for an existing, resolvable entry file and the
+  closure scan now covers `@opencode/plugin` too, plus a generation
+  advisory — when the installed host and the config point at different
+  generations, doctor fails and names the fix (`init --force`; package-
+  name entries installed via `opencode plugin add` are recorded but not
+  path-checked). Field-verified on real hosts 1.18.34 and 2.0.1.
+
+- **D61 — proactive capture cluster: propose posture, a shared
+  memorability rubric, and capture-time aliasing (retrieval layer 3).**
+  Builds on the "proactive capture" open question below and the
+  CHECKPOINT_PROACTIVITY / MEMORY_VISIBILITY notes. Three pieces,
+  shipped together because they are one user-visible behavior — the
+  agent capturing well without being asked each time:
+  (1) **Posture: propose, not auto-draft.** When the agent finishes a
+  task the user would describe in one sentence, it proposes 1–3 short
+  candidate memories in the conversation and saves only what the user
+  approves (approved inferences are saved with `source: "inference"`,
+  the §3.5 convention). The guidance is text, not mechanism — the same
+  rubric written into the bundled skill, the AGENTS.md memory-hygiene
+  footer, the MCP handshake instructions, the `memory_add` tool
+  description, and a one-line summary in the injected context block —
+  with throttling rules (task end / decision / gotcha moments only, no
+  mid-task interruptions, never re-propose a declined candidate). The
+  auto-draft posture (write first, surface later in bulk) is deferred
+  until memory visibility ships: without an inventory the user can
+  read, silent drafting reads as surveillance, so D61 deliberately
+  does not build it.
+  (2) **Rubric.** One memorability standard, shared by this live
+  capture path and the future retrospective-distillation group:
+  worth saving — decisions and their reasons, preferences,
+  conventions, gotchas, approaches tried and abandoned, and
+  `reference` memories pointing at authoritative docs; not worth
+  saving — one-off task details and anything re-derivable from the
+  code. Retrieval robustness layer 2 (agent-side query expansion:
+  decompose into concepts, 2–3 phrasings each, cross-language, check
+  the other scope) ships as guidance in the same texts, on top of the
+  D56 server-side layer 1.
+  (3) **Capture-time aliases (layer 3).** When a memory is saved, the
+  agent attaches up to 4 aliases — alternate phrasings, synonyms,
+  equivalents in the user's other language — stored in a new optional
+  frontmatter field `aliases` (additive; files without it parse
+  unchanged, `schema_version` stays 2) and indexed in their own FTS
+  column (index schema 6→7, rebuilt from markdown automatically).
+  Gated by a new `captureAliases` config flag (init asks once, default
+  on, `config set captureAliases off` opts out): when off, aliases
+  passed by agents are dropped and the alias guidance disappears from
+  the MCP handshake. Turning it off never rewrites existing memory
+  files — aliases already stored stay stored and searchable, and
+  supersede keeps carrying them forward; the flag gates new captures
+  only (no silent data destruction). Aliases pass through the same
+  secret redaction as memory content before they are stored, and a
+  malformed alias list (blanks, more than 4) is normalized silently —
+  never a tool-call error.
+  Keyword capture (no agent in the loop) leaves
+  aliases empty rather than inventing them; `supersede` carries
+  aliases forward unless the caller replaces them. Aliases are
+  normalized (trim, case-insensitive dedupe, cap 4) and bad ones cost
+  nothing — they rank as bm25 noise, never an error. Retrospective
+  distillation over host transcripts stays its own group; it will
+  reuse this rubric.
+
+- **D62 — environment variable names grow current-name aliases.** The
+  data-root and config-path overrides predate the rename and kept the
+  old package's name (`MY_O_MEMORY_HOME`, `MY_O_MEMORY_CONFIG`) — a
+  stale-looking name is a trap for users and agents scripting against
+  the current one. `OPEN_MEMEX_HOME` / `OPEN_MEMEX_CONFIG` are now the
+  preferred names; the legacy names still work as fallbacks (new name
+  wins when both are set), so existing setups and scripts never break.
+  The data root itself does not move — only the variable names change.
+  `doctor`'s storage check notes when the root arrived via the legacy
+  variable, and its pre-rename-dir leftovers check reads whichever
+  variable is in effect.
+
+- **D63 — correctness fixes from a whole-project external review.** Six
+  verified silent-wrong-answer bugs, fixed as one batch: (1) VS init
+  dropped the parsed `.mcp.json` instead of merging it, wiping other
+  servers; (2) forget reported success when unlink failed — only ENOENT
+  is success now, both in the tool op and the CLI; (3) the config
+  loader's regex comment-stripper was not string-aware and corrupted
+  redact patterns (`src/**/secrets` → `srcsecrets`) — replaced with a
+  string-aware scanner now shared with doctor (one parser, not two);
+  (4) `loadConfig` enforces the `memoryDir` no-escape invariant on
+  hand-edited files, falling back to the default with a warning;
+  (5) `migrate` rewrites `scope`/`visibility` with the key, and
+  conflict resolution compares parsed timestamps (lexicographic
+  RFC-3339 order breaks at fractional seconds); (6) bundle import
+  enforces staging-dir containment (resolve + realpath), rejecting
+  `../` and symlink escapes. Rule going forward: any behavior that can
+  fail must fail loudly in its return value; "already gone" is the only
+  swallowed delete error.
+
+- **D64 — second batch from the same review: stale answers, stranded
+  files, and holes between surfaces.** (1) The opencode plugin hosts
+  synced the index only at bootstrap, so memories written by the CLI or
+  another client stayed invisible all session (and exact duplicates
+  accumulated); plugin tool calls now reconcile from disk first,
+  mirroring the MCP server's per-call sync. (2) Superseding a published
+  memory reset `review_state` to `draft` in the repo, where submit
+  could not reach it and promote refuses drafts — the replacement now
+  re-enters at `proposed` whenever the old memory had entered review.
+  (3) Every memory-file rewrite now goes through the atomic
+  tmp+rename helper (D57 covered creates only); a torn read mid-rewrite
+  previously parsed as a deletion. (4) `setStatus` refuses
+  `retracted → active`: retraction is one-way through this path, or
+  withdrawn content silently returns to recall. (5) Propose copies get
+  `visibility: internal` instead of inheriting `private`, which export
+  excludes by default — the team copy no longer vanishes from bundles.
+  (6) `opencodeGlobalConfigPath` resolves whichever of `.json`/`.jsonc`
+  actually exists, as init's writer does; uninstall no longer reports
+  "nothing to remove" while leaving the plugin entry behind.
+  (7) `doctor` now checks all eleven MCP tool names (it checked the
+  plugin's five) and flags v1 memories stranded under `memories/user/`,
+  which v2 read paths cannot see. (8) `memory_status` output is capped
+  per section with an "… and N more" line; `memory_list` accepts
+  `scope: both`; `forget` says when the deleted file lived in the repo
+  (commit the deletion); the Copilot instructions and the MCP handshake
+  now tell the agent the same thing about when to call
+  `memory_status`; the AGENTS.md distillation footer teaches
+  `source: "inference"` like every other surface; `where` prints the
+  config path it always promised. Standing rule reinforced: any surface
+  that answers a question must be reading current truth, and every
+  workflow state must have a next step.
+
+- **D65 — keyword capture: natural phrasings fell through.** Default-pattern
+  fixes found while verifying a review claim: (1) `帮我记住…` — arguably the
+  most natural Chinese phrasing — matched no pattern at all; it now captures
+  to personal, following the established 我-rule (same as 替我记）, while
+  `帮我们记住…` still routes project. (2) A leading `请` defeated every
+  记住-led pattern (`请记住我…`, `请记住：…`, `请记住（个人）…`); the
+  `(?:请)?` prefix the 记一下 patterns already had is now uniform.
+  (3) English `remember to …` left a stray leading "to" in the captured
+  body; the pattern consumes it (with backtracking verified so
+  "remember Toronto…" is not mangled). Patterns are code defaults, so
+  upgrades pick these up automatically unless the user customized the
+  pattern lists. Deliberately NOT changed: multi-line paste triggering
+  and the secret-masking windows stay as they are — narrowing them is a
+  capture-recall tradeoff that needs an explicit decision, not a drive-by.
+
+- **D66 — follow-up review of the D63–D65 stack.** (1) The 帮/替
+  keyword family is rebuilt around full verb phrases: an optional `请`,
+  `记` + optional `住|录` + optional `一下`, then a separator boundary —
+  `请帮我记住：…` captures (D65's new pattern lacked its own `请`),
+  `帮我记录一下：…` saves `周五不发布` instead of the mid-word garbage
+  `录一下：…`, and `帮我记得…` does not fire. `help me remember: …`
+  joins the personal patterns. Still deliberately unchanged: shortening
+  the ≥3-char content floor (it eats `记一下这个`-type captures, but
+  lowering it invites junk) and adding narrative triggers like `记得…` /
+  `remind me to…` (imperative-vs-narration ambiguity) — both need an
+  explicit decision. (2) `sync-status` CLI shows the full list; the
+  20-line cap binds only agent renders, whose "… and N more" line names
+  the CLI. `list --scope both` reaches CLI parity with the tool, and
+  `status --help` documents the retracted one-way door. (3) The test
+  suite is Windows-safe (probe imports are `file://` URLs, the uninstall
+  test sets `USERPROFILE` since `os.homedir()` ignores `HOME` there)
+  and refuses to run against a stale `dist/`. (4) Sync-error posture is
+  now a stated asymmetry: the MCP adapter lets pre-call sync errors
+  propagate as tool errors; the plugin adapter logs them at debug and
+  answers from a possibly-stale index rather than taking the tools
+  down. (5) §19's legacy-paths text now names the shipped locations;
+  historical decision entries keep their as-decided wording.
+
+- **D67 — keyword capture: a trigger must be a statement to the store.**
+  Three rulings, all from the D66 review's open items plus one bug D66
+  introduced. (1) **The boundary guard guards the bare verb only.** D66 put
+  a separator requirement *after* the whole verb phrase, which killed the
+  commonest Chinese form — `帮我记一下这个配置`, `帮我记住这个配置`,
+  `替我记一下我住在杭州`, `帮我们记一下这个约定` all stopped matching, because
+  the noun follows 记一下/记住 directly. The guard now applies only to a
+  bare 记: `记` + (`住`|`录`, never followed by a verb continuation like
+  得/着) + optional `一下`, or a separator. So mid-word garbage (`帮我记得带伞`
+  → `带伞`) is still impossible while the natural form captures. (2) **The
+  ≥3-char body floor stays, but stops being silent.** A trigger that yields
+  `这个` or `OK` is a match on the trigger, not a memory, and a 2-char memory
+  is noise in every later injection — so the floor is deliberately *not*
+  lowered (a script-aware floor is the escape hatch if short Latin bodies
+  ever matter). What changed is honesty: `capture --dry-run` prints the
+  rejection with the reason, and `logLevel: debug` logs it, so "nothing
+  happened" is never a mystery. A rejected **personal** match also keeps
+  its line claimed — otherwise `记住我：OK` fell through to the generic
+  记住 and was saved as the nonsense project memory `我：OK`. (3) **Narrative
+  forms are not triggers.** `记得…`, `remind me to…`, `I always forget to…`
+  stay out: they are imperatives aimed at the agent, they are the most
+  frequent sentences in any conversation that mentions memory, and a false
+  trigger writes permanent state nobody reviewed — while a missed trigger
+  costs one sentence. The asymmetry is deliberate: precision over recall.
+  For the two ambiguous forms already in the list, an explicit marker now
+  separates narration from instruction: `别忘了：…` / `don't forget: …` /
+  `don't forget that …` capture; bare `别忘了带伞` / `don't forget the wifi
+  password` do not. The `note` family is untouched — `note the API is v2`
+  was never ambiguous. (4) Test/tooling honesty: `test-full.ts` guards the
+  built `dist/` with a content fingerprint (`scripts/build-stamp.mjs`)
+  rather than mtimes — `git checkout` rewrites mtimes, so a branch switch
+  could leave an older-branch dist looking fresh — and the agent-facing
+  `memory_status` cap is pinned again (20 entries per section plus a
+  "full list: open-memex sync-status" pointer) after D66's CLI-parity test
+  had dropped that coverage.
+
+- **D68 — memory visibility: the inventory is a protocol surface.** Group 3-C
+  (design: `docs/memory-visibility-design.md` v2). `memory_list` output
+  becomes a numbered, structured inventory (`[type] id=… created=…
+  source=…`, state tags for project scopes; `created=` is when the fact
+  was learned, `updated=` shown only when it moved materially later). The
+  raw enums stay in the data; plain-language renderings live in the
+  guidance surfaces (tool descriptions, MCP handshake, SKILL.md,
+  distill-agents footer) so agents rephrase in the conversation's
+  language. New input `include: "active" | "all"` (default `active`) —
+  a deliberate behavior change: superseded versions and retracted /
+  archived memories leave the default listing (audit view via `all`).
+  Every listing states its true total; truncation is disclosed, never
+  silent (the D66 lesson applied to this surface). `open-memex
+  inventory` renders the same data layer as text (default) or JSON
+  (`open-memex-inventory/1`); a report containing personal memories
+  refuses to be written inside a git working tree without
+  `--allow-personal`. `memory_forget` gains `soft` (CLI `forget
+  --soft`): retraction as a first-class tool action — hidden from lists
+  and search, file kept, still one-way per D64 (restoring the fact means
+  saving it again; no un-hide, no undo, no recycle bin). Deletion stays
+  a confirmed conversation: agents re-list before acting on a number
+  (numbers are only valid for the listing just produced) and read the
+  entry back before deleting. The HTML rendering of the same data layer
+  follows as a separate change; auto-draft stays gated on the unlock
+  conditions in the design doc.
+
+- **D69 — inventory HTML rendering lands (3-C complete on the visibility side).**
+  `open-memex inventory --format html` renders the D68 data layer into a
+  single local page: scopes grouped, outbox drafts in their own section,
+  replaced/hidden history folded with supersede-chain pointers, all
+  content escaped, filter box is local show/hide (no innerHTML, no
+  network). Default output is the data dir's `inventory.html`; the D68
+  worktree refusal applies unchanged. Sections fold above 50 current
+  entries. With this, the 3-C visibility surfaces are complete (agent
+  inventory in chat, text/JSON reports, HTML page; hide + confirmed
+  delete as the correction actions). Auto-draft remains gated on the
+  unlock conditions in `docs/memory-visibility-design.md`.
+
+- **D70 — visibility follow-ups: one number, one guard, one truth.** The
+  3-C review of D68/D69 found the surfaces honest individually and
+  inconsistent with each other. (1) **Every visibility surface discloses
+  truncation.** `memory_list` did; `open-memex list` — the command a
+  sceptical user runs first — silently showed 20 of 25. It now renders
+  the same structured line as the tool and states how many entries it
+  dropped, naming the command that shows everything. (2) **Numbers are
+  unique within a listing.** Ordinals ran per scope, so a single
+  `scope: both` output contained two `#1`s and "delete #3" was a guess;
+  the counter now runs across every section of one listing (tool, CLI and
+  the text report). (3) **A correction that touches the repo says so.**
+  The hard delete already did (D64); the soft hide did not, so a
+  retraction of an in-repo memory read as "hidden" while it was only a
+  local working-tree edit — the team still had the memory. Both surfaces
+  now name the commit and push. (4) **The report guard fails closed and
+  exists once.** `isInsideWorkTree` ran `git -C` on the output's parent
+  directory, so a not-yet-created directory made the check throw and
+  report "not in a worktree" — a fail-open on the one path where personal
+  memories would ride a commit; it now resolves the nearest existing
+  ancestor, reports a missing directory as itself, and both formats share
+  a single refusal helper instead of two copies. (5) **`open-memex-inventory/2`**
+  drops the absolute `file` path: the JSON renderer exists to be handed to
+  an agent, i.e. pasted into a cloud conversation, and it carried the
+  user's home directory. (6) Smaller honesty fixes: an empty scope is
+  reported as `(0)` instead of vanishing; only the HTML audit view loads
+  the hidden rows themselves (text/json pay for counts); the page's
+  "no network requests" claim is now enforced by a `default-src 'none'`
+  CSP rather than asserted; and `countList`'s comment states its one known
+  divergence (a self-healed dangling chain pointer) instead of claiming
+  equivalence. Deliberately NOT done, pending a decision: HTML i18n and a
+  size cap for very large stores.
 
-_All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._
+## Open Questions
 
-- **Checkpoint proactivity for capture (open, 2026-10-02):** D53 retired checkpoint *polling* — the server pushes draft counts instead. But agent proactivity at task checkpoints genuinely helps knowledge capture (§3.5 distillation), so the open question is the degree: proactive enough to catch distillable moments, without nagging the user or burning tokens at every checkpoint. Candidate directions (server-pushed hints in tool results, client-side heuristics, or a middle setting) to be evaluated in a later version; default posture TBD.
+_Some early questions are resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull). The entries below are open unless marked decided._
+- **Checkpoint proactivity for capture (open, 2026-10-02):** D53 retired checkpoint *polling* — the server pushes draft counts instead. But agent proactivity at task checkpoints genuinely helps knowledge capture (§3.5 distillation), so the open question is the degree: proactive enough to catch distillable moments, without nagging the user or burning tokens at every checkpoint. Candidate directions (server-pushed hints in tool results, client-side heuristics, or a middle setting) to be evaluated in a later version; default posture TBD. **Update (2026-10-03): decided in D61 — propose posture** (agent proposes 1–3 candidates at task checkpoints, saves only on approval; auto-draft deferred until memory visibility ships, see the MEMORY_VISIBILITY question below).
 
-- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases. **Status (2026-10-03): layer (1) shipped (D56, 0.6.1)** — query construction now filters EN/CJK function words, dedupes, and caps terms. Layers (2) agent-side expansion and (3) capture-time aliasing remain open; embeddings stay deferred.
+- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases. **Status (2026-10-03): layer (1) shipped (D56, 0.6.1)** — query construction now filters EN/CJK function words, dedupes, and caps terms. Layers (2) agent-side expansion and (3) capture-time aliasing remain open; embeddings stay deferred. **Update (2026-10-03): layers (2) and (3) shipped in D61** — agent-side expansion as guidance text on every surface, capture-time aliases indexed in their own FTS column behind the `captureAliases` flag. Embeddings stay deferred.
 
 - **Proactive capture: agent judgment of what is worth remembering (open, 2026-10-03):** companion to the checkpoint-proactivity question above — that one asks *when* to prompt; this one asks *what qualifies*. Agent hosts with good long-term memory (e.g. Muse) get their results from explicit memorability criteria plus checkpoint consolidation, not from silent background magic; open-memex can adopt both halves. Candidate criteria to teach via the skill/instructions: decisions **and their rationale**, preferences, conventions, gotchas, and abandoned paths ("we tried X, it failed because…") are worth proposing; one-off task details and anything re-derivable from the code are not. Two postures to evaluate: propose-at-checkpoint (agent asks "worth saving?", user vetoes, then `memory_add`) versus auto-draft (agent writes outbox drafts unasked and surfaces them in a batch at the next checkpoint — drafts are git-invisible and deletable, so the cost of a wrong guess is low). Hard boundaries either way: project scope never auto-submits, and no cross-session background consolidation is possible — the plugin lives inside sessions, so consolidation happens at in-session checkpoints and wrap-up passes only. This question also decides how much aliasing (retrieval question above) the capture pass should generate.
 
@@ -1230,7 +1533,7 @@ _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._
 
 - **Novice experience: first success and plain language (open, 2026-10-03):** from an AI-novice review. The install ends with instructions, not an experience: candidate fix is a 60-second magic moment — init offers to save one sample memory and immediately has the user's agent answer a question using it, so the user *sees* recall work before being asked to trust it. Same screen should state the privacy model in plain words (personal never leaves this machine, no cloud, detected secrets are masked — all already true, all currently buried in docs), and the first time a suspected secret is masked, the capture path should say so. Underneath: a plain-language layer over the state machine ("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. **Status (2026-10-03): partially addressed** — `init` now states the privacy model in plain words (D56); the 60-second magic moment and the plain-language layer remain open.
 
-- **Memory visibility and correctability (open, 2026-10-03):** also from the novice review, and arguably the trust foundation for every other feature. A non-CLI user currently cannot answer "what does my assistant remember about me?" without reading Markdown files. Candidate directions: a human-readable inventory (local HTML export or equivalent) listing memories in plain language with provenance shown the way a person asks for it ("saved 3 days ago while you were discussing deploys in project X") and one-step forget/undo from the same view. Provenance fields already exist in frontmatter; this is presentation, not schema. Without it, proactive capture (above) will read to novices as surveillance rather than help — so this question probably gates the auto-draft posture decision in the capture question.
+- **Memory visibility and correctability (open, 2026-10-03):** also from the novice review, and arguably the trust foundation for every other feature. A non-CLI user currently cannot answer "what does my assistant remember about me?" without reading Markdown files. Candidate directions: a human-readable inventory (local HTML export or equivalent) listing memories in plain language with provenance shown the way a person asks for it ("saved 3 days ago while you were discussing deploys in project X") and one-step forget/undo from the same view. Provenance fields already exist in frontmatter; this is presentation, not schema. Without it, proactive capture (above) will read to novices as surveillance rather than help — so this question probably gates the auto-draft posture decision in the capture question. **Status (2026-10-03): decided (D68)** — the inventory ships as structured list + text/JSON report with conversational rendering taught to agents; "one-step forget/undo from the view" was deliberately not built (deletion stays a confirmed conversation; soft-hide added instead); the HTML rendering follows separately. Auto-draft remains gated on the unlock conditions in `docs/memory-visibility-design.md`.
 
 ---
 

package/docs/memory-visibility-design.md

@@ -0,0 +1,130 @@
+# OpenMemex 3-C 设计稿：记忆可见性 inventory（v2 · 已按 review 修订）
+
+## 为什么先做这个（已定）
+
+2026-10-03 拍板：auto-draft 姿态等 3-C 记忆可见性出来再开。理由是信任顺序不能反——在用户能一眼看清"你到底记了我什么、每条是哪来的、怎么删"之前，agent 不经询问就往草稿箱里塞东西，只会读作监控而不是帮忙。3-C 就是补上这个"看得见、删得掉"的面。
+
+现状盘点（已核对代码，见文末"事实校正"）：
+
+- `memory_list`（D64 已支持 `scope: both`）输出是开发者格式：`- [type] [review_state] id=ULID — 片段`。**没有**生命周期状态、没有时间、没有来源（`source`/`created_at` 在 DB 里但没进 SELECT）。
+- `memory_status` 管的是同步队列（草稿箱/待审），不是"记忆全貌"。
+- 删除只有 `memory_forget`（硬删文件，无 undo）和 CLI `status retracted`（软藏，工具面没有这个动作）。
+- provenance 字段其实齐全：`source`（user/tool/keyword/inference/import）、`created_at`、`review_state`、`review_history`、`derived_from` 都在 frontmatter 里。**这是展示问题，不是 schema 问题**——3-C 不动 schema。
+
+## 三条硬约束（review 追加，先于功能）
+
+1. **personal 不出机器。** 单一产物不得默认落在 git 工作树里。报告同时含 personal + project 内容，`-o` 指到仓库里就是一次泄露——这不是概率问题，是一次误操作就到。
+2. **协议是冻结的（v0.2）。** 动 `memory_list` 的入参和输出格式就是动协议面：形状必须在实现前定死，实现 PR 里追加 D 条目，事后加就是破坏性变更。
+3. **可见性面不许静默截断。** 截断必须自报（与 D66 `sync-status` 的教训同源）。用户问"你记得我什么"而答案被悄悄砍掉一半，比没有这个面更伤信任。
+
+## 3-C 做什么
+
+### 一、聊天内清单（A 面，先做）
+
+把 `memory_list` 的输出改成**结构化行 + 稳定句柄**，让任何宿主的 agent 能直接拿它回答"你记得我什么"：
+
+```
+## 关于你（personal）
+3. [fact] id=01K6AB3XZQ7WVD9J1M2N4P5Q6R7 created=3d source=user — 喜欢简洁的 diff
+7. [preference] id=01K6AB3XZQ7WVD9J1M2N4P5Q6R8 created=12d updated=2d source=inference — 家里网络是双线负载
+## 当前项目（open-memex）
+1. [decision] id=01K6…R9 created=2d source=keyword [draft] — 发布走 alpha 线
+… 另有 34 条未显示（--limit 100，或用 memory_search 查具体内容）
+```
+
+要点：
+
+- **序号与 id 永远同时出现。** 序号是给嘴用的（"删掉第 3 条"），id 是给机器用的契约。删除确认语里带 id。
+- **时间用 `created_at`（学会的时间），不是 `updated_at`。** list 的排序键是 `updated_at`，而它在 supersede/promote 时会动；两者不同才补一个 `updated=`。别把"3 天前学的、2 天前改过"说成"2 天前"。
+- **输出里保留原始枚举，不写死中文短语。** `source=user` 对模型比对"你亲口说的"更可靠，也不锁语言、不锁措辞；人话短语（user→"你亲口说的"、inference→"我推断的"、keyword→"关键词自动抓的"）放进工具描述 + SKILL.md + MCP 握手，由 agent 按对话语言转述。仓库规则是"一个声音说指引"，不是"一个声音说数据"。
+- **入参（协议面，D68）**：`include: "active" | "all"`，默认 `active`。注意：**现在的 list 完全没有状态过滤**，所以"默认只列 active"是新行为——必须显式参数化并在 CHANGELOG 写明，不能悄悄改默认（依赖旧默认的 agent 会突然找不到 superseded 的链条）。`archived`/`retracted` 只在 `all` 下出现。
+- **截断自报。** `limit` 默认 20、上限 100 是既有事实。输出必须带真实总数 + 截断说明行（文案见上）。
+- **序号只在本次清单内有效**（顺序依赖 `updated_at`，会话中途一次 supersede 就可能重排）。指引里写死：被要求删某条时若只记得序号，先重新 `memory_list` 再复述内容确认，不要凭上一轮的序号映射。
+- review_state 标签沿用现状（personal 不显示，因为 `hitStateLabel` 对 personal 返回空）；`published` 常态不提。`memory_status` 的待审队列另有去处，两个面不混。
+- 指引文案四处同步（SKILL.md、`memory_list` 工具描述、MCP 握手、`distill-agents` 输出的 AGENTS.md 片段）：被问"你记得我什么"时调 `memory_list(scope: both)` 并用大白话复述、别甩内部 id；用户点名删某条时先复述那条内容确认再调 `memory_forget`。
+
+### 二、inventory 命令（B 面，三段走：text → json → html）
+
+CLI 新增 `open-memex inventory`，一个数据源、三种渲染：
+
+- `--format text`（默认，先行）：纯文本清单，~30 行代码，可在任何终端/CI 里 diff。**先用它验证清单格式本身对不对**，再谈 UI。
+- `--format json`：给 agent 用。agent 不该去解析 HTML——这条也让 A 面和 B 面共用同一份数据，未来加字段只改一处。
+- `--format html`（最后）：本地单文件，浏览器打开即看。按 scope 分组、纯静态、无脚本外链、无网络请求；页内一个本地过滤框（内嵌小 JS）。
+
+硬规则：
+
+- **HTML 必须全量转义。** 记忆正文可能来自 `import` 出来的包或粘贴的网页内容，`file://` 下一个没转义的 `<script>` 就是在用户自己浏览器里执行。过滤逻辑用 `input` + 事件委托，不用 `innerHTML`。
+- **默认输出到数据目录，不落工作树。** `--output` 指到 git 工作树内时**拒绝**，除非显式 `--allow-personal`（报告含 personal，这是 D62/铁律的边界，不是洁癖）。`export` 已有同类先例可循。
+- **每条给可复制的 id。** 不再只给"内容前 12 字"——截断、引号、内容改动都会让那句提示失效，而 id 不会。
+- **独立分节**：还没进仓库的（outbox，与 `memory_status` 计数一致）、折叠的"已替换 / 已隐藏"（含 `supersedes` 链接）。聊天清单里不出现历史，但报告里必须可审计——否则用户发现答案过时了却查不出它怎么变成过时的，最可能的反应是把旧事实重新加一遍。
+- **复用 `export.ts` 的 manifest/序列化**，不写第二个序列化器。两份实现必然漂移。
+- **规模**：条数很大时给分页或显式截断说明，不静默砍。默认 `--scope` 全量（personal + 当前项目），可加 `--scope` 过滤。
+- 报告只读，不放删除按钮、不回连本地服务（起 server 管端口违背本地优先的简单性，删除本来就该发生在有确认语的对话里）。
+
+### 三、纠正动作的诚实边界
+
+- **删除 = 硬删，无 undo。** 不假装有回收站。防呆全在对话层：agent 删除前**复述内容**、用户点头（写进指引）。复述的是内容不是序号。
+- **新增并列的软动作："先藏起来"（`retracted`）。** 语义现成（检索会排除 `retracted`），只是工具面没有——把它暴露成 `memory_forget --soft` 或一个 `memory_status` 入参即可。理由：不可撤销的动作有两种时，用户才敢选；只给"删"的清单会让人不敢删。不确定是不是该删的，就先藏。
+- **删除在序号上不做猜测。** 用户只给序号时，agent 先重新列清单、把候选内容念出来让用户点名。
+- 已进仓库的记忆被删 = 工作树删除，要 commit 才算数（`memory_forget` 已有该提示，保持；报告页脚注提一句，不当卖点）。
+- 清单和报告默认都不显示 `retracted`/`archived`/`superseded`（走 `include`/`--all`），报告的"已替换/已隐藏"折叠节是唯一的例外。
+
+### 四、与 auto-draft 的解锁关系
+
+3-C 落地后 auto-draft 的解锁条件（将来开 auto-draft 时回来对照）：
+
+1. A 面指引已教会 agent 在检查点汇报草稿箱存量（"我新存了 2 条草稿，你可以随时让我列出来"）；
+2. B 面报告存在，且草稿箱一节与 `memory_status` 计数一致；
+3. 删除路径在清单语境里验证过（序号→id 映射、复述确认语、仓库内删除的 commit 提示）；
+4. 软藏（retract）路径在清单语境里验证过（agent 能藏、能列出被藏的、用户知道怎么取消——若不做，则明确记录"只有硬删"是当前的诚实边界）。
+
+**回滚条款（现在就写下来）：** 开了 auto-draft 之后，如果用户仍说不清库里到底有什么、或者第一反应是要求清库而不是用起来，就退回 D61 的 propose 姿态（agent 提议、用户点头），而不是继续加提示。
+
+**度量：** 本地优先、不带遥测，所以度量只能是人工的：找 5–10 个真实用户做同一个任务——"在 30 秒内找到并删掉一条你知道被记下来的事"，记录卡在哪一步（找不到 / 不敢删 / 不知道删的是哪条）。这个任务同时验证可见性和纠正动作，比任何问卷都准。
+
+## 事实校正（review 逐条核对代码，与原稿有出入的地方）
+
+- `list()` 只显示 `review_state`，**不显示生命周期 `status`**；而且 `hitStateLabel` 对 personal 直接返回空串（`src/retrieve/search.ts:73`）。原稿"有 status/review_state"只对了一半。
+- 索引里的 `created_at`/`updated_at` 是 INTEGER epoch ms（`src/store/db.ts:46-47`），RFC3339 只存在于 frontmatter。
+- `list()` 的排序键是 `updated_at DESC`，`limit` 默认 20、上限 100（`src/retrieve/search.ts:217-225`）——"3 天前"和"截断"两个问题都源于此。
+- 索引里 `source` 列已存在（`src/store/db.ts:43`），补 SELECT 即可，不需要重建索引。
+- `loadConfig` 是浅合并 `{...DEFAULT_CONFIG, ...parsed}`（`src/config.ts:226`）：用户自定义 `keywordPatterns` 会**整表替换** 12 条默认 pattern。这是"后续一件"的形态依据，也是现在的脚枪。
+- 坏正则被静默跳过（`src/capture/keywords.ts` 的 `catch { continue }`）——自定义 pattern 校验要补的就是这一条。
+- `loadConfig` 已有"对用户可写的字段做加载期校验"的先例（`memoryDir`，`src/config.ts:231`），列表键照此办理。
+
+## 不做（明确划出）
+
+- 本地 Web 服务 / 可点击回连的 UI（起 server 那套）。
+- undo / 回收站机制（软藏 `retracted` 不是回收站：它不进清单，但也不可恢复）。
+- 新 frontmatter 字段、新 schema 版本（"你确认过"这类概念本稿不承诺——schema 里没有确认态，只有 `source` 和 `review_history`）。
+- 报告的自动定时生成（用户想看时手动跑，或让 agent 跑）。
+- 任意正则的自定义触发词（先做 curated 开关，见下）。
+
+## 实现清单（估大小）
+
+| 块 | 内容 | 量 |
+|---|---|---|
+| 清单格式 | list 查询补 `source`/`created_at`；`include` 入参；输出改结构化行（序号+id+相对时间+来源）、截断自报 | 小 |
+| 纠正动作 | `memory_forget --soft`（或 status 入参）；指引文案里的复述确认语与序号失效规则 | 小 |
+| inventory text | `--format text`：复用 manifest 序列化，两 scope + outbox 一节 | 小 |
+| inventory json | `--format json`：同一数据源，给 agent | 小 |
+| inventory html | 单文件 HTML：转义、过滤框、`--output` 工作树拒绝、折叠历史节、规模处理 | 中 |
+| 测试/文档 | test-full 加清单格式/截断自报/软藏/html 转义/工作树拒绝；README 双语、CHANGELOG、V2-DESIGN 追加 D68 同 commit | 小 |
+
+建议 PR 切分：A（清单格式 + 纠正动作 + text/json）一个 PR，HTML 一个 PR——HTML 是呈现层，格式先被 text/json 验证过再上。
+
+版本号：本稿不动版本；实现时按当时 alpha 线递增（Stone 2026-10-03 定："3C 时换版本号"）。实现 PR 必须同时在 `docs/V2-DESIGN.md` 追加 D68（协议面改动：`memory_list` 入参 + 输出格式）。
+
+## 后续一件（3-C 之后单独实现，不进本组）
+
+**用户自定义关键词触发模式**（Stone 2026-10-03 提出）：D67 把 `don't forget …` / `别忘了…` 裸形收紧为需要分隔符或 `that`，但裸形正是部分用户的习惯说法（Stone 本人就是）。默认保持收紧，另给一条加回来的路，分两步：
+
+1. **curated 开关（先做）**：`narrationTriggers: false`（默认关）。打开即恢复 D67 收紧的那几个裸形。代价写在文档里——召回上去了，误捕叙事的风险也回来了，这是明确的取舍而不是 bug。
+2. **追加式自定义 pattern（后做）**：`keywordPatternsExtra` / `keywordPersonalPatternsExtra`，**追加**在默认表之后（不是替换——`config.ts:226` 的浅合并会让整表替换，用户加一条就丢掉其余 12 条）。需要：`config set` 的列表键校验、set 时编译正则并报错（现在坏正则被静默跳过）。
+
+## 待你拍板（剩余项；不回我按推荐走）
+
+1. **软藏进不进工具面？** 推荐进：`memory_forget --soft`（最小改动，复用现有语义与检索排除逻辑），可撤回的前提是"能藏"这个动作存在。
+2. **HTML 过滤框的交互？** 推荐：条数 ≤ 50 全展开，超过则历史折叠、内容按 scope 折叠；过滤框始终可见。
+3. **`inventory --scope` 默认值？** 推荐默认全量（personal + 当前项目），因为"看不见"正是本组要治的病。
+4. **D68 落在哪个 PR？** 推荐随 A 面那个 PR 一起落（协议面与实现同 commit）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.6.2",
+  "version": "0.7.0-alpha.11",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",
@@ -17,7 +17,7 @@
     "typecheck": "tsc --noEmit",
     "cli": "node --experimental-strip-types src/cli.ts",
     "mcp": "node --experimental-strip-types src/mcp.ts",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/build-stamp.mjs",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/postinstall.js"
   },