dsh-context-memory 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,315 @@
 # Changelog
 
+## 0.9.0
+
+**A memory a check contradicts is no longer offered as guidance, Chinese queries return
+results, a project's memory follows the project rather than the launch directory, the model
+can ask what is remembered, a guard can read a file's structure instead of scanning its
+text, and an ordinary declarative sentence is offered for confirmation instead of being
+silently dropped or silently kept.**
+
+These close defects that made the plugin quietly worse than having no memory at all, and
+add the two abilities the design was missing: a structural check, and a capture rule wider
+than an explicit verb.
+
+### A contradicted memory is filtered out, not down-weighted
+
+`verify` has always sorted outcomes three ways, but the verdict never reached recall:
+the fold recorded `verification` on the state and left `status: 'active'` alone, and
+`scoreMemory` deducted 0.2 from the score. So a memory the filesystem had explicitly
+denied still ranked, still fit under `Relevant memories from previous sessions`, and
+still reached the model — as advice. That is worse than the plugin not existing, because
+the user believes the agent has remembered something.
+
+The population is now split. `guidance()` and `recall()` exclude contradicted memories;
+`contradicted()` returns them; the panel lists them under their own heading; and the
+pre-step renders them as a separate block that says not to rely on them and to correct
+or supersede them. They stay in the log — a memory the world disproved is the most
+informative record it holds — and they are never ranked.
+
+A `broken` check still says nothing about the memory: an unusable check leaves the
+memory in `guidance()`. Only `violated` is evidence.
+
+Conflicts are computed over guidance only. A memory whose check denied it is not an open
+question — the world already answered it — so presenting one as a live conflict would be
+the opposite of resolving it.
+
+### Chinese recall was zero
+
+`tokenize` split on `/[^a-z0-9_.-]+/`, which is every CJK code point, so any Chinese query
+produced an empty token list and matched nothing:
+
+```
+tokenize('这个项目构建用 pnpm')  → ['pnpm']
+tokenize('构建用什么')           → []
+```
+
+`capture.ts` had always accepted Chinese memory verbs, so the plugin could store Chinese
+statements and never find them again.
+
+CJK runs are now cut into overlapping 2-grams alongside the existing Latin tokens —
+`构建用什么` becomes `构建 / 建用 / 用什 / 什么`. Two characters is the smallest unit that
+carries meaning in Chinese, and 2-grams need no dictionary, no dependency, and no model.
+Straddling grams are what let a query match a memory whose surrounding wording differs.
+
+### Memory follows the project, not the process
+
+`apply()` used `resolve(process.cwd())`. dsh sessions carry their own working directory,
+and it can move: `workingDirectory.set()` is called by the worktree plugin and the SDK
+server. So a session started one level down inside a checkout wrote to a different log,
+and a session that moved wrote somewhere else again.
+
+The pre-step now asks the host — `ctx.workingDirectory.ensure(agent, signal)` — and falls
+back to the session header's original `cwd`. `findProjectRoot` then climbs to the top of
+the checkout, which is what makes `packages/app/src` and the repository root the same
+project. The marker set is `.git` and `pnpm-workspace.yaml`; `package.json` is
+deliberately not one, because a stray `package.json` in a home directory would merge every
+unrelated folder beneath it into one project.
+
+The CLI resolves the same way, so `cd packages/x && dsh-context-memory list` sees the
+root's log. Subagents are skipped: they run in their own session and must not inherit the
+parent's project just by sharing a process.
+
+### Two scopes instead of one
+
+A project convention and a working preference are different claims. `remember` takes a
+`scope`: `project` (default, `<projectRoot>/.memory/`) or `user`
+(`$DSH_HOME/context-memory/`, resolved through `@deepseek-ai/dsh-home-paths`). The fold
+reads both logs; a memory carries the scope it was written under, and the two populations
+do not leak into each other. The CLI gains `--scope` and `--global`, the panel route
+accepts `scope`, and a log written by 0.8.x reads as `project`, which is what it was.
+
+The id is unchanged by scope, so promoting a statement from project to user keeps its
+identity visible rather than appearing as two unrelated hashes.
+
+### `verify` can run without writing
+
+`verify(now, { record, changedOnly })`: `record: false` computes results without appending;
+`changedOnly: true` appends only when the outcome differs from the last recorded one. The
+pre-step re-checks at most once a day and uses `changedOnly`, so guarding against staleness
+no longer grows the log by one line per memory per day.
+
+### The plugin did not load on the runtime it was built for
+
+The peer set was pinned to `0.2.0-rc.2`. The installed dsh is `0.2.1-rc.2` — both the
+CLI and the desktop app — and `dsh` refuses to mount a bundle whose peers disagree with
+the running version:
+
+```
+dsh: skipping profile bundle "dsh-context-memory": Error: Plugin
+dsh-context-memory@0.9.0 is incompatible with dsh 0.2.1-rc.2 ...
+```
+
+That is a hard skip, not a warning: nothing in this release would have run. Peers are now
+`^0.2.1-rc.2` (which `semver` reads as "≥ 0.2.1-rc.2 and < 0.3.0"), with
+`@deepseek-ai/cordis` at `~4.0.5`, matching the versions the official 0.2.1-rc.2 plugins
+declare.
+
+`@deepseek-ai/dsh-working-directory` is a **devDependency only**. It is imported for its
+types — the package augments cordis's `Context` with `workingDirectory`, so the call site
+is checked against the signature the host was built with instead of a hand-written mirror
+— and `import type {}` erases at build time, so there is nothing to resolve at runtime.
+`src/working-directory.ts`, which restated that interface by hand, is gone.
+
+### `workingDirectory` is read opportunistically, not required
+
+`export const inject = ['workingDirectory']` was wrong, and measurably so. That service is
+mounted by a row in the `dsh-base` bundle's patch, and this machine's global install has
+`@deepseek-ai/dsh-base@0.2.0-rc.2` next to `dsh@0.2.1-rc.2` — npm reports it as
+`invalid`, the host boots anyway, and the row that mounts `working-directory` is simply
+absent. Declaring the dependency made the whole plugin wait:
+
+```
+dsh-context-memory (dsh-context-memory): pending (waiting for service: workingDirectory)
+```
+
+A pending fiber is indistinguishable from an absent one: no pre-step, no service, no
+recall. It now reads `ctx.get('workingDirectory')` — which returns `undefined` rather than
+throwing for an unprovided service, confirmed against cordis 4.0.5 — and falls back to the
+session header's `cwd`, which is what the plugin used before it knew the service existed.
+`inject` is `[]`.
+
+`tests/activation.test.mjs` is new and covers both cases: the empty declaration, and a
+full pre-step on a host with no `workingDirectory` service at all. These are the checks the
+rest of the suite could not make — every other test constructs `ContextMemory` directly,
+so all of them pass on a plugin the host would refuse to load.
+
+### The model can ask, not only be told
+
+Memory had one direction: the pre-step pushes what the plugin thinks is relevant. A model
+that needed to know "what did we already decide about this" had no way to ask, so the one
+question memory exists to answer was the one it could not pose.
+
+Two tools now fill the pull half.
+
+`memory_recall(query?, limit?, include?)` ranks stored memories and returns each with its
+id, kind, scope, and verification state. `include` selects the population — `guidance`
+(default), `contradicted`, `superseded`, `all` — and the default deliberately matches what
+the push path may offer. The two directions want different answers to "what is true":
+unsolicited text influences the turn, so it may only carry guidance; an answer to a
+question someone asked may include what a check disproved, if they asked for it by name.
+Omitting `query` returns the newest rather than nothing, because "what do you remember"
+has no lexical content to rank.
+
+`memory_remember(text, kind?, subject?, scope?)` records with `source: 'agent'`, so the
+panel still separates what the user said from what the model wrote down. The reply carries
+the compiled check, or says plainly that none could be compiled. A statement already on
+file reports `updated: true` with its original id and creation time — the log is
+append-only and folds by id, so the honest answer is "refreshed", not "recorded".
+
+Both register through `ctx.inject(['tools'])`. A static `inject` entry would make the tool
+registry a precondition for the whole plugin, and this plugin must keep working on a host
+that mounts none — the CLI, a headless profile. There, exactly two tools are absent and
+everything else runs. `tests/activation.test.mjs` asserts that.
+
+`tests/tools.test.mjs` runs both through a real `ToolRuntime` rather than calling the
+executor: `defineTool` compiles the schema at registration and validates arguments and
+output per call, so a direct call would pass on a definition the registry rejects.
+
+Writing these tests found a real gap in the injection path as well. `runGuard` reports a
+reason when a check *cannot run*, but a check that ran and came back false returns an
+empty `output` — so every contradicted memory was rendered as "contradicted" with no
+indication of which path or string had been tested. `describeContradiction` now falls back
+to the check's own description, and the pre-step block and `verify` output both use it.
+
+### Guards can read a file's structure, not only its text
+
+Four predicates answered questions about a file's *text*. That made the most common
+verifiable claims in a JS/TS project uncheckable, and the workaround was worse than
+admitting it: `the file package.json contains tsx` compiles, passes, and verifies nothing —
+`tsx` is in the description, in a `files` entry, or inside another script's command string.
+A memory that has never been checked is honest; one whose check passes for the wrong reason
+is not.
+
+Four structured predicates now parse the file instead of scanning it:
+
+| Statement | Predicate |
+|---|---|
+| `package.json depends on X` / `does not depend on X` | `depends` — a key in `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies` |
+| `package.json script build runs tsc --noEmit` / `has no deploy script` | `script` — exact value of `scripts.build` |
+| `tsconfig enables strict` / `does not enable strict` | `option` — top level or `compilerOptions` |
+| `the file X has at most N lines` / `at least N lines` | `lineLimit` — content lines |
+
+Still no shell: `JSON.parse` and a line count are in-process. The memory still supplies
+operands only — a key name, a script name, a bound — never a program.
+
+Three decisions in there are load-bearing:
+
+- **Exact script match, not prefix.** `build runs tsc` and `build runs tsc --noEmit` are
+  different claims; a prefix match would let one verify the other.
+- **`compilerOptions` is searched.** Every real `tsconfig.json` puts `strict` inside it, so
+  a top-level-only lookup would report a correct memory as `violated` — and a false
+  contradiction is the one outcome this module must not produce.
+- **A negated option means "not on", not "not present".** `tsconfig does not enable strict`
+  carries `value: true, absent: true`, so an explicit `"strict": false` satisfies it. Testing
+  only for key absence would call that memory violated.
+
+`usableGuard` changed from four `||` comparisons to a whitelist. An unknown `kind` — from a
+newer version, or a hand-edited log — is dropped and the memory becomes `uncheckable`,
+instead of reaching `runGuard` and being answered by whichever branch its fallthrough
+happens to be.
+
+One gap surfaced while shaking out the real host: a `lineLimit` guard with neither `max`
+nor `min` (only reachable from a hand-edited log) counted the lines and reported `passed`,
+which is a check that verified nothing. It is `broken` now, and tested.
+
+### Capture notices more, but writes only what was asked for
+
+The capture rules required an explicit verb — "记住…", "remember that…", "以后…". That
+kept the log clean and made the plugin miss the most ordinary way a person states a fact:
+"我们用 sqlite 存会话数据" is exactly the kind of thing a memory is for, and nothing
+captured it.
+
+Widening the regex would have been the wrong fix. The same sentence shape produces "we use
+sqlite" and "we use two queues in this diagram"; a rule that cannot tell them apart and
+writes both is a rule that makes recall worse than the narrow one it replaced.
+
+So capture now has two tiers, and the wide one does not write:
+
+| Tier | Trigger | Outcome |
+|---|---|---|
+| explicit | a memory verb | written to the log, as before |
+| implicit | a declarative shape plus a technical token | **proposed**, in `.memory/candidates.jsonl` |
+
+A proposal becomes a memory only when someone accepts it — from the panel's 「待确认」 card
+or with `dsh-context-memory accept <id>`. Dismissing records the answer, so the same
+sentence is not offered again on every step.
+
+What the proposal rule actually requires, and why each condition is there:
+
+- **A technical token** (`pnpm`, `@scope/pkg`, a path) — the only cheap proxy for
+  "something a future reader could act on". Without it, "我们用两个队列" becomes a candidate.
+- **Not a question, not a directive** — "我们用 sqlite 吗？" asks, and "帮我用 pnpm 装一下"
+  instructs this turn; neither is a claim about the project.
+- **At most three per message** — a message that trips more patterns is usually about
+  something else, and ten rows at once get ignored exactly like none.
+
+The queue is a second append-only log beside `events.jsonl`, folded the same way. Two
+processes reading it agree on which questions are open, and "we offered this and you
+declined" stays answerable. A candidate has no scope, no guard, and no claim on recall;
+`accept` is the only path from a heuristic into the log, and it writes with
+`source: 'user'` because a person said yes.
+
+`tests/candidates.test.mjs` (13) checks that boundary from both sides — pending never
+appears in `recall`, accepting writes once, dismissing writes nothing, and a decided id
+cannot be re-answered. `tests/routes.test.mjs` (6) covers the panel route, including the
+one that matters: there is no route that remembers an unaccepted proposal.
+
+### Declarations
+
+`src/scope.ts` is new (root discovery, user path). `src/tools.ts` is new.
+`src/candidates.ts` is new (the append-only proposal queue). `MemoryStore`
+now takes the `.memory` directory rather than the project directory, because the caller is
+the one that knows which scope it is. `ContextMemory.record` returns the memory plus
+whether it already existed, so the tool does not have to re-derive the id to answer that.
+`recall` and `ContextMemory.recall` take a trailing `target`, defaulting to `guidance`.
+`Guard` grows from four members to eleven (eight predicates; three with a negated variant).
+`runGuard` is a flat dispatch per kind rather than "exists/absent, then read and search",
+which is what let the structured kinds be added without each one inheriting the text
+branch's assumptions. `ContextMemory` gains `propose` / `candidates` / `accept` / `dismiss`,
+where `accept` is the only method that writes a candidate into the log.
+
+138 tests, up from 60. Of those, 110 came with the recall/guard work (four activation,
+eight tool, twenty-two guard); the widening added eight capture cases, thirteen for the
+queue itself, six through the real route registration, and one that runs a declarative
+statement through the real `agent/pre-step` waterfall and asserts it is proposed, not
+remembered.
+
+
+
+## 0.8.0
+
+**Checks are evaluated against the filesystem instead of compiled into shell commands.**
+
+A guard used to be a shell command string, run through
+`spawnSync(..., { shell: true })`, with a different spelling per platform. That made the
+one question this module exists to answer — did the check run at all? — undecidable on
+Windows: cmd.exe reports both "the program is missing" and "the check ran and failed" as
+exit status 1, and its own diagnostic is a localized resource string. On a zh-CN host it
+arrives as GBK bytes decoding to mojibake under `utf8`, so a classifier reading the text
+answered differently depending on the system language. It also meant a guard could not
+distinguish the two outcomes the plugin is built around, so a defective check could mark
+a true memory as contradicted.
+
+`Guard` is now a predicate over the filesystem — `exists`, `absent`, `contains`,
+`lacks` — with a path and, where relevant, a search string. Evaluation is `fs`, so:
+
+- Nothing from memory text is executed. A statement supplies operands, never a program,
+  an argument list, or shell syntax; `$(whoami)` in a path is a filename, not a command.
+- There is no quoting layer to get wrong, and no `%VAR%` expansion inside quotes.
+- The result does not depend on the host language, because no output is parsed.
+- `broken` (the check could not be carried out: a directory named as a file, a path the
+  filesystem refuses to answer for) is now a fact about a return value rather than a
+  guess about stderr, and it still never reaches the caller's exit code.
+
+Guards recorded by earlier versions as `{ command }` are dropped on fold, so those
+memories report as `uncheckable` — honest about not being runnable here — rather than
+being read through a shape this version no longer understands. The log itself is not
+rewritten.
+
+`shellQuote` and `compileGuard`'s `platform` parameter are gone, and `classify` no longer
+takes an output string. `describeGuard` renders a check for the CLI and the log.
+
 ## 0.7.1
 
 **Client half now type-checks against the host's own client types.**
@@ -12,6 +322,7 @@ registration signature requires before it will accept `locale: NS`.
 
 That check immediately found missing dictionary keys: strings the panel asked for that
 neither dictionary defined (they rendered as the raw key). They are now translated in both.
+
 ## 0.7.0
 
 **dsh 0.2.0-rc.2 alignment: host-provided packages move to pinned peer dependencies.**
@@ -26,6 +337,7 @@ The recall message this plugin injects now declares its own `MessageSourceMap` k
 (`dsh-context-memory`, form `recall`). 0.2.0-rc.2 removed the shared catch-all `plugin` kind:
 a producer declares its own kind by augmenting the map in its own module, as the official
 `dsh-agent-loop` does for `runtime-context`.
+
 ## 0.5.1
 
 **Fixed: the previous release only covered `ui.tsx`.**

package/README.md

@@ -29,15 +29,20 @@ This plugin keeps it, and — unlike a note file — re-checks the parts that ca
   answer.
 - **Recall.** Retrieval is ranked (token overlap, recency, verification strength) instead
   of pasting every memory into the context window. Each hit reports the breakdown of its
-  score, so a ranking is never something you have to trust.
+  score, so a ranking is never something you have to trust. Chinese and English are
+  tokenized equally, so a Chinese question finds a Chinese memory.
 - **Forget with a reason.** A memory is superseded, never deleted. The wrong memories are
   the most valuable records in the log — they are the only thing that can explain a past
   decision.
 - **Conflict detection.** Two active memories about the same subject are reported as a
-  conflict. The plugin does not pick a winner; the log does not say which one is right,
-  and guessing would be the unfounded assertion this plugin exists to remove.
+  conflict, with both texts shown. The plugin does not pick a winner; the log does not say
+  which one is right, and guessing would be the unfounded assertion this plugin exists to
+  remove.
 - **Verification.** A memory whose statement has a checkable shape is compiled into a
-  platform-aware guard and re-checked on demand. This is the part a notes file cannot do.
+  guard and re-checked — automatically at most once a day, and on demand from the CLI or
+  the panel. This is the part a notes file cannot do.
+- **Two scopes.** A convention of this checkout and a preference that follows you are
+  different claims, and they are stored in different logs.
 
 ## The point
 
@@ -62,32 +67,111 @@ passed 1, violated 1, broken 1, uncheckable 1
 
 Four outcomes, and the distinction between them is the whole point:
 
-| Outcome | Meaning |
-|---|---|
-| `passed` | The check ran and the memory holds. |
-| `violated` | The check ran and the world disagrees with the memory. |
-| `broken` | The check itself could not run — a typo, a missing binary. **Not** evidence about the memory. |
-| `uncheckable` | No check could be compiled. The memory is still stored and recalled; it is just not verified. |
+| Outcome | Meaning | Reaches the model as guidance? |
+|---|---|---|
+| `passed` | The check ran and the memory holds. | yes, and it ranks higher |
+| `violated` | The check ran and the world disagrees with the memory. | **no** — reported separately as contradicted |
+| `broken` | The check itself could not run — its operand is unreadable. **Not** evidence about the memory. | yes |
+| `uncheckable` | No check could be compiled. The memory is still stored and recalled; it is just not verified. | yes |
+
+A `violated` memory stays in the log and in the panel, but recall skips it and the
+injected context puts it in its own block, marked as not to be relied on. A claim the
+filesystem denies has no score at which it is safe to hand to the agent, so it is filtered
+rather than down-weighted.
 
 `verify` exits non-zero **only** for `violated`. A broken guard is a defect in the check,
 and letting it turn a pipeline red is how a typo would get a true memory marked false —
 after which you learn to ignore the output.
 
 Nothing is ever marked as verified because it was stored, and a memory supplied by the
-agent is never executed as a command: guards come from templates that only ever
-interpolate quoted file paths and literal search strings.
+agent is never executed: a guard supplies a path and a search string to `fs`, never a
+program or an argument list.
+
+### What can be checked
+
+Eight statement shapes compile to a guard. Four are about a file's text; four are about a
+file's structure, which is answered by `JSON.parse` and a line count — still in-process,
+still with no program taken from the memory.
+
+| Statement | Predicate | Read as |
+|---|---|---|
+| `the file X exists` / `never commit X` | `exists` / `absent` | `fs.stat` |
+| `the file X contains Y` / `the file X must not contain Y` | `contains` / `lacks` | substring |
+| `package.json depends on X` / `package.json does not depend on X` | `depends` | key in `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies` |
+| `package.json script build runs tsc --noEmit` / `package.json has no deploy script` | `script` | exact value in `scripts` |
+| `tsconfig enables strict` / `tsconfig does not enable strict` | `option` | top-level or `compilerOptions`; `jsconfig` works too |
+| `the file X has at most N lines` / `at least N lines` | `lineLimit` | content lines, not a trailing newline |
+
+The structural predicates exist because the text ones cannot answer structural questions
+honestly. `the file package.json contains tsx` passes when `tsx` appears in a description,
+a `files` entry, or another script's command string — a check that reports `passed` while
+verifying nothing. `package.json depends on tsx` reads the key. Likewise a script command
+is matched exactly, not by prefix: `build runs tsc` and `build runs tsc --noEmit` are
+different claims and must not verify each other.
+
+Everything else stays `uncheckable`, deliberately. `the build uses pnpm` needs a
+definition of "build tool"; any approximation would produce a check that passes for some
+other reason. A statement with no unambiguous predicate is more honest left unverified.
+
+## Where memories live
+
+| Scope | Directory | Use it for |
+|---|---|---|
+| `project` (default) | `<projectRoot>/.memory/` | build tooling, layout, pitfalls of this checkout |
+| `user` | `$DSH_HOME/context-memory/` | preferences that follow you across every project |
+
+The project root is found by climbing to the nearest `.git` or `pnpm-workspace.yaml`, and
+the session's own working directory is what the climb starts from — so a session opened in
+`packages/app/src` and one opened at the root share a log. A directory with no marker above
+it is its own project.
+
+The session directory comes from the host's `workingDirectory` service when one is
+mounted, and from the session header's `cwd` when it is not. The plugin does **not**
+declare that service as a dependency: it is only mounted by hosts whose `dsh-base` bundle
+includes it, and declaring it would leave the whole plugin `pending (waiting for service:
+workingDirectory)` on a host that does not — which looks exactly like the plugin not being
+installed.
 
 ## CLI
 
 ```sh
 dsh-context-memory remember "the file package.json exists"
+dsh-context-memory remember "always answer in Chinese" --global
 dsh-context-memory list
-dsh-context-memory recall "how do we install"
+dsh-context-memory recall "构建用什么"
 dsh-context-memory conflicts
+dsh-context-memory candidates      # statements noticed but not remembered
+dsh-context-memory accept 4f2a9c1b8e30
+dsh-context-memory dismiss 9c1e77b0d3aa
 dsh-context-memory forget 4f2a9c1b8e30 "moved to bun"
 dsh-context-memory verify        # exit 1 only on a real violation
 ```
 
+## Model tools (pull)
+
+Injection is one direction only. Two tools give the model the other one, so it can ask
+rather than wait to be told:
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `memory_recall` | `query?`, `limit?` (1–20, default 5), `include?` | Matching memories with id, kind, scope, and verification state |
+| `memory_remember` | `text`, `kind?`, `subject?`, `scope?` | The new id, and the check that will re-verify it (or an explicit "none could be compiled") |
+
+`memory_recall`'s `include` chooses the population: `guidance` (default — active and not
+contradicted), `contradicted`, `superseded`, or `all`. The default matches what the push
+path may offer, because unsolicited text and an answer to a question are not the same
+thing; widening it is a per-call decision the caller makes by name. Omit `query` to list
+the newest memories instead of the most relevant — "what do you remember" has no lexical
+content to rank.
+
+`memory_remember` writes with `source: 'agent'`, so the panel can tell what the user said
+from what the model decided to write down. A statement already on file reports
+`updated: true` with its original id and creation time, rather than claiming a new record.
+
+Both tools are registered through `ctx.inject(['tools'])`, not a static dependency. A host
+with no tool registry — the CLI, a headless profile — loses exactly these two tools and
+nothing else; the pre-step, the service, and the panel keep working.
+
 ## Auto capture and recall injection (0.6.0+)
 
 The plugin hooks into `agent/pre-step` to close the loop automatically:
@@ -99,36 +183,79 @@ The plugin hooks into `agent/pre-step` to close the loop automatically:
 
 - **Recall injection.** Before each agent step, the top-5 memories whose subject
   overlaps the user's text are folded into the request as a collapsible context message
-  (source `plugin/dsh-context-memory`, form `recall`). Unresolved conflicts are included
-  with a warning. The injection position is right after the claimed batch — the same
+  (source `plugin/dsh-context-memory`, form `recall`). Contradicted memories go into a
+  separate block marked as not to be relied on, and unresolved conflicts are listed with
+  both sides. The injection position is right after the claimed batch — the same
   slot the host's own context plugins use.
+- **Automatic re-verification.** At most once a day, the guards are re-run before the
+  recall is composed, so a memory the world has since disproved is never offered in the
+  very step that would have used it. Only a changed outcome is appended to the log.
+
+- **Candidate proposals.** Statements that look like durable facts but were never asked to
+  be kept — "我们用 sqlite 存会话数据" with no "记住" — are proposed to the panel instead of
+  being written to the log. Accepting one turns it into a memory; dismissing it records
+  the answer so it is not asked again. See below.
 
 Both features can be toggled from the panel's 「集成」 card. When auto capture is off,
 memories are still stored via the CLI and service API. When recall injection is off,
 the plugin still records but does not inject.
 
+## Candidates: what the plugin noticed but was not allowed to keep
+
+Explicit verbs are safe to act on because the user asked. Widening the patterns to
+ordinary declarative sentences is not: the same shape produces "we use sqlite" and "we use
+two queues in this diagram", and writing both to the log makes recall worse than the
+narrow rule it replaced.
+
+So the wide net **proposes** and does not write:
+
+| Step | Where it lives | Effect on recall |
+|---|---|---|
+| A declarative sentence with a technical token is noticed | `.memory/candidates.jsonl` | none — it is not a memory |
+| You accept it (panel, `accept <id>`) | `.memory/events.jsonl` | it becomes a memory, `source: 'user'` |
+| You dismiss it (`dismiss <id>`) | stays in `candidates.jsonl` as dismissed | none, and it is not proposed again |
+
+What the proposal rule requires, in order: not a question, not a directive to the agent,
+at least six characters, and a token that looks like a name (`pnpm`, `@scope/pkg`, a path).
+That last condition is what separates "we use pnpm" from "我们用两个队列" — the first names
+something a future reader could act on, the second is ordinary conversation. At most three
+are proposed per message; a message that trips more patterns is usually about something
+else.
+
+The queue is append-only and folded the same way the memory log is, so two processes
+reading it agree on which questions are still open, and "we offered this and you declined"
+stays answerable.
+
 ## Panel
 
-A `Context memory` page inside Settings: active and superseded memories, verification
-status per memory, conflicts, provenance, and integration toggles. The host registers
-`GET /api/context-memory.panel` and rebuilds the payload from the log on every request,
-so the panel shows what is on disk rather than what was in memory at startup. A headless
-host has no web connection and simply skips the route.
+A `Context memory` page inside Settings: active, contradicted, and superseded memories,
+verification status per memory, conflicts, provenance, and integration toggles. The host
+registers `GET /api/context-memory.panel` and rebuilds the payload from the log on every
+request, so the panel shows what is on disk rather than what was in memory at startup. A
+headless host has no web connection and simply skips the route.
 
 ## Layout
 
 | Path | Role |
 |---|---|
 | `src/index.ts` | Host half — `apply(ctx)`, exposes the `contextMemory` service |
-| `src/memory.ts` | Fold the log, remember, supersede, conflicts, verify |
-| `src/store.ts` | Append-only `.memory/events.jsonl` |
-| `src/guard.ts` | Statement → platform-aware check; run it; classify pass / violated / broken |
-| `src/recall.ts` | Relevance ranking with an explainable score |
+| `src/memory.ts` | Fold the logs, remember, supersede, conflicts, verify |
+| `src/store.ts` | Append-only `.memory/events.jsonl` for one scope |
+| `src/scope.ts` | Project-root discovery and the user-global directory |
+| `src/guard.ts` | Statement → filesystem predicate; run it; classify pass / violated / broken |
+| `src/recall.ts` | Relevance ranking with an explainable score; CJK 2-gram tokenizer |
 | `src/identity.ts` | Id derived from the normalised subject, so repeats fold |
+| `src/capture.ts` | Pure distiller: explicit verbs in, statements out; wide-net proposals |
+| `src/candidates.ts` | Append-only proposal queue — noticed, decided, never auto-remembered |
 | `src/cli.ts` / `src/bin.ts` | Command-line entry, usable without dsh |
+| `src/tools.ts` | Model-facing `memory_recall` / `memory_remember` |
 | `src/routes.ts` | Panel and verify routes on the host's web connection |
 | `src/client/view.tsx` | Browser half — pure rendering, statically tested in Node |
 | `src/client/index.tsx` | Browser half — fetch and settings registration |
+| `tests/activation.test.mjs` | Boots the plugin in a real cordis `Context` — the checks the rest of the suite cannot make |
+| `tests/tools.test.mjs` | Runs both tools through a real `ToolRuntime` — registration, argument validation, output validation |
+| `tests/candidates.test.mjs` | Proposals are questions: they never reach recall without an acceptance |
+| `tests/routes.test.mjs` | The candidate route table on a real connection registration |
 
 ## Why the log is append-only
 

package/icon.svg

@@ -0,0 +1,16 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect x="5" y="6" width="26" height="24" rx="6" stroke="url(#memory-frame)" stroke-width="2.5" />
+  <path d="M10.5 12.5h15M10.5 18h15M10.5 23.5h8" stroke="#658EFF" stroke-width="2.5" stroke-linecap="round" />
+  <circle cx="26" cy="24.5" r="6" fill="url(#memory-check)" />
+  <path d="M23.2 24.4l1.9 1.9 3.7-3.8" stroke="#FFFFFF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+  <defs>
+    <linearGradient id="memory-frame" x1="5" y1="6" x2="31" y2="30" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#41E1AC" />
+      <stop offset="1" stop-color="#658EFF" />
+    </linearGradient>
+    <linearGradient id="memory-check" x1="20" y1="18.5" x2="32" y2="30.5" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#658EFF" />
+      <stop offset="1" stop-color="#41E1AC" />
+    </linearGradient>
+  </defs>
+</svg>

package/lib/candidates.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The candidate queue: statements worth offering, not worth remembering unasked.
+ *
+ * A capture rule can be generous or be safe. Explicit verbs ("记住…", "remember that…")
+ * are safe because the user asked; widening the patterns to ordinary declarative
+ * sentences is not, because the same shape produces "we use sqlite" and "we use two
+ * queues in this diagram". Writing both to the log would make recall worse than the
+ * narrower rule it replaced.
+ *
+ * So the wider rule produces a *question*. A candidate is proposed to the panel, and
+ * only a person turns it into a memory. The queue is append-only for the same reason the
+ * log is: "we offered this and you dismissed it" has to stay answerable, and a mutable
+ * queue would let a later run silently re-ask what was already declined.
+ *
+ * A dismissed candidate is remembered as dismissed rather than deleted, so the same
+ * sentence in the same session is not proposed again on every step.
+ *
+ * @module context-memory/candidates
+ */
+import type { Candidate, CandidateState, MemoryKind } from './types.js';
+/** What a caller proposes, before an id exists. */
+export interface ProposeInput {
+    text: string;
+    kind?: MemoryKind;
+    sessionId?: string;
+}
+/** Enough of `ContextMemory` to answer "is this already remembered". */
+export interface KnownMemories {
+    has(id: string): boolean;
+}
+export declare class CandidateQueue {
+    private readonly dir;
+    private readonly logPath;
+    /**
+     * The last parsed log, revalidated against the file's size and mtime on every read.
+     *
+     * Same reasoning as `MemoryStore`: the pre-step asks the queue one question per
+     * noticed statement (`propose` → `has`/`get`), and re-parsing an unchanged file for
+     * each of them is work that answers nothing new. A change on disk invalidates it, so
+     * two processes still agree.
+     */
+    private cached;
+    constructor(dir: string);
+    get path(): string;
+    private signature;
+    private append;
+    /**
+     * Fold the queue's log.
+     *
+     * The same shape as the memory fold, and the same reason: two processes reading one
+     * file must agree on which questions are still open. A decision naming a proposal that
+     * is not in the log is skipped rather than inventing a candidate.
+     *
+     * The returned array is shared with the cache: treat it as read-only.
+     */
+    all(): CandidateState[];
+    private parse;
+    pending(): CandidateState[];
+    get(id: string): CandidateState | undefined;
+    /**
+     * Offer a statement, unless it is already settled.
+     *
+     * Three suppressions, each for a different noise source: an active memory (the user
+     * already has it), a pending candidate (this step and the last one said the same
+     * thing), and a dismissed one (a question already answered — re-asking it every step
+     * is how a prompt becomes nagging).
+     */
+    propose(input: ProposeInput, known: KnownMemories): Candidate | undefined;
+    /** Record a decision. Returns false when there is no such open candidate. */
+    decide(id: string, status: 'accepted' | 'dismissed', at?: number): boolean;
+}