dsh-context-memory 0.7.0 → 0.9.0

package/lib/routes.js

@@ -13,6 +13,7 @@ export const MEMORY_RECALL_PATH = '/api/context-memory.recall';
 export const MEMORY_REMEMBER_PATH = '/api/context-memory.remember';
 export const MEMORY_FORGET_PATH = '/api/context-memory.forget';
 export const MEMORY_PREFS_PATH = '/api/context-memory.prefs';
+export const MEMORY_CANDIDATES_PATH = '/api/context-memory.candidates';
 export function registerMemoryRoutes(ctx, memory) {
     // Injecting rather than reading `ctx.connection` directly: a plain property access on
     // a service that was not declared throws, and the web connection is absent in headless
@@ -71,6 +72,8 @@ export function registerMemoryRoutes(ctx, memory) {
                     input.subject = body.subject;
                 if (body.kind)
                     input.kind = body.kind;
+                if (body.scope === 'user' || body.scope === 'project')
+                    input.scope = body.scope;
                 if (body.source)
                     input.source = body.source;
                 const mem = memory.remember(input);
@@ -92,12 +95,58 @@ export function registerMemoryRoutes(ctx, memory) {
                 }
                 if (!body.id)
                     return Response.json({ error: 'missing id' }, { status: 400 });
-                const ok = memory.forget(body.id, body.reason ?? 'superseded from panel', body.replacedBy);
+                const scope = body.scope === 'user' || body.scope === 'project' ? body.scope : undefined;
+                const ok = memory.forget(body.id, body.reason ?? 'superseded from panel', {
+                    ...(body.replacedBy !== undefined ? { replacedBy: body.replacedBy } : {}),
+                    ...(scope !== undefined ? { scope } : {}),
+                });
                 if (!ok)
                     return Response.json({ error: 'not found' }, { status: 404 });
                 return Response.json({ ok: true });
             },
         });
+        // Candidate decisions — accept writes a memory, dismiss records the answer.
+        //
+        // Accepting is the only path from a heuristic to the log, which is why it takes an
+        // explicit id: the caller names the proposal it is confirming, and there is no route
+        // that turns "a sentence that looked like a fact" into a memory on its own.
+        connection.fetch.register({
+            path: MEMORY_CANDIDATES_PATH,
+            methods: ['GET', 'POST'],
+            requestBody: 'buffered',
+            fetch: async (request) => {
+                if (request.method === 'GET') {
+                    return Response.json({ candidates: memory.candidates() }, { headers: { 'cache-control': 'no-store' } });
+                }
+                let body;
+                try {
+                    body = await request.json();
+                }
+                catch {
+                    return Response.json({ error: 'invalid JSON' }, { status: 400 });
+                }
+                if (body.id === undefined || body.id.length === 0)
+                    return Response.json({ error: 'missing id' }, { status: 400 });
+                if (body.action === 'dismiss') {
+                    const ok = memory.dismiss(body.id);
+                    return ok ? Response.json({ ok: true }) : Response.json({ error: 'not found' }, { status: 404 });
+                }
+                if (body.action === 'accept') {
+                    const overrides = {};
+                    if (body.text !== undefined && body.text.trim().length > 0)
+                        overrides.text = body.text;
+                    if (body.kind !== undefined)
+                        overrides.kind = body.kind;
+                    if (body.scope === 'user' || body.scope === 'project')
+                        overrides.scope = body.scope;
+                    const stored = memory.accept(body.id, overrides);
+                    return stored === undefined
+                        ? Response.json({ error: 'not found' }, { status: 404 })
+                        : Response.json(stored);
+                }
+                return Response.json({ error: 'action must be accept or dismiss' }, { status: 400 });
+            },
+        });
         // Feature switches — GET to read, POST a partial patch to set
         connection.fetch.register({
             path: MEMORY_PREFS_PATH,

package/lib/scope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a memory lives.
+ *
+ * Two scopes, because "the build uses pnpm" and "answer me in Chinese" are stored in
+ * different places for different reasons. A project convention is only true inside that
+ * checkout and should travel with it; a working preference is true everywhere the user
+ * works and should not be re-stated in every repository.
+ *
+ * The scope is a property of the memory, not of the installation: one log holds both,
+ * and each entry is routed to the store its scope names. That keeps one fold and one
+ * panel while still letting the two populations move independently.
+ *
+ * @module context-memory/scope
+ */
+/**
+ * Directory names that mark the top of a project, in probe order.
+ *
+ * `package.json` is deliberately absent. It is the marker everyone reaches for and it is
+ * the wrong one: a stray `package.json` in a home directory makes every unrelated folder
+ * beneath it one project, so a scratch directory on the Desktop would share a memory log
+ * with everything else in the profile. `.git` marks a checkout, and a workspace file only
+ * appears at the top of a workspace, which is what a project root means here.
+ *
+ * This matches `dsh-agent-instructions`, whose default `projectRootMarkers` is `['.git']`.
+ */
+export declare const PROJECT_ROOT_MARKERS: readonly [".git", "pnpm-workspace.yaml"];
+/** Where the user-global log lives, under the harness home. */
+export declare function userStoreDir(): string;
+/**
+ * Find the top of the project containing `start`.
+ *
+ * Mirrors `dsh-agent-instructions`'s discovery: climb while the marker is *absent*, and
+ * stop at the first directory that carries one. The difference from `process.cwd()` is
+ * the whole point — a session started three levels down inside a monorepo is still the
+ * same project, and two directories that are not the same project must not share a log.
+ *
+ * When no marker is found anywhere on the way up, `start` is its own project — which is
+ * honest: there is no evidence that anything above it belongs to the same work.
+ *
+ * @param start - absolute directory to begin from.
+ * @returns the discovered project root, or `start` when nothing marks one.
+ */
+export declare function findProjectRoot(start: string): string;
+/** Resolve the directory a project memory is stored under. */
+export declare function resolveProjectStore(cwd?: string): string;

package/lib/scope.js

@@ -0,0 +1,75 @@
+/**
+ * Where a memory lives.
+ *
+ * Two scopes, because "the build uses pnpm" and "answer me in Chinese" are stored in
+ * different places for different reasons. A project convention is only true inside that
+ * checkout and should travel with it; a working preference is true everywhere the user
+ * works and should not be re-stated in every repository.
+ *
+ * The scope is a property of the memory, not of the installation: one log holds both,
+ * and each entry is routed to the store its scope names. That keeps one fold and one
+ * panel while still letting the two populations move independently.
+ *
+ * @module context-memory/scope
+ */
+import { statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+/**
+ * Directory names that mark the top of a project, in probe order.
+ *
+ * `package.json` is deliberately absent. It is the marker everyone reaches for and it is
+ * the wrong one: a stray `package.json` in a home directory makes every unrelated folder
+ * beneath it one project, so a scratch directory on the Desktop would share a memory log
+ * with everything else in the profile. `.git` marks a checkout, and a workspace file only
+ * appears at the top of a workspace, which is what a project root means here.
+ *
+ * This matches `dsh-agent-instructions`, whose default `projectRootMarkers` is `['.git']`.
+ */
+export const PROJECT_ROOT_MARKERS = ['.git', 'pnpm-workspace.yaml'];
+/** Where the user-global log lives, under the harness home. */
+export function userStoreDir() {
+    return dshHomePath('context-memory');
+}
+/**
+ * Find the top of the project containing `start`.
+ *
+ * Mirrors `dsh-agent-instructions`'s discovery: climb while the marker is *absent*, and
+ * stop at the first directory that carries one. The difference from `process.cwd()` is
+ * the whole point — a session started three levels down inside a monorepo is still the
+ * same project, and two directories that are not the same project must not share a log.
+ *
+ * When no marker is found anywhere on the way up, `start` is its own project — which is
+ * honest: there is no evidence that anything above it belongs to the same work.
+ *
+ * @param start - absolute directory to begin from.
+ * @returns the discovered project root, or `start` when nothing marks one.
+ */
+export function findProjectRoot(start) {
+    const origin = resolve(start);
+    let current = origin;
+    for (;;) {
+        for (const marker of PROJECT_ROOT_MARKERS) {
+            if (exists(join(current, marker)))
+                return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return origin;
+        current = parent;
+    }
+}
+/** `statSync` that answers a yes/no question without throwing on absence. */
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the directory a project memory is stored under. */
+export function resolveProjectStore(cwd) {
+    return findProjectRoot(cwd !== undefined && isAbsolute(cwd) ? cwd : resolve('.'));
+}

package/lib/store.d.ts

@@ -11,11 +11,31 @@
  */
 import type { MemoryEvent } from './types.js';
 export declare class MemoryStore {
-    private readonly projectDir;
     private readonly dir;
     private readonly logPath;
-    constructor(projectDir: string);
+    /**
+     * The parsed log, together with the file identity it was parsed from.
+     *
+     * This is not the cache the module comment warns about. That one was rejected because
+     * it would let one process's view of history outlive the events that contradict it;
+     * this one is revalidated against the file's own size and mtime on every read, so an
+     * append by another process is seen on the next call exactly as before. What it avoids
+     * is re-parsing an unchanged file — the same log is folded several times inside one
+     * pre-step, and parsing it once per fold is the only part of that which is avoidable.
+     */
+    private cached;
+    /** @param dir - the `.memory` directory itself, already resolved for its scope. */
+    constructor(dir: string);
     get path(): string;
+    /**
+     * An identity for the file as it is right now, or null when there is no file.
+     *
+     * Size alone would miss a rewrite; mtime alone is too coarse on some Windows
+     * filesystems. Together they change on every append this process or another makes.
+     * `stat` costs a syscall; reading and parsing the file costs a syscall plus an
+     * allocation plus a JSON.parse per line, which is why this is worth doing.
+     */
+    signature(): string | null;
     append(event: MemoryEvent): void;
     /**
      * Read the whole log.
@@ -25,6 +45,9 @@ export declare class MemoryStore {
      * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
      * anywhere else is a real problem and is reported rather than skipped, because
      * silently ignoring a damaged record is how a log stops being evidence.
+     *
+     * The returned array is shared with the cache: treat it as read-only.
      */
     readAll(): MemoryEvent[];
+    private parse;
 }

package/lib/store.js

@@ -9,25 +9,55 @@
  *
  * @module context-memory/store
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export class MemoryStore {
-    projectDir;
     dir;
     logPath;
-    constructor(projectDir) {
-        this.projectDir = projectDir;
-        this.dir = join(projectDir, '.memory');
+    /**
+     * The parsed log, together with the file identity it was parsed from.
+     *
+     * This is not the cache the module comment warns about. That one was rejected because
+     * it would let one process's view of history outlive the events that contradict it;
+     * this one is revalidated against the file's own size and mtime on every read, so an
+     * append by another process is seen on the next call exactly as before. What it avoids
+     * is re-parsing an unchanged file — the same log is folded several times inside one
+     * pre-step, and parsing it once per fold is the only part of that which is avoidable.
+     */
+    cached;
+    /** @param dir - the `.memory` directory itself, already resolved for its scope. */
+    constructor(dir) {
+        this.dir = dir;
         this.logPath = join(this.dir, 'events.jsonl');
     }
     get path() {
         return this.logPath;
     }
+    /**
+     * An identity for the file as it is right now, or null when there is no file.
+     *
+     * Size alone would miss a rewrite; mtime alone is too coarse on some Windows
+     * filesystems. Together they change on every append this process or another makes.
+     * `stat` costs a syscall; reading and parsing the file costs a syscall plus an
+     * allocation plus a JSON.parse per line, which is why this is worth doing.
+     */
+    signature() {
+        try {
+            const stats = statSync(this.logPath);
+            return `${stats.size}:${stats.mtimeMs}`;
+        }
+        catch {
+            return null;
+        }
+    }
     append(event) {
         if (!existsSync(this.dir))
             mkdirSync(this.dir, { recursive: true });
         // One `write` of one line: a crash can truncate the final line, but cannot interleave.
         appendFileSync(this.logPath, `${JSON.stringify(event)}\n`, 'utf8');
+        // Not strictly needed — the next `signature()` no longer matches — but it keeps the
+        // cached array from being handed out after this process has moved the log on.
+        this.cached = undefined;
     }
     /**
      * Read the whole log.
@@ -37,10 +67,18 @@ export class MemoryStore {
      * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
      * anywhere else is a real problem and is reported rather than skipped, because
      * silently ignoring a damaged record is how a log stops being evidence.
+     *
+     * The returned array is shared with the cache: treat it as read-only.
      */
     readAll() {
-        if (!existsSync(this.logPath))
-            return [];
+        const key = this.signature();
+        if (this.cached !== undefined && this.cached.key === key)
+            return this.cached.events;
+        const events = key === null ? [] : this.parse();
+        this.cached = { key, events };
+        return events;
+    }
+    parse() {
         const lines = readFileSync(this.logPath, 'utf8').split('\n');
         const events = [];
         for (let index = 0; index < lines.length; index += 1) {

package/lib/tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Model-facing tools: the pull half of memory.
+ *
+ * Recall injection pushes what the plugin thinks is relevant. That is one direction only,
+ * and it leaves the model unable to ask the question it most often needs answered:
+ * "what did we already decide about this?" This module registers that question as two
+ * tools, so memory is something the model can consult rather than only something that
+ * arrives unasked.
+ *
+ * The two directions deliberately answer differently. The push path may only offer
+ * guidance — active and not contradicted — because unsolicited text influences the turn.
+ * The pull path is answering a question someone actually asked, so it can widen to
+ * contradicted or superseded records when asked to by name. The difference is carried by
+ * the `include` argument rather than by a second implementation, and `guidance` is still
+ * the default: a model that does not think about populations gets the same conservatism
+ * the push path applies.
+ *
+ * @module context-memory/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContextMemory } from './memory.js';
+/** How this plugin finds the log belonging to one call's recording context. */
+export interface MemoryToolOptions {
+    /**
+     * The instance for the session that issued the call.
+     *
+     * A tool call belongs to an agent, and an agent belongs to a session with its own
+     * working directory — which may not be the project the last pre-step resolved. Reading
+     * the shared "current" instance instead would answer a question about one project with
+     * another project's log.
+     */
+    resolve(agent: Agent | undefined, signal: AbortSignal): Promise<ContextMemory>;
+}
+/**
+ * Register both tools, once the host's tool registry exists.
+ *
+ * Registered through `ctx.inject` rather than a static `inject` entry for the same reason
+ * the working directory is read through `ctx.get`: this plugin must keep working on a host
+ * that mounts no tool registry (the CLI, a headless profile without tools), and a declared
+ * dependency on `tools` would leave the whole plugin pending — including the pre-step
+ * injection and the panel — on such a host. The tools are an addition, not a precondition.
+ */
+export declare function registerMemoryTools(ctx: Context, options: MemoryToolOptions): void;

package/lib/tools.js

@@ -0,0 +1,241 @@
+/**
+ * Model-facing tools: the pull half of memory.
+ *
+ * Recall injection pushes what the plugin thinks is relevant. That is one direction only,
+ * and it leaves the model unable to ask the question it most often needs answered:
+ * "what did we already decide about this?" This module registers that question as two
+ * tools, so memory is something the model can consult rather than only something that
+ * arrives unasked.
+ *
+ * The two directions deliberately answer differently. The push path may only offer
+ * guidance — active and not contradicted — because unsolicited text influences the turn.
+ * The pull path is answering a question someone actually asked, so it can widen to
+ * contradicted or superseded records when asked to by name. The difference is carried by
+ * the `include` argument rather than by a second implementation, and `guidance` is still
+ * the default: a model that does not think about populations gets the same conservatism
+ * the push path applies.
+ *
+ * @module context-memory/tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { describeContradiction, describeGuard } from './guard.js';
+/** Populations a caller may search, in the order the schema lists them. */
+const TARGETS = ['guidance', 'contradicted', 'superseded', 'all'];
+/** Kinds a memory may be recorded as. Mirrors `MemoryKind`. */
+const KINDS = ['fact', 'decision', 'preference', 'pitfall'];
+/** Scopes a memory may be written to. Mirrors `MemoryScope`. */
+const SCOPES = ['project', 'user'];
+/** Bounds on one search, so a model cannot ask for the whole log by accident. */
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 20;
+const DEFAULT_LIMIT = 5;
+/** Clamp a requested result count into the range one call may return. */
+function clampLimit(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return DEFAULT_LIMIT;
+    const whole = Math.trunc(requested);
+    return Math.min(Math.max(whole, MIN_LIMIT), MAX_LIMIT);
+}
+/**
+ * The verification word for one memory, as the model sees it.
+ *
+ * `unverified` and `broken` are kept apart from `violated` for the same reason the guard
+ * module keeps them apart: a check that could not run is not evidence about the memory.
+ * Collapsing them into "failed" would teach the model to distrust true statements whose
+ * guard happens to be broken.
+ */
+function verificationOf(memory) {
+    const outcome = memory.verification?.outcome;
+    if (outcome === undefined)
+        return 'unverified';
+    return outcome;
+}
+/** The first line of a failed check, for a caller that wants to know why. */
+function contradictionOf(memory) {
+    return describeContradiction(memory.guard, memory.verification?.output);
+}
+/** One result row in the tool's output shape. */
+function hitOf(memory) {
+    return {
+        id: memory.id,
+        text: memory.text,
+        kind: memory.kind,
+        scope: memory.scope,
+        verification: verificationOf(memory),
+        // Only an actual contradiction gets a reason. `broken` says the check is unusable,
+        // and attaching its message here would read as evidence against the memory.
+        ...(memory.verification?.outcome === 'violated' ? { detail: contradictionOf(memory) } : {}),
+    };
+}
+/**
+ * Register both tools, once the host's tool registry exists.
+ *
+ * Registered through `ctx.inject` rather than a static `inject` entry for the same reason
+ * the working directory is read through `ctx.get`: this plugin must keep working on a host
+ * that mounts no tool registry (the CLI, a headless profile without tools), and a declared
+ * dependency on `tools` would leave the whole plugin pending — including the pre-step
+ * injection and the panel — on such a host. The tools are an addition, not a precondition.
+ */
+export function registerMemoryTools(ctx, options) {
+    ctx.inject(['tools'], (toolCtx) => {
+        toolCtx.tools.register(defineTool({
+            name: 'memory_recall',
+            description: 'Search this project\'s stored memories (conventions, decisions, preferences, pitfalls recorded in earlier sessions) and return the strongest matches with their verification state. By default only memories that are active and not contradicted are returned; pass include to widen. Omit query to list the newest memories instead.',
+            parameters: {
+                query: {
+                    type: 'string',
+                    description: 'What to look for. Latin words match as words, Chinese text matches on two-character runs. Omit to list the newest memories.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: `How many memories to return. ${MIN_LIMIT}-${MAX_LIMIT}, default ${DEFAULT_LIMIT}.`,
+                },
+                include: {
+                    type: 'string',
+                    enum: [...TARGETS],
+                    description: 'Which memories to search: guidance (default) is active and not contradicted; contradicted is active but disproved by a check; superseded was retired; all is everything recorded.',
+                },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        hits: {
+                            type: 'array',
+                            required: true,
+                            description: 'Matches, strongest first.',
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    id: { type: 'string', required: true, description: 'Reference for this memory.' },
+                                    text: { type: 'string', required: true, description: 'The remembered statement.' },
+                                    kind: { type: 'string', required: true, description: 'fact, decision, preference, or pitfall.' },
+                                    scope: { type: 'string', required: true, description: 'project or user.' },
+                                    verification: { type: 'string', required: true, description: 'passed, violated, broken, or unverified.' },
+                                    detail: { type: 'string', description: 'Why a check contradicted it, when one did.' },
+                                },
+                            },
+                        },
+                        include: { type: 'string', required: true, description: 'The population actually searched.' },
+                        note: { type: 'string', description: 'Present when the search returned nothing, or when it fell back to newest-first.' },
+                    },
+                },
+                render: (_args, value) => {
+                    const lines = [];
+                    if (value.hits.length === 0) {
+                        lines.push(`No stored memory matched (searched: ${value.include}).`);
+                    }
+                    else {
+                        lines.push(`${value.hits.length} memory${value.hits.length === 1 ? '' : 'ies'} (searched: ${value.include}):`);
+                        for (const hit of value.hits) {
+                            const detail = hit.detail === undefined ? '' : ` — contradicted by ${hit.detail}`;
+                            lines.push(`- [${hit.kind}] ${hit.text}  (id ${hit.id}, ${hit.scope}, ${hit.verification})${detail}`);
+                        }
+                    }
+                    if (value.note !== undefined)
+                        lines.push('', value.note);
+                    return [{ type: 'text', text: lines.join('\n') }];
+                },
+            },
+            isConcurrencySafe: () => true,
+            async execute(args, exec) {
+                const memory = await options.resolve(exec.agent, exec.signal);
+                const target = (args.include ?? 'guidance');
+                const limit = clampLimit(args.limit);
+                const query = args.query?.trim() ?? '';
+                // An empty query is a question about nothing, and a lexical search would answer it
+                // with nothing. "What do you remember" is a real question, so it gets the newest
+                // entries of the requested population instead.
+                if (query.length === 0) {
+                    const hits = memory.recent(limit, target);
+                    return {
+                        hits: hits.map(hitOf),
+                        include: target,
+                        ...(hits.length > 0 ? { note: 'No query was given, so these are the newest memories rather than the most relevant.' } : {}),
+                    };
+                }
+                return {
+                    hits: memory.recall(query, limit, Date.now(), target).map((hit) => hitOf(hit.memory)),
+                    include: target,
+                };
+            },
+        }));
+        toolCtx.tools.register(defineTool({
+            name: 'memory_remember',
+            description: 'Record a durable memory for this project or for the user, so later sessions see it. Use it for conventions, decisions, preferences, and pitfalls the user states or that the work establishes — not for transient task state. The statement is stored as text; only a few narrow statement shapes get a filesystem check that can later verify or contradict it.',
+            parameters: {
+                text: {
+                    type: 'string',
+                    required: true,
+                    description: 'The statement to remember, in the user\'s own words. One claim per call.',
+                },
+                kind: {
+                    type: 'string',
+                    enum: [...KINDS],
+                    description: 'fact (default), decision, preference, or pitfall.',
+                },
+                subject: {
+                    type: 'string',
+                    description: 'What the claim is about. Two different statements with the same subject are reported as a conflict; omit to use the statement itself.',
+                },
+                scope: {
+                    type: 'string',
+                    enum: [...SCOPES],
+                    description: 'project (default) travels with this checkout; user applies everywhere this user works.',
+                },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: { type: 'string', required: true, description: 'Reference for the recorded memory.' },
+                        text: { type: 'string', required: true, description: 'The statement as stored (trimmed).' },
+                        kind: { type: 'string', required: true, description: 'The kind it was recorded as.' },
+                        scope: { type: 'string', required: true, description: 'Which log it was written to.' },
+                        check: { type: 'string', description: 'The filesystem check that will re-verify it. Absent when none could be compiled.' },
+                        updated: { type: 'boolean', required: true, description: 'True when this statement was already recorded and only its timestamp was refreshed.' },
+                    },
+                },
+                render: (_args, value) => [{
+                        type: 'text',
+                        text: [
+                            `${value.updated ? 'Already recorded' : 'Remembered'} ${value.id} [${value.scope}, ${value.kind}]: ${value.text}`,
+                            value.check === undefined
+                                ? 'No check could be compiled from this statement, so nothing will re-verify it.'
+                                : `Check: ${value.check}.`,
+                        ].join('\n'),
+                    }],
+            },
+            // Writes append one line to a file. Two of them commute, and the registry already
+            // serializes nothing else about them, so they may share a parallel group.
+            isConcurrencySafe: () => true,
+            async execute(args, exec) {
+                const memory = await options.resolve(exec.agent, exec.signal);
+                const kind = (args.kind ?? 'fact');
+                const scope = (args.scope ?? 'project');
+                const { memory: stored, updated } = memory.record({
+                    text: args.text,
+                    kind,
+                    scope,
+                    // Provenance is not decoration: the panel distinguishes what the user said from
+                    // what the model decided to write down, and a memory is only as trustworthy as
+                    // its source is.
+                    source: 'agent',
+                    ...(args.subject === undefined || args.subject.trim().length === 0 ? {} : { subject: args.subject }),
+                    ...(exec.agent === undefined ? {} : { sessionId: exec.agent.id }),
+                });
+                return {
+                    id: stored.id,
+                    text: stored.text,
+                    kind: stored.kind,
+                    scope,
+                    ...(stored.guard === undefined ? {} : { check: describeGuard(stored.guard) }),
+                    updated,
+                };
+            },
+        }));
+    });
+}