dsh-context-memory 0.7.0 → 0.9.0

package/lib/identity.d.ts

@@ -12,14 +12,25 @@
  *
  * @module context-memory/identity
  */
+/**
+ * Strip the discourse padding in front of a statement.
+ *
+ * Shared with `compileGuard` on purpose. The subject is what a memory is keyed by and
+ * the check is what makes it verifiable; if the two disagreed about where the actual
+ * statement starts, "note that the file README.md exists" would get the subject of
+ * "file README.md exists" — and no check at all, because the guard patterns are
+ * anchored at the start.
+ *
+ * Applied repeatedly: fillers stack ("please note that the build uses pnpm"), and a
+ * single pass would leave "note that …" behind.
+ */
+export declare function stripLeadingFillers(text: string): string;
 /**
  * Reduce a memory to the key it is stored and compared under.
  *
- * Lowercased, punctuation-stripped, whitespace-collapsed, and with a leading article
- * dropped, so "The build uses pnpm" and "build uses pnpm" are the same memory. Filler
- * that varies in wording but not meaning — "always", "never", "please" — is stripped
- * too: those words change how a memory is checked, not what it is about, and keeping
- * them would make the same fact conflict with itself.
+ * Lowercased, punctuation-stripped, whitespace-collapsed, and with discourse fillers and
+ * a leading article dropped, so "The build uses pnpm" and "build uses pnpm" are the same
+ * memory while "never commit secrets" stays a different claim from "commit secrets".
  */
 export declare function normaliseSubject(text: string): string;
 /**

package/lib/identity.js

@@ -14,32 +14,50 @@
  */
 import { createHash } from 'node:crypto';
 /**
- * Reduce a memory to the key it is stored and compared under.
+ * Words a statement can carry in front without changing what it claims.
  *
- * Lowercased, punctuation-stripped, whitespace-collapsed, and with a leading article
- * dropped, so "The build uses pnpm" and "build uses pnpm" are the same memory. Filler
- * that varies in wording but not meaning — "always", "never", "please" — is stripped
- * too: those words change how a memory is checked, not what it is about, and keeping
- * them would make the same fact conflict with itself.
+ * Deliberately *not* included: `never` and `always`. They read like chatter but they set
+ * the polarity and the scope of the claim — "never commit secrets" and "commit secrets"
+ * are opposites, so folding them into one subject lets the second overwrite the first
+ * without a trace. Discourse fillers ("please", "note that", "remember that") and the
+ * leading article carry nothing and are stripped.
  */
-export function normaliseSubject(text) {
-    const stripped = text
-        .toLowerCase()
-        .replace(/[`"'.,;:!?()[\]]/g, ' ')
-        .replace(/\s+/g, ' ')
-        .replace(/^(?:always|never|please|note that|remember that|the)\s+/i, '')
-        .trim();
-    // Applied repeatedly: fillers stack ("please note that the build uses pnpm"), and a
-    // single pass would leave "note that …" behind, so the same fact said politely and
-    // said plainly would be two subjects instead of one.
-    let result = stripped;
+const LEADING_FILLER = /^(?:please|note that|remember that|the)\s+/i;
+/**
+ * Strip the discourse padding in front of a statement.
+ *
+ * Shared with `compileGuard` on purpose. The subject is what a memory is keyed by and
+ * the check is what makes it verifiable; if the two disagreed about where the actual
+ * statement starts, "note that the file README.md exists" would get the subject of
+ * "file README.md exists" — and no check at all, because the guard patterns are
+ * anchored at the start.
+ *
+ * Applied repeatedly: fillers stack ("please note that the build uses pnpm"), and a
+ * single pass would leave "note that …" behind.
+ */
+export function stripLeadingFillers(text) {
+    let result = text;
     let previous;
     do {
         previous = result;
-        result = result.replace(/^(?:always|never|please|note that|remember that|the)\s+/i, '');
+        result = result.replace(LEADING_FILLER, '');
     } while (result !== previous);
     return result;
 }
+/**
+ * Reduce a memory to the key it is stored and compared under.
+ *
+ * Lowercased, punctuation-stripped, whitespace-collapsed, and with discourse fillers and
+ * a leading article dropped, so "The build uses pnpm" and "build uses pnpm" are the same
+ * memory while "never commit secrets" stays a different claim from "commit secrets".
+ */
+export function normaliseSubject(text) {
+    return stripLeadingFillers(text
+        .toLowerCase()
+        .replace(/[`"'.,;:!?()[\]]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()).trim();
+}
 /**
  * A stable short id for a memory, derived from its subject *and* its text.
  *

package/lib/index.d.ts

@@ -9,8 +9,23 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { ContextMemory, type RememberInput } from './memory.js';
-import type { MemoryKind, MemorySource, PanelPayload, RecallHit, VerifySummary } from './types.js';
+import type { MemoryKind, MemoryScope, MemorySource, PanelPayload, RecallHit, VerifySummary } from './types.js';
 export declare const name = "dsh-context-memory";
+/**
+ * What this plugin needs from the host before it can run.
+ *
+ * Deliberately empty. The only host service it reads is `workingDirectory`, and that
+ * one is read opportunistically through `ctx.get`, not declared here.
+ *
+ * The reason is measurable: `working-directory` is a row in the `dsh-base` bundle's
+ * patch, and a profile whose `dsh-base` is older than the running dsh does not have
+ * that row — npm reports the mismatch (`@deepseek-ai/dsh-base@0.2.0-rc.2 invalid`) but
+ * the host still boots. Declaring the service here makes the whole plugin wait for it:
+ * `pending (waiting for service: workingDirectory)` and nothing runs at all, including
+ * the CLI-visible memory. Reading it optionally degrades to the session header's `cwd`,
+ * which is what the plugin used before it knew about the service.
+ */
+export declare const inject: string[];
 /** Panel-facing feature switches, mirrored by the prefs route. */
 export interface MemoryPrefs {
     autoCapture: boolean;
@@ -19,14 +34,30 @@ export interface MemoryPrefs {
 /** The service shape other plugins and the panel use. */
 export interface MemoryService {
     remember(input: RememberInput): ReturnType<ContextMemory['remember']>;
-    forget(id: string, reason: string, replacedBy?: string): boolean;
+    forget(id: string, reason: string, options?: {
+        replacedBy?: string;
+        scope?: MemoryScope;
+    }): boolean;
     recall(query: string, limit?: number): RecallHit[];
     conflicts(): ReturnType<ContextMemory['conflicts']>;
     verify(): VerifySummary;
     active(): ReturnType<ContextMemory['active']>;
     panel(): PanelPayload;
+    /** Statements the capture heuristics noticed but never had permission to keep. */
+    candidates(): ReturnType<ContextMemory['candidates']>;
+    accept(id: string, overrides?: {
+        text?: string;
+        kind?: MemoryKind;
+        scope?: 'project' | 'user';
+    }): ReturnType<ContextMemory['accept']>;
+    dismiss(id: string): boolean;
     prefs(): MemoryPrefs;
     setPrefs(patch: Partial<MemoryPrefs>): MemoryPrefs;
+    /** Where each scope is stored, so the panel can say which log it is showing. */
+    locations(): {
+        project: string;
+        user: string | undefined;
+    };
 }
 export declare function apply(ctx: Context): void;
 export type { MemoryKind, MemorySource };

package/lib/index.js

@@ -7,24 +7,119 @@
  *
  * @module context-memory/index
  */
-import { resolve } from 'node:path';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { ContextMemory } from './memory.js';
-import { distill } from './capture.js';
+import { candidates, distill } from './capture.js';
+import { describeContradiction } from './guard.js';
 import { registerMemoryRoutes } from './routes.js';
+import { registerMemoryTools } from './tools.js';
+import { resolveProjectStore, userStoreDir } from './scope.js';
 import { isRecallMessage, recallSource } from './source.js';
 export const name = 'dsh-context-memory';
+/**
+ * What this plugin needs from the host before it can run.
+ *
+ * Deliberately empty. The only host service it reads is `workingDirectory`, and that
+ * one is read opportunistically through `ctx.get`, not declared here.
+ *
+ * The reason is measurable: `working-directory` is a row in the `dsh-base` bundle's
+ * patch, and a profile whose `dsh-base` is older than the running dsh does not have
+ * that row — npm reports the mismatch (`@deepseek-ai/dsh-base@0.2.0-rc.2 invalid`) but
+ * the host still boots. Declaring the service here makes the whole plugin wait for it:
+ * `pending (waiting for service: workingDirectory)` and nothing runs at all, including
+ * the CLI-visible memory. Reading it optionally degrades to the session header's `cwd`,
+ * which is what the plugin used before it knew about the service.
+ */
+export const inject = [];
+/**
+ * How often the pre-step re-checks memories, in milliseconds.
+ *
+ * A day is chosen against the failure it prevents: a memory that quietly stopped being
+ * true. Checking less often lets a stale claim survive whole sessions; checking every
+ * step spends filesystem work on an answer that cannot have changed between two
+ * consecutive prompts.
+ */
+const REVERIFY_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export function apply(ctx) {
-    const root = resolve(process.cwd());
-    const memory = new ContextMemory(root);
+    // One instance per project root, created on demand. The launch directory is only the
+    // starting point: a session may begin below the project root, and its directory may
+    // move. The pre-step resolves the session's own directory per request; the panel reads
+    // whichever project a step most recently resolved, which is the one the user is in.
+    const instances = new Map();
+    const memoryFor = (cwd) => {
+        const root = resolveProjectStore(cwd);
+        const existing = instances.get(root);
+        if (existing)
+            return existing;
+        const created = new ContextMemory(root, { userDir: userStoreDir() });
+        instances.set(root, created);
+        return created;
+    };
+    let memory = memoryFor();
+    /**
+     * The directory a session is working in.
+     *
+     * The session's own directory, not the launch directory: a session can start below the
+     * project root and can be moved mid-life, and both must keep the same memory. `ensure`
+     * is the host's authoritative answer (it follows `workingDirectory.set`).
+     *
+     * Read through `ctx.get`, not `ctx.workingDirectory`: the service is optional here (see
+     * `inject` above), and a host without it must fall back rather than refuse to load. The
+     * header's original `cwd` is the fallback, and the launch directory the last resort.
+     *
+     * A silent fallback would be the wrong kind of resilience. If a future `dsh-base` stops
+     * mounting the service — a renamed row, a bundle that drops it — every session would
+     * quietly resolve to its *initial* cwd, and memories written after a `workingDirectory.set`
+     * would land in the wrong project's log with nothing to show it happened. So each
+     * degraded path reports itself once per process; `warn` being unavailable is the only
+     * thing that may fail silently, because logging must never break a step.
+     */
+    let warnedNoService = false;
+    let warnedEnsureFailed = false;
+    const warn = (message) => {
+        try {
+            ctx.logger('dsh-context-memory').warn(message);
+        }
+        catch {
+            // A Context without a logger service (a bare test context) still gets the fallback.
+        }
+    };
+    const cwdFor = async (agent, signal) => {
+        if (agent === undefined)
+            return undefined;
+        try {
+            const service = ctx.get('workingDirectory');
+            if (service === undefined) {
+                if (!warnedNoService) {
+                    warnedNoService = true;
+                    warn('no workingDirectory service on this host; using the session header cwd. '
+                        + 'Memory written after a directory change will be filed under the original directory.');
+                }
+                return agent.session.header.cwd;
+            }
+            return (await service.ensure(agent, signal)) ?? agent.session.header.cwd;
+        }
+        catch (error) {
+            if (!warnedEnsureFailed) {
+                warnedEnsureFailed = true;
+                warn(`workingDirectory.ensure failed; using the session header cwd: ${error.message}`);
+            }
+            return agent.session.header.cwd;
+        }
+    };
+    /** When the last automatic re-check ran, so a day's worth of steps do not each run one. */
+    let lastReverifyAt = 0;
     const service = {
         remember: (input) => memory.remember(input),
-        forget: (id, reason, replacedBy) => memory.forget(id, reason, replacedBy),
+        forget: (id, reason, options) => memory.forget(id, reason, options),
         recall: (query, limit) => memory.recall(query, limit),
         conflicts: () => memory.conflicts(),
         verify: () => memory.verify(),
         active: () => memory.active(),
         panel: () => memory.panel(),
+        candidates: () => memory.candidates(),
+        accept: (id, overrides) => memory.accept(id, overrides),
+        dismiss: (id) => memory.dismiss(id),
         prefs: () => ({ autoCapture: captureEnabled, recallInject: injectEnabled }),
         setPrefs: (patch) => {
             if (typeof patch.autoCapture === 'boolean')
@@ -33,9 +128,23 @@ export function apply(ctx) {
                 injectEnabled = patch.recallInject;
             return { autoCapture: captureEnabled, recallInject: injectEnabled };
         },
+        locations: () => memory.locations,
     };
     ctx.provide('contextMemory', service);
     registerMemoryRoutes(ctx, service);
+    // The pull half. Registered through `ctx.inject(['tools'])` inside, so a host with no
+    // tool registry (the CLI, a headless profile) loses the two tools and nothing else.
+    registerMemoryTools(ctx, {
+        // A tool call belongs to the agent that issued it, and an agent belongs to a session
+        // with its own directory. Answering with whatever the last pre-step resolved would
+        // let one project's question be answered from another project's log whenever two
+        // sessions are open — so the instance is resolved per call, from the caller's own
+        // directory, and the pre-step's "current" instance is not consulted at all.
+        resolve: async (agent, signal) => {
+            const cwd = await cwdFor(agent, signal);
+            return memoryFor(cwd);
+        },
+    });
     // ─── Recall injection + auto capture (durable plugin context) ─
     //
     // Before each step the active memories whose subject overlaps the incoming
@@ -53,7 +162,7 @@ export function apply(ctx) {
     let injectEnabled = true;
     let captureEnabled = true;
     let injectedMessageIds = [];
-    const contextMessageFor = (query) => {
+    const contextMessageFor = (memory, query) => {
         const hits = memory.recall(query, 5);
         const lines = [];
         if (hits.length > 0) {
@@ -61,12 +170,33 @@ export function apply(ctx) {
             for (const hit of hits)
                 lines.push(`- [${hit.memory.kind}] ${hit.memory.text}`);
         }
+        // Contradicted memories are shown as a problem, never as guidance. Silently dropping
+        // them would hide the fact that the log now contains a claim the world denies; the
+        // model can resolve it (and should), while a user reading the transcript learns that
+        // something needs superseding.
+        const contradicted = memory.contradicted().slice(0, 3);
+        if (contradicted.length > 0) {
+            if (lines.length > 0)
+                lines.push('');
+            lines.push('Memories a check has contradicted (do not rely on these; correct or supersede them):');
+            for (const item of contradicted) {
+                // A check that ran and came back false reports no output of its own, so the
+                // fallback names the operand that no longer matches. Without it the line reads
+                // "contradicted" with no way to tell what was tested.
+                lines.push(`- [${item.kind}] ${item.text}  ← ${describeContradiction(item.guard, item.verification?.output)}`);
+            }
+        }
         const conflicts = memory.conflicts();
         if (conflicts.length > 0) {
-            lines.push('');
+            if (lines.length > 0)
+                lines.push('');
             lines.push('Unresolved memory conflicts (verify before relying on either side):');
+            // Both sides are shown, not just the count: a conflict the reader cannot see the
+            // two texts of is a question they cannot answer.
             for (const conflict of conflicts.slice(0, 3)) {
-                lines.push(`- Subject "${conflict.subject}" has ${conflict.memories.length} disagreeing records`);
+                lines.push(`- Subject "${conflict.subject}" has ${conflict.memories.length} disagreeing records:`);
+                for (const item of conflict.memories)
+                    lines.push(`  · ${item.id} ${item.text}`);
             }
         }
         return createUserMessage({
@@ -99,18 +229,50 @@ export function apply(ctx) {
         const trimmed = prompt.trim();
         if (trimmed.length === 0)
             return decision;
+        // A subagent runs in its own session with its own header; it must not inherit the
+        // parent's project just because it shares a process. Sessions with no declared origin
+        // are ordinary user sessions.
+        const origin = agent.session.header.origin;
+        if (origin === 'subagent')
+            return decision;
+        // The session's own directory, not the launch directory: a session can start below
+        // the project root and can be moved mid-life, and both must keep the same memory.
+        memory = memoryFor(await cwdFor(agent, signal));
+        // Re-check before composing, so a memory the world has since disproved is never
+        // offered as guidance in the very step that would have used it. Throttled: the
+        // answer cannot change between two prompts, and the guards are filesystem reads
+        // that should not run on every step.
+        if (Date.now() - lastReverifyAt >= REVERIFY_INTERVAL_MS) {
+            lastReverifyAt = Date.now();
+            try {
+                memory.verify(Date.now(), { record: true, changedOnly: true });
+            }
+            catch { /* a check that cannot be persisted must not stop the step */ }
+        }
         // Auto capture FIRST (see comment above): explicit "记住…" statements from
         // this very request are persisted with session provenance, then excluded
         // from the recall composed below.
         if (captureEnabled) {
-            for (const distilled of distill(trimmed, agent.id)) {
+            const distilled = distill(trimmed, agent.id);
+            for (const statement of distilled) {
                 try {
-                    memory.remember(distilled);
+                    memory.remember(statement);
                 }
                 catch { /* empty statement cannot occur here */ }
             }
+            // Then the wide net, which does not write: a declarative sentence that looks like a
+            // durable fact becomes a question in the panel. Keeping the two apart is the whole
+            // point of P5 — the explicit rule is what the user asked for, the implicit one is
+            // only what the plugin noticed, and conflating them is how a memory log fills with
+            // things nobody wanted.
+            for (const candidate of candidates(trimmed, agent.id, distilled.map((statement) => statement.text))) {
+                try {
+                    memory.propose(candidate);
+                }
+                catch { /* a queue that cannot be written must not stop the step */ }
+            }
         }
-        const desired = contextMessageFor(trimmed);
+        const desired = contextMessageFor(memory, trimmed);
         // Nothing relevant and nothing conflicting → empty content: skip entirely
         // rather than ship an empty row into the transcript.
         if (desired.content.length === 0)

package/lib/memory.d.ts

@@ -6,9 +6,16 @@
  * what is remembered, and a cache would let one process's view of history outlive the
  * events that contradict it.
  *
+ * There are two logs, one per scope. They are folded together rather than merged on
+ * disk: a project convention and a working preference are different statements kept in
+ * different places for different reasons, and collapsing them would make "this checkout"
+ * and "everywhere" the same claim. Which log an event is appended to follows the
+ * memory's own scope, never the caller's convenience.
+ *
  * @module context-memory/memory
  */
-import type { Conflict, Memory, MemoryKind, MemorySource, MemoryState, PanelPayload, RecallHit, VerifySummary } from './types.js';
+import { type ProposeInput } from './candidates.js';
+import type { Candidate, CandidateState, Conflict, Memory, MemoryKind, MemoryScope, MemorySource, MemoryState, MemoryTarget, PanelPayload, RecallHit, VerifySummary } from './types.js';
 export interface RememberInput {
     text: string;
     /**
@@ -18,25 +25,71 @@ export interface RememberInput {
     subject?: string;
     kind?: MemoryKind;
     source?: MemorySource;
+    /** Which log to write. Defaults to `project` — the narrow claim is the safe default. */
+    scope?: MemoryScope;
     sessionId?: string;
     step?: number;
 }
+/** Construction options. */
+export interface ContextMemoryOptions {
+    /**
+     * Directory of the user-global log.
+     *
+     * Omitted means the instance is project-only: `all()` folds one log, and asking to
+     * remember something user-global throws rather than quietly writing it to the project.
+     * Tests rely on that — an omitted directory must never reach the real home.
+     */
+    userDir?: string;
+}
 export declare class ContextMemory {
     private readonly projectDir;
-    private readonly store;
-    constructor(projectDir: string);
+    private readonly projectStore;
+    private readonly userStore;
+    private readonly queue;
+    /**
+     * The last fold, keyed by the identity of both log files.
+     *
+     * The pre-step asks the same question several times in one pass — who is relevant,
+     * who is contradicted, who disagrees — and each answer used to re-fold both logs. The
+     * fold is still recomputed whenever either file changes, so two processes reading one
+     * log still agree: everything below re-derives from the files, this only avoids
+     * deriving the same state from the same bytes more than once.
+     */
+    private folded;
+    constructor(projectDir: string, options?: ContextMemoryOptions);
+    /** Where each scope is written, for the panel and the CLI. */
+    get locations(): {
+        project: string;
+        user: string | undefined;
+    };
+    /** The project log's path. Kept for callers that only know about the project scope. */
     get logPath(): string;
+    private storeFor;
     /**
-     * Fold the log into current state.
+     * Fold the logs into current state.
      *
      * Events are applied in log order and a memory is always addressable by id, so a
      * supersede or verify that names a memory not yet seen is skipped rather than
      * creating a phantom entry — a log that lost its `remember` line must not resurrect
      * the memory from its consequences.
+     *
+     * A memory's scope is part of its identity here: the same sentence can legitimately
+     * exist in both logs, and they are two claims about two different domains, so both
+     * are kept rather than one shadowing the other.
      */
     all(): MemoryState[];
+    private scopes;
     active(): MemoryState[];
-    get(id: string): MemoryState | undefined;
+    /**
+     * Active memories no check has contradicted — the population recall ranks and the
+     * pre-step may offer the model.
+     */
+    guidance(): MemoryState[];
+    /** Active memories a check ran against and failed — visible, never offered. */
+    contradicted(): MemoryState[];
+    get(id: string, scope?: MemoryScope): MemoryState | undefined;
+    /** Whether a memory with this id exists in either scope — the candidate queue's dedupe. */
+    has(id: string): boolean;
     /**
      * Record a memory.
      *
@@ -51,6 +104,19 @@ export declare class ContextMemory {
      * command would be an injection path.
      */
     remember(input: RememberInput, now?: number): Memory;
+    /**
+     * `remember`, plus whether the statement was already on file.
+     *
+     * The distinction exists for the model-facing tool: "recorded" and "already knew that"
+     * are different answers, and a caller reporting the first when the second happened is
+     * claiming work it did not do. It is computed here rather than by the caller because
+     * the id is derived from the subject and text, and a second copy of that derivation
+     * would drift from this one.
+     */
+    record(input: RememberInput, now?: number): {
+        memory: Memory;
+        updated: boolean;
+    };
     /**
      * Retire a memory, with a reason.
      *
@@ -59,7 +125,11 @@ export declare class ContextMemory {
      * marked superseded and kept, and the reason is required because "why did this stop
      * being true" is the question that will be asked later.
      */
-    forget(id: string, reason: string, replacedBy?: string, now?: number): boolean;
+    forget(id: string, reason: string, options?: {
+        replacedBy?: string;
+        scope?: MemoryScope;
+        now?: number;
+    }): boolean;
     /**
      * Group active memories that share a subject but say different things.
      *
@@ -67,10 +137,53 @@ export declare class ContextMemory {
      * and different text means one of them is wrong and the log does not say which; a
      * plausible-looking choice would be exactly the unfounded assertion this plugin exists
      * to eliminate.
+     *
+     * A contradicted memory is left out: it is not an open question, the world already
+     * answered it. Keeping it here would present a settled matter as undecided.
      */
     conflicts(): Conflict[];
-    /** Rank active memories against a query. */
-    recall(query: string, limit?: number, now?: number): RecallHit[];
+    /**
+     * Rank memories against a query.
+     *
+     * Defaults to guidance — the population the pre-step may offer. The pull tool widens
+     * the target explicitly when the model asks what is *recorded* rather than what is
+     * *true*, and that difference is carried by the argument instead of by a second
+     * implementation.
+     */
+    recall(query: string, limit?: number, now?: number, target?: MemoryTarget): RecallHit[];
+    /**
+     * The newest memories in one population, for a caller that asked without a query.
+     *
+     * "What do you remember" has no lexical content to rank, and answering it with an
+     * empty result would be pedantically correct and useless. Newest-first is the one
+     * ordering that needs no claim about relevance — it is simply the log's own order,
+     * read backwards.
+     */
+    recent(limit?: number, target?: MemoryTarget): MemoryState[];
+    /**
+     * Offer a statement.
+     *
+     * Returns undefined when it is already settled — an active memory, an open candidate,
+     * or one already dismissed. That check is against the *log*, not against the message,
+     * so a sentence repeated across a session is asked once rather than on every step.
+     */
+    propose(input: ProposeInput): Candidate | undefined;
+    candidates(): CandidateState[];
+    dismiss(id: string, now?: number): boolean;
+    /**
+     * Turn a candidate into a memory.
+     *
+     * The decision is recorded *before* the memory is written, so a write that throws
+     * leaves a dismissed-looking proposal rather than a candidate that reappears beside a
+     * memory it duplicates. The candidate keeps the kind and provenance it was proposed
+     * with, and the user's acceptance is the reason it exists — which is why the memory is
+     * written with `source: 'user'`: a person said yes to it.
+     */
+    accept(id: string, overrides?: {
+        text?: string;
+        kind?: MemoryKind;
+        scope?: MemoryScope;
+    }, now?: number): Memory | undefined;
     /**
      * Re-run every compiled guard.
      *
@@ -78,8 +191,17 @@ export declare class ContextMemory {
      * disagreeing with a memory, `broken` is the check itself being unusable, and
      * `uncheckable` is there being no check. Only the first is evidence about the memory,
      * so only the first may influence a caller's exit code.
+     *
+     * @param options.record - when false, results are computed but not appended. The
+     *   pre-step re-checks often; a log entry per check per step would grow the file
+     *   without saying anything new.
+     * @param options.changedOnly - append only when the outcome differs from the last
+     *   recorded one, so a memory that keeps passing does not add a line per run.
      */
-    verify(now?: number): VerifySummary;
+    verify(now?: number, options?: {
+        record?: boolean;
+        changedOnly?: boolean;
+    }): VerifySummary;
     /**
      * The exit code a caller should use.
      *