@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/tools.js

@@ -1,818 +1,828 @@
-// Agent tools: memory_search / remember / workspaces / associate / sync / forget.
-import { realpathSync } from 'node:fs'
-import { isAbsolute, resolve } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { search } from './search.js'
-import { remember } from './remember.js'
-import { summarizeState, writeStateSection } from './state.js'
-import { rerankHits } from './rerank.js'
-import { logRun } from './telemetry.js'
-import { isSubagentSession } from './session.js'
-import { appendActivity, clearActivity, readWorking, workingSummary, writeWorkingSection } from './working.js'
-import { associate, listWorkspaces } from './workspace.js'
-import { forget, forgetUndo } from './forget.js'
-import { buildMap } from './map.js'
-import { backupTasks, defaultSchedulePath, describeTask, listTasks, planRestore, readScheduleStore, TASK_STATES, writeTask } from './tasks.js'
-
-function renderHits(hits) {
-  if (!hits || hits.length === 0) return [{ type: 'text', text: '(no memory matches)' }]
-  return [{ type: 'text', text: hits
-    .map((h) => h.file + ':' + h.line + (h.id ? ' [' + h.id + ']' : '') + ' ' + h.snippet)
-    .join('\n') }]
-}
-
-function canonicalPath(pathArg, exec) {
-  if (!pathArg) {
-    const cwd = exec?.agent?.session?.header?.cwd
-    return cwd ? realpathSync(cwd) : undefined
-  }
-  const base = exec?.agent?.session?.header?.cwd
-  const abs = isAbsolute(pathArg) ? pathArg : (base ? resolve(base, pathArg) : resolve(pathArg))
-  return realpathSync(abs)
-}
-
-
-/** The text face of a map snapshot: what a caller without a UI still needs to know. */
-function renderMap(value) {
-  const parts = []
-  const store = value.store
-  if (store) {
-    const layers = store.layers.filter((l) => l.count > 0).map((l) => l.name + ' ' + l.count).join(', ')
-    parts.push(store.total + ' entries at ' + store.root)
-    parts.push('layers: ' + layers)
-    const f = store.freshness
-    parts.push('freshness: ' + f.fresh + ' fresh' + (f.stale ? ', ' + f.stale + ' STALE' : '') + (f.skip ? ', ' + f.skip + ' superseded' : ''))
-    const q = store.queue
-    const attention = q.attention.length
-      ? ', needs attention: ' + q.attention.slice(0, 3).map((a) => a.count + ' ' + a.state + ' (' + a.reason + ')').join(', ')
-      : ''
-    parts.push('queue: ' + q.waiting + ' waiting' + (q.recoverable ? ', ' + q.recoverable + ' recoverable' : '') + attention)
-  }
-  const session = value.session
-  if (session) {
-    const received = session.received
-    const sections = received.sections.map((s) => s.name + (s.marker ? ' ' + s.marker : '')).join(', ')
-    parts.push('this session received ' + received.chars + ' chars: ' + (sections || '(nothing injected)'))
-    const written = session.written
-    const byLayer = Object.keys(written.byLayer).map((k) => k + ' ' + written.byLayer[k]).join(', ')
-    parts.push('and wrote ' + written.total + ' entr' + (written.total === 1 ? 'y' : 'ies') + (byLayer ? ' (' + byLayer + ')' : ''))
-  }
-  return parts.join('; ') + '.'
-}
-/** The text face of a tasks report: what a caller without a UI still needs to know. */
-function renderTasks(value) {
-  const parts = []
-  parts.push('Scheduled tasks: ' + value.live + ' live, ' + value.backedUp + ' backed up')
-  const p = value.pending ?? {}
-  if (p.add) parts.push(p.add + ' would be restored')
-  if (p.present) parts.push(p.present + ' already present')
-  if (p.paused) parts.push(p.paused + ' held back')
-  if (p.refused) parts.push(p.refused + ' refused')
-  if (value.changed) parts.push('this call: ' + JSON.stringify(value.changed))
-  const states = {}
-  for (const task of value.tasks ?? []) states[task.state] = (states[task.state] ?? 0) + 1
-  const summary = Object.keys(states).map((s) => s + ' ' + states[s]).join(', ')
-  if (summary) parts.push('states: ' + summary)
-  if (value.unreadable && value.unreadable.length) parts.push(value.unreadable.length + ' file(s) unreadable: ' + value.unreadable.join(', '))
-  if (value.error) parts.push('COULD NOT READ THE SCHEDULE STORE: ' + value.error)
-  return parts.join('; ') + '.'
-}
-
-export function registerTools(ctx, store, extras = {}) {
-  /**
-   * Refuse a WRITE from a subagent session.
-   *
-   * Memory is the main agent's account of the work. A subagent reports back to its parent, and
-   * the parent decides what was durable; letting the child write as well produces two partial
-   * accounts of one task, with the child's - written without the parent's context - competing
-   * with it in search. Reads are unrestricted: a subagent may consult memory freely.
-   */
-  const refuseSubagentWrite = (exec, tool) => {
-    if (!isSubagentSession(exec?.agent?.session)) return
-    throw new Error(tool + ': memory is written by the main agent only. A subagent should return its findings to the caller, which decides what is durable; do not record memory from here.')
-  }
-  const syncNow = extras.syncNow
-  const consolidate = extras.consolidate
-  const workspaceOf = extras.workspaceOf
-  const historyOf = extras.historyOf
-  const refreshNow = extras.refresh
-  const rerankSearch = extras.rerankSearch
-  const statusNow = extras.status
-  const recoverNow = extras.recover
-  const injectionMaxChars = extras.injectionMaxChars
-  const tasksNow = extras.tasksNow
-  const tasksRestore = extras.tasksRestore
-  const schedulePathOf = extras.schedulePath
-
-  ctx.tools.register(defineTool({
-    name: 'memory_search',
-    description: 'Search the dsh-memory store (global + workspace layers). Returns ranked facts with file:line citations.',
-    parameters: {
-      query: { type: 'string', required: true, description: 'Natural-language query or keywords.' },
-      scope: { type: 'string', description: 'global, workspace, or all (default all).' },
-      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
-      limit: { type: 'integer', description: 'Maximum hits (default 10).' },
-      rerank: { type: 'boolean', description: 'Ask the session model to reorder the hits by usefulness (costs one call; off unless enabled in config).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          query: { type: 'string', required: true },
-          hits: {
-            type: 'array', required: true,
-            items: {
-              type: 'object', additionalProperties: false,
-              properties: {
-                file: { type: 'string', required: true },
-                line: { type: 'integer', required: true },
-                section: { type: 'string' },
-                snippet: { type: 'string', required: true },
-                id: { type: 'string' },
-                score: { type: 'number' },
-              },
-            },
-          },
-        },
-      },
-      render: (_args, value) => renderHits(value.hits),
-    },
-    async execute(args, exec) {
-      // Fetch a few extra so reranking has something to promote from, then trim to the limit.
-      const limit = args.limit ?? 10
-      const hits = search(store, args.query, { scope: args.scope, key: args.workspace, limit })
-      // Reranking is advisory: rerankSearch returns the original order on any failure, so a
-      // model that is missing, slow or unparseable cannot break search.
-      if (rerankSearch) {
-        const outcome = await rerankSearch(exec.agent, args.query, hits, { enabled: args.rerank !== false })
-        return { query: args.query, hits: outcome.hits.slice(0, limit) }
-      }
-      return { query: args.query, hits }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_remember',
-    description: 'Write a durable fact into the dsh-memory store (global or a workspace layer). Use the codebase layer to map a module or subsystem of the current repository. Do NOT call this to fill a gap: if the turn produced nothing durable, writing nothing is the correct outcome.',
-    parameters: {
-      text: { type: 'string', required: true, description: 'The fact body. The Id/Source/Date/… header is added automatically.' },
-      layer: { type: 'string', required: true, description: 'semantic, episodic, procedural, learning, or codebase.' },
-      scope: { type: 'string', description: 'global or workspace. Omit it and a fact recorded inside a known repository is filed to THAT WORKSPACE, because a fact about one repo is not global knowledge. Pass global explicitly for something true across repositories.' },
-      workspace: { type: 'string', description: 'Workspace key when scope is workspace. Defaults to the workspace of the current session.' },
-      topic: { type: 'string', description: 'Optional heading; defaults to the first sentence.' },
-      source: { type: 'string', description: 'Provenance; defaults to agent:<sessionId>.' },
-      importance: { type: 'integer', description: '1-3 (default 2).' },
-      volatility: { type: 'string', description: 'How fast this decays: stable (a language or license choice), normal (default), volatile (a port, a version in flight, anything with a date).' },
-      until: { type: 'string', description: 'Optional ISO expiry (Valid-until).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          id: { type: 'string', required: true },
-          file: { type: 'string', required: true },
-          layer: { type: 'string', required: true },
-          scopeId: { type: 'string', required: true },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: 'Remembered ' + value.id + ' -> ' + value.file }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_remember')
-      // DEFAULTS TO THE SESSION'S WORKSPACE, not to global. Defaulting to global is how a
-      // session's entire body of work about one repository - 25 entries in one observed case -
-      // was filed as cross-repository knowledge, where it is both wrong and unfindable from the
-      // workspace it belongs to. A fact recorded inside a repo is about that repo unless the
-      // caller says otherwise, so the safe default is the narrow one and global is opt-in.
-      let scope = args.scope
-      let key = args.workspace
-      // Resolve the session workspace ONCE: it fills in a missing key as well as a missing
-      // scope, so 'workspace' with no key is answerable whenever the session is in a repo.
-      const inferred = (workspaceOf && exec.agent) ? await workspaceOf(exec.agent) : undefined
-      if (!scope) {
-        if (inferred) { scope = 'workspace'; key = key ?? inferred }
-        else scope = 'global'
-      } else if (scope === 'workspace' && !key) {
-        key = inferred
-      }
-      if (scope === 'workspace' && !key) {
-        throw new Error('memory_remember: scope workspace needs a workspace key, and none could be inferred for this session. Pass workspace, or use scope global for cross-repository knowledge.')
-      }
-      const result = remember(store, {
-        scope,
-        key,
-        layer: args.layer,
-        text: args.text,
-        topic: args.topic,
-        source: args.source ?? (exec.agent ? 'agent:' + exec.agent.session.id : 'manual'),
-        importance: args.importance ?? 2,
-        until: args.until,
-        volatility: args.volatility,
-      })
-      return { id: result.id, file: result.file, layer: result.layer, scopeId: result.scopeId }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_codebase',
-    description: 'Record what a module, file or subsystem of the CURRENT repository does, as you discover it. Builds the workspace codebase map. Use the path (or a subsystem name) as the topic so re-discoveries update the same topic file.',
-    parameters: {
-      topic: { type: 'string', required: true, description: 'Module path or subsystem name, e.g. src/layers.js or the capture pipeline.' },
-      text: { type: 'string', required: true, description: 'What it is and does, its entry points, and anything surprising.' },
-      importance: { type: 'integer', description: '1-3 (default 2).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          id: { type: 'string', required: true },
-          file: { type: 'string', required: true },
-          workspace: { type: 'string', required: true },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: 'Mapped ' + value.id + ' -> ' + value.file }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_codebase')
-      if (!workspaceOf) throw new Error('memory_codebase is unavailable in this context')
-      const workspace = await workspaceOf(exec.agent)
-      if (!workspace) throw new Error('no workspace for this session yet: the codebase map is per repository. Associate one first (memory_associate) or run from inside the repo.')
-      const r = remember(store, {
-        scope: 'workspace', key: workspace, layer: 'codebase',
-        text: args.text, topic: args.topic, importance: args.importance ?? 2,
-        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
-      })
-      return { id: r.id, file: r.file, workspace }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_decision',
-    description: 'Record a settled decision with its context, rationale, alternatives considered, and consequences. Use for dependency choices, conventions, architecture and other choices future work must respect.',
-    parameters: {
-      decision: { type: 'string', required: true, description: 'The decision statement, used as the topic heading.' },
-      context: { type: 'string', description: 'The problem or context that required a choice.' },
-      rationale: { type: 'string', required: true, description: 'Why this option won.' },
-      alternatives: { type: 'array', description: 'Other options considered and rejected.' },
-      consequences: { type: 'string', description: 'What this commits us to, or what follows from it.' },
-      scope: { type: 'string', description: 'global (default) or workspace.' },
-      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
-      importance: { type: 'integer', description: '1-3 (default 2).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          id: { type: 'string', required: true },
-          file: { type: 'string', required: true },
-          scopeId: { type: 'string', required: true },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: 'Decision recorded ' + value.id + ' -> ' + value.file }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_decision')
-      const scope = args.scope ?? 'global'
-      const workspace = args.workspace ?? (scope === 'workspace' && workspaceOf ? await workspaceOf(exec.agent) : undefined)
-      if (scope === 'workspace' && !workspace) throw new Error('workspace decisions need an associated repository')
-      const r = remember(store, {
-        scope, key: workspace, layer: 'decision', topic: args.decision,
-        text: args.rationale, decision: { context: args.context, rationale: args.rationale, alternatives: args.alternatives, consequences: args.consequences },
-        importance: args.importance ?? 2,
-        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
-      })
-      return { id: r.id, file: r.file, scopeId: r.scopeId }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_working',
-    description: 'Record what YOU are working on in this workspace: the task in hand, what you recently did, and what comes next. This is agent working memory, NOT repository state (use memory_state for what the repo is). Set a section (Task, Next steps, Plan, Blocked by) or append to the rolling activity log.',
-    parameters: {
-      section: { type: 'string', description: 'A current-state section to replace: Task, Next steps, Plan, Blocked by (or any short name). Omit when only logging activity.' },
-      content: { type: 'string', description: 'The content of that section. Required with section.' },
-      activity: { type: 'array', description: 'One or more short notes about what you just did, appended to the rolling log (newest last, oldest trimmed).' },
-      clearActivity: { type: 'boolean', description: 'Clear the activity log, keeping the current sections.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspace: { type: 'string', required: true },
-          sections: { type: 'array', items: { type: 'string' } },
-          activity: { type: 'integer' },
-          added: { type: 'integer' },
-          verdict: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: 'Working memory (' + value.workspace + '): ' + (value.sections || []).join(', ') + ' | ' + value.activity + ' activity note(s)' + (value.added ? ', +' + value.added : '') + ' | ' + value.verdict }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_working')
-      if (!workspaceOf) throw new Error('memory_working is unavailable in this context')
-      const workspace = await workspaceOf(exec.agent)
-      if (!workspace) throw new Error('no workspace for this session yet: working memory is per workspace')
-      let added = 0
-      if (args.clearActivity) clearActivity(store.root, 'workspace', workspace)
-      if (args.section && args.content) writeWorkingSection(store.root, 'workspace', workspace, args.section, args.content)
-      if (args.activity && args.activity.length) added = appendActivity(store.root, 'workspace', workspace, args.activity).added
-      if (!args.section && !args.activity && !args.clearActivity) throw new Error('nothing to record: pass section+content, activity, or clearActivity')
-      const summary = workingSummary(store.root, 'workspace', workspace)
-      const working = readWorking(store.root, 'workspace', workspace)
-      return {
-        workspace, added,
-        sections: working ? working.sections.map((s) => s.name) : [],
-        activity: working ? working.activity.length : 0,
-        verdict: summary.verdict,
-      }
-    },
-  }))
-
-
-  ctx.tools.register(defineTool({
-    name: 'memory_tasks',
-    description: 'Show and manage the backup of this machine\'s DSH scheduled tasks. The schedule store is the only copy of them: it is in no git repository, and the host DELETES a task when its owning session stops, so a task can vanish with nothing to observe. Memory keeps one file per task under global/tasks/ and restores them automatically into a session on boot. Actions: report (default), backup, restore, pause, resume.',
-    parameters: {
-      action: { type: 'string', description: 'report (default), backup, restore, pause or resume.' },
-      title: { type: 'string', description: 'Task title, required for pause and resume.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          action: { type: 'string', required: true },
-          schedulePath: { type: 'string', required: true },
-          live: { type: 'integer', required: true },
-          backedUp: { type: 'integer', required: true },
-          tasks: { type: 'array', items: { type: 'object', additionalProperties: true }, required: true },
-          unreadable: { type: 'array', items: { type: 'string' } },
-          changed: { type: 'object', additionalProperties: true },
-          // What a restore would do, which is the question a reader of this report is asking:
-          // how many tasks would be re-armed, how many are already there, how many are held.
-          pending: { type: 'object', additionalProperties: true },
-          error: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: renderTasks(value) }],
-      // The structured face. Without presentationMeta a tool result reaches its session event with
-      // no meta at all (core/tools/src/index.ts:1845-1859), which is the only channel a UI has.
-      presentationMeta: (_args, value) => value,
-    },
-    async execute(args, exec) {
-      const action = ['report', 'backup', 'restore', 'pause', 'resume'].includes(args.action) ? args.action : 'report'
-      const schedulePath = schedulePathOf || defaultSchedulePath()
-      let changed = null
-      if (action === 'backup') {
-        if (!tasksNow) throw new Error('memory_tasks: the backup is unavailable in this context')
-        const r = backupTasks(store.root, { schedulePath })
-        changed = { written: r.written, refreshed: r.refreshed, stopped: r.stopped, skipped: r.skipped.length, error: r.error }
-      } else if (action === 'restore') {
-        if (!tasksRestore) throw new Error('memory_tasks: the restore is unavailable in this context')
-        // FORCED, because the once-per-process guard has almost certainly already been consumed by
-        // the boot restore - the manual action exists to run it again on demand.
-        // The outcome is REPORTED rather than assumed: this used to say { restored: true } whatever
-        // happened, including when nothing did.
-        changed = await tasksRestore(exec.agent, { force: true })
-      } else if (action === 'pause' || action === 'resume') {
-        if (!args.title) throw new Error('memory_tasks: ' + action + ' needs a title')
-        const { tasks } = listTasks(store.root)
-        const match = tasks.find((task) => String(task.record.title ?? '') === args.title)
-        if (!match) throw new Error('memory_tasks: no backed-up task titled "' + args.title + '"')
-        // Pausing writes the STATE only. It does not touch the live store: a held task is not
-        // disarmed here, it is simply never re-armed by an automatic pass, which is the decision a
-        // pause expresses. Resuming returns it to the queue, and the next pass derives it afresh.
-        const nextState = action === 'pause' ? TASK_STATES.PAUSED : TASK_STATES.PENDING
-        writeTask(store.root, match.record, nextState, match.backedUpAt ?? new Date().toISOString())
-        changed = { title: args.title, state: nextState }
-      }
-      // The report is read AFTER the action, so what the caller sees is the state they produced.
-      const live = readScheduleStore(schedulePath)
-      const { tasks, unreadable } = listTasks(store.root)
-      const plan = planRestore(store.root, { liveTasks: live.tasks })
-      const rows = tasks.map((task) => {
-        const described = describeTask(task, Date.now())
-        return {
-          title: String(task.record.title ?? ''),
-          kind: String(task.record.kind ?? ''),
-          state: described.state,
-          reason: described.reason,
-          file: task.file,
-        }
-      })
-      return {
-        action,
-        schedulePath,
-        live: live.tasks.length,
-        backedUp: tasks.length,
-        tasks: rows,
-        unreadable,
-        ...(changed ? { changed } : {}),
-        ...(live.error ? { error: live.error } : {}),
-        // Carried for the tool's own use, never shown: the planner's own view of what a restore
-        // would do, which is the question a reader of this report is actually asking.
-        pending: { add: plan.add.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length },
-      }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_map',
-    description: 'Show what memory holds, and what THIS session has done with it. scope "store" reports the whole store - entries per layer, freshness, workspaces, and the ingest queue. scope "session" reports what memory injected into this conversation and what this conversation wrote back. "all" returns both. Read-only, and the data behind the Memory view.',
-    parameters: {
-      scope: { type: 'string', description: 'Which view: "store" (what exists), "session" (what this conversation received and wrote), or "all" (default).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          scope: { type: 'string', required: true },
-          generatedAt: { type: 'string', required: true },
-          store: { type: 'object', additionalProperties: true },
-          session: { type: 'object', additionalProperties: true },
-        },
-      },
-      // The text face, for the agent and for any caller without a UI.
-      render: (_args, value) => [{ type: 'text', text: renderMap(value) }],
-      // The STRUCTURED face, and the only reason the Memory tab and the inline card can draw
-      // anything. A tool result reaches the session event with a `meta` field ONLY when the tool
-      // declares presentationMeta (core/tools/src/index.ts:1845-1859), and that field is what
-      // ui-chat forwards to a view (conversation-nodes/tool.ts:77: meta: match.event.data.meta).
-      // Without this, memory_map rendered its snapshot to prose and threw the value away: the tab
-      // showed 'the result carried no snapshot' while the same call displayed 2,197 entries in
-      // the conversation. The rendered text is not a substitute - rebuilding panels by parsing it
-      // would be a second source of truth.
-      presentationMeta: (_args, value) => value,
-    },
-    async execute(args, exec) {
-      const scope = args.scope === 'store' || args.scope === 'session' ? args.scope : 'all'
-      // The session id is what attributes writes: every tool records source 'agent:<sessionId>'.
-      const sessionId = exec?.agent?.session?.id
-      let key
-      if (workspaceOf && exec?.agent) {
-        try { key = await workspaceOf(exec.agent) } catch { key = undefined }
-      }
-      // The goal and the char cap are read exactly as the injection reads them, so the
-      // RECEIVED panel describes the card that was actually built.
-      const goal = ctx.get('goals')?.get(exec?.agent)?.objective
-      return buildMap(store, {
-        scope,
-        sessionId,
-        memoryScope: key && key !== 'global' ? 'workspace' : 'global',
-        key: key && key !== 'global' ? key : undefined,
-        goal,
-        maxChars: injectionMaxChars,
-      })
-    },
-  }))
-  ctx.tools.register(defineTool({
-    name: 'memory_state',
-    description: 'Record or refresh one section of the CURRENT repository state overview (what is running, the layout, what is pending, health). Replaces that section: state describes now, so a newer statement supersedes the old one. Each section carries a Verified timestamp and stale sections are reported as such.',
-    parameters: {
-      section: { type: 'string', required: true, description: 'Section name: Summary, Layout, Running, Pending, Health (or any short name).' },
-      content: { type: 'string', required: true, description: 'The current state of that area. Be concrete and short; this is an overview.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          section: { type: 'string', required: true },
-          created: { type: 'boolean', required: true },
-          workspace: { type: 'string', required: true },
-          sections: { type: 'array', required: true, items: { type: 'string' } },
-          unverified: { type: 'array', items: { type: 'string' } },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: (value.created ? 'Recorded ' : 'Updated ') + 'state section ' + value.section + ' for ' + value.workspace + '. Sections: ' + (value.sections || []).join(', ') + (value.unverified && value.unverified.length ? ' (still unverified: ' + value.unverified.join(', ') + ')' : '') }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_state')
-      if (!workspaceOf) throw new Error('memory_state is unavailable in this context')
-      const workspace = await workspaceOf(exec.agent)
-      if (!workspace) throw new Error('no workspace for this session yet: repository state is per workspace')
-      const r = writeStateSection(store.root, workspace, args.section, args.content, {
-        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
-      })
-      const summary = summarizeState(store.root, workspace)
-      return { section: r.section, created: r.created, workspace, sections: r.sections, unverified: summary.stale }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_recover',
-    description: 'Rebuild memory candidates whose working material was pruned but whose source session survives. Called with no arguments it REPORTS what is recoverable and changes nothing. Recovering a large session asks for approval first.',
-    parameters: {
-      id: { type: 'string', description: 'One candidate to recover. Omit to see a report, or to recover a bounded number of the smallest.' },
-      limit: { type: 'integer', description: 'Recover up to this many, smallest first. Each large one asks for approval.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          mode: { type: 'string', required: true },
-          total: { type: 'integer' },
-          recoverable: { type: 'integer' },
-          oversized: { type: 'integer' },
-          missing: { type: 'integer' },
-          thresholdBytes: { type: 'integer' },
-          recovered: { type: 'array', items: { type: 'object', additionalProperties: true } },
-          declined: { type: 'array', items: { type: 'object', additionalProperties: true } },
-        },
-      },
-      render: (_args, value) => {
-        if (value.mode === 'report') {
-          return [{ type: 'text', text: 'memory_recover: ' + value.total + ' candidate(s) stopped with missing material. '
-            + value.recoverable + ' recoverable now, ' + value.oversized + ' need approval (>= '
-            + Math.round((value.thresholdBytes ?? 0) / 1048576) + 'MB), ' + value.missing + ' have no locatable session.' }]
-        }
-        const done = value.recovered ?? []
-        const no = value.declined ?? []
-        return [{ type: 'text', text: 'memory_recover: rebuilt ' + done.length + ' candidate(s)'
-          + (no.length ? '; ' + no.length + ' declined or refused' : '') + '.' }]
-      },
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_recover')
-      if (!recoverNow) throw new Error('memory_recover is unavailable in this context')
-      const plan = recoverNow.plan()
-      if (!args.id && !args.limit) {
-        // `entries: undefined` is NOT lossless JSON - JSON has no undefined - so the harness
-        // rejected the entire result with 'value is not lossless JSON'. The field is a per-id
-        // list that the report deliberately withholds, so it must be OMITTED, not blanked.
-        const { entries: _omitted, ...summary } = plan
-        return { mode: 'report', ...summary }
-      }
-      return recoverNow.run(args, exec)
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_status',
-    description: 'Report the memory store state: where it lives, how many digests await consolidation, and whether the last git sync left a conflict. Use it to check memory health before trusting it.',
-    parameters: {},
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          root: { type: 'string', required: true },
-          pendingDigests: { type: 'integer', required: true },
-          conflicted: { type: 'boolean', required: true },
-          lastSyncOk: { type: 'boolean' },
-          modelCalls: { type: 'integer' },
-          eventCounts: { type: 'object', additionalProperties: true },
-          savedBy: { type: 'object', additionalProperties: true },
-          queue: {
-            type: 'object', additionalProperties: false,
-            properties: {
-              states: { type: 'object', additionalProperties: true, required: true },
-              waiting: { type: 'integer', required: true },
-              retrying: { type: 'integer', required: true },
-              recoverable: { type: 'integer', required: true },
-              parked: { type: 'object', additionalProperties: true },
-              attention: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'One row per CLASS of problem, largest first, each with a sample of ids.' },
-            },
-          },
-        },
-      },
-            render: (_args, value) => {
-        const q = value.queue ?? {}
-        const parts = ['Memory at ' + value.root + ': ' + value.pendingDigests + ' digest(s) pending']
-        // What stopped is reported by NAME. A count would say something is wrong; the list says
-        // what, which is the difference between a warning and something a reader can act on.
-        if (q.recoverable) parts.push(q.recoverable + ' need recovery (memory_recover)')
-        if (q.retrying) parts.push(q.retrying + ' retrying')
-        if (q.parked && Object.keys(q.parked).length) parts.push('parked: ' + Object.entries(q.parked).map(([why, c]) => c + ' ' + why).join(', '))
-        const attention = q.attention ?? []
-        if (attention.length) {
-          // One clause per CLASS of problem, largest first: '78 orphaned (digest-missing)' says
-          // more than 78 identical lines ever could.
-          const classes = attention.slice(0, 3).map((a) => a.count + ' ' + a.state + (a.reason ? ' (' + a.reason + ')' : ''))
-          parts.push('needs attention: ' + classes.join(', ') + (attention.length > 3 ? ', +' + (attention.length - 3) + ' more kinds' : ''))
-        }
-        if (value.conflicted) parts.push('THE LAST SYNC CONFLICTED (see state/CONFLICT.md)')
-        parts.push('model calls ' + (value.modelCalls || 0))
-        return [{ type: 'text', text: parts.join('; ') + '.' }]
-      },
-    },
-    async execute() {
-      if (!statusNow) throw new Error('memory_status is unavailable in this context')
-      const s = statusNow()
-      return {
-        root: s.root, pendingDigests: s.pendingDigests, conflicted: s.conflicted,
-        ...(s.lastSync && typeof s.lastSync.ok === 'boolean' ? { lastSyncOk: s.lastSync.ok } : {}),
-        modelCalls: s.metrics?.modelCalls ?? 0, eventCounts: s.metrics?.events ?? {}, savedBy: s.metrics?.savedBy ?? {},
-        ...(s.queue ? { queue: s.queue } : {}),
-      }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_refresh',
-    description: 'Run the freshness pass now instead of waiting for the daily cadence: stale and time-bounded entries are re-examined and kept, updated, or superseded by the model.',
-    parameters: {
-      limit: { type: 'integer', description: 'Maximum entries to review (default 3).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          refreshed: { type: 'integer', required: true },
-          updated: { type: 'integer', required: true },
-          superseded: { type: 'integer', required: true },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: value.refreshed === 0 ? 'Nothing needed refreshing.' : 'Reviewed ' + value.refreshed + ' entr(ies): ' + value.updated + ' updated, ' + value.superseded + ' superseded.' }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_refresh')
-      if (!refreshNow) throw new Error('memory_refresh is unavailable in this context')
-      const r = await refreshNow(exec.agent, { limit: args.limit })
-      return { refreshed: r.refreshed ?? 0, updated: r.updated ?? 0, superseded: r.superseded ?? 0 }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_history',
-    description: 'Ingest this repository commit history into the workspace history layer (how the codebase changed over time). Incremental: only commits not yet recorded are added. Safe to call repeatedly.',
-    parameters: {
-      limit: { type: 'integer', description: 'Maximum new commits to record (default 40).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          ok: { type: 'boolean', required: true },
-          added: { type: 'integer', required: true },
-          skipped: { type: 'integer' },
-          head: { type: 'string' },
-          reason: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: value.ok
-        ? 'Recorded ' + value.added + ' commit(s) into the history layer' + (value.skipped ? ' (' + value.skipped + ' already known)' : '') + '.'
-        : 'No history recorded: ' + (value.reason || 'unavailable') }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_history')
-      if (!historyOf) throw new Error('memory_history is unavailable in this context')
-      const r = await historyOf(exec.agent, { limit: args.limit })
-      // A manual ingest must leave the same trace as the cadence, or the history layer grows
-      // with nothing anywhere explaining where its files came from.
-      logRun(store.root, 'history-ingest', { source: 'tool', count: (r && r.added) || 0, detail: { ok: Boolean(r && r.ok), reason: (r && r.reason) || '' } })
-      return {
-        ok: Boolean(r && r.ok), added: (r && r.added) || 0,
-        ...(r && r.skipped ? { skipped: r.skipped } : {}),
-        ...(r && r.head ? { head: String(r.head).slice(0, 12) } : {}),
-        ...(r && r.reason ? { reason: String(r.reason) } : {}),
-      }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_workspaces',
-    description: 'List the workspaces (local folders/repos) associated with the dsh-memory store.',
-    parameters: {},
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaces: {
-            type: 'array', required: true,
-            items: {
-              type: 'object', additionalProperties: false,
-              properties: {
-                key: { type: 'string', required: true },
-                title: { type: 'string', required: true },
-                remotes: { type: 'array', required: true, items: { type: 'string' } },
-                path: { type: 'string' },
-              },
-            },
-          },
-        },
-      },
-      render: (_args, value) => [{
-        type: 'text',
-        text: value.workspaces.length
-          ? value.workspaces.map((w) => w.key + ' (' + w.title + ')' + (w.path ? ' -> ' + w.path : '')).join('\n')
-          : '(no workspaces associated)',
-      }],
-    },
-    async execute() {
-      const workspaces = listWorkspaces(store).map((w) => ({ key: w.key, title: w.title, remotes: w.remotes, path: w.path }))
-      return { workspaces }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_associate',
-    description: 'Associate a local folder/repo with a workspace key (creates the workspace layer).',
-    parameters: {
-      key: { type: 'string', required: true, description: 'Workspace key (filesystem-safe slug).' },
-      title: { type: 'string', description: 'Optional display title.' },
-      path: { type: 'string', description: 'Local folder; defaults to the current session working directory.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: { key: { type: 'string', required: true } },
-      },
-      render: (_args, value) => [{ type: 'text', text: 'Associated workspace ' + value.key }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_associate')
-      let cwd
-      try { cwd = canonicalPath(args.path, exec) } catch { cwd = undefined }
-      const key = associate(store, { key: args.key, title: args.title, cwd })
-      return { key }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_sync',
-    description: 'Commit local memory changes and sync (pull + push) with the configured GitHub origin.',
-    parameters: {},
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          synced: { type: 'boolean', required: true },
-          conflict: { type: 'boolean' },
-          error: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: value.conflict
-        ? 'Memory sync needs attention: ' + (value.error || 'git reported a failure') + ' (see state/CONFLICT.md)'
-        : (value.synced ? 'Memory synced.' : 'Memory sync unavailable (no git remote configured).') }],
-    },
-    async execute(_args, exec) {
-      refuseSubagentWrite(exec, 'memory_sync')
-      if (!syncNow) return { synced: false }
-      const status = await syncNow()
-      return {
-        synced: Boolean(status && (status.synced || status.committed || status.initialized)),
-        ...(status && status.conflict ? { conflict: true } : {}),
-        ...(status && status.error ? { error: String(status.error) } : {}),
-      }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_forget',
-    description: 'Forget a memory entry (supersede it and suppress re-adding), or release it with undo.',
-    parameters: {
-      id: { type: 'string', required: true, description: 'Entry id (e.g. global-sem-0001).' },
-      undo: { type: 'boolean', description: 'Set true to release a previously forgotten entry.' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: { id: { type: 'string', required: true }, undone: { type: 'boolean' }, hashPrefix: { type: 'string' } },
-      },
-      render: (_args, value) => [{ type: 'text', text: value.undone ? 'Released ' + value.id : 'Forgot ' + value.id }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_forget')
-      if (args.undo) return { id: args.id, undone: forgetUndo(store, args.id) }
-      const r = forget(store, args.id)
-      return { id: r.id, undone: false, hashPrefix: r.hash.slice(0, 12) }
-    },
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'memory_consolidate',
-    description: 'Consolidate pending captured session digests into durable memory entries (LLM pass). Forces memory to update now instead of waiting for the automatic cadence.',
-    parameters: {
-      limit: { type: 'integer', description: 'Maximum digests to consolidate in this pass (default 3).' },
-    },
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          consolidated: { type: 'integer', required: true },
-          written: { type: 'integer', required: true },
-          pending: { type: 'integer', required: true },
-          parseFailed: { type: 'boolean' },
-          writeFailed: { type: 'integer' },
-          writeErrors: { type: 'string' },
-        },
-      },
-      render: (_args, value) => [{
-        type: 'text',
-        text: value.parseFailed
-          ? 'The model reply could not be read; nothing was written (see logs/). ' + value.pending + ' digest(s) still pending.'
-          : value.writeFailed
-            ? 'Consolidated ' + value.consolidated + ' digest(s), but ' + value.writeFailed + ' entr(ies) failed to write: ' + (value.writeErrors || 'unknown error')
-            : 'Consolidated ' + value.consolidated + ' digest(s) into ' + value.written + ' entr(ies); ' + value.pending + ' still pending.',
-      }],
-    },
-    async execute(args, exec) {
-      refuseSubagentWrite(exec, 'memory_consolidate')
-      if (!consolidate) throw new Error('memory_consolidate is unavailable in this context')
-      const r = await consolidate(exec.agent, { batchSize: args.limit })
-      return {
-        consolidated: r.consolidated, written: r.written, pending: r.pending,
-        ...(r.parseFailed ? { parseFailed: true } : {}),
-        ...(r.writeFailed ? { writeFailed: r.writeFailed, writeErrors: String(r.writeErrors ?? '').slice(0, 300) } : {}),
-      }
-    },
-  }))
-}
+// Agent tools: memory_search / remember / workspaces / associate / sync / forget.
+import { realpathSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { search } from './search.js'
+import { remember } from './remember.js'
+import { summarizeState, writeStateSection } from './state.js'
+import { rerankHits } from './rerank.js'
+import { logRun } from './telemetry.js'
+import { isSubagentSession } from './session.js'
+import { appendActivity, clearActivity, readWorking, workingSummary, writeWorkingSection } from './working.js'
+import { associate, listWorkspaces } from './workspace.js'
+import { forget, forgetUndo } from './forget.js'
+import { buildMap } from './map.js'
+import { backupTasks, defaultSchedulePath, describeTask, listTasks, planRestore, readScheduleStore, TASK_STATES, writeTask } from './tasks.js'
+
+function renderHits(hits) {
+  if (!hits || hits.length === 0) return [{ type: 'text', text: '(no memory matches)' }]
+  return [{ type: 'text', text: hits
+    .map((h) => h.file + ':' + h.line + (h.id ? ' [' + h.id + ']' : '') + ' ' + h.snippet)
+    .join('\n') }]
+}
+
+function canonicalPath(pathArg, exec) {
+  if (!pathArg) {
+    const cwd = exec?.agent?.session?.header?.cwd
+    return cwd ? realpathSync(cwd) : undefined
+  }
+  const base = exec?.agent?.session?.header?.cwd
+  const abs = isAbsolute(pathArg) ? pathArg : (base ? resolve(base, pathArg) : resolve(pathArg))
+  return realpathSync(abs)
+}
+
+
+/** The text face of a map snapshot: what a caller without a UI still needs to know. */
+function renderMap(value) {
+  const parts = []
+  const store = value.store
+  if (store) {
+    const layers = store.layers.filter((l) => l.count > 0).map((l) => l.name + ' ' + l.count).join(', ')
+    parts.push(store.total + ' entries at ' + store.root)
+    parts.push('layers: ' + layers)
+    const f = store.freshness
+    parts.push('freshness: ' + f.fresh + ' fresh' + (f.stale ? ', ' + f.stale + ' STALE' : '') + (f.skip ? ', ' + f.skip + ' superseded' : ''))
+    const q = store.queue
+    const attention = q.attention.length
+      ? ', needs attention: ' + q.attention.slice(0, 3).map((a) => a.count + ' ' + a.state + ' (' + a.reason + ')').join(', ')
+      : ''
+    parts.push('queue: ' + q.waiting + ' waiting' + (q.recoverable ? ', ' + q.recoverable + ' recoverable' : '') + attention)
+  }
+  const session = value.session
+  if (session) {
+    const received = session.received
+    const sections = received.sections.map((s) => s.name + (s.marker ? ' ' + s.marker : '')).join(', ')
+    parts.push('this session received ' + received.chars + ' chars: ' + (sections || '(nothing injected)'))
+    const written = session.written
+    const byLayer = Object.keys(written.byLayer).map((k) => k + ' ' + written.byLayer[k]).join(', ')
+    parts.push('and wrote ' + written.total + ' entr' + (written.total === 1 ? 'y' : 'ies') + (byLayer ? ' (' + byLayer + ')' : ''))
+  }
+  return parts.join('; ') + '.'
+}
+/** The text face of a tasks report: what a caller without a UI still needs to know. */
+function renderTasks(value) {
+  const parts = []
+  parts.push('Scheduled tasks: ' + value.live + ' live, ' + value.backedUp + ' backed up')
+  const p = value.pending ?? {}
+  if (p.add) parts.push(p.add + ' would be restored')
+  if (p.present) parts.push(p.present + ' already present')
+  if (p.paused) parts.push(p.paused + ' held back')
+  if (p.refused) parts.push(p.refused + ' refused')
+  if (value.changed) parts.push('this call: ' + JSON.stringify(value.changed))
+  const states = {}
+  for (const task of value.tasks ?? []) states[task.state] = (states[task.state] ?? 0) + 1
+  const summary = Object.keys(states).map((s) => s + ' ' + states[s]).join(', ')
+  if (summary) parts.push('states: ' + summary)
+  if (value.unreadable && value.unreadable.length) parts.push(value.unreadable.length + ' file(s) unreadable: ' + value.unreadable.join(', '))
+  if (value.error) parts.push('COULD NOT READ THE SCHEDULE STORE: ' + value.error)
+  return parts.join('; ') + '.'
+}
+
+export function registerTools(ctx, store, extras = {}) {
+  /**
+   * Refuse a WRITE from a subagent session.
+   *
+   * Memory is the main agent's account of the work. A subagent reports back to its parent, and
+   * the parent decides what was durable; letting the child write as well produces two partial
+   * accounts of one task, with the child's - written without the parent's context - competing
+   * with it in search. Reads are unrestricted: a subagent may consult memory freely.
+   */
+  const refuseSubagentWrite = (exec, tool) => {
+    if (!isSubagentSession(exec?.agent?.session)) return
+    throw new Error(tool + ': memory is written by the main agent only. A subagent should return its findings to the caller, which decides what is durable; do not record memory from here.')
+  }
+  const syncNow = extras.syncNow
+  const consolidate = extras.consolidate
+  const workspaceOf = extras.workspaceOf
+  const historyOf = extras.historyOf
+  const refreshNow = extras.refresh
+  const rerankSearch = extras.rerankSearch
+  const statusNow = extras.status
+  const recoverNow = extras.recover
+  const injectionMaxChars = extras.injectionMaxChars
+  const tasksNow = extras.tasksNow
+  const tasksRestore = extras.tasksRestore
+  const schedulePathOf = extras.schedulePath
+
+  ctx.tools.register(defineTool({
+    name: 'memory_search',
+    description: 'Search the dsh-memory store (global + workspace layers). Returns ranked facts with file:line citations.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'Natural-language query or keywords.' },
+      scope: { type: 'string', description: 'global, workspace, or all (default all).' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
+      limit: { type: 'integer', description: 'Maximum hits (default 10).' },
+      rerank: { type: 'boolean', description: 'Ask the session model to reorder the hits by usefulness (costs one call; off unless enabled in config).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          query: { type: 'string', required: true },
+          hits: {
+            type: 'array', required: true,
+            items: {
+              type: 'object', additionalProperties: false,
+              properties: {
+                file: { type: 'string', required: true },
+                line: { type: 'integer', required: true },
+                section: { type: 'string' },
+                snippet: { type: 'string', required: true },
+                id: { type: 'string' },
+                score: { type: 'number' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => renderHits(value.hits),
+    },
+    async execute(args, exec) {
+      // Fetch a few extra so reranking has something to promote from, then trim to the limit.
+      const limit = args.limit ?? 10
+      const hits = search(store, args.query, { scope: args.scope, key: args.workspace, limit })
+      // Reranking is advisory: rerankSearch returns the original order on any failure, so a
+      // model that is missing, slow or unparseable cannot break search.
+      if (rerankSearch) {
+        const outcome = await rerankSearch(exec.agent, args.query, hits, { enabled: args.rerank !== false })
+        return { query: args.query, hits: outcome.hits.slice(0, limit) }
+      }
+      return { query: args.query, hits }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_remember',
+    description: 'Write a durable fact into the dsh-memory store (global or a workspace layer). Use the codebase layer to map a module or subsystem of the current repository. Do NOT call this to fill a gap: if the turn produced nothing durable, writing nothing is the correct outcome.',
+    parameters: {
+      text: { type: 'string', required: true, description: 'The fact body. The Id/Source/Date/… header is added automatically.' },
+      layer: { type: 'string', required: true, description: 'semantic, episodic, procedural, learning, or codebase.' },
+      scope: { type: 'string', description: 'global or workspace. Omit it and a fact recorded inside a known repository is filed to THAT WORKSPACE, because a fact about one repo is not global knowledge. Pass global explicitly for something true across repositories.' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace. Defaults to the workspace of the current session.' },
+      topic: { type: 'string', description: 'Optional heading; defaults to the first sentence.' },
+      source: { type: 'string', description: 'Provenance; defaults to agent:<sessionId>.' },
+      importance: { type: 'integer', description: '1-3 (default 2).' },
+      volatility: { type: 'string', description: 'How fast this decays: stable (a language or license choice), normal (default), volatile (a port, a version in flight, anything with a date).' },
+      until: { type: 'string', description: 'Optional ISO expiry (Valid-until).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          file: { type: 'string', required: true },
+          layer: { type: 'string', required: true },
+          scopeId: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'Remembered ' + value.id + ' -> ' + value.file }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_remember')
+      // DEFAULTS TO THE SESSION'S WORKSPACE, not to global. Defaulting to global is how a
+      // session's entire body of work about one repository - 25 entries in one observed case -
+      // was filed as cross-repository knowledge, where it is both wrong and unfindable from the
+      // workspace it belongs to. A fact recorded inside a repo is about that repo unless the
+      // caller says otherwise, so the safe default is the narrow one and global is opt-in.
+      let scope = args.scope
+      let key = args.workspace
+      // Resolve the session workspace ONCE: it fills in a missing key as well as a missing
+      // scope, so 'workspace' with no key is answerable whenever the session is in a repo.
+      const inferred = (workspaceOf && exec.agent) ? await workspaceOf(exec.agent) : undefined
+      if (!scope) {
+        if (inferred) { scope = 'workspace'; key = key ?? inferred }
+        else scope = 'global'
+      } else if (scope === 'workspace' && !key) {
+        key = inferred
+      }
+      if (scope === 'workspace' && !key) {
+        throw new Error('memory_remember: scope workspace needs a workspace key, and none could be inferred for this session. Pass workspace, or use scope global for cross-repository knowledge.')
+      }
+      const result = remember(store, {
+        scope,
+        key,
+        layer: args.layer,
+        text: args.text,
+        topic: args.topic,
+        source: args.source ?? (exec.agent ? 'agent:' + exec.agent.session.id : 'manual'),
+        importance: args.importance ?? 2,
+        until: args.until,
+        volatility: args.volatility,
+      })
+      return { id: result.id, file: result.file, layer: result.layer, scopeId: result.scopeId }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_codebase',
+    description: 'Record what a module, file or subsystem of the CURRENT repository does, as you discover it. Builds the workspace codebase map. Use the path (or a subsystem name) as the topic so re-discoveries update the same topic file.',
+    parameters: {
+      topic: { type: 'string', required: true, description: 'Module path or subsystem name, e.g. src/layers.js or the capture pipeline.' },
+      text: { type: 'string', required: true, description: 'What it is and does, its entry points, and anything surprising.' },
+      importance: { type: 'integer', description: '1-3 (default 2).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          file: { type: 'string', required: true },
+          workspace: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'Mapped ' + value.id + ' -> ' + value.file }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_codebase')
+      if (!workspaceOf) throw new Error('memory_codebase is unavailable in this context')
+      const workspace = await workspaceOf(exec.agent)
+      if (!workspace) throw new Error('no workspace for this session yet: the codebase map is per repository. Associate one first (memory_associate) or run from inside the repo.')
+      const r = remember(store, {
+        scope: 'workspace', key: workspace, layer: 'codebase',
+        text: args.text, topic: args.topic, importance: args.importance ?? 2,
+        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
+      })
+      return { id: r.id, file: r.file, workspace }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_decision',
+    description: 'Record a settled decision with its context, rationale, alternatives considered, and consequences. Use for dependency choices, conventions, architecture and other choices future work must respect.',
+    parameters: {
+      decision: { type: 'string', required: true, description: 'The decision statement, used as the topic heading.' },
+      context: { type: 'string', description: 'The problem or context that required a choice.' },
+      rationale: { type: 'string', required: true, description: 'Why this option won.' },
+      alternatives: { type: 'array', description: 'Other options considered and rejected.' },
+      consequences: { type: 'string', description: 'What this commits us to, or what follows from it.' },
+      scope: { type: 'string', description: 'global (default) or workspace.' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
+      importance: { type: 'integer', description: '1-3 (default 2).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          file: { type: 'string', required: true },
+          scopeId: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'Decision recorded ' + value.id + ' -> ' + value.file }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_decision')
+      const scope = args.scope ?? 'global'
+      const workspace = args.workspace ?? (scope === 'workspace' && workspaceOf ? await workspaceOf(exec.agent) : undefined)
+      if (scope === 'workspace' && !workspace) throw new Error('workspace decisions need an associated repository')
+      const r = remember(store, {
+        scope, key: workspace, layer: 'decision', topic: args.decision,
+        text: args.rationale, decision: { context: args.context, rationale: args.rationale, alternatives: args.alternatives, consequences: args.consequences },
+        importance: args.importance ?? 2,
+        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
+      })
+      return { id: r.id, file: r.file, scopeId: r.scopeId }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_working',
+    description: 'Record what YOU are working on in this workspace: the task in hand, what you recently did, and what comes next. This is agent working memory, NOT repository state (use memory_state for what the repo is). Set a section (Task, Next steps, Plan, Blocked by) or append to the rolling activity log.',
+    parameters: {
+      section: { type: 'string', description: 'A current-state section to replace: Task, Next steps, Plan, Blocked by (or any short name). Omit when only logging activity.' },
+      content: { type: 'string', description: 'The content of that section. Required with section.' },
+      activity: { type: 'array', description: 'One or more short notes about what you just did, appended to the rolling log (newest last, oldest trimmed).' },
+      clearActivity: { type: 'boolean', description: 'Clear the activity log, keeping the current sections.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          workspace: { type: 'string', required: true },
+          sections: { type: 'array', items: { type: 'string' } },
+          activity: { type: 'integer' },
+          added: { type: 'integer' },
+          verdict: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'Working memory (' + value.workspace + '): ' + (value.sections || []).join(', ') + ' | ' + value.activity + ' activity note(s)' + (value.added ? ', +' + value.added : '') + ' | ' + value.verdict }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_working')
+      if (!workspaceOf) throw new Error('memory_working is unavailable in this context')
+      const workspace = await workspaceOf(exec.agent)
+      if (!workspace) throw new Error('no workspace for this session yet: working memory is per workspace')
+      let added = 0
+      if (args.clearActivity) clearActivity(store.root, 'workspace', workspace)
+      if (args.section && args.content) writeWorkingSection(store.root, 'workspace', workspace, args.section, args.content)
+      if (args.activity && args.activity.length) added = appendActivity(store.root, 'workspace', workspace, args.activity).added
+      if (!args.section && !args.activity && !args.clearActivity) throw new Error('nothing to record: pass section+content, activity, or clearActivity')
+      const summary = workingSummary(store.root, 'workspace', workspace)
+      const working = readWorking(store.root, 'workspace', workspace)
+      return {
+        workspace, added,
+        sections: working ? working.sections.map((s) => s.name) : [],
+        activity: working ? working.activity.length : 0,
+        verdict: summary.verdict,
+      }
+    },
+  }))
+
+
+  ctx.tools.register(defineTool({
+    name: 'memory_tasks',
+    description: 'Show and manage the backup of this machine\'s DSH scheduled tasks. The schedule store is the only copy of them: it is in no git repository, and the host DELETES a task when its owning session stops, so a task can vanish with nothing to observe. Memory keeps one file per task under global/tasks/ and restores them automatically into a session on boot. Actions: report (default), backup, restore, pause, resume.',
+    parameters: {
+      action: { type: 'string', description: 'report (default), backup, restore, pause or resume.' },
+      title: { type: 'string', description: 'Task title, required for pause and resume.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          action: { type: 'string', required: true },
+          schedulePath: { type: 'string', required: true },
+          live: { type: 'integer', required: true },
+          backedUp: { type: 'integer', required: true },
+          tasks: { type: 'array', items: { type: 'object', additionalProperties: true }, required: true },
+          unreadable: { type: 'array', items: { type: 'string' } },
+          changed: { type: 'object', additionalProperties: true },
+          // What a restore would do, which is the question a reader of this report is asking:
+          // how many tasks would be re-armed, how many are already there, how many are held.
+          pending: { type: 'object', additionalProperties: true },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderTasks(value) }],
+      // The structured face. Without presentationMeta a tool result reaches its session event with
+      // no meta at all (core/tools/src/index.ts:1845-1859), which is the only channel a UI has.
+      presentationMeta: (_args, value) => value,
+    },
+    async execute(args, exec) {
+      const action = ['report', 'backup', 'restore', 'pause', 'resume'].includes(args.action) ? args.action : 'report'
+      const schedulePath = schedulePathOf || defaultSchedulePath()
+      let changed = null
+      if (action === 'backup') {
+        if (!tasksNow) throw new Error('memory_tasks: the backup is unavailable in this context')
+        const r = backupTasks(store.root, { schedulePath })
+        changed = { written: r.written, refreshed: r.refreshed, stopped: r.stopped, skipped: r.skipped.length, error: r.error }
+      } else if (action === 'restore') {
+        if (!tasksRestore) throw new Error('memory_tasks: the restore is unavailable in this context')
+        // FORCED, because the once-per-process guard has almost certainly already been consumed by
+        // the boot restore - the manual action exists to run it again on demand.
+        // The outcome is REPORTED rather than assumed: this used to say { restored: true } whatever
+        // happened, including when nothing did.
+        changed = await tasksRestore(exec.agent, { force: true })
+      } else if (action === 'pause' || action === 'resume') {
+        if (!args.title) throw new Error('memory_tasks: ' + action + ' needs a title')
+        const { tasks } = listTasks(store.root)
+        const match = tasks.find((task) => String(task.record.title ?? '') === args.title)
+        if (!match) throw new Error('memory_tasks: no backed-up task titled "' + args.title + '"')
+        // Pausing writes the STATE only. It does not touch the live store: a held task is not
+        // disarmed here, it is simply never re-armed by an automatic pass, which is the decision a
+        // pause expresses. Resuming returns it to the queue, and the next pass derives it afresh.
+        const nextState = action === 'pause' ? TASK_STATES.PAUSED : TASK_STATES.PENDING
+        writeTask(store.root, match.record, nextState, match.backedUpAt ?? new Date().toISOString())
+        changed = { title: args.title, state: nextState }
+      }
+      // The report is read AFTER the action, so what the caller sees is the state they produced.
+      const live = readScheduleStore(schedulePath)
+      const { tasks, unreadable } = listTasks(store.root)
+      const plan = planRestore(store.root, { liveTasks: live.tasks })
+      const rows = tasks.map((task) => {
+        const described = describeTask(task, Date.now())
+        return {
+          title: String(task.record.title ?? ''),
+          kind: String(task.record.kind ?? ''),
+          state: described.state,
+          reason: described.reason,
+          file: task.file,
+        }
+      })
+      return {
+        action,
+        schedulePath,
+        live: live.tasks.length,
+        backedUp: tasks.length,
+        tasks: rows,
+        unreadable,
+        ...(changed ? { changed } : {}),
+        ...(live.error ? { error: live.error } : {}),
+        // Carried for the tool's own use, never shown: the planner's own view of what a restore
+        // would do, which is the question a reader of this report is actually asking.
+        pending: { add: plan.add.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length },
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_map',
+    description: 'Show what memory holds, and what THIS session has done with it. scope "store" reports the whole store - entries per layer, freshness, workspaces, and the ingest queue. scope "session" reports what memory injected into this conversation and what this conversation wrote back. "all" returns both. Read-only, and the data behind the Memory view.',
+    parameters: {
+      scope: { type: 'string', description: 'Which view: "store" (what exists), "session" (what this conversation received and wrote), or "all" (default).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          scope: { type: 'string', required: true },
+          generatedAt: { type: 'string', required: true },
+          store: { type: 'object', additionalProperties: true },
+          session: { type: 'object', additionalProperties: true },
+        },
+      },
+      // The text face, for the agent and for any caller without a UI.
+      render: (_args, value) => [{ type: 'text', text: renderMap(value) }],
+      // The STRUCTURED face, and the only reason the Memory tab and the inline card can draw
+      // anything. A tool result reaches the session event with a `meta` field ONLY when the tool
+      // declares presentationMeta (core/tools/src/index.ts:1845-1859), and that field is what
+      // ui-chat forwards to a view (conversation-nodes/tool.ts:77: meta: match.event.data.meta).
+      // Without this, memory_map rendered its snapshot to prose and threw the value away: the tab
+      // showed 'the result carried no snapshot' while the same call displayed 2,197 entries in
+      // the conversation. The rendered text is not a substitute - rebuilding panels by parsing it
+      // would be a second source of truth.
+      presentationMeta: (_args, value) => value,
+    },
+    async execute(args, exec) {
+      const scope = args.scope === 'store' || args.scope === 'session' ? args.scope : 'all'
+      // The session id is what attributes writes: every tool records source 'agent:<sessionId>'.
+      const sessionId = exec?.agent?.session?.id
+      let key
+      if (workspaceOf && exec?.agent) {
+        try { key = await workspaceOf(exec.agent) } catch { key = undefined }
+      }
+      // The goal and the char cap are read exactly as the injection reads them, so the
+      // RECEIVED panel describes the card that was actually built.
+      const goal = ctx.get('goals')?.get(exec?.agent)?.objective
+      return buildMap(store, {
+        scope,
+        sessionId,
+        memoryScope: key && key !== 'global' ? 'workspace' : 'global',
+        key: key && key !== 'global' ? key : undefined,
+        goal,
+        maxChars: injectionMaxChars,
+      })
+    },
+  }))
+  ctx.tools.register(defineTool({
+    name: 'memory_state',
+    description: 'Record or refresh one section of the CURRENT repository state overview (what is running, the layout, what is pending, health). Replaces that section: state describes now, so a newer statement supersedes the old one. Each section carries a Verified timestamp and stale sections are reported as such.',
+    parameters: {
+      section: { type: 'string', required: true, description: 'Section name: Summary, Layout, Running, Pending, Health (or any short name).' },
+      content: { type: 'string', required: true, description: 'The current state of that area. Be concrete and short; this is an overview.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          section: { type: 'string', required: true },
+          created: { type: 'boolean', required: true },
+          workspace: { type: 'string', required: true },
+          sections: { type: 'array', required: true, items: { type: 'string' } },
+          unverified: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: (value.created ? 'Recorded ' : 'Updated ') + 'state section ' + value.section + ' for ' + value.workspace + '. Sections: ' + (value.sections || []).join(', ') + (value.unverified && value.unverified.length ? ' (still unverified: ' + value.unverified.join(', ') + ')' : '') }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_state')
+      if (!workspaceOf) throw new Error('memory_state is unavailable in this context')
+      const workspace = await workspaceOf(exec.agent)
+      if (!workspace) throw new Error('no workspace for this session yet: repository state is per workspace')
+      const r = writeStateSection(store.root, workspace, args.section, args.content, {
+        source: 'agent:' + (exec.agent && exec.agent.session ? exec.agent.session.id : 'unknown'),
+      })
+      const summary = summarizeState(store.root, workspace)
+      return { section: r.section, created: r.created, workspace, sections: r.sections, unverified: summary.stale }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_recover',
+    description: 'Rebuild memory candidates whose working material was pruned but whose source session survives. Called with no arguments it REPORTS what is recoverable and changes nothing. Recovering a large session asks for approval first.',
+    parameters: {
+      id: { type: 'string', description: 'One candidate to recover. Omit to see a report, or to recover a bounded number of the smallest.' },
+      limit: { type: 'integer', description: 'Recover up to this many, smallest first. Each large one asks for approval.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          mode: { type: 'string', required: true },
+          total: { type: 'integer' },
+          recoverable: { type: 'integer' },
+          oversized: { type: 'integer' },
+          missing: { type: 'integer' },
+          thresholdBytes: { type: 'integer' },
+          recovered: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          declined: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args, value) => {
+        if (value.mode === 'report') {
+          return [{ type: 'text', text: 'memory_recover: ' + value.total + ' candidate(s) stopped with missing material. '
+            + value.recoverable + ' recoverable now, ' + value.oversized + ' need approval (>= '
+            + Math.round((value.thresholdBytes ?? 0) / 1048576) + 'MB), ' + value.missing + ' have no locatable session.' }]
+        }
+        const done = value.recovered ?? []
+        const no = value.declined ?? []
+        return [{ type: 'text', text: 'memory_recover: rebuilt ' + done.length + ' candidate(s)'
+          + (no.length ? '; ' + no.length + ' declined or refused' : '') + '.' }]
+      },
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_recover')
+      if (!recoverNow) throw new Error('memory_recover is unavailable in this context')
+      const plan = recoverNow.plan()
+      if (!args.id && !args.limit) {
+        // `entries: undefined` is NOT lossless JSON - JSON has no undefined - so the harness
+        // rejected the entire result with 'value is not lossless JSON'. The field is a per-id
+        // list that the report deliberately withholds, so it must be OMITTED, not blanked.
+        const { entries: _omitted, ...summary } = plan
+        return { mode: 'report', ...summary }
+      }
+      return recoverNow.run(args, exec)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_status',
+    description: 'Report the memory store state: where it lives, how many digests await consolidation, and whether the last git sync left a conflict. Use it to check memory health before trusting it.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          root: { type: 'string', required: true },
+          pendingDigests: { type: 'integer', required: true },
+          conflicted: { type: 'boolean', required: true },
+          lastSyncOk: { type: 'boolean' },
+          modelCalls: { type: 'integer' },
+          eventCounts: { type: 'object', additionalProperties: true },
+          savedBy: { type: 'object', additionalProperties: true },
+          queue: {
+            type: 'object', additionalProperties: false,
+            properties: {
+              states: { type: 'object', additionalProperties: true, required: true },
+              waiting: { type: 'integer', required: true },
+              retrying: { type: 'integer', required: true },
+              recoverable: { type: 'integer', required: true },
+              parked: { type: 'object', additionalProperties: true },
+              attention: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'One row per CLASS of problem, largest first, each with a sample of ids.' },
+            },
+          },
+        },
+      },
+            render: (_args, value) => {
+        const q = value.queue ?? {}
+        const parts = ['Memory at ' + value.root + ': ' + value.pendingDigests + ' digest(s) pending']
+        // What stopped is reported by NAME. A count would say something is wrong; the list says
+        // what, which is the difference between a warning and something a reader can act on.
+        if (q.recoverable) parts.push(q.recoverable + ' need recovery (memory_recover)')
+        if (q.retrying) parts.push(q.retrying + ' retrying')
+        if (q.parked && Object.keys(q.parked).length) parts.push('parked: ' + Object.entries(q.parked).map(([why, c]) => c + ' ' + why).join(', '))
+        const attention = q.attention ?? []
+        if (attention.length) {
+          // One clause per CLASS of problem, largest first: '78 orphaned (digest-missing)' says
+          // more than 78 identical lines ever could.
+          const classes = attention.slice(0, 3).map((a) => a.count + ' ' + a.state + (a.reason ? ' (' + a.reason + ')' : ''))
+          parts.push('needs attention: ' + classes.join(', ') + (attention.length > 3 ? ', +' + (attention.length - 3) + ' more kinds' : ''))
+        }
+        if (value.conflicted) parts.push('THE LAST SYNC CONFLICTED (see state/CONFLICT.md)')
+        parts.push('model calls ' + (value.modelCalls || 0))
+        return [{ type: 'text', text: parts.join('; ') + '.' }]
+      },
+    },
+    async execute() {
+      if (!statusNow) throw new Error('memory_status is unavailable in this context')
+      const s = statusNow()
+      return {
+        root: s.root, pendingDigests: s.pendingDigests, conflicted: s.conflicted,
+        ...(s.lastSync && typeof s.lastSync.ok === 'boolean' ? { lastSyncOk: s.lastSync.ok } : {}),
+        modelCalls: s.metrics?.modelCalls ?? 0, eventCounts: s.metrics?.events ?? {}, savedBy: s.metrics?.savedBy ?? {},
+        ...(s.queue ? { queue: s.queue } : {}),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_refresh',
+    description: 'Run the freshness pass now instead of waiting for the daily cadence: stale and time-bounded entries are re-examined and kept, updated, or superseded by the model.',
+    parameters: {
+      limit: { type: 'integer', description: 'Maximum entries to review (default 3).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          refreshed: { type: 'integer', required: true },
+          updated: { type: 'integer', required: true },
+          superseded: { type: 'integer', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.refreshed === 0 ? 'Nothing needed refreshing.' : 'Reviewed ' + value.refreshed + ' entr(ies): ' + value.updated + ' updated, ' + value.superseded + ' superseded.' }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_refresh')
+      if (!refreshNow) throw new Error('memory_refresh is unavailable in this context')
+      const r = await refreshNow(exec.agent, { limit: args.limit })
+      return { refreshed: r.refreshed ?? 0, updated: r.updated ?? 0, superseded: r.superseded ?? 0 }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_history',
+    description: 'Ingest this repository commit history into the workspace history layer (how the codebase changed over time). Incremental: only commits not yet recorded are added. Safe to call repeatedly.',
+    parameters: {
+      limit: { type: 'integer', description: 'Maximum new commits to record (default 40).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          added: { type: 'integer', required: true },
+          skipped: { type: 'integer' },
+          head: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.ok
+        ? 'Recorded ' + value.added + ' commit(s) into the history layer' + (value.skipped ? ' (' + value.skipped + ' already known)' : '') + '.'
+        : 'No history recorded: ' + (value.reason || 'unavailable') }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_history')
+      if (!historyOf) throw new Error('memory_history is unavailable in this context')
+      const r = await historyOf(exec.agent, { limit: args.limit })
+      // A manual ingest must leave the same trace as the cadence, or the history layer grows
+      // with nothing anywhere explaining where its files came from.
+      logRun(store.root, 'history-ingest', { source: 'tool', count: (r && r.added) || 0, detail: { ok: Boolean(r && r.ok), reason: (r && r.reason) || '' } })
+      return {
+        ok: Boolean(r && r.ok), added: (r && r.added) || 0,
+        ...(r && r.skipped ? { skipped: r.skipped } : {}),
+        ...(r && r.head ? { head: String(r.head).slice(0, 12) } : {}),
+        ...(r && r.reason ? { reason: String(r.reason) } : {}),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_workspaces',
+    description: 'List the workspaces (local folders/repos) associated with the dsh-memory store.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          workspaces: {
+            type: 'array', required: true,
+            items: {
+              type: 'object', additionalProperties: false,
+              properties: {
+                key: { type: 'string', required: true },
+                title: { type: 'string', required: true },
+                remotes: { type: 'array', required: true, items: { type: 'string' } },
+                path: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.workspaces.length
+          ? value.workspaces.map((w) => w.key + ' (' + w.title + ')' + (w.path ? ' -> ' + w.path : '')).join('\n')
+          : '(no workspaces associated)',
+      }],
+    },
+    async execute() {
+      // `path` is OMITTED when the workspace has no local folder, rather than set to undefined.
+      // An explicit undefined is not lossless JSON, and the harness rejects the WHOLE result - so a
+      // single workspace with no folder on this machine broke the entire listing, and every other
+      // workspace went down with it. Found by calling the tool against the real store: 'puzzle' has
+      // no path, and the call failed with "value is not lossless JSON".
+      const workspaces = listWorkspaces(store).map((w) => ({
+        key: w.key,
+        title: w.title,
+        remotes: w.remotes,
+        ...(w.path === undefined ? {} : { path: w.path }),
+      }))
+      return { workspaces }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_associate',
+    description: 'Associate a local folder/repo with a workspace key (creates the workspace layer).',
+    parameters: {
+      key: { type: 'string', required: true, description: 'Workspace key (filesystem-safe slug).' },
+      title: { type: 'string', description: 'Optional display title.' },
+      path: { type: 'string', description: 'Local folder; defaults to the current session working directory.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: { key: { type: 'string', required: true } },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'Associated workspace ' + value.key }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_associate')
+      let cwd
+      try { cwd = canonicalPath(args.path, exec) } catch { cwd = undefined }
+      const key = associate(store, { key: args.key, title: args.title, cwd })
+      return { key }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_sync',
+    description: 'Commit local memory changes and sync (pull + push) with the configured GitHub origin.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          synced: { type: 'boolean', required: true },
+          conflict: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.conflict
+        ? 'Memory sync needs attention: ' + (value.error || 'git reported a failure') + ' (see state/CONFLICT.md)'
+        : (value.synced ? 'Memory synced.' : 'Memory sync unavailable (no git remote configured).') }],
+    },
+    async execute(_args, exec) {
+      refuseSubagentWrite(exec, 'memory_sync')
+      if (!syncNow) return { synced: false }
+      const status = await syncNow()
+      return {
+        synced: Boolean(status && (status.synced || status.committed || status.initialized)),
+        ...(status && status.conflict ? { conflict: true } : {}),
+        ...(status && status.error ? { error: String(status.error) } : {}),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_forget',
+    description: 'Forget a memory entry (supersede it and suppress re-adding), or release it with undo.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Entry id (e.g. global-sem-0001).' },
+      undo: { type: 'boolean', description: 'Set true to release a previously forgotten entry.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: { id: { type: 'string', required: true }, undone: { type: 'boolean' }, hashPrefix: { type: 'string' } },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.undone ? 'Released ' + value.id : 'Forgot ' + value.id }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_forget')
+      if (args.undo) return { id: args.id, undone: forgetUndo(store, args.id) }
+      const r = forget(store, args.id)
+      return { id: r.id, undone: false, hashPrefix: r.hash.slice(0, 12) }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_consolidate',
+    description: 'Consolidate pending captured session digests into durable memory entries (LLM pass). Forces memory to update now instead of waiting for the automatic cadence.',
+    parameters: {
+      limit: { type: 'integer', description: 'Maximum digests to consolidate in this pass (default 3).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          consolidated: { type: 'integer', required: true },
+          written: { type: 'integer', required: true },
+          pending: { type: 'integer', required: true },
+          parseFailed: { type: 'boolean' },
+          writeFailed: { type: 'integer' },
+          writeErrors: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.parseFailed
+          ? 'The model reply could not be read; nothing was written (see logs/). ' + value.pending + ' digest(s) still pending.'
+          : value.writeFailed
+            ? 'Consolidated ' + value.consolidated + ' digest(s), but ' + value.writeFailed + ' entr(ies) failed to write: ' + (value.writeErrors || 'unknown error')
+            : 'Consolidated ' + value.consolidated + ' digest(s) into ' + value.written + ' entr(ies); ' + value.pending + ' still pending.',
+      }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_consolidate')
+      if (!consolidate) throw new Error('memory_consolidate is unavailable in this context')
+      const r = await consolidate(exec.agent, { batchSize: args.limit })
+      return {
+        consolidated: r.consolidated, written: r.written, pending: r.pending,
+        ...(r.parseFailed ? { parseFailed: true } : {}),
+        ...(r.writeFailed ? { writeFailed: r.writeFailed, writeErrors: String(r.writeErrors ?? '').slice(0, 300) } : {}),
+      }
+    },
+  }))
+}