dsh-memory-recall 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-memory-recall",
-  "version": "0.1.0",
-  "description": "Persistent memory for dsh in the style of Hermes Agent: a memory tool that keeps a user profile and the model's own notes in every new chat's prompt, and a session_search tool that reads earlier chats only after the user approves, with a Memory panel to see and edit what is kept.",
+  "version": "0.2.1",
+  "description": "Persistent memory for dsh in the style of Hermes Agent: a memory tool that keeps a user profile and the model's own notes, delivered to every chat as a logged context message — at the start, after a change and after compaction — and a session_search tool that reads earlier chats only after the user approves, with a Memory panel to see and edit what is kept.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {

package/src/index.js

@@ -1,156 +1,217 @@
-// dsh-memory-recall — Hermes Agent-style memory for dsh.
-//
-//   memory          the model saves, corrects and forgets facts in USER.md and
-//                   MEMORY.md; every new chat starts with them in its prompt
-//   session_search  the model looks things up in earlier chats — after the
-//                   user allows it, through dsh's own approval prompt
-//
-// Data lives in ~/.dsh/dsh-memory-recall/. Nothing leaves the machine.
-//
-// Config (all optional, set on this plugin's row in cordis.patch.yml):
-//   dir                   where USER.md and MEMORY.md live
-//   limits: {memory, user} character budgets (default 2200 / 1375)
-//   recall: false         drop session_search, keep memory
-//   askBeforeRecall: false read earlier chats without asking (default: ask)
-
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { MemoryStore } from './store.js';
-import { SECTION_NAME, SECTION_ORDER, renderSection } from './snapshot.js';
-import { createMemoryTool } from './memory-tool.js';
-import { createRecall } from './recall.js';
-import { createRecallTool } from './recall-tool.js';
-import { createRecallLog, registerRoutes } from './routes.js';
-import { createChatIndex } from './chats.js';
-import { loadDefineTool } from './dsh-tools.js';
-
-export const name = 'dsh-memory-recall';
-
-/**
- * Required services only. The session query, approval and system-prompt
- * services are resolved per use with `get`, so a composition without one
- * loses that feature rather than failing to load the plugin.
- */
-export const inject = ['webServer', 'tools'];
-
-/** Look a service up without throwing when it is absent. */
-function service(ctx, id) {
-  try {
-    return ctx?.get?.(id);
-  } catch {
-    return undefined;
-  }
-}
-
-/** A user's own chat — not a sub-agent the model started. */
-function isTopLevel(agent) {
-  const header = agent?.session?.header;
-  return !header || (!header.parentSession && header.origin !== 'subagent');
-}
-
-/**
- * @param {object} ctx host plugin context
- * @param {object} [config]
- * @param {object} [deps] test hooks: defineTool, loadDefineTool
- */
-export async function apply(ctx, config = {}, deps = {}) {
-  const dir = config.dir || join(homedir(), '.dsh', 'dsh-memory-recall');
-  const store = new MemoryStore({ dir, limits: config.limits });
-  await store.load();
-
-  const log = createRecallLog();
-  const grants = new Map();
-  // Every chat, grouped by workspace: the @ menu's list, and what a
-  // `workspace` given to session_search resolves against.
-  const chatIndex = createChatIndex({
-    getQuery: () => service(ctx, 'sessionQuery'),
-    getWorkspaces: () => service(ctx, 'workspaceRegistry'),
-  });
-  const cwdOf = async (sessionId) => {
-    try {
-      const rows = await service(ctx, 'sessionQuery')?.filterSessions?.([{ kind: 'id', values: [sessionId] }]);
-      return rows?.[0]?.header?.cwd ?? null;
-    } catch {
-      return null;
-    }
-  };
-  const disposers = [];
-  // Whether the model actually got its tools. The prompt and the Memory
-  // panel both read this, so neither can promise a tool that is not there.
-  const tooling = { ok: false, error: null, tools: [] };
-
-  // ---- the model's tools ----------------------------------------------
-  if (ctx.tools?.register) {
-    try {
-      const defineTool = deps.defineTool ?? (await (deps.loadDefineTool ?? loadDefineTool)());
-      const tools = [createMemoryTool({ store, defineTool })];
-      if (config.recall !== false) {
-        const recall = createRecall({ getQuery: () => service(ctx, 'sessionQuery'), options: config.recallOptions });
-        tools.push(createRecallTool({
-          recall,
-          defineTool,
-          getApproval: () => service(ctx, 'approval'),
-          grants,
-          log,
-          askFirst: config.askBeforeRecall !== false,
-          resolveWorkspace: (name) => chatIndex.resolveWorkspace(name),
-          listWorkspaces: async () => (await chatIndex.list()).workspaces,
-        }));
-      }
-      for (const tool of tools) {
-        const dispose = ctx.tools.register(tool);
-        if (typeof dispose === 'function') disposers.push(dispose);
-        tooling.tools.push(tool.name);
-      }
-      tooling.ok = true;
-    } catch (error) {
-      tooling.error = String(error?.message ?? error);
-      ctx.logger?.warn?.(`[dsh-memory-recall] tools not registered: ${tooling.error}`);
-    }
-  } else {
-    tooling.error = 'this dsh has no tool registry';
-  }
-
-  // ---- each new chat: memory in its prompt, frozen for its lifetime ---
-  const briefed = new WeakSet();
-  ctx.on?.('agent/session-start', (payload) => {
-    const agent = payload?.agent;
-    const agentCtx = agent?.ctx;
-    if (!agentCtx || briefed.has(agentCtx) || !isTopLevel(agent)) return;
-    briefed.add(agentCtx);
-    try {
-      const prompt = service(agentCtx, 'systemPrompt');
-      if (typeof prompt?.section !== 'function') return;
-      // Read now, once: this text is what the chat keeps, so a save made later
-      // in it never rewrites its prompt (which would cost the cached prefix).
-      const text = renderSection(store.loadSync(), store.limits, { tools: tooling.ok });
-      const register = () => prompt.section({ name: SECTION_NAME, order: SECTION_ORDER, text });
-      if (typeof agentCtx.effect === 'function') agentCtx.effect(register, 'dsh-memory-recall: memory snapshot');
-      else register();
-    } catch (error) {
-      // Losing the snapshot costs this chat its memory, never the chat.
-      ctx.logger?.warn?.(`[dsh-memory-recall] no memory for this chat: ${error?.message ?? error}`);
-    }
-  });
-
-  // One "allow" lasts until the reply it was given in ends.
-  ctx.on?.('agent/status', (payload) => {
-    if (payload?.status === 'idle' && payload.agent?.id) grants.delete(payload.agent.id);
-  });
-
-  // ---- the browser half ----------------------------------------------
-  if (ctx.webServer?.register) {
-    disposers.push(registerRoutes(ctx.webServer, { store, log, chatIndex, cwdOf, tooling }));
-  } else {
-    ctx.logger?.warn?.('[dsh-memory-recall] webServer unavailable; the Memory panel and cards will be empty');
-  }
-
-  ctx.on?.('dispose', () => {
-    for (const dispose of disposers) {
-      try { dispose(); } catch { /* keep disposing the rest */ }
-    }
-  });
-  // cordis treats a returned value as an effect disposer; return nothing.
-}
-
-export default { apply, inject, name };
+// dsh-memory-recall — Hermes Agent-style memory for dsh.
+//
+//   memory          the model saves, corrects and forgets facts in USER.md and
+//                   MEMORY.md; every new chat starts with them in its prompt
+//   session_search  the model looks things up in earlier chats — after the
+//                   user allows it, through dsh's own approval prompt
+//
+// Data lives in ~/.dsh/dsh-memory-recall/. Nothing leaves the machine.
+//
+// Config (all optional, set on this plugin's row in cordis.patch.yml):
+//   dir                   where USER.md and MEMORY.md live
+//   limits: {memory, user} character budgets (default 2200 / 1375)
+//   recall: false         drop session_search, keep memory
+//   askBeforeRecall: false read earlier chats without asking (default: ask)
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { MemoryStore } from './store.js';
+import { SECTION_NAME, SECTION_ORDER, renderSection } from './snapshot.js';
+import { createMemoryTool } from './memory-tool.js';
+import { createRecall } from './recall.js';
+import { createRecallTool } from './recall-tool.js';
+import { createBriefings, createRecallLog, registerRoutes } from './routes.js';
+import { createChatIndex } from './chats.js';
+import { loadDefineTool } from './dsh-tools.js';
+import { injectionReason, memoryMessage, pendingMemory } from './inject.js';
+import { digestOf } from './routes.js';
+
+export const name = 'dsh-memory-recall';
+
+/**
+ * Required services only. The session query, approval and system-prompt
+ * services are resolved per use with `get`, so a composition without one
+ * loses that feature rather than failing to load the plugin.
+ */
+export const inject = ['webServer', 'tools'];
+
+/** Look a service up without throwing when it is absent. */
+function service(ctx, id) {
+  try {
+    return ctx?.get?.(id);
+  } catch {
+    return undefined;
+  }
+}
+
+/** A user's own chat — not a sub-agent the model started. */
+function isTopLevel(agent) {
+  const header = agent?.session?.header;
+  return !header || (!header.parentSession && header.origin !== 'subagent');
+}
+
+/**
+ * @param {object} ctx host plugin context
+ * @param {object} [config]
+ * @param {object} [deps] test hooks: defineTool, loadDefineTool
+ */
+export async function apply(ctx, config = {}, deps = {}) {
+  const dir = config.dir || join(homedir(), '.dsh', 'dsh-memory-recall');
+  const store = new MemoryStore({ dir, limits: config.limits });
+  await store.load();
+
+  const log = createRecallLog();
+  const grants = new Map();
+  // Every chat, grouped by workspace: the @ menu's list, and what a
+  // `workspace` given to session_search resolves against.
+  const chatIndex = createChatIndex({
+    getQuery: () => service(ctx, 'sessionQuery'),
+    getWorkspaces: () => service(ctx, 'workspaceRegistry'),
+  });
+  const cwdOf = async (sessionId) => {
+    try {
+      const rows = await service(ctx, 'sessionQuery')?.filterSessions?.([{ kind: 'id', values: [sessionId] }]);
+      return rows?.[0]?.header?.cwd ?? null;
+    } catch {
+      return null;
+    }
+  };
+  const disposers = [];
+  // Whether the model actually got its tools. The prompt and the Memory
+  // panel both read this, so neither can promise a tool that is not there.
+  const tooling = { ok: false, error: null, tools: [] };
+
+  // ---- the model's tools ----------------------------------------------
+  if (ctx.tools?.register) {
+    try {
+      const defineTool = deps.defineTool ?? (await (deps.loadDefineTool ?? loadDefineTool)());
+      const tools = [createMemoryTool({ store, defineTool })];
+      if (config.recall !== false) {
+        const recall = createRecall({ getQuery: () => service(ctx, 'sessionQuery'), options: config.recallOptions });
+        tools.push(createRecallTool({
+          recall,
+          defineTool,
+          getApproval: () => service(ctx, 'approval'),
+          grants,
+          log,
+          askFirst: config.askBeforeRecall !== false,
+          resolveWorkspace: (name) => chatIndex.resolveWorkspace(name),
+          listWorkspaces: async () => (await chatIndex.list()).workspaces,
+        }));
+      }
+      for (const tool of tools) {
+        const dispose = ctx.tools.register(tool);
+        if (typeof dispose === 'function') disposers.push(dispose);
+        tooling.tools.push(tool.name);
+      }
+      tooling.ok = true;
+    } catch (error) {
+      tooling.error = String(error?.message ?? error);
+      ctx.logger?.warn?.(`[dsh-memory-recall] tools not registered: ${tooling.error}`);
+    }
+  } else {
+    tooling.error = 'this dsh has no tool registry';
+  }
+
+  // ---- each new chat: memory guidance in its prompt, frozen for its
+  // lifetime. dsh 0.1.7 removed `agent/session-start`; `agent/created` and
+  // `agent/disposed` exist on every dsh from 0.1.0-rc.7 through 0.2.x, so
+  // they are the seam — session-start stays wired as a back-compat path,
+  // deduped by the same map.
+  /** Agent contexts already carrying the section -> the registering fiber. */
+  const briefed = new WeakMap();
+  // sessionId -> what that chat's prompt was given, for the composer chip.
+  const briefings = createBriefings();
+
+  const installGuidance = (agent) => {
+    const agentCtx = agent?.ctx;
+    if (!agentCtx || briefed.has(agentCtx) || !isTopLevel(agent)) return;
+    try {
+      // Read now, once: this text is what the chat keeps, so a save made later
+      // in it never rewrites its prompt (which would cost the cached prefix).
+      // The guidance only: fixed text, so the cached prompt prefix holds.
+      const text = renderSection(null, store.limits, { tools: tooling.ok });
+      // `inject` rather than `get`: at agent/created the prompt service may not
+      // be resolvable yet; the callback runs once it is, and the fiber's
+      // dispose() takes the section back out.
+      const fiber = agentCtx.inject?.(['systemPrompt'], (scope) => {
+        if (!isTopLevel(agent)) return; // the header may have attached since created
+        try {
+          scope.systemPrompt?.section?.({ name: SECTION_NAME, order: SECTION_ORDER, text });
+        } catch {
+          // Already registered (e.g. after a plugin reload): a duplicate name throws.
+        }
+      });
+      if (fiber) briefed.set(agentCtx, fiber);
+    } catch (error) {
+      // Losing the guidance costs this chat its memory, never the chat.
+      ctx.logger?.warn?.(`[dsh-memory-recall] no memory for this chat: ${error?.message ?? error}`);
+    }
+  };
+
+  const uninstallGuidance = (agent) => {
+    const agentCtx = agent?.ctx;
+    const fiber = agentCtx && briefed.get(agentCtx);
+    if (!fiber) return;
+    briefed.delete(agentCtx);
+    try {
+      fiber.dispose?.();
+    } catch {
+      // Teardown must not throw.
+    }
+  };
+
+  // Agents that already exist when this plugin mounts (a reload).
+  ctx.inject?.(['agents'], (scope) => {
+    for (const agent of scope.agents?.list?.() ?? []) installGuidance(agent);
+  });
+  ctx.on?.('agent/created', (payload) => installGuidance(payload?.agent));
+  ctx.on?.('agent/disposed', (payload) => uninstallGuidance(payload?.agent));
+  // Older hosts fire this instead of agent/created; the map dedupes.
+  ctx.on?.('agent/session-start', (payload) => installGuidance(payload?.agent));
+
+  // ---- the memory itself: a logged context message, whenever the chat
+  // cannot see the current version (start, after compaction, after a change).
+  ctx.on?.('agent/pre-step', async (payload, next) => {
+    const decision = await next();
+    const agent = payload?.agent;
+    if (!decision || decision.kind === 'reject' || !agent?.session || !isTopLevel(agent)) return decision;
+    try {
+      const stores = await store.load();
+      const reason = injectionReason(agent.session, digestOf(stores));
+      const pending = pendingMemory(decision.messages);
+      if (!reason) {
+        return pending ? { ...decision, messages: decision.messages.filter((m) => m !== pending) } : decision;
+      }
+      const message = memoryMessage(stores, store.limits, reason);
+      if (agent.id) briefings.record(agent.id, stores, reason);
+      const messages = decision.messages ?? [];
+      return { ...decision, messages: pending ? messages.map((m) => (m === pending ? message : m)) : [...messages, message] };
+    } catch (error) {
+      // Memory that cannot be read costs this step its memory, never the step.
+      ctx.logger?.warn?.(`[dsh-memory-recall] memory not delivered: ${error?.message ?? error}`);
+      return decision;
+    }
+  });
+
+  // One "allow" lasts until the reply it was given in ends.
+  ctx.on?.('agent/status', (payload) => {
+    if (payload?.status === 'idle' && payload.agent?.id) grants.delete(payload.agent.id);
+  });
+
+  // ---- the browser half ----------------------------------------------
+  if (ctx.webServer?.register) {
+    disposers.push(registerRoutes(ctx.webServer, { store, log, chatIndex, cwdOf, tooling, briefings }));
+  } else {
+    ctx.logger?.warn?.('[dsh-memory-recall] webServer unavailable; the Memory panel and cards will be empty');
+  }
+
+  ctx.on?.('dispose', () => {
+    for (const dispose of disposers) {
+      try { dispose(); } catch { /* keep disposing the rest */ }
+    }
+  });
+  // cordis treats a returned value as an effect disposer; return nothing.
+}
+
+export default { apply, inject, name };

package/src/inject.js

@@ -0,0 +1,87 @@
+// Memory as a logged context message, the way dsh delivers its skill catalog.
+//
+// Before each model step (`agent/pre-step`), memory is appended to the step's
+// new messages when the chat does not already SEE the current version:
+//
+//   start       the chat has never been given memory
+//   compaction  it was given memory, but that message is no longer on the
+//               visible surface — the conversation was compacted past it
+//   update      the memory it can see is older than what is on disk
+//
+// dsh logs each one as a "Context injection · memory · <summary>" row the user
+// can expand, and the model gets the current memory in the conversation itself,
+// next to the work — no tool call, nothing the model has to remember to do.
+
+import { randomUUID } from 'node:crypto';
+import { digestOf } from './routes.js';
+import { renderBlock } from './snapshot.js';
+
+/** The producer label dsh shows on the row ("Context injection · memory"). */
+export const INJECT_LABEL = 'memory';
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+/** "2 profile · 5 notes", the counts part of the row's summary. */
+export function countsText(stores) {
+  return `${(stores.user ?? []).length} profile · ${plural((stores.memory ?? []).length, 'note', 'notes')}`;
+}
+
+/** Is this logged message one of ours? */
+function isMemorySource(source) {
+  return source?.kind === 'plugin' && source?.plugin === INJECT_LABEL;
+}
+
+/**
+ * Why the chat needs memory now, or null when it already sees the current one.
+ * @param {object} session  agent.session: seq, eventAt(i), surface.nodes
+ * @param {string} digest   digestOf(the stores on disk)
+ */
+export function injectionReason(session, digest) {
+  const visible = new Set(session?.surface?.nodes ?? []);
+  let seen = false;
+  for (let index = (session?.seq ?? 0) - 1; index >= 0; index -= 1) {
+    const event = session.eventAt(index);
+    if (event?.type !== 'user/message' || !isMemorySource(event.data?.source)) continue;
+    seen = true;
+    if (!visible.has(event.seq)) continue; // compacted away; an older one may still be visible
+    return event.data.source.digest === digest ? null : 'update';
+  }
+  return seen ? 'compaction' : 'start';
+}
+
+/** Our message among a step's pending messages, if one is already there. */
+export function pendingMemory(messages = []) {
+  return messages.find((m) => isMemorySource(m?.source)) ?? null;
+}
+
+const LEAD = {
+  start: 'Your persistent memory, carried over from earlier chats.',
+  compaction: 'Your persistent memory again — the conversation was compacted, so here it is in full.',
+  update: 'Your persistent memory changed. This is the current version; it replaces any earlier memory message.',
+};
+
+/**
+ * The context message: what the model reads, and the source dsh logs and labels.
+ * @param {{user: string[], memory: string[]}} stores
+ * @param {{user: number, memory: number}} limits
+ * @param {'start'|'compaction'|'update'} reason
+ */
+export function memoryMessage(stores, limits, reason, id = randomUUID()) {
+  const blocks = [renderBlock('user', stores.user ?? [], limits.user), renderBlock('memory', stores.memory ?? [], limits.memory)].filter(Boolean);
+  const text = [
+    '<system-reminder>',
+    LEAD[reason] ?? LEAD.start,
+    'Use it without being asked: follow the preferences, rely on the facts and conventions instead of rediscovering them or asking',
+    'again, and apply the lessons. Do not announce that you read it.',
+    '',
+    blocks.length ? blocks.join('\n\n') : '(Nothing is saved yet.)',
+    '</system-reminder>',
+  ].join('\n');
+  const summary = (reason === 'compaction' ? 'after compaction · ' : reason === 'update' ? 'updated · ' : '') + countsText(stores);
+  return Object.freeze({
+    id,
+    role: 'user',
+    content: Object.freeze([Object.freeze({ type: 'text', text })]),
+    source: Object.freeze({ kind: 'plugin', plugin: INJECT_LABEL, form: 'notice', summary, reason, digest: digestOf(stores) }),
+  });
+}