@dsh-cc/memory 0.5.0

package/lib/recall.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dynamic recall: an `agent/pre-step` listener that asks a small-model side
+ * query (a forked subagent) which topic files are relevant to the turn, then
+ * injects their bodies through `agent.inject()`. Topic files already shown
+ * this session are never re-injected. Recall runs for top-level agents only —
+ * a forked child (including the selector itself) never recalls, so no chain of
+ * memory-recall subagents can form. Best-effort: absence of the subagent
+ * service or provider skips recall without error.
+ * @module @dsh-cc/memory/recall
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        memory: {
+            kind: 'memory';
+        };
+    }
+}
+/** How many topic files the selector may surface per query. */
+export declare const MAX_RECALL_MEMORIES = 5;
+/** One topic file offered to the selector. */
+export interface RecallCandidate {
+    path: string;
+    filename: string;
+    description: string;
+}
+/** The async relevance selector contract, injectable for tests. */
+export interface MemorySelector {
+    /**
+     * Pick at most {@link MAX_RECALL_MEMORIES} filenames relevant to a query.
+     * @param query - the user turn text.
+     * @param candidates - topic files (filename + description) not yet shown.
+     * @param signal - cancellation for the underlying model request.
+     * @param recentTools - tool names used earlier this session; the selector
+     *   should not surface usage-reference/API-doc memories for these tools.
+     * @returns selected filenames.
+     */
+    select(query: string, candidates: readonly RecallCandidate[], signal: AbortSignal, recentTools: readonly string[]): Promise<string[]>;
+}
+/**
+ * Default selector backed by `ctx.subagents`: asks a forked small-model
+ * one-shot subagent to return the filenames most useful for the query. The
+ * parent agent is supplied per query so the child seeds from the right turn.
+ */
+export declare class SubagentMemorySelector implements MemorySelector {
+    private readonly ctx;
+    private readonly parent;
+    private readonly providerName;
+    private readonly agentOptions?;
+    /**
+     * Create a subagent-backed selector for one parent agent.
+     * @param ctx - host context with the optional `subagents` service.
+     * @param parent - the agent whose turn triggers recall.
+     * @param providerName - the one-shot provider to fork (default `fork`).
+     * @param agentOptions - optional model selection passed to the child.
+     */
+    constructor(ctx: Context, parent: Agent, providerName?: string, agentOptions?: unknown | undefined);
+    select(query: string, candidates: readonly RecallCandidate[], signal: AbortSignal, recentTools: readonly string[]): Promise<string[]>;
+}
+/** Loose JSON extraction tolerant of code fences and prose around the array. */
+export declare function extractSelectedNames(text: string): string[];
+/** The per-agent recall coordinator. Holds the shown-path set per agent. */
+export declare class MemoryRecall {
+    private readonly ctx;
+    private readonly home;
+    private readonly state;
+    private readonly providerName;
+    private readonly createSelector;
+    private readonly recentTools;
+    private readonly disposers;
+    /**
+     * Register the `agent/pre-step` and `tools/post-execute` listeners.
+     * @param ctx - host context with `fs`, `subagents`, and the agent channel.
+     * @param home - the memory home: the global directory and the root under
+     *   which each agent's workspace directory (`projects/<slug>`) is resolved.
+     * @param options - provider name, whether recall is enabled, and an optional
+     *   selector factory (defaults to {@link SubagentMemorySelector}; inject a
+     *   fake for deterministic tests).
+     */
+    constructor(ctx: Context, home: string, options?: {
+        providerName?: string;
+        enabled?: boolean;
+        createSelector?: (ctx: Context, agent: Agent) => MemorySelector;
+    });
+    /** Remove both the pre-step and post-execute listeners. */
+    dispose(): void;
+    private onPreStep;
+    private maybeRecall;
+}
+//# sourceMappingURL=recall.d.ts.map

package/lib/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../src/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAmB,MAAM,wBAAwB,CAAA;AAMpE,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,gBAAgB;QACxB,MAAM,EAAE;YAAE,IAAI,EAAE,QAAQ,CAAA;SAAE,CAAA;KAC3B;CACF;AAMD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CACrB;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IASzD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAXhC;;;;;;OAMG;gBAEgB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,KAAK,EACb,YAAY,SAAS,EACrB,YAAY,CAAC,EAAE,OAAO,YAAA;IAGnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,eAAe,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAmD5I;AAeD,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAY3D;AAED,4EAA4E;AAC5E,qBAAa,YAAY;IAiBrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAjBvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkE;IACxF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgD;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD;;;;;;;;OAQG;gBAEgB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EAC7B,OAAO,GAAE;QACP,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,cAAc,CAAA;KAC3D;IAsBR,2DAA2D;IAC3D,OAAO,IAAI,IAAI;YAKD,SAAS;YA4BT,WAAW;CA+D1B"}

package/lib/recall.js

@@ -0,0 +1,253 @@
+/**
+ * Dynamic recall: an `agent/pre-step` listener that asks a small-model side
+ * query (a forked subagent) which topic files are relevant to the turn, then
+ * injects their bodies through `agent.inject()`. Topic files already shown
+ * this session are never re-injected. Recall runs for top-level agents only —
+ * a forked child (including the selector itself) never recalls, so no chain of
+ * memory-recall subagents can form. Best-effort: absence of the subagent
+ * service or provider skips recall without error.
+ * @module @dsh-cc/memory/recall
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { scanMemoryDirectory } from "./scan.js";
+import { cwdOf, resolveWorkspaceMemoryDir } from "./paths.js";
+// The canonical `tools/post-execute` waterfall signature comes from
+// @dsh-cc/tools (a real dependency since save.ts); memory only observes
+// tool usage for recall suppression and delegates to `next()` unchanged.
+/** How many topic files the selector may surface per query. */
+export const MAX_RECALL_MEMORIES = 5;
+/**
+ * Default selector backed by `ctx.subagents`: asks a forked small-model
+ * one-shot subagent to return the filenames most useful for the query. The
+ * parent agent is supplied per query so the child seeds from the right turn.
+ */
+export class SubagentMemorySelector {
+    ctx;
+    parent;
+    providerName;
+    agentOptions;
+    /**
+     * Create a subagent-backed selector for one parent agent.
+     * @param ctx - host context with the optional `subagents` service.
+     * @param parent - the agent whose turn triggers recall.
+     * @param providerName - the one-shot provider to fork (default `fork`).
+     * @param agentOptions - optional model selection passed to the child.
+     */
+    constructor(ctx, parent, providerName = 'fork', agentOptions) {
+        this.ctx = ctx;
+        this.parent = parent;
+        this.providerName = providerName;
+        this.agentOptions = agentOptions;
+    }
+    async select(query, candidates, signal, recentTools) {
+        const subagents = this.ctx.get('subagents');
+        if (subagents === undefined)
+            return [];
+        const manifest = candidates
+            .map(candidate => `- ${candidate.filename}: ${candidate.description}`)
+            .join('\n');
+        const system = [
+            'You select memories useful for processing a user query.',
+            `Return a JSON object with a "selected_memories" array of filenames (at most ${MAX_RECALL_MEMORIES}).`,
+            'Only include memories you are certain are helpful. If none are clearly useful, return an empty array.',
+            'If a list of recently-used tools is provided, do not select memories that are usage reference or API documentation for those tools (the agent is already exercising them). DO still select memories containing warnings, gotchas, or known issues about those tools — active use is exactly when those matter.',
+        ].join('\n');
+        // When a tool is actively in use, its reference-doc memory is noise — the
+        // conversation already contains working usage and keyword overlap would
+        // otherwise false-positive the selector. Surface the list so it can suppress.
+        const toolsSection = recentTools.length > 0
+            ? `\n\nRecently used tools: ${recentTools.join(', ')}`
+            : '';
+        let run;
+        try {
+            run = await subagents.start(this.providerName, {
+                label: 'memory-recall',
+                signal,
+                prompt: [{ type: 'text', text: `${system}\n\nQuery: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}` }],
+                parent: this.parent,
+                ...(this.agentOptions !== undefined ? { agentOptions: this.agentOptions } : {}),
+            });
+        }
+        catch {
+            // Provider absent or services unavailable: best-effort recall skips.
+            return [];
+        }
+        // run.result rejects only on infrastructure faults; child-level failures
+        // arrive RESOLVED with a non-completed stopReason. Both must skip recall
+        // quietly — this path is fire-and-forget, so a throw becomes an unhandled
+        // rejection in the host.
+        let result;
+        try {
+            result = await run.result;
+        }
+        catch {
+            return [];
+        }
+        if (result.stopReason === 'error')
+            return [];
+        // SubagentResult carries the transcript blocks as `output` (not `content`).
+        const text = (result.output ?? [])
+            .filter(block => block.type === 'text')
+            .map(block => block.text ?? '')
+            .join('');
+        const names = extractSelectedNames(text);
+        const valid = new Set(candidates.map(candidate => candidate.filename));
+        return names.filter(name => valid.has(name)).slice(0, MAX_RECALL_MEMORIES);
+    }
+}
+/** Loose JSON extraction tolerant of code fences and prose around the array. */
+export function extractSelectedNames(text) {
+    const match = /"selected_memories"\s*:\s*(\[[^\]]*\])/.exec(text);
+    const encoded = match?.[1];
+    if (encoded === undefined)
+        return [];
+    try {
+        const parsed = JSON.parse(encoded);
+        return Array.isArray(parsed)
+            ? parsed.filter((value) => typeof value === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The per-agent recall coordinator. Holds the shown-path set per agent. */
+export class MemoryRecall {
+    ctx;
+    home;
+    state = new WeakMap();
+    providerName;
+    createSelector;
+    recentTools = new Set();
+    disposers = [];
+    /**
+     * Register the `agent/pre-step` and `tools/post-execute` listeners.
+     * @param ctx - host context with `fs`, `subagents`, and the agent channel.
+     * @param home - the memory home: the global directory and the root under
+     *   which each agent's workspace directory (`projects/<slug>`) is resolved.
+     * @param options - provider name, whether recall is enabled, and an optional
+     *   selector factory (defaults to {@link SubagentMemorySelector}; inject a
+     *   fake for deterministic tests).
+     */
+    constructor(ctx, home, options = {}) {
+        this.ctx = ctx;
+        this.home = home;
+        this.providerName = options.providerName ?? 'fork';
+        this.createSelector = options.createSelector
+            ?? ((ctx, agent) => new SubagentMemorySelector(ctx, agent, this.providerName));
+        if (options.enabled ?? true) {
+            this.disposers.push(this.ctx.on('agent/pre-step', (payload, next) => this.onPreStep(payload, next)));
+        }
+        // Track tools used this session so recall can suppress reference-doc
+        // memories for the tools the agent is already exercising. This is a
+        // waterfall observer: it must delegate to `next()` so the tools pipeline
+        // continues unchanged.
+        this.disposers.push(this.ctx.on('tools/post-execute', (exec, _result, next) => {
+            if (exec.name.length > 0)
+                this.recentTools.add(exec.name);
+            return next();
+        }));
+    }
+    /** Remove both the pre-step and post-execute listeners. */
+    dispose() {
+        for (const dispose of this.disposers.splice(0))
+            dispose();
+        this.recentTools.clear();
+    }
+    async onPreStep({ agent, messages, signal, }, next) {
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        signal.throwIfAborted();
+        // Recall enriches top-level agents only. Every agent runs this same
+        // waterfall — including the forked memory-recall selector itself — so
+        // recalling inside a subagent would spawn another selector whose own
+        // pre-step recalls again: an unbounded chain of memory-recall subagents.
+        const header = agent.session.header;
+        if (header.origin === 'subagent' || (header.delegationDepth ?? 0) > 0)
+            return decision;
+        // Fire-and-forget: recall is model-visible enrichment, never worth an
+        // unhandled rejection in the host — any fault inside skips quietly.
+        void this.maybeRecall(agent, messages, signal, this.createSelector(this.ctx, agent))
+            .catch(() => { });
+        return decision;
+    }
+    async maybeRecall(agent, messages, signal, selector) {
+        const fileSystem = this.ctx.get('fs');
+        if (fileSystem === undefined)
+            return;
+        const query = messages
+            .map(message => message.content.filter(block => block.type === 'text').map(block => block.text ?? '').join(' '))
+            .join('\n')
+            .trim();
+        if (query.length === 0)
+            return;
+        // Recall spans both layers: the agent's workspace directory and the
+        // global directory. Shown-tracking keys on full paths, so identical
+        // filenames across layers never collide.
+        const workspaceDir = resolveWorkspaceMemoryDir(this.home, cwdOf(agent));
+        const [workspaceScan, globalScan] = await Promise.all([
+            scanMemoryDirectory(fileSystem, workspaceDir, signal),
+            scanMemoryDirectory(fileSystem, this.home, signal),
+        ]);
+        const topics = [...workspaceScan.topics, ...globalScan.topics];
+        if (topics.length === 0)
+            return;
+        let entry = this.state.get(agent);
+        if (entry === undefined) {
+            entry = { shown: new Set(), inFlight: false };
+            this.state.set(agent, entry);
+        }
+        const fresh = topics.filter(topic => !entry.shown.has(topic.path));
+        if (fresh.length === 0)
+            return;
+        // Pre-step fires once per step while a turn runs; a pending selection must
+        // not pile up overlapping selectors for the same agent.
+        if (entry.inFlight)
+            return;
+        entry.inFlight = true;
+        try {
+            const selected = await selector.select(query, fresh.map(topic => ({ path: topic.path, filename: topic.filename, description: topic.frontmatter.description })), signal, Array.from(this.recentTools));
+            if (signal.aborted || selected.length === 0)
+                return;
+            const byFilename = new Map(topics.map(topic => [topic.filename, topic]));
+            const bodies = [];
+            for (const filename of selected) {
+                const topic = byFilename.get(filename);
+                if (topic === undefined)
+                    continue;
+                entry.shown.add(topic.path);
+                const raw = await readOptionalText(fileSystem, topic.path, signal);
+                if (raw !== undefined && raw.trim().length > 0) {
+                    bodies.push(`## Memory: ${topic.frontmatter.name}\n\n${raw.trim()}`);
+                }
+            }
+            signal.throwIfAborted();
+            if (bodies.length === 0)
+                return;
+            agent.inject(createUserMessage({
+                content: [{ type: 'text', text: bodies.join('\n\n') }],
+                source: { kind: 'memory' },
+            }));
+        }
+        finally {
+            entry.inFlight = false;
+        }
+    }
+}
+async function readOptionalText(fs, path, signal) {
+    try {
+        const target = signal !== undefined
+            ? await fs.resolve(path, { signal })
+            : await fs.resolve(path);
+        return await fs.readText(target, signal);
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error
+            && (error.code === 'FS_NOT_FOUND'
+                || error.code === 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=recall.js.map

package/lib/recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.js","sourceRoot":"","sources":["../src/recall.ts"],"names":[],"mappings":"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"}

package/lib/save.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The `memory_save` tool: the model-facing save channel for the memory
+ * directory.
+ *
+ * Direct `write`/`edit` calls aimed at the memory directory always fail — it
+ * lives in the harness home, outside every session workspace, so the fs
+ * sandbox fences them. This tool is the working alternative: the model passes
+ * structured fields, the plugin generates the frontmatter, maintains the
+ * MEMORY.md pointer, and writes host-side under a per-call policy confined to
+ * the memory directory (see `writeback.ts`).
+ * @module @dsh-cc/memory/save
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemorySection } from './section.ts';
+/** The registered tool name. */
+export declare const MEMORY_SAVE_TOOL = "memory_save";
+/** Where a saved memory lands. */
+export declare const MEMORY_SAVE_SCOPES: readonly ["workspace", "global"];
+/** A model-visible save failure (maps to an isError tool result). */
+export declare class MemorySaveError extends Error {
+}
+export interface MemorySaveArgs {
+    /** Kebab-case topic slug; the topic file is `<name>.md`. */
+    name: string;
+    /** One of the four memory types. */
+    type: string;
+    /** One-line relevance description for the MEMORY.md pointer. */
+    description: string;
+    /** Markdown body (frontmatter is generated host-side). */
+    body: string;
+    /** `workspace` (default) saves to this workspace's directory; `global` saves to the cross-workspace directory. */
+    scope?: string;
+}
+/** Assemble the topic file body with rationalized frontmatter. */
+export declare function renderTopicFile(args: MemorySaveArgs): string;
+/** The MEMORY.md pointer line for one topic (mirrors the section's index format). */
+export declare function pointerLine(args: MemorySaveArgs): string;
+/**
+ * Upsert the topic's pointer in the MEMORY.md body: replace the line whose
+ * link target is `<name>.md`, append otherwise.
+ */
+export declare function upsertPointer(entrypoint: string, args: MemorySaveArgs): string;
+/**
+ * Register the `memory_save` tool. No-op when the host has no tools service
+ * or no fs seam (a providerless host keeps memory read-only).
+ * @param ctx - the host context.
+ * @param home - the memory home: the global directory and the root under
+ *   which each workspace's private directory lives (`projects/<slug>`).
+ * @param section - the memory section to refresh after a successful save.
+ * @returns the registration disposer, or `undefined` when not registered.
+ */
+export declare function registerMemorySaveTool(ctx: Context, home: string, section: MemorySection): (() => void) | undefined;
+//# sourceMappingURL=save.d.ts.map

package/lib/save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../src/save.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,gCAAgC;AAChC,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAO7C,kCAAkC;AAClC,eAAO,MAAM,kBAAkB,kCAAmC,CAAA;AAElE,qEAAqE;AACrE,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,kHAAkH;IAClH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAW5D;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAW9E;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GACrB,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAmF1B"}

package/lib/save.js

@@ -0,0 +1,180 @@
+/**
+ * The `memory_save` tool: the model-facing save channel for the memory
+ * directory.
+ *
+ * Direct `write`/`edit` calls aimed at the memory directory always fail — it
+ * lives in the harness home, outside every session workspace, so the fs
+ * sandbox fences them. This tool is the working alternative: the model passes
+ * structured fields, the plugin generates the frontmatter, maintains the
+ * MEMORY.md pointer, and writes host-side under a per-call policy confined to
+ * the memory directory (see `writeback.ts`).
+ * @module @dsh-cc/memory/save
+ */
+import { join } from 'node:path';
+import { defineTool } from '@dsh-cc/tools';
+import { MEMORY_TYPES } from "./types.js";
+import { ENTRYPOINT_NAME } from "./truncate.js";
+import { validateMemoryWrites, writeMemoryFiles } from "./writeback.js";
+import { cwdOf, resolveWorkspaceMemoryDir } from "./paths.js";
+/** The registered tool name. */
+export const MEMORY_SAVE_TOOL = 'memory_save';
+/** Topic slugs are kebab-case; the file is `<name>.md`. */
+const NAME_RULE = /^[a-z0-9][a-z0-9-]*$/;
+/** One-line relevance description cap. */
+const MAX_DESCRIPTION_CHARS = 200;
+/** Where a saved memory lands. */
+export const MEMORY_SAVE_SCOPES = ['workspace', 'global'];
+/** A model-visible save failure (maps to an isError tool result). */
+export class MemorySaveError extends Error {
+}
+/** Assemble the topic file body with rationalized frontmatter. */
+export function renderTopicFile(args) {
+    return [
+        '---',
+        `name: ${args.name}`,
+        `description: ${args.description}`,
+        `type: ${args.type}`,
+        '---',
+        '',
+        args.body.trimEnd(),
+        '',
+    ].join('\n');
+}
+/** The MEMORY.md pointer line for one topic (mirrors the section's index format). */
+export function pointerLine(args) {
+    return `- [${args.name}](${args.name}.md) — ${args.description}`;
+}
+/**
+ * Upsert the topic's pointer in the MEMORY.md body: replace the line whose
+ * link target is `<name>.md`, append otherwise.
+ */
+export function upsertPointer(entrypoint, args) {
+    const line = pointerLine(args);
+    const target = `](${args.name}.md)`;
+    const lines = entrypoint.split('\n');
+    const at = lines.findIndex(l => l.includes(target));
+    if (at >= 0) {
+        lines[at] = line;
+        return lines.join('\n');
+    }
+    const trimmed = entrypoint.trimEnd();
+    return trimmed.length > 0 ? `${trimmed}\n${line}\n` : `${line}\n`;
+}
+function validateArgs(args) {
+    if (!NAME_RULE.test(args.name)) {
+        throw new MemorySaveError(`invalid memory name "${args.name}": use a kebab-case slug (lowercase letters, digits, dashes)`);
+    }
+    if (args.name.toLowerCase() === 'memory') {
+        throw new MemorySaveError('the name "memory" is reserved for the MEMORY.md index');
+    }
+    if (!MEMORY_TYPES.includes(args.type)) {
+        throw new MemorySaveError(`invalid memory type "${args.type}": use one of ${MEMORY_TYPES.join(', ')}`);
+    }
+    if (args.description.trim().length === 0 || args.description.includes('\n')) {
+        throw new MemorySaveError('description must be a single non-empty line');
+    }
+    if (args.description.length > MAX_DESCRIPTION_CHARS) {
+        throw new MemorySaveError(`description is ${args.description.length} chars, over the ${MAX_DESCRIPTION_CHARS} cap`);
+    }
+    if (args.body.trim().length === 0) {
+        throw new MemorySaveError('body must not be empty');
+    }
+    if (args.scope !== undefined && !MEMORY_SAVE_SCOPES.includes(args.scope)) {
+        throw new MemorySaveError(`invalid memory scope "${args.scope}": use one of ${MEMORY_SAVE_SCOPES.join(', ')}`);
+    }
+}
+/**
+ * Register the `memory_save` tool. No-op when the host has no tools service
+ * or no fs seam (a providerless host keeps memory read-only).
+ * @param ctx - the host context.
+ * @param home - the memory home: the global directory and the root under
+ *   which each workspace's private directory lives (`projects/<slug>`).
+ * @param section - the memory section to refresh after a successful save.
+ * @returns the registration disposer, or `undefined` when not registered.
+ */
+export function registerMemorySaveTool(ctx, home, section) {
+    const tools = ctx.get('tools');
+    if (tools === undefined)
+        return undefined;
+    return tools.register(defineTool({
+        name: MEMORY_SAVE_TOOL,
+        description: 'Save a durable memory (a fact or preference useful in FUTURE conversations) to the persistent memory '
+            + 'system. By default the memory is private to the current workspace; pass `scope: "global"` for facts '
+            + 'useful across all workspaces. Writes the topic file and updates the MEMORY.md index for you. This is '
+            + 'the ONLY way to save memories: direct write/edit calls to a memory directory are fenced by the '
+            + 'sandbox and always fail. Do not use it for ephemeral task detail.',
+        parameters: {
+            name: {
+                type: 'string',
+                required: true,
+                description: 'Kebab-case topic slug, e.g. "user-profile". The topic file is `<name>.md`; saving an existing name overwrites it.',
+            },
+            type: {
+                type: 'string',
+                enum: MEMORY_TYPES,
+                required: true,
+                description: 'user: who the user is; feedback: how the user wants you to work; project: ongoing work state; reference: pointers to external resources.',
+            },
+            description: {
+                type: 'string',
+                required: true,
+                description: 'One-line relevance note shown in the MEMORY.md index (max 200 chars).',
+            },
+            body: {
+                type: 'string',
+                required: true,
+                description: 'Markdown body of the memory (without frontmatter — it is generated for you).',
+            },
+            scope: {
+                type: 'string',
+                enum: MEMORY_SAVE_SCOPES,
+                description: 'workspace (default): visible only to sessions in the current workspace. global: visible to every workspace.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    message: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.message }],
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const fs = ctx.get('fs');
+            if (fs === undefined)
+                throw new MemorySaveError('memory save unavailable: no fs seam');
+            validateArgs(args);
+            const dir = args.scope === 'global'
+                ? home
+                : resolveWorkspaceMemoryDir(home, exec.agent !== undefined ? cwdOf(exec.agent) : process.cwd());
+            const filename = `${args.name}.md`;
+            const writes = [
+                { path: filename, content: renderTopicFile(args) },
+            ];
+            // Reuse the write-back validator so tool saves and fork reports share
+            // one security boundary (filename rule + size caps).
+            const validated = validateMemoryWrites({ writes });
+            // Upsert the index pointer first from the CURRENT entrypoint body, then
+            // write both files under the policy confined to the memory directory.
+            let entrypoint = '';
+            try {
+                entrypoint = await fs.readText(await fs.resolve(join(dir, ENTRYPOINT_NAME)));
+            }
+            catch {
+                // No index yet — the upsert starts from an empty body.
+            }
+            validated.push({ path: ENTRYPOINT_NAME, content: upsertPointer(entrypoint, args) });
+            await writeMemoryFiles(fs, dir, validated);
+            await section.refresh(exec.agent);
+            return {
+                path: join(dir, filename),
+                message: `Saved memory "${args.name}" (${args.type}) to ${filename} and updated ${ENTRYPOINT_NAME}.`,
+            };
+        },
+    }));
+}
+//# sourceMappingURL=save.js.map

package/lib/save.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.js","sourceRoot":"","sources":["../src/save.ts"],"names":[],"mappings":"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"}

package/lib/scan.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Directory scan over a memdir through the optional `ctx.fs` seam: list topic
+ * files, parse their frontmatter, and read the always-loaded entrypoint. Used
+ * by the system-prompt section index and by recall.
+ * @module @dsh-cc/memory/scan
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { MemoryIndexEntry } from './types.ts';
+/** One observed memdir state. */
+export interface MemoryDirectoryState {
+    /** The memory directory path. */
+    dir: string;
+    /** Raw (pre-truncation) entrypoint text, or `undefined` when absent. */
+    entrypoint: string | undefined;
+    /** Topic files with rationalized headers, excluding MEMORY.md itself. */
+    topics: MemoryIndexEntry[];
+}
+/**
+ * Scan a memory directory for its entrypoint and topic files.
+ * A missing directory or entrypoint is not an error — the caller renders an
+ * empty section. Files are read with the caller's cancellation signal; the
+ * result contains only topics whose frontmatter parsed successfully.
+ * @param fs - the contiguous filesystem seam.
+ * @param dir - the memory directory to scan.
+ * @param signal - optional cancellation for the underlying fs reads.
+ * @returns the observed directory state, never throwing for absent files.
+ */
+export declare function scanMemoryDirectory(fs: FileSystem, dir: string, signal?: AbortSignal): Promise<MemoryDirectoryState>;
+//# sourceMappingURL=scan.d.ts.map

package/lib/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,qBAAqB,CAAA;AAGxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,yEAAyE;IACzE,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CA4B/B"}