dsh-memory-ledger 0.0.0-stage → 1.0.1

package/index.js

@@ -0,0 +1,776 @@
+/**
+ * dsh-memory-ledger — a persistent, user-owned memory ledger for DeepSeek Harness.
+ *
+ * It contributes four things to the Harness:
+ *
+ * 1. A prompt section that surfaces the user's standing settings and the
+ *    verified lessons collected so far, so a later session does not re-ask and
+ *    does not re-pay for the same investigation. Lessons written in a working
+ *    directory stay in that project's ledger.
+ * 2. Three model-facing tools (`memory_save`, `memory_search`, `memory_forget`)
+ *    that maintain the ledger inside a conversation, with scoped retrieval
+ *    (hybrid BM25 + TF-IDF vector cosine, keyword, or vector only).
+ * 3. Mechanical incident counting on `tools/result`: a failing tool call is
+ *    reduced to a stable signature and counted, so a repeat is visible in the
+ *    prompt without the model spending a token on detecting it.
+ * 4. A browser panel with a left-sidebar entry (`sidebar.panellist` + `main`)
+ *    that lists, searches, and prunes the same ledger over gated HTTP routes.
+ *
+ * State lives outside the profile: `$DSH_HOME/memory/memory.json` for the user
+ * scope and `$DSH_HOME/memory/projects/<slug>.json` per working directory.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { LedgerHub, SCOPES } from './ledger.js'
+import { isUserStatement, looksLikeSetting, reminderText } from './reminder.js'
+
+export const name = 'dsh-memory-ledger'
+export const inject = ['tools', 'systemPrompt']
+
+export const Config = Schema.object({
+  dataDir: Schema.string()
+    .default('')
+    .description('Absolute directory for the ledger files; empty means $DSH_HOME/memory.'),
+  projectMemory: Schema.boolean()
+    .default(true)
+    .description('Keep a separate ledger per working directory instead of one global bank.'),
+  maxPromptChars: Schema.number()
+    .default(1600)
+    .description('Hard character budget of the injected memory section.'),
+  maxLessonsInPrompt: Schema.number()
+    .default(8)
+    .description('Verified lessons surfaced in the prompt at most.'),
+  searchMode: Schema.string()
+    .default('hybrid')
+    .description('Default retrieval mode: hybrid, keyword, or vector.'),
+  captureFailures: Schema.boolean()
+    .default(true)
+    .description('Count failed tool calls mechanically and surface recurring ones.'),
+  incidentThreshold: Schema.number()
+    .default(2)
+    .description('Repeat count from which a recurring failure is surfaced in the prompt.'),
+  maxIncidents: Schema.number()
+    .default(40)
+    .description('Incident signatures kept on disk at most, per ledger.'),
+  incidentMaxAgeDays: Schema.number()
+    .default(60)
+    .description('Incidents older than this many days are dropped.'),
+  sectionOrder: Schema.number()
+    .default(100)
+    .description('Prompt section order; lower appears earlier. Defaults right after the persona.'),
+  includeUsageHint: Schema.boolean()
+    .default(true)
+    .description('Append the short maintenance reminder to the injected section.'),
+  constraintKeys: Schema.string()
+    .default('pen_name,signature')
+    .description('Comma-separated fact keys that become hard constraints in their own high-priority prompt section. Pinned facts are constraints too.'),
+  maxConstraintChars: Schema.number()
+    .default(300)
+    .description('Character budget of the hard-constraint section.'),
+  remindUnrecorded: Schema.boolean()
+    .default(true)
+    .description('When a turn ends with a likely unrecorded user setting, queue one short reminder for the next turn.'),
+  ui: Schema.boolean()
+    .default(true)
+    .description('Serve the browser panel routes and register the left-sidebar entry.'),
+  routePrefix: Schema.string()
+    .default('/dsh-memory/api/v1')
+    .description('HTTP path prefix of the panel routes.'),
+})
+
+/**
+ * Resolve the ledger directory.
+ * @param {string} configured Configured `dataDir`.
+ * @returns {string} Absolute directory.
+ */
+export function resolveDataDir(configured) {
+  const trimmed = typeof configured === 'string' ? configured.trim() : ''
+  if (trimmed !== '') return isAbsolute(trimmed) ? trimmed : resolve(trimmed)
+  const home = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
+  return join(home, 'memory')
+}
+
+/**
+ * Read the working directory a session is bound to.
+ * @param {{ session?: { header?: { cwd?: string } } }} agent
+ * @returns {string} The directory, or '' when unavailable.
+ */
+function sessionCwd(agent) {
+  const cwd = agent?.session?.header?.cwd
+  return typeof cwd === 'string' ? cwd.trim() : ''
+}
+
+/**
+ * Collect the model-facing text of a failed tool result.
+ * @param {{ content?: Array<{ type?: string, text?: string }> }} result
+ * @returns {string}
+ */
+function failureText(result) {
+  const blocks = Array.isArray(result?.content) ? result.content : []
+  return blocks
+    .map(block => (block && typeof block === 'object' && typeof block.text === 'string' ? block.text : ''))
+    .filter(Boolean)
+    .join('\n')
+    .trim()
+}
+
+function sendJson(response, status, payload) {
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-type': 'application/json; charset=utf-8',
+  })
+  response.end(JSON.stringify(payload))
+}
+
+/** Whether a `Host` header names a loopback authority. */
+function loopbackAuthority(host) {
+  if (typeof host !== 'string' || host === '') return false
+  const lower = host.toLowerCase()
+  const name = lower.startsWith('[') ? lower.slice(0, lower.indexOf(']') + 1) : lower.split(':')[0]
+  return name === '127.0.0.1' || name === 'localhost' || name === '[::1]'
+}
+
+/**
+ * Refuse another page driving these routes: loopback Host, no cross-site
+ * fetch, and an Origin that matches Host when one is present.
+ * @param {import('node:http').IncomingMessage} request
+ * @returns {boolean}
+ */
+function sameOrigin(request) {
+  const host = request.headers.host
+  if (host !== undefined && !loopbackAuthority(host)) return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === host
+  } catch {
+    return false
+  }
+}
+
+/** Read a size-capped JSON body. */
+async function readJsonBody(request, maxBytes = 4096) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buffer.length
+    if (size > maxBytes) throw new Error('request body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * @param {object} ctx Cordis plugin context supplied by the Harness.
+ * @param {{ dataDir: string, projectMemory: boolean, maxPromptChars: number,
+ *   maxLessonsInPrompt: number, searchMode: string, captureFailures: boolean,
+ *   incidentThreshold: number, maxIncidents: number, incidentMaxAgeDays: number,
+ *   sectionOrder: number, includeUsageHint: boolean, ui: boolean,
+ *   routePrefix: string }} config
+ */
+export function apply(ctx, config) {
+  const logger = ctx.logger?.(name)
+  const hub = new LedgerHub({ dir: resolveDataDir(config?.dataDir ?? ''), logger })
+  const projectMemory = config.projectMemory !== false
+  const defaultMode = ['hybrid', 'keyword', 'vector'].includes(config.searchMode) ? config.searchMode : 'hybrid'
+  const prefix = String(config.routePrefix || '/dsh-memory/api/v1').replace(/\/+$/u, '')
+
+  const promptOptions = () => ({
+    maxChars: config.maxPromptChars,
+    maxLessons: config.maxLessonsInPrompt,
+    incidentThreshold: config.incidentThreshold,
+    includeUsageHint: config.includeUsageHint,
+  })
+  const cwdFor = (agent) => (projectMemory ? sessionCwd(agent) : '')
+
+  // ── 1. The injected memory section ────────────────────────────────────────
+  // `interpolate: false` keeps user-authored text containing `{{…}}` literal.
+  ctx.systemPrompt.section({
+    name: 'dsh-memory:ledger',
+    order: config.sectionOrder,
+    interpolate: false,
+    text: (context) => hub.renderFor(cwdFor(context?.agent), promptOptions()),
+  })
+
+  // A second, higher-priority section for the settings that must not be
+  // overridden by style defaults — pen name, signature, and anything pinned.
+  ctx.systemPrompt.section({
+    name: 'dsh-memory:constraints',
+    order: config.sectionOrder - 10,
+    interpolate: false,
+    text: (context) => hub.renderConstraintsFor(cwdFor(context?.agent), {
+      constraintKeys: config.constraintKeys,
+      maxChars: config.maxConstraintChars,
+    }),
+  })
+
+  // ── 2. Tools ──────────────────────────────────────────────────────────────
+  ctx.tools.register(defineTool({
+    name: 'memory_save',
+    description: [
+      'Save one long-lived memory entry, or update the one it replaces.',
+      'Use kind="fact" for a stable setting about the user or the project (identity, pen name, signature, language, stack, constraints): later sessions then treat it as a premise instead of asking again.',
+      'Use kind="lesson" after a problem is actually solved, recording the cause and the exact fix, so the same investigation is not paid for twice.',
+      'Facts default to the user-wide ledger so they follow the user everywhere; lessons default to the current working directory so one project\'s tooling quirks do not leak into another. Pass scope="user" to share a lesson everywhere.',
+      'Saving a fact under the key it already has overwrites that value in the same scope, which is how a user-changed setting stays in sync.',
+    ].join(' '),
+    parameters: {
+      kind: {
+        type: 'string',
+        required: true,
+        description: '"fact" for a standing setting, "lesson" for a verified problem -> solution.',
+      },
+      title: {
+        type: 'string',
+        required: true,
+        description: 'One short line the model re-reads every step; keep it under 80 characters.',
+      },
+      body: {
+        type: 'string',
+        description: 'Optional detail: the symptom, the cause, the exact command or fix.',
+      },
+      key: {
+        type: 'string',
+        description: 'Stable slot for a fact, e.g. "pen_name". Saving the same key again in the same scope replaces the old value.',
+      },
+      tags: {
+        type: 'string',
+        description: 'Comma-separated lowercase tags, e.g. "filesystem,powershell".',
+      },
+      pinned: {
+        type: 'boolean',
+        description: 'Keep this entry at the top of the injected section.',
+      },
+      reason: {
+        type: 'string',
+        description: 'Why this is being recorded, one short line (for example "user stated their pen name" or "fixed the schema validation error"). Shown in the panel beside the entry so the user can judge whether it still applies.',
+      },
+      scope: {
+        type: 'string',
+        description: '"user" for every project, "project" for this working directory only. Defaults to the kind-based rule above.',
+      },
+      id: {
+        type: 'string',
+        description: 'Update this existing entry instead of creating a new one.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          kind: { type: 'string', required: true },
+          title: { type: 'string', required: true },
+          key: { type: 'string', required: true },
+          scope: { type: 'string', required: true },
+          updated: { type: 'boolean', required: true },
+          facts: { type: 'number', required: true },
+          lessons: { type: 'number', required: true },
+          pendingIncidents: { type: 'number', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `${value.updated ? 'Updated' : 'Saved'} ${value.kind} ${value.id} in the ${value.scope} ledger: ${value.title}`
+          + ` (this ledger now: ${value.facts} facts, ${value.lessons} lessons, ${value.pendingIncidents} pending incidents)`,
+      }],
+    },
+    async execute(args, exec) {
+      const cwd = cwdFor(exec?.agent)
+      const sessionId = String(exec?.agent?.id ?? '')
+      const origin = cwd === ''
+        ? undefined
+        : { cwd, label: cwd, sessionId, at: new Date().toISOString() }
+      const { entry, updated, scope } = hub.upsert({
+        id: args.id,
+        kind: args.kind,
+        title: args.title,
+        body: args.body,
+        key: args.key,
+        tags: args.tags,
+        pinned: args.pinned,
+        reason: args.reason !== undefined && String(args.reason).trim() !== ''
+          ? args.reason
+          : (args.kind === 'lesson' ? 'agent 在任务中验证后写入' : 'agent 在会话中写入的设定'),
+        origin,
+        scope: SCOPES.includes(String(args.scope)) ? String(args.scope) : undefined,
+        cwd,
+      })
+      const stats = scope === 'project' ? hub.project(cwd).stats() : hub.user().stats()
+      return {
+        id: entry.id,
+        kind: entry.kind,
+        title: entry.title,
+        key: entry.key,
+        scope,
+        updated,
+        facts: stats.facts,
+        lessons: stats.lessons,
+        pendingIncidents: stats.pending,
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_search',
+    description: [
+      'Search the persistent memory ledger before re-investigating a problem or re-asking about the user.',
+      'Retrieval is hybrid by default: BM25 keyword scoring plus a TF-IDF vector cosine over word and CJK character-bigram terms, so a paraphrased problem still finds the stored lesson. `mode="keyword"` or `mode="vector"` narrows it.',
+      'The user ledger and the current project ledger are searched together by default; an empty query lists the strongest entries (pinned, then most repeated, then most recent).',
+    ].join(' '),
+    parameters: {
+      query: {
+        type: 'string',
+        description: 'Free-form query. Empty lists the strongest entries.',
+      },
+      kind: {
+        type: 'string',
+        description: '"fact" or "lesson" to restrict the result.',
+      },
+      tags: {
+        type: 'string',
+        description: 'Comma-separated tags that must all match.',
+      },
+      mode: {
+        type: 'string',
+        description: '"hybrid" (default), "keyword", or "vector".',
+      },
+      scope: {
+        type: 'string',
+        description: '"auto" (default: user + current project), "user", "project", or "all" (every project on disk).',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum matches, 1-50; defaults to 10.',
+      },
+      full: {
+        type: 'boolean',
+        description: 'Return complete bodies instead of 400-character previews.',
+      },
+      includeArchived: {
+        type: 'boolean',
+        description: 'Also return entries that were forgotten (archived).',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          total: { type: 'number', required: true },
+          mode: { type: 'string', required: true },
+          ledger: { type: 'string', required: true },
+          matches: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                kind: { type: 'string', required: true },
+                scope: { type: 'string', required: true },
+                title: { type: 'string', required: true },
+                key: { type: 'string', required: true },
+                tags: { type: 'array', items: { type: 'string' }, required: true },
+                body: { type: 'string', required: true },
+                pinned: { type: 'boolean', required: true },
+                archived: { type: 'boolean', required: true },
+                occurrences: { type: 'number', required: true },
+                reason: { type: 'string', required: true },
+                originLabel: { type: 'string', required: true },
+                score: { type: 'number', required: true },
+                updatedAt: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        if (value.total === 0) {
+          return [{ type: 'text', text: `No memory entry matched. Ledger: ${value.ledger}` }]
+        }
+        const lines = value.matches.map(match => {
+          const slot = match.key !== '' ? ` [${match.key}]` : ''
+          const repeat = match.occurrences > 1 ? ` (${match.occurrences}x)` : ''
+          const archived = match.archived ? ' (archived)' : ''
+          const source = match.originLabel !== '' ? ` · 来源 ${match.originLabel}` : ''
+          const reason = match.reason !== '' ? ` · 原因 ${match.reason}` : ''
+          const body = match.body !== '' ? ` — ${match.body}` : ''
+          return `- ${match.id} (${match.kind}/${match.scope})${slot}${repeat}${archived} ${match.title}${source}${reason}${body}`
+        })
+        return [{ type: 'text', text: `${value.total} match(es) via ${value.mode}; ledger: ${value.ledger}\n${lines.join('\n')}` }]
+      },
+    },
+    async execute(args, exec) {
+      const cwd = cwdFor(exec?.agent)
+      const mode = ['hybrid', 'keyword', 'vector'].includes(String(args.mode)) ? String(args.mode) : defaultMode
+      const matches = hub.search({
+        text: args.query,
+        kind: args.kind,
+        tags: args.tags,
+        mode,
+        scope: args.scope,
+        cwd,
+        limit: args.limit ?? 10,
+        includeArchived: args.includeArchived === true,
+      })
+      const full = args.full === true
+      const userStats = hub.user().stats()
+      const projectStats = cwd === '' ? null : hub.project(cwd).stats()
+      return {
+        total: matches.length,
+        mode,
+        ledger: `${userStats.facts} user facts, ${userStats.lessons} user lessons`
+          + (projectStats === null ? '' : `; ${projectStats.facts} project facts, ${projectStats.lessons} project lessons (${cwd})`)
+          + `; ${userStats.pending + (projectStats?.pending ?? 0)} pending incidents`,
+        matches: matches.map(entry => ({
+          id: entry.id,
+          kind: entry.kind,
+          scope: entry.scope ?? 'user',
+          title: entry.title,
+          key: entry.key,
+          tags: entry.tags,
+          body: full ? entry.body : entry.body.slice(0, 400),
+          pinned: entry.pinned,
+          archived: entry.archived,
+          occurrences: entry.occurrences,
+          reason: typeof entry.reason === 'string' ? entry.reason : '',
+          originLabel: typeof entry.origin?.label === 'string' ? entry.origin.label : '',
+          score: Number(entry._score ?? 0),
+          updatedAt: entry.updatedAt,
+        })),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_forget',
+    description: [
+      'Remove a memory entry by id, wherever it lives (user ledger or project ledger).',
+      'The entry is archived by default so it stops entering the prompt while staying recoverable; pass hard=true to delete it from the ledger file.',
+      'Use it when the user says a stored setting is wrong, outdated, or no longer applies.',
+    ].join(' '),
+    parameters: {
+      id: {
+        type: 'string',
+        required: true,
+        description: 'Entry id from memory_search.',
+      },
+      hard: {
+        type: 'boolean',
+        description: 'Delete the record instead of archiving it.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          hard: { type: 'boolean', required: true },
+          title: { type: 'string', required: true },
+          scope: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `${value.hard ? 'Deleted' : 'Archived'} ${value.id} (${value.scope}): ${value.title}`,
+      }],
+    },
+    async execute(args) {
+      return hub.forget(args.id, args.hard === true)
+    },
+  }))
+
+  // ── 3. Mechanical incident counting ───────────────────────────────────────
+  let flushTimer = null
+  const pending = new Set()
+
+  const scheduleFlush = () => {
+    if (flushTimer !== null) return
+    flushTimer = setTimeout(() => {
+      flushTimer = null
+      try {
+        for (const store of pending) {
+          store.pruneIncidents({ max: config.maxIncidents, maxAgeDays: config.incidentMaxAgeDays })
+        }
+        pending.clear()
+      } catch (error) {
+        logger?.warn?.(`failed to persist incidents: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }, 1200)
+    if (typeof flushTimer.unref === 'function') flushTimer.unref()
+  }
+
+  ctx.effect(() => () => {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer)
+      flushTimer = null
+    }
+  })
+
+  if (config.captureFailures) {
+    ctx.on('tools/result', (exec, result) => {
+      try {
+        if (!result || result.isError !== true) return
+        const tool = String(exec?.name ?? '')
+        // The ledger's own tools never count as incidents.
+        if (tool === '' || tool.startsWith('memory_')) return
+        const message = typeof result.error?.message === 'string' && result.error.message !== ''
+          ? result.error.message
+          : failureText(result)
+        const cwd = cwdFor(exec?.agent)
+        const store = cwd === '' ? hub.user() : hub.project(cwd)
+        store.recordIncident(tool, message)
+        pending.add(store)
+        scheduleFlush()
+      } catch (error) {
+        logger?.warn?.(`failed to record incident: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    })
+  }
+
+  // ── 4. Unrecorded-setting reminder ────────────────────────────────────────
+  // Zero model tokens: a regex over the claimed user message decides whether a
+  // reminder is queued at all, and only one reminder is ever emitted per
+  // pending statement.
+  const pendingReminders = new Map()
+
+  const messageText = (message) => {
+    const blocks = Array.isArray(message?.content) ? message.content : []
+    return blocks
+      .filter(block => block && block.type === 'text' && typeof block.text === 'string')
+      .map(block => block.text)
+      .join('\n')
+      .trim()
+  }
+
+  if (config.remindUnrecorded) {
+    ctx.on('agent/inbox/claimed', (payload) => {
+      try {
+        // Only what the human typed: an injected reminder mentions 笔名/署名
+        // itself and would otherwise re-trigger this detector forever.
+        if (!isUserStatement(payload?.message)) return
+        const text = messageText(payload?.message)
+        if (!looksLikeSetting(text)) return
+        const id = String(payload?.agent?.id ?? '')
+        if (id === '') return
+        const current = pendingReminders.get(id)
+        if (current !== undefined && current.reminded !== true) {
+          current.quotes.push(text)
+          if (current.quotes.length > 3) current.quotes.shift()
+          return
+        }
+        pendingReminders.set(id, { quotes: [text], turn: payload?.turn ?? 0, reminded: false, emitted: current?.emitted ?? 0 })
+      } catch (error) {
+        logger?.warn?.(`failed to inspect an inbox claim: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    })
+
+    // A successful save answers the reminder: nothing more to say.
+    ctx.on('tools/result', (exec, result) => {
+      if (exec?.name !== 'memory_save' || result?.isError === true) return
+      const id = String(exec?.agent?.id ?? '')
+      if (id !== '') pendingReminders.delete(id)
+    })
+
+    ctx.on('agent/turn-stopping', (payload) => {
+      try {
+        const id = String(payload?.agent?.id ?? '')
+        const pending = pendingReminders.get(id)
+        if (pending === undefined || pending.reminded === true || pending.quotes.length === 0) return
+        // Belt and braces: never let one session be nagged without bound.
+        if ((pending.emitted ?? 0) >= 5) {
+          pendingReminders.delete(id)
+          return
+        }
+        const agent = payload?.agent
+        if (typeof agent?.inject !== 'function') return
+        agent.inject(createUserMessage({
+          content: [{ type: 'text', text: reminderText(pending.quotes[0]) }],
+          source: { kind: 'plugin:dsh-memory-ledger', plugin: 'dsh-memory-ledger' },
+        }))
+        pending.reminded = true
+        pending.emitted = (pending.emitted ?? 0) + 1
+      } catch (error) {
+        logger?.warn?.(`failed to queue the memory reminder: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    })
+
+    ctx.on('agent/disposed', (payload) => {
+      const id = String(payload?.agent?.id ?? '')
+      if (id !== '') pendingReminders.delete(id)
+    })
+  }
+
+  // ── 5. Human entry points ─────────────────────────────────────────────────
+  const commands = ctx.get('commands')
+  if (commands) {
+    ctx.effect(() => commands.register({
+      name: 'memory',
+      description: 'Show, search, or forget persistent memory entries.',
+      input: { hint: '[list | search <keywords> | forget <id>]' },
+      handler: (invocation) => {
+        const raw = String(invocation?.rawInput ?? '').trim()
+        const [verb = 'list', ...rest] = raw.split(/\s+/u)
+        try {
+          if (verb === 'search') {
+            const matches = hub.search({ text: rest.join(' '), cwd: cwdFor(invocation?.agent), limit: 10 })
+            if (matches.length === 0) return { kind: 'success', text: `No match for "${rest.join(' ')}".` }
+            return {
+              kind: 'success',
+              text: matches.map(entry => `${entry.id} (${entry.kind}/${entry.scope ?? 'user'}) ${entry.title}`).join('\n'),
+            }
+          }
+          if (verb === 'forget') {
+            const id = rest[0]
+            if (!id) return { kind: 'error', text: '用法：/memory forget <id> --yes' }
+            if (!rest.includes('--yes')) {
+              const target = hub.locate(id)
+              if (target === undefined) return { kind: 'error', text: `没有 id 为 ${id} 的记忆条目` }
+              const entry = target.store.get(id)
+              return {
+                kind: 'success',
+                text: `确认要归档这条记忆吗？\n  ${id} (${entry.kind}/${target.scope}) ${entry.title}\n归档不会删除，只是不再进入提示词，可恢复。确认请再输入：/memory forget ${id} --yes`,
+              }
+            }
+            const removed = hub.forget(id, false)
+            return { kind: 'success', text: `已归档 ${removed.id} (${removed.scope})：${removed.title}` }
+          }
+          if (verb === 'help') {
+            return { kind: 'success', text: 'Usage: /memory [list | search <keywords> | forget <id>]' }
+          }
+          const user = hub.user()
+          const cwd = cwdFor(invocation?.agent)
+          const project = cwd === '' ? undefined : hub.project(cwd)
+          const userFacts = user.list({ kind: 'fact', limit: 30 })
+          const userLessons = user.list({ kind: 'lesson', limit: 30 })
+          const projectFacts = project?.list({ kind: 'fact', limit: 30 }) ?? []
+          const projectLessons = project?.list({ kind: 'lesson', limit: 30 }) ?? []
+          const lines = [
+            `User ledger: ${user.path}`,
+            `  ${userFacts.length} facts, ${userLessons.length} lessons, ${user.stats().pending} pending incidents`,
+            ...(cwd === '' ? [] : ['', `Project ledger: ${project?.path ?? ''}`, `  ${projectFacts.length} facts, ${projectLessons.length} lessons`]),
+            '',
+            ...userFacts.map(entry => `  ${entry.id} [user] ${entry.title}`),
+            ...userLessons.map(entry => `  ${entry.id} [user] ${entry.title}`),
+            ...projectFacts.map(entry => `  ${entry.id} [project] ${entry.title}`),
+            ...projectLessons.map(entry => `  ${entry.id} [project] ${entry.title}`),
+          ]
+          return { kind: 'success', text: lines.join('\n') }
+        } catch (error) {
+          return { kind: 'error', text: error instanceof Error ? error.message : String(error) }
+        }
+      },
+    }))
+  }
+
+  // ── 6. Browser panel routes ───────────────────────────────────────────────
+  // The webserver is NOT ready when this plugin applies on a cold start (and a
+  // headless profile has none at all), so wait for the service instead of
+  // probing once: `ctx.inject` runs the callback when it appears and re-runs it
+  // after any change.
+  if (config.ui !== false) {
+    ctx.inject(['webServer'], (child) => {
+    const webServer = child.webServer
+    const guard = (handler) => async (request, response) => {
+      if (!sameOrigin(request)) {
+        sendJson(response, 403, { error: 'untrusted origin' })
+        return
+      }
+      try {
+        await handler(request, response)
+      } catch (error) {
+        logger?.warn?.(`${prefix}: ${error instanceof Error ? error.stack ?? error.message : String(error)}`)
+        if (!response.headersSent) sendJson(response, 500, { error: 'memory ledger failure' })
+      }
+    }
+
+    child.effect(() => webServer.register({
+      kind: 'exact',
+      path: `${prefix}/ledger`,
+      handler: guard(async (request, response) => {
+        if (request.method !== 'GET') {
+          response.writeHead(405, { allow: 'GET' })
+          response.end()
+          return
+        }
+        const url = new URL(request.url ?? '/', 'http://localhost')
+        sendJson(response, 200, hub.snapshot(url.searchParams.get('cwd') ?? '', {
+          text: url.searchParams.get('q') ?? '',
+          kind: url.searchParams.get('kind') ?? undefined,
+          mode: url.searchParams.get('mode') ?? defaultMode,
+          scope: url.searchParams.get('scope') ?? undefined,
+          includeArchived: url.searchParams.get('archived') === '1',
+        }))
+      }),
+    }))
+
+    child.effect(() => webServer.register({
+      kind: 'exact',
+      path: `${prefix}/update`,
+      handler: guard(async (request, response) => {
+        if (request.method !== 'POST') {
+          response.writeHead(405, { allow: 'POST' })
+          response.end()
+          return
+        }
+        const body = await readJsonBody(request, 16_384)
+        const id = typeof body?.id === 'string' ? body.id : ''
+        if (id === '') {
+          sendJson(response, 400, { error: 'id is required' })
+          return
+        }
+        try {
+          const { entry, scope } = hub.patch(id, {
+            title: typeof body.title === 'string' ? body.title : undefined,
+            body: typeof body.body === 'string' ? body.body : undefined,
+            key: typeof body.key === 'string' ? body.key : undefined,
+            tags: typeof body.tags === 'string' || Array.isArray(body.tags) ? body.tags : undefined,
+            pinned: typeof body.pinned === 'boolean' ? body.pinned : undefined,
+            kind: typeof body.kind === 'string' ? body.kind : undefined,
+            reason: typeof body.reason === 'string' ? body.reason : undefined,
+            archived: typeof body.archived === 'boolean' ? body.archived : undefined,
+          })
+          sendJson(response, 200, { id: entry.id, kind: entry.kind, title: entry.title, key: entry.key, archived: entry.archived, scope })
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          sendJson(response, /no memory entry/u.test(message) ? 404 : 400, { error: message })
+        }
+      }),
+    }))
+
+    child.effect(() => webServer.register({
+      kind: 'exact',
+      path: `${prefix}/forget`,
+      handler: guard(async (request, response) => {
+        if (request.method !== 'POST') {
+          response.writeHead(405, { allow: 'POST' })
+          response.end()
+          return
+        }
+        const body = await readJsonBody(request)
+        const id = typeof body?.id === 'string' ? body.id : ''
+        if (id === '') {
+          sendJson(response, 400, { error: 'id is required' })
+          return
+        }
+        try {
+          sendJson(response, 200, hub.forget(id, body?.hard === true))
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          sendJson(response, /no memory entry/u.test(message) ? 404 : 500, { error: message })
+        }
+      }),
+    }))
+    })
+  }
+}