dsh-context-memory 0.7.1 → 0.10.0

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,
+                };
+            },
+        }));
+    });
+}

package/lib/types.d.ts

@@ -13,15 +13,129 @@
 export type MemoryKind = 'fact' | 'decision' | 'preference' | 'pitfall';
 /** Who wrote the memory. Provenance, so "why does the agent think it knows this" has an answer. */
 export type MemorySource = 'user' | 'agent' | 'plugin';
+/**
+ * Where the memory lives.
+ *
+ * `project` is a convention of one checkout; `user` is a working preference that holds
+ * everywhere. The distinction is scope, not importance — both are equally worth
+ * recalling, but they belong to different populations and must not leak into each other.
+ */
+export type MemoryScope = 'project' | 'user';
 /** A memory is active until something explicitly supersedes it. */
 export type MemoryStatus = 'active' | 'superseded';
+/**
+ * Which populations a search may draw from.
+ *
+ * `guidance` is the only one the push path may use: active and not contradicted. The
+ * others exist for questions that are *about* the log rather than for guidance —
+ * "what did we decide before", "what did the check disprove" — which only a reader who
+ * asked for them by name should receive.
+ */
+export type MemoryTarget = 'guidance' | 'contradicted' | 'superseded' | 'all';
 /** The same three-outcome model dsh-verdict uses: inability to check is not failure. */
 export type GuardOutcome = 'passed' | 'violated' | 'broken';
-/** An executable check compiled from a memory statement. */
-export interface Guard {
-    command: string;
+/**
+ * An executable check compiled from a memory statement.
+ *
+ * A check names one predicate and its operands — never a program. That is what keeps
+ * memory text from becoming something to execute: the statement contributes paths,
+ * keys, and search strings, and the evaluation is `fs` plus `JSON.parse`, not a shell.
+ *
+ * The `kind` discriminates the predicate. Check `kind` before reading an operand: the
+ * operands each kind needs differ, so a field that exists on one is absent on another.
+ *
+ * The file predicates (`exists` / `absent` / `contains` / `lacks`) answer "is this text in
+ * this file". The structured predicates (`depends` / `script` / `option` / `lineLimit`)
+ * answer questions about a *parsed* file, which is a different thing: `contains` would say
+ * `"yarn"` is in `package.json` because the word appears in a comment, a description, or
+ * inside some other key. Parsing is still in-process and still has no program in it.
+ */
+export type Guard = {
+    kind: 'exists';
+    path: string;
+    source: 'template';
+} | {
+    kind: 'absent';
+    path: string;
+    source: 'template';
+} | {
+    kind: 'contains';
+    path: string;
+    needle: string;
+    source: 'template';
+} | {
+    kind: 'lacks';
+    path: string;
+    needle: string;
     source: 'template';
 }
+/**
+ * `package.json` declares `name` in any of `dependencies` / `devDependencies` /
+ * `peerDependencies` / `optionalDependencies`. All four count: a memory saying "we use
+ * X" is not wrong because X arrived as a peer.
+ */
+ | {
+    kind: 'depends';
+    name: string;
+    source: 'template';
+    absent?: false;
+}
+/** `package.json` declares no such dependency. */
+ | {
+    kind: 'depends';
+    name: string;
+    source: 'template';
+    absent: true;
+}
+/** `package.json` has a `scripts` entry `name`, and `cmd` (when given) is its value. */
+ | {
+    kind: 'script';
+    name: string;
+    cmd?: string;
+    source: 'template';
+    absent?: false;
+}
+/** `package.json` has no such script. */
+ | {
+    kind: 'script';
+    name: string;
+    source: 'template';
+    absent: true;
+}
+/**
+ * A JSON config file sets `option`, and `value` (when given) is what it is set to.
+ *
+ * `value: true` plus `absent: true` is the negation of "the option is on" — it is
+ * satisfied by the key being absent *and* by it being explicitly `false`, because
+ * "strict is not enabled" is true in both cases.
+ */
+ | {
+    kind: 'option';
+    path: string;
+    option: string;
+    value?: boolean;
+    source: 'template';
+    absent?: false;
+}
+/** The same config option is not set to `value` (or is not set at all). */
+ | {
+    kind: 'option';
+    path: string;
+    option: string;
+    value?: boolean;
+    source: 'template';
+    absent: true;
+}
+/** The file has at most `max` lines, or at least `min`. */
+ | {
+    kind: 'lineLimit';
+    path: string;
+    max?: number;
+    min?: number;
+    source: 'template';
+};
+/** The predicates above, as a value to switch on. */
+export type GuardKind = Guard['kind'];
 /** The immutable payload recorded by a `remember` event. */
 export interface Memory {
     id: string;
@@ -30,6 +144,13 @@ export interface Memory {
     text: string;
     kind: MemoryKind;
     source: MemorySource;
+    /**
+     * Which log this memory was written to.
+     *
+     * Absent in logs written before 0.9.0, which were project-only by construction; the
+     * fold reads a missing scope as `project`, since that is what those logs meant.
+     */
+    scope?: MemoryScope;
     createdAt: number;
     sessionId?: string;
     step?: number;
@@ -37,6 +158,8 @@ export interface Memory {
 }
 /** A memory folded together with every later event about it. */
 export interface MemoryState extends Memory {
+    /** Always known here: the fold derives it from the log the memory was read out of. */
+    scope: MemoryScope;
     status: MemoryStatus;
     supersededReason?: string;
     supersededBy?: string;
@@ -83,10 +206,47 @@ export interface Conflict {
     subject: string;
     memories: MemoryState[];
 }
+/** A statement the capture heuristics noticed but did not have permission to keep. */
+export interface Candidate {
+    id: string;
+    text: string;
+    kind: MemoryKind;
+    proposedAt: number;
+    sessionId?: string;
+}
+/**
+ * Where a candidate stands.
+ *
+ * `dismissed` is kept rather than deleted: the question was asked and answered, and a
+ * queue that forgets the answer asks it again on the next step.
+ */
+export type CandidateStatus = 'pending' | 'accepted' | 'dismissed';
+export interface CandidateState extends Candidate {
+    status: CandidateStatus;
+}
+/** The candidate log, folded the same way the memory log is. */
+export type CandidateEvent = {
+    type: 'propose';
+    at: number;
+    candidate: Candidate;
+} | {
+    type: 'decide';
+    at: number;
+    id: string;
+    status: Exclude<CandidateStatus, 'pending'>;
+};
 /** One verification result per memory that was considered. */
 export interface VerifyResult {
     id: string;
     text: string;
+    /**
+     * The check that produced this outcome, when there was one.
+     *
+     * Reported rather than left to the caller to look up: `verify` already holds the guard
+     * it just ran, and a caller that wanted to describe the outcome would otherwise fold
+     * the whole log once per result to fetch what it was already handed.
+     */
+    guard?: Guard;
     /** `uncheckable` means no guard could be compiled — not that the memory is wrong. */
     outcome: GuardOutcome | 'uncheckable';
     exitCode: number | null;
@@ -103,12 +263,31 @@ export interface VerifySummary {
 export interface PanelPayload {
     active: MemoryState[];
     superseded: MemoryState[];
+    /**
+     * Active memories a check contradicted.
+     *
+     * Listed apart from `active` because they are a different kind of statement: still
+     * recorded, still visible, but no longer offered as guidance. The panel must show them
+     * — a memory the world disproved is the most informative record in the log — while the
+     * injection path must not.
+     */
+    contradicted: MemoryState[];
     conflicts: Conflict[];
+    /**
+     * Statements the capture heuristics noticed but did not have permission to keep.
+     *
+     * In the panel payload rather than folded into `active`, because they are a question
+     * for the user, not a memory: a candidate has no scope, no guard, and no claim on
+     * recall until someone accepts it.
+     */
+    candidates: CandidateState[];
     totals: {
         active: number;
         superseded: number;
+        contradicted: number;
         withGuard: number;
         verified: number;
         unverified: number;
+        candidates: number;
     };
 }

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Context memory",
+    "description": "Remembers what you decided across sessions, injects the relevant parts before each step, and re-checks the claims it can check."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "跨会话记忆",
+    "description": "记住你在不同会话里定过的事，每次回复前自动注入相关的那几条，并重新核对能核对的部分。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-memory",
-  "version": "0.7.1",
+  "version": "0.10.0",
   "description": "Cross-session memory for your dsh agent: remembered, recalled, and re-verified instead of assumed.",
   "type": "module",
   "main": "lib/index.js",
@@ -17,14 +17,19 @@
       "types": "./lib/client/index.d.ts",
       "default": "./lib/memory.web.js"
     },
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
     "./package.json": "./package.json"
   },
   "files": [
     "lib",
     "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
     "README.md",
     "CHANGELOG.md"
   ],
+  "icon": "./icon.svg",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -62,25 +67,27 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2"
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-brand": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.2",
     "@types/node": "^22.20.3",
     "@types/react": "^19.3.0",
     "esbuild": "^0.28.2",