agent-working-memory 0.17.0 → 0.18.1

package/src/mcp.ts

@@ -1,1475 +1,1521 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * MCP Server — Model Context Protocol interface for AgentWorkingMemory.
- *
- * Runs as a stdio-based MCP server that Claude Code connects to directly.
- * Uses the storage and engine layers in-process (no HTTP overhead).
- *
- * Tools exposed (19):
- *   memory_write       — store a memory (salience filter decides disposition)
- *   memory_recall      — activate memories by context (cognitive retrieval)
- *   memory_feedback    — report whether a recalled memory was useful
- *   memory_retract     — invalidate a wrong memory with optional correction
- *   memory_supersede   — replace an outdated memory with a current one
- *   memory_stats       — get memory health metrics
- *   memory_whoami      — identify this instance, mode, store, and sibling agent spaces
- *   memory_checkpoint  — save structured execution state (survives compaction)
- *   memory_restore     — restore state + targeted recall after compaction
- *   memory_task_add    — create a prioritized task
- *   memory_task_update — change task status, priority, or blocking
- *   memory_task_list   — list tasks filtered by status
- *   memory_task_next   — get the highest-priority actionable task
- *   memory_task_begin  — start a task (auto-checkpoint + recall)
- *   memory_task_end    — end a task (write summary + checkpoint)
- *   compress_output    — encode structured tool output as TOON (token-efficient, lossless)
- *   retrieve_original  — get the verbatim source for a compress_output ref
- *
- * Run: npx tsx src/mcp.ts
- * Config: add to ~/.claude.json or .mcp.json
- */
-
-import { readFileSync } from 'node:fs';
-import { deriveAgentFromDir as deriveAgentFromDirShared } from './core/agent-id.js';
-import { resolve, basename } from 'node:path';
-import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-// Load .env file if present (no external dependency)
-try {
-  const envPath = resolve(process.cwd(), '.env');
-  const envContent = readFileSync(envPath, 'utf-8');
-  for (const line of envContent.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eqIdx = trimmed.indexOf('=');
-    if (eqIdx === -1) continue;
-    const key = trimmed.slice(0, eqIdx).trim();
-    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
-    if (!process.env[key]) process.env[key] = val;
-  }
-} catch { /* No .env file */ }
-
-// MCP uses stdout for JSON-RPC. Redirect console.log to stderr so engine
-// startup messages (ConsolidationScheduler, model loading, etc.) don't
-// corrupt the transport. This MUST happen before any engine imports.
-console.log = console.error;
-
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-
-import { EngramStore } from './storage/sqlite.js';
-import { openStore, getConfiguredBackend, type StoreBackend } from './storage/factory.js';
-import type { IEngramStore } from './storage/store.js';
-import { ActivationEngine } from './engine/activation.js';
-import { ConnectionEngine } from './engine/connections.js';
-import { StagingBuffer } from './engine/staging.js';
-import { EvictionEngine } from './engine/eviction.js';
-import { RetractionEngine } from './engine/retraction.js';
-import { EvalEngine } from './engine/eval.js';
-import { ConsolidationEngine } from './engine/consolidation.js';
-import { ConsolidationScheduler } from './engine/consolidation-scheduler.js';
-import { evaluateSalience, computeNovelty, computeNoveltyWithMatch } from './core/salience.js';
-import { performWrite } from './core/write-pipeline.js';
-import type { ConsciousState } from './types/checkpoint.js';
-import type { SalienceEventType } from './core/salience.js';
-import type { TaskStatus, TaskPriority, AbstentionInfo } from './types/engram.js';
-import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
-import { embed, getEmbedder } from './core/embeddings.js';
-import { getReranker } from './core/reranker.js';
-import { getExpander } from './core/query-expander.js';
-import { startSidecar } from './hooks/sidecar.js';
-import { initLogger, log, getLogPath } from './core/logger.js';
-import { VERSION } from './version.js';
-import { buildPack, INTERVIEW_QUESTIONS } from './onboard/index.js';
-import { liteCompress, retrieveOriginal } from './core/lite-compress.js';
-import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-decisions.js';
-import { startLoopLagMonitor } from './core/write-telemetry.js';
-import { buildWhoami, formatWhoami } from './core/whoami.js';
-import { renderTaskEndInvitation, validateRecipeWrite, recipeSlug, getRecipe } from './recipes/index.js';
-import { formatRecallResultLine } from './core/format-recall.js';
-import { packRecallByBudget, formatTokenFooter, estimateTokens } from './core/token-budget.js';
-
-// --- Incognito Mode ---
-// When AWM_INCOGNITO=1, register zero tools. Claude won't see memory tools at all.
-// No DB, no engines, no sidecar — just a bare MCP server that exposes nothing.
-
-const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO === 'true';
-
-if (INCOGNITO) {
-  console.error('AWM: incognito mode — all memory tools disabled, nothing will be recorded');
-  const server = new McpServer({ name: 'agent-working-memory', version: VERSION });
-  const transport = new StdioServerTransport();
-  server.connect(transport).catch(err => {
-    console.error('MCP server failed:', err);
-    process.exit(1);
-  });
-  // No tools registered — Claude won't see any memory_* tools
-} else {
-
-// --- Setup ---
-
-const BACKEND: StoreBackend = getConfiguredBackend();
-const DB_PATH = process.env.AWM_DB_PATH ?? (BACKEND === 'pglite' ? 'memory-pglite' : 'memory.db');
-
-// Fallback agent selection when AWM_AGENT_ID/WORKER_NAME are unset: derive from
-// the project directory (core/agent-id.ts — one definition shared with `awm setup`
-// and mirrored in the shipped hook scripts, so the server, the installer and the
-// hooks always name the same pool for a given directory).
-const deriveAgentFromDir = () => deriveAgentFromDirShared(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
-const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? deriveAgentFromDir();
-const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
-// 0.14.2: ports to try upward from HOOK_PORT when it is busy (see sidecar.ts).
-const HOOK_PORT_RANGE = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE ?? '10', 10) || 10);
-// Set once the sidecar starts; whoami reads the bound port from it.
-let sidecarHandle: { boundPort: () => number | null } | null = null;
-function sidecarPortLabel(): string {
-  const p = sidecarHandle?.boundPort() ?? null;
-  if (p === null) return `not bound (preferred ${HOOK_PORT}; hooks disabled)`;
-  return p === HOOK_PORT ? `127.0.0.1:${p}` : `127.0.0.1:${p} (preferred ${HOOK_PORT} was busy)`;
-}
-const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
-
-initLogger(DB_PATH);
-log(AGENT_ID, 'startup', `MCP server starting (backend: ${BACKEND}, db: ${DB_PATH}, hooks: ${HOOK_PORT})`);
-
-// AWM 0.8.x: openStore() returns either SQLite (sync) or PGlite (async) store.
-// Engines accept either via IEngramStore (MaybePromise<T> contract).
-const { store: storeAny } = await openStore();
-// Engines accept the async contract; SQLite-only call sites must guard on BACKEND.
-const store = storeAny as unknown as IEngramStore & Partial<EngramStore>;
-const activationEngine = new ActivationEngine(store);
-const connectionEngine = new ConnectionEngine(store, activationEngine);
-const stagingBuffer = new StagingBuffer(store, activationEngine);
-const evictionEngine = new EvictionEngine(store);
-const retractionEngine = new RetractionEngine(store);
-const evalEngine = new EvalEngine(store);
-const consolidationEngine = new ConsolidationEngine(store, connectionEngine);
-const consolidationScheduler = new ConsolidationScheduler(store, consolidationEngine);
-
-stagingBuffer.start(DEFAULT_AGENT_CONFIG.stagingTtlMs);
-consolidationScheduler.start();
-startLoopLagMonitor();
-
-// Coordination DB handle — set when AWM_COORDINATION=true, used by memory_write for decision propagation
-let coordDb: import('better-sqlite3').Database | null = null;
-
-const server = new McpServer({
-  name: 'agent-working-memory',
-  version: VERSION,
-});
-
-server.registerResource(
-  'awm-overview',
-  'awm://server/overview',
-  {
-    title: 'AWM Overview',
-    description: 'AgentWorkingMemory MCP server metadata and discovery notes',
-    mimeType: 'text/markdown',
-  },
-  async () => ({
-    contents: [{
-      uri: 'awm://server/overview',
-      text: [
-        '# Agent Working Memory',
-        '',
-        `Agent: ${AGENT_ID}`,
-        `DB: ${DB_PATH}`,
-        `Coordination: ${process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1' ? 'enabled' : 'disabled'}`,
-        '',
-        'This MCP server primarily exposes tools such as `memory_restore`, `memory_recall`, `memory_write`, and task/checkpoint operations.',
-        'The resources below exist so generic MCP clients can discover the server through `resources/list` and `resources/templates/list`.',
-      ].join('\n'),
-      mimeType: 'text/markdown',
-    }],
-  })
-);
-
-server.registerResource(
-  'awm-memory-template',
-  new ResourceTemplate('awm://memory/{id}', { list: undefined }),
-  {
-    title: 'AWM Memory By ID',
-    description: 'Metadata resource template for a memory identifier',
-    mimeType: 'text/markdown',
-  },
-  async (_uri, variables) => ({
-    contents: [{
-      uri: `awm://memory/${variables.id ?? ''}`,
-      text: [
-        '# AWM Memory Reference',
-        '',
-        `Requested memory id: ${variables.id ?? ''}`,
-        '',
-        'Use the AWM memory tools for actual retrieval and mutation:',
-        '- `memory_recall` for cognitive retrieval',
-        '- `memory_restore` for session state',
-        '- `memory_feedback`, `memory_retract`, `memory_supersede` for memory maintenance',
-      ].join('\n'),
-      mimeType: 'text/markdown',
-    }],
-  })
-);
-
-// --- Auto-classification for memory types ---
-
-function classifyMemoryType(content: string): 'episodic' | 'semantic' | 'procedural' | 'unclassified' {
-  const lower = content.toLowerCase();
-  // Procedural: how-to, steps, numbered lists
-  if (/\bhow to\b|\bsteps?:/i.test(content) || /^\s*\d+[\.\)]\s/m.test(content) || /\bthen run\b|\bfirst,?\s/i.test(content)) {
-    return 'procedural';
-  }
-  // Episodic: past tense events, incidents, specific time references
-  if (/\b(discovered|debugged|fixed|encountered|happened|resolved|found that|we did|i did|yesterday|last week|today)\b/i.test(content)) {
-    return 'episodic';
-  }
-  // Semantic: facts, decisions, rules, patterns
-  if (/\b(is|are|should|always|never|must|uses?|requires?|means|pattern|decision|rule|convention)\b/i.test(content) && content.length < 500) {
-    return 'semantic';
-  }
-  return 'unclassified';
-}
-
-// --- Tools ---
-
-server.tool(
-  'memory_write',
-  `Store a memory. The salience filter decides whether it's worth keeping (active), needs more evidence (staging), or should be discarded.
-
-CALL THIS PROACTIVELY — do not wait to be asked. Write memories when you:
-- Discover something about the codebase, bugs, or architecture
-- Make a decision and want to remember why
-- Encounter and resolve an error
-- Learn a user preference or project pattern
-- Complete a significant piece of work
-
-The concept should be a short label (3-8 words). The content should be the full detail.`,
-  {
-    concept: z.string().describe('Short label for this memory (3-8 words)'),
-    content: z.string().describe('Full detail of what was learned'),
-    tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
-    event_type: z.enum(['observation', 'decision', 'friction', 'surprise', 'causal'])
-      .optional().default('observation')
-      .describe('Type of event: observation (default), decision, friction (error/blocker), surprise, causal (root cause)'),
-    surprise: z.number().min(0).max(1).optional().default(0.3)
-      .describe('How surprising was this? 0=expected, 1=very unexpected'),
-    decision_made: z.boolean().optional().default(false)
-      .describe('Was a decision made? True boosts importance'),
-    causal_depth: z.number().min(0).max(1).optional().default(0.3)
-      .describe('How deep is the causal understanding? 0=surface, 1=root cause'),
-    resolution_effort: z.number().min(0).max(1).optional().default(0.3)
-      .describe('How much effort to resolve? 0=trivial, 1=significant debugging'),
-    memory_class: z.enum(['canonical', 'working', 'ephemeral']).optional().default('working')
-      .describe('Memory class: canonical (source-of-truth, never stages), working (default), ephemeral (temporary, decays faster)'),
-    memory_type: z.enum(['episodic', 'semantic', 'procedural', 'unclassified']).optional()
-      .describe('Memory type: episodic (events/incidents), semantic (facts/decisions), procedural (how-to/steps). Auto-classified if omitted.'),
-    supersedes: z.string().optional()
-      .describe('ID of an older memory this one replaces. The old memory is down-ranked, not deleted.'),
-    // --- Agent-provided metadata (stored as searchable tags) ---
-    project: z.string().optional()
-      .describe('Project context (e.g., "EquiHub", "AWM"). Becomes a searchable tag.'),
-    topic: z.string().optional()
-      .describe('Subject area (e.g., "database-migration", "auth-flow"). Becomes a searchable tag.'),
-    source: z.enum(['code-reading', 'debugging', 'discussion', 'research', 'testing', 'observation']).optional()
-      .describe('How this knowledge was acquired.'),
-    confidence_level: z.enum(['verified', 'observed', 'assumed']).optional()
-      .describe('Confidence: verified (tested), observed (read in code), assumed (reasoning).'),
-    session_id: z.string().optional()
-      .describe('Session/conversation grouping ID. Memories with same session_id are associated.'),
-    origin_class: z.enum(['user-stated', 'tool-output', 'inference', 'recipe']).optional()
-      .describe('Provenance (D5, log-only): where this knowledge came from. user-stated = the human said it; tool-output = read from a tool/system; inference = your reasoning; recipe = produced by a cognition recipe.'),
-    recipe_id: z.string().optional()
-      .describe('Cognition-recipe id+version when origin_class is recipe.'),
-    valid_from: z.string().optional()
-      .describe('ISO date when the FACT becomes valid (temporal validity, not ingestion time).'),
-    valid_to: z.string().optional()
-      .describe('ISO date when the FACT stops being valid (e.g., a deadline or a superseding change).'),
-    intent: z.enum(['decision', 'question', 'todo', 'finding', 'context']).optional()
-      .describe('What kind of memory this is.'),
-  },
-  async (params) => {
-    // Assemble tags: user-provided + agent metadata (stored as searchable prefixed tags)
-    const userTags = params.tags ?? [];
-    const metaTags: string[] = [];
-    if (params.project) metaTags.push(`proj=${params.project}`);
-    if (params.topic) metaTags.push(`topic=${params.topic}`);
-    if (params.source) metaTags.push(`src=${params.source}`);
-    if (params.confidence_level) metaTags.push(`conf=${params.confidence_level}`);
-    if (params.session_id) metaTags.push(`sid=${params.session_id}`);
-    if (params.intent) metaTags.push(`intent=${params.intent}`);
-
-    // D14 (2026-07-30): recipe write-backs are contract-checked. Provenance
-    // must never claim a recipe that does not exist, and malformed
-    // derivations are rejected with the contract echoed back so the host
-    // can self-correct in one retry.
-    if (params.origin_class === 'recipe') {
-      if (!params.recipe_id) {
-        return { content: [{ type: 'text' as const, text: "Recipe write rejected: origin_class 'recipe' requires recipe_id (e.g. 'skill-derivation@1')." }] };
-      }
-      const v = validateRecipeWrite(params.recipe_id, params.concept, params.content);
-      if (!v.ok) {
-        const contract = getRecipe(params.recipe_id)?.writeBack ?? 'unknown recipe';
-        return { content: [{ type: 'text' as const, text: `Recipe write rejected (${params.recipe_id}): ${v.errors.join('; ')}\nContract: ${contract}` }] };
-      }
-      // Standardize recipe write-backs: canonical class, standard tags.
-      const slug = recipeSlug(params.concept);
-      const ensure = (tag: string) => { if (!userTags.includes(tag) && !metaTags.includes(tag)) metaTags.push(tag); };
-      if (params.recipe_id.startsWith('skill-derivation')) {
-        ensure('topic=skill'); ensure(`skill=${slug}`);
-        params.memory_type = params.memory_type ?? 'procedural';
-      } else if (params.recipe_id.startsWith('friction-lesson')) {
-        ensure('topic=friction'); ensure(`about=${slug}`);
-        // zod defaults event_type to 'observation', so force the recipe's
-        // contract value rather than ??-guarding against undefined.
-        params.event_type = 'friction';
-      }
-      params.memory_class = 'canonical';
-    }
-
-    const memoryType = params.memory_type ?? classifyMemoryType(params.content);
-
-    const result = await performWrite({ store, connectionEngine }, {
-      agentId: AGENT_ID,
-      concept: params.concept,
-      content: params.content,
-      tags: [...userTags, ...metaTags],
-      eventType: params.event_type as SalienceEventType,
-      surprise: params.surprise,
-      decisionMade: params.decision_made,
-      causalDepth: params.causal_depth,
-      resolutionEffort: params.resolution_effort,
-      memoryClass: params.memory_class,
-      memoryType,
-      supersedes: params.supersedes,
-      originClass: params.origin_class,
-      writerSession: params.session_id,
-      recipeId: params.recipe_id,
-      validFrom: params.valid_from,
-      validTo: params.valid_to,
-    });
-
-    // Auto-checkpoint — covers create/reinforce/supersede uniformly
-    try { await store.updateAutoCheckpointWrite(AGENT_ID, result.engram.id); } catch { /* non-fatal */ }
-
-    if (result.action === 'reinforce') {
-      log(AGENT_ID, 'write:reinforce', `"${params.concept}" → reinforced "${result.engram.concept}" (conf ${result.reinforce!.previousConfidence.toFixed(2)} → ${result.reinforce!.newConfidence.toFixed(2)}, novelty=${result.noveltyResult.novelty.toFixed(2)})`);
-      return {
-        content: [{
-          type: 'text' as const,
-          text: `Reinforced existing memory "${result.engram.concept}" (confidence ${result.reinforce!.previousConfidence.toFixed(2)} → ${result.reinforce!.newConfidence.toFixed(2)})`,
-        }],
-      };
-    }
-
-    const engram = result.engram;
-    const salience = result.salience!; // create/supersede always have salience
-    const novelty = result.noveltyResult.novelty;
-    const isLowSalience = salience.disposition === 'discard';
-
-    // Decision propagation: when decision_made=true and coordination is enabled,
-    // broadcast to coord_decisions so other agents can discover it
-    if (params.decision_made && coordDb) {
-      try {
-        const agent = coordDb.prepare(
-          `SELECT id, current_task FROM coord_agents WHERE name = ? AND status != 'dead' ORDER BY last_seen DESC LIMIT 1`
-        ).get(AGENT_ID) as { id: string; current_task: string | null } | undefined;
-        if (agent) {
-          coordDb.prepare(
-            `INSERT INTO coord_decisions (author_id, assignment_id, tags, summary) VALUES (?, ?, ?, ?)`
-          ).run(agent.id, agent.current_task, params.tags ? JSON.stringify(params.tags) : null, params.concept);
-        }
-      } catch { /* decision propagation is non-fatal */ }
-    }
-
-    const logDisposition = isLowSalience ? 'low-salience' : salience.disposition;
-    log(AGENT_ID, `write:${logDisposition}`, `"${params.concept}" salience=${salience.score.toFixed(2)} novelty=${novelty.toFixed(1)} id=${engram.id}`);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Stored (${salience.disposition}) "${params.concept}" [${salience.score.toFixed(2)}]\nID: ${engram.id}`
-          + (isLowSalience
-            ? `\nNOTE: low salience — this memory is kept but demoted and may fade first. If it MUST survive and be recallable, retry with memory_class: 'canonical'. (Discards are audited: reason codes ${JSON.stringify(salience.reasonCodes.slice(0, 4))})`
-            : ''),
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_recall',
-  `Recall memories relevant to a query. Uses cognitive activation — not keyword search.
-
-ALWAYS call this when:
-- Starting work on a project or topic (recall what you know)
-- Debugging (recall similar errors and solutions)
-- Making decisions (recall past decisions and outcomes)
-- The user mentions a topic you might have stored memories about
-
-Accepts either "query" or "context" parameter — both work identically.
-Returns the most relevant memories ranked by text relevance, temporal recency, and associative strength.`,
-  {
-    query: z.string().optional().describe('What to search for — describe the situation, question, or topic'),
-    context: z.string().optional().describe('Alias for query (either works)'),
-    limit: z.number().optional().default(3).describe('Max memories to return (default 3). Measured on 400 real-store probes: k=3 is the only token-POSITIVE setting (+115 tok/recall, against -680 at k=5) and is 41% faster at p50, because `limit` sizes the cross-encoder rerank pool (min(limit*8, 40) — so 24 at k=3 against 40 at k=5) and rerank is 83% of warm recall time. It costs ~0.5pp success@1 versus k=5 — about 3 queries in 400, inside noise. Raise it explicitly when you want breadth for orientation rather than a specific fact; that is the case this default deliberately does not optimize for.'),
-    min_score: z.number().optional().default(0.05).describe('Minimum relevance score (default 0.05)'),
-    include_staging: z.boolean().optional().default(false).describe('Include weak/unconfirmed memories?'),
-    use_reranker: z.boolean().optional().default(true).describe('Use cross-encoder re-ranking for better relevance (default true)'),
-    use_expansion: z.boolean().optional().default(true).describe('Expand query with synonyms for better recall (default true)'),
-    memory_type: z.enum(['episodic', 'semantic', 'procedural']).optional().describe('Filter by memory type (omit to search all types)'),
-    workspace: z.string().optional().describe('Search across all agents in this workspace (hive mode). Omit for agent-scoped recall only.'),
-    require_confidence: z.number().optional().default(0.05).describe('Abstain (return nothing) when recall confidence is below this threshold. Defaults to 0.05 — a LIGHT filter, chosen from measurement: it halves the rate of answering off-topic queries at zero cost to hit rate. Raise it only for push-style use where nobody asked (the prime hook uses 0.10 — it was 0.25 until 0.14.6, when 0.25 was measured silencing prompts with a clear winner). Do NOT raise it for ordinary recall: a miss is expensive, because the agent then reads the codebase instead (~2,106 tokens), so aggressive thresholds measurably destroy value — 0.20+ cut net tokens saved by 25% in tests/abstention-eval. Pass 0 to disable. NOTE: this is NOT min_score — it gates on the SHAPE of the score distribution across the whole result set, not per-result relevance, so memories that pass min_score can still be withheld. When that happens the reply says RECALL ABSTAINED and reports how many were withheld; an empty result is only absence when it does not.'),
-    granularity: z.enum(['full', 'compact', 'auto']).optional().describe('Output granularity (Paper 3: cognitive teaming). "full" (default): no change. "compact": every result carries a short summary field. "auto": confidence-adaptive — top result gets a longer summary when there is a clear winner, otherwise everything is compact for scanning.'),
-    max_tokens: z.number().optional().describe('Token budget for the response. `limit` is a COUNT and is token-blind — 5 results may cost 400 tokens or 4,000. Use this when context is tight: results are packed by value-per-token until the budget is reached, the top-scored match always gets first refusal, and the reply reports what it cost and what was withheld. Omit for no budget (everything is returned, still with accounting).'),
-  },
-  async (params) => {
-    const queryText = params.query ?? params.context;
-    if (!queryText) {
-      return {
-        content: [{
-          type: 'text' as const,
-          text: 'Error: provide either "query" or "context" parameter with your search text.',
-        }],
-      };
-    }
-    // Use workspace from param, env var, or omit for agent-scoped
-    const workspace = params.workspace ?? process.env.AWM_WORKSPACE ?? undefined;
-    // Set only when a gate WITHHELD results. Distinguishes abstention from absence,
-    // which an empty array cannot.
-    let abstained: AbstentionInfo | undefined;
-    const results = await activationEngine.activate({
-      agentId: AGENT_ID,
-      context: queryText,
-      limit: params.limit,
-      minScore: params.min_score,
-      includeStaging: params.include_staging,
-      useReranker: params.use_reranker,
-      useExpansion: params.use_expansion,
-      memoryType: params.memory_type,
-      workspace,
-      requireConfidence: params.require_confidence,
-      granularity: params.granularity,
-      onAbstain: (info) => { abstained = info; },
-    });
-
-    // Auto-checkpoint: track recall
-    try {
-      const ids = results.map(r => r.engram.id);
-      await store.updateAutoCheckpointRecall(AGENT_ID, queryText, ids);
-    } catch { /* non-fatal */ }
-
-    log(AGENT_ID, 'recall', `"${queryText.slice(0, 80)}" → ${results.length} results`);
-
-    // Peer decisions: append recent decisions by other agents relevant to this query
-    const peerSuffix = coordDb
-      ? formatPeerDecisions(queryPeerDecisions(coordDb, AGENT_ID, queryText))
-      : '';
-
-    if (results.length === 0) {
-      // Two very different conditions used to render identically as
-      // "No relevant memories found." — a claim of absence the system cannot make
-      // when a gate withheld matches. Callers read it as absence and stopped
-      // looking, for memories scoring well above minScore.
-      const text = abstained
-        ? [
-            `RECALL ABSTAINED — this is NOT "no memories exist".`,
-            ``,
-            `${abstained.candidates} candidate${abstained.candidates === 1 ? '' : 's'} matched ` +
-              `(best score ${abstained.topScore.toFixed(3)}) and ${abstained.candidates === 1 ? 'was' : 'were'} ` +
-              `withheld because recall confidence ` +
-              `${abstained.confidence !== undefined ? abstained.confidence.toFixed(3) + ' ' : ''}` +
-              `fell below your require_confidence of ${abstained.threshold ?? '?'}.`,
-            ``,
-            `require_confidence is NOT min_score. It gates on the SHAPE of the score` +
-              ` distribution across the whole result set, not on how relevant any single` +
-              ` memory is — so results that comfortably pass min_score can still be withheld here.`,
-            ``,
-            `To see them: re-run this query with require_confidence: 0.`,
-            `Do not conclude the memories are absent without doing that.`,
-          ].join('\n') + peerSuffix
-        : 'No relevant memories found.' + peerSuffix;
-      return { content: [{ type: 'text' as const, text }] };
-    }
-
-    // Confidence-adaptive output (Paper 3: cognitive teaming) and D8
-    // (2026-07-30) conflict surfacing both live in the shared formatter now —
-    // see core/format-recall.ts for why it's extracted (0.12.1: unit-testable
-    // without booting the server) and why the id sits after the score.
-    // 0.13.3: pack to a token budget (if given) and always report the spend.
-    // `limit` is a count and is token-blind; max_tokens bounds what this call
-    // actually costs the caller's context. See core/token-budget.ts for why the
-    // top-scored result gets first refusal rather than pure density packing.
-    // Reserve what the rest of the reply will cost, so max_tokens bounds the
-    // WHOLE response and not just the result lines. FOOTER_ALLOWANCE is a
-    // fixed upper bound on the accounting line (measured at ~15-25 tokens; the
-    // unit test asserts it stays under 40).
-    const FOOTER_ALLOWANCE = 40;
-    const reserved = estimateTokens(peerSuffix) + FOOTER_ALLOWANCE;
-    const packed = packRecallByBudget(
-      results, formatRecallResultLine, params.max_tokens, reserved,
-    );
-
-    // A budget too small to admit even the best match must not look like "no
-    // memories found" — that is a different fact and would send the caller off
-    // to read code that AWM could have answered. Say what actually happened so
-    // the fix (raise the budget) is obvious.
-    if (packed.kept === 0 && packed.total > 0) {
-      return {
-        content: [{
-          type: 'text' as const,
-          text: `${packed.total} memories matched, but none fit a ${params.max_tokens}-token budget `
-              + `(smallest result is ~${packed.withheldTokens} tok across ${packed.total}). `
-              + `Raise max_tokens, or use granularity: 'compact' to shrink each result.`
-              + peerSuffix,
-        }],
-      };
-    }
-
-    // 0.14.3: surface the activation event id once, so memory_feedback can join
-    // to this recall. Rendered after the token footer; cheap (one short line).
-    const evId = results[0]?.activationEventId;
-    const evFooter = evId ? `\n[recall_id: ${evId}]` : '';
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: packed.lines.join('\n') + peerSuffix + formatTokenFooter(packed, params.max_tokens) + evFooter,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_feedback',
-  `Report whether a recalled memory was actually useful. This updates the memory's confidence score — useful memories become stronger, useless ones weaken.
-
-Always call this after using a recalled memory so the system learns what's valuable.`,
-  {
-    engram_id: z.string().describe('ID of the memory (from memory_recall results)'),
-    useful: z.boolean().describe('Was this memory actually helpful?'),
-    context: z.string().optional().describe('Brief note on why it was/wasn\'t useful'),
-    recall_id: z.string().optional().describe(
-      'The [recall_id: …] printed at the end of the memory_recall output that returned this memory. '
-      + 'Pass it so the feedback is joined to that recall; omitted, it defaults to the most recent recall in this session.',
-    ),
-  },
-  async (params) => {
-    // 0.14.3: join feedback to the recall that produced it. Explicit recall_id
-    // wins; otherwise fall back to the engine's most recent logged activation —
-    // the common case is "recall, use, feedback" in one turn. Before this the
-    // MCP path hardcoded null (the HTTP route already accepted the id), which
-    // is why every retrieval_feedback row in the live store was orphaned.
-    const eventId = params.recall_id ?? activationEngine.lastActivationEventId ?? null;
-    await store.logRetrievalFeedback(eventId, params.engram_id, params.useful, params.context ?? '');
-
-    const engram = await store.getEngram(params.engram_id);
-    if (engram) {
-      const delta = params.useful
-        ? DEFAULT_AGENT_CONFIG.feedbackPositiveBoost
-        : -DEFAULT_AGENT_CONFIG.feedbackNegativePenalty;
-      await store.updateConfidence(engram.id, engram.confidence + delta);
-    }
-
-    // Validation-gated Hebbian: resolve pending co-activation pairs for this engram
-    const hebbianUpdated = await activationEngine.resolveHebbianFeedback(params.engram_id, params.useful);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Feedback: ${params.useful ? '+useful' : '-not useful'}${hebbianUpdated > 0 ? ` (${hebbianUpdated} association${hebbianUpdated > 1 ? 's' : ''} ${params.useful ? 'strengthened' : 'weakened'})` : ''}`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_retract',
-  `Retract a memory that turned out to be wrong. Creates a correction and reduces confidence of related memories.
-
-Use this when you discover a memory contains incorrect information.`,
-  {
-    engram_id: z.string().describe('ID of the wrong memory'),
-    reason: z.string().describe('Why is this memory wrong?'),
-    correction: z.string().optional().describe('What is the correct information? (creates a new memory)'),
-  },
-  async (params) => {
-    const result = await retractionEngine.retract({
-      agentId: AGENT_ID,
-      targetEngramId: params.engram_id,
-      reason: params.reason,
-      counterContent: params.correction,
-    });
-
-    const parts = [`Memory ${params.engram_id} retracted.`];
-    if (result.correctionId) {
-      parts.push(`Correction stored as ${result.correctionId}.`);
-    }
-    parts.push(`${result.associatesAffected} related memories had confidence reduced.`);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: parts.join(' '),
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_supersede',
-  `Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct.
-
-Use this when:
-- A status or count has changed (e.g., "5 reviews done" → "7 reviews done")
-- Architecture or infrastructure evolved (e.g., "two-repo model" → "three-repo model")
-- A schedule or plan was updated
-
-The old memory stays in the database (searchable for history) but is heavily down-ranked in recall so the current version dominates.`,
-  {
-    old_engram_id: z.string().describe('ID of the outdated memory (from memory_recall results, or memory_write\'s own response if you just wrote it)'),
-    new_engram_id: z.string().describe('ID of the replacement memory'),
-    reason: z.string().optional().describe('Why the old memory is outdated'),
-  },
-  async (params) => {
-    const oldEngram = await store.getEngram(params.old_engram_id);
-    if (!oldEngram) {
-      return { content: [{ type: 'text' as const, text: `Old memory not found: ${params.old_engram_id}` }] };
-    }
-    const newEngram = await store.getEngram(params.new_engram_id);
-    if (!newEngram) {
-      return { content: [{ type: 'text' as const, text: `New memory not found: ${params.new_engram_id}` }] };
-    }
-
-    await store.supersedeEngram(params.old_engram_id, params.new_engram_id);
-
-    // Create supersession association (new → old)
-    await store.upsertAssociation(params.new_engram_id, params.old_engram_id, 0.8, 'causal', 0.9);
-
-    // Reduce old memory's confidence (not to zero — it's historical, not wrong)
-    await store.updateConfidence(params.old_engram_id, Math.max(0.2, oldEngram.confidence * 0.4));
-
-    log(AGENT_ID, 'supersede', `"${oldEngram.concept}" → "${newEngram.concept}"${params.reason ? ` (${params.reason})` : ''}`);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Superseded: "${oldEngram.concept}" → "${newEngram.concept}"`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_whoami',
-  `Identify THIS AWM instance — agent id, mode (standalone/hive), backend, store path, code provenance, ports, and the sibling agent spaces present in the same store. Call when unsure which AWM instance or memory space you are talking to.`,
-  {},
-  async () => {
-    const info = await buildWhoami(store, AGENT_ID, 'mcp', sidecarHandle ? sidecarHandle.boundPort() : undefined);
-    return { content: [{ type: 'text', text: formatWhoami(info) }] };
-  },
-);
-
-server.tool(
-  'memory_stats',
-  `Get memory health stats — how many memories, confidence levels, association count, and system performance.
-Also shows the activity log path so the user can tail it to see what's happening.`,
-  {},
-  async () => {
-    const metrics = await evalEngine.computeMetrics(AGENT_ID);
-    const checkpoint = await store.getCheckpoint(AGENT_ID);
-    // 0.14.3: outcome numbers, not activity counters. "Edge utility" (share of
-    // edges ever activated) was monotone — it could only rise — and read as
-    // health when it was not. Latency was a mean over a column that mixes cold
-    // loads and stalls (live store: mean 20 s, median 1.6 s); medians only now.
-    const usage = await evalEngine.computeUsage(AGENT_ID);
-    const lines = [
-      `Agent: ${AGENT_ID}`,
-      `Active memories: ${metrics.activeEngramCount}`,
-      `Staging: ${metrics.stagingEngramCount}`,
-      `Retracted: ${metrics.retractedCount}`,
-      `Avg confidence: ${metrics.avgConfidence.toFixed(3)}`,
-      `Total edges: ${metrics.totalEdges}`,
-      ``,
-      `Write:recall (30d): 1 : ${usage.recallsPerWrite30d.toFixed(2)}  (${usage.writes30d} writes, ${usage.recalls30d} recalls)`,
-      `Never recalled: ${(usage.neverRecalledShare * 100).toFixed(0)}% of active memories`,
-      `Recall→use (7d): ${usage.feedbackLinked7d > 0 ? (usage.usefulShare7d * 100).toFixed(0) + '% useful of ' + usage.feedbackLinked7d + ' judged' : 'no linked feedback yet'}`,
-      `Activations (24h): ${metrics.activationCount}`,
-      `Recall latency (24h): p50 ${metrics.p50LatencyMs.toFixed(0)}ms  p90 ${metrics.p90LatencyMs.toFixed(0)}ms`,
-      ``,
-      `Session writes: ${checkpoint?.auto.writeCountSinceConsolidation ?? 0}`,
-      `Session recalls: ${checkpoint?.auto.recallCountSinceConsolidation ?? 0}`,
-      `Last activity: ${checkpoint?.auto.lastActivityAt?.toISOString() ?? 'never'}`,
-      `Checkpoint: ${checkpoint?.executionState ? checkpoint.executionState.currentTask : 'none'}`,
-      ``,
-      `Activity log: ${getLogPath() ?? 'not configured'}`,
-      // Report the port actually BOUND, not the one configured. Before 0.14.2
-      // this line said 8401 in every session, including the ones whose sidecar
-      // had lost the port and silently disabled hooks.
-      `Hook sidecar: ${sidecarPortLabel()}`,
-    ];
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: lines.join('\n'),
-      }],
-    };
-  }
-);
-
-// --- Checkpointing Tools ---
-
-server.tool(
-  'memory_checkpoint',
-  `Save your current execution state so you can recover after context compaction.
-
-ALWAYS call this before:
-- Long operations (multi-file generation, large refactors, overnight work)
-- Anything that might fill the context window
-- Switching to a different task
-
-Also call periodically during long sessions to avoid losing state. The state is saved per-agent and overwrites any previous checkpoint.`,
-  {
-    current_task: z.string().describe('What you are currently working on'),
-    decisions: z.array(z.string()).optional().default([])
-      .describe('Key decisions made so far'),
-    active_files: z.array(z.string()).optional().default([])
-      .describe('Files you are currently working with'),
-    next_steps: z.array(z.string()).optional().default([])
-      .describe('What needs to happen next'),
-    related_memory_ids: z.array(z.string()).optional().default([])
-      .describe('IDs of memories relevant to current work'),
-    notes: z.string().optional().default('')
-      .describe('Any other context worth preserving'),
-    episode_id: z.string().optional()
-      .describe('Current episode ID if known'),
-  },
-  async (params) => {
-    const state: ConsciousState = {
-      currentTask: params.current_task,
-      decisions: params.decisions,
-      activeFiles: params.active_files,
-      nextSteps: params.next_steps,
-      relatedMemoryIds: params.related_memory_ids,
-      notes: params.notes,
-      episodeId: params.episode_id ?? null,
-    };
-
-    await store.saveCheckpoint(AGENT_ID, state);
-    log(AGENT_ID, 'checkpoint', `"${params.current_task}" decisions=${params.decisions.length} files=${params.active_files.length}`);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Checkpoint saved: "${params.current_task}" (${params.decisions.length} decisions, ${params.active_files.length} files)`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_restore',
-  `Restore your previous execution state after context compaction or at session start.
-
-Returns:
-- Your saved execution state (task, decisions, next steps, files)
-- Recently recalled memories for context
-- Your last write for continuity
-- How long you were idle
-
-Use this at the start of every session or after compaction to pick up where you left off.`,
-  {},
-  async () => {
-    const checkpoint = await store.getCheckpoint(AGENT_ID);
-
-    // Cold-store nudge: an empty store means the agent has nothing to recall — offer to warm-start.
-    let coldStoreNudge = '';
-    try {
-      const activeCount = (await store.getEngramsByAgent(AGENT_ID)).length;
-      if (activeCount < 3) {
-        coldStoreNudge = `🌱 **This memory store is nearly empty (${activeCount} ${activeCount === 1 ? 'memory' : 'memories'}).** Warm-start it before other work: recall the "onboard a new project" skill and follow it — or call \`onboard_scan\` on this project's docs/repo, refine the results, and save them with \`memory_write\` (canonical). Recall becomes useful immediately.`;
-      }
-    } catch { /* count is best-effort */ }
-
-    const now = Date.now();
-    const idleMs = checkpoint
-      ? now - checkpoint.auto.lastActivityAt.getTime()
-      : 0;
-
-    // Get last written engram
-    let lastWrite: { id: string; concept: string; content: string } | null = null;
-    if (checkpoint?.auto.lastWriteId) {
-      const engram = await store.getEngram(checkpoint.auto.lastWriteId);
-      if (engram) {
-        lastWrite = { id: engram.id, concept: engram.concept, content: engram.content };
-      }
-    }
-
-    // Recall memories using last context
-    let recalledMemories: Array<{ id: string; concept: string; content: string; score: number }> = [];
-    const recallContext = checkpoint?.auto.lastRecallContext
-      ?? checkpoint?.executionState?.currentTask
-      ?? null;
-
-    if (recallContext) {
-      try {
-        const results = await activationEngine.activate({
-          agentId: AGENT_ID,
-          context: recallContext,
-          // 3, not 5 — measured token-positive (+115/recall vs -680) and 41% faster.
-          // The case is stronger here than for explicit recall: this is push-style, so
-          // nobody asked for these results and every one of them costs context the user
-          // did not request.
-          limit: 3,
-          minScore: 0.05,
-          useReranker: true,
-          useExpansion: true,
-          workspace: process.env.AWM_WORKSPACE ?? undefined,
-        });
-        recalledMemories = results.map(r => ({
-          id: r.engram.id,
-          concept: r.engram.concept,
-          content: r.engram.content,
-          score: r.score,
-        }));
-      } catch { /* recall failure is non-fatal */ }
-    }
-
-    // Consolidation on restore:
-    // - If idle >5min but last consolidation was recent (graceful exit ran it), skip
-    // - If idle >5min and no recent consolidation, run full cycle (non-graceful exit fallback)
-    const MINI_IDLE_MS = 5 * 60_000;
-    const FULL_CONSOLIDATION_GAP_MS = 10 * 60_000; // 10 min — if last consolidation was longer ago, run full
-    let miniConsolidationTriggered = false;
-    let fullConsolidationTriggered = false;
-
-    if (idleMs > MINI_IDLE_MS) {
-      const sinceLastConsolidation = checkpoint?.lastConsolidationAt
-        ? now - checkpoint.lastConsolidationAt.getTime()
-        : Infinity;
-
-      if (sinceLastConsolidation > FULL_CONSOLIDATION_GAP_MS) {
-        // No recent consolidation — graceful exit didn't happen, run full cycle
-        fullConsolidationTriggered = true;
-        try {
-          const result = await consolidationEngine.consolidate(AGENT_ID);
-          await store.markConsolidation(AGENT_ID, false);
-          log(AGENT_ID, 'consolidation', `full sleep cycle on restore (no graceful exit, idle ${Math.round(idleMs / 60_000)}min, last consolidation ${Math.round(sinceLastConsolidation / 60_000)}min ago) — ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
-        } catch { /* consolidation failure is non-fatal */ }
-      } else {
-        // Recent consolidation exists — graceful exit already handled it, just do mini
-        miniConsolidationTriggered = true;
-        consolidationScheduler.runMiniConsolidation(AGENT_ID).catch(() => {});
-      }
-    }
-
-    // Format response
-    const parts: string[] = [];
-    const idleMin = Math.round(idleMs / 60_000);
-    const consolidationNote = fullConsolidationTriggered
-      ? ' (full consolidation — no graceful exit detected)'
-      : miniConsolidationTriggered
-        ? ' (mini-consolidation triggered)'
-        : '';
-    log(AGENT_ID, 'restore', `idle=${idleMin}min checkpoint=${!!checkpoint?.executionState} recalled=${recalledMemories.length} lastWrite=${lastWrite?.concept ?? 'none'}${fullConsolidationTriggered ? ' FULL_CONSOLIDATION' : ''}`);
-    parts.push(`Idle: ${idleMin}min${consolidationNote}`);
-    if (coldStoreNudge) parts.push(`\n${coldStoreNudge}`);
-
-    if (checkpoint?.executionState) {
-      const s = checkpoint.executionState;
-      parts.push(`\n**Current task:** ${s.currentTask}`);
-      if (s.decisions.length) parts.push(`**Decisions:** ${s.decisions.join('; ')}`);
-      if (s.nextSteps.length) parts.push(`**Next steps:** ${s.nextSteps.map((st, i) => `${i + 1}. ${st}`).join(', ')}`);
-      if (s.activeFiles.length) parts.push(`**Active files:** ${s.activeFiles.join(', ')}`);
-      if (s.notes) parts.push(`**Notes:** ${s.notes}`);
-      if (checkpoint.checkpointAt) parts.push(`_Saved at: ${checkpoint.checkpointAt.toISOString()}_`);
-    } else {
-      parts.push('\nNo explicit checkpoint saved.');
-      parts.push('\n**Tip:** Use memory_write to save important learnings, and memory_checkpoint before long operations so you can recover state.');
-    }
-
-    if (lastWrite) {
-      parts.push(`\n**Last write:** ${lastWrite.concept}\n${lastWrite.content}`);
-    }
-
-    if (recalledMemories.length > 0) {
-      parts.push(`\n**Recalled memories (${recalledMemories.length}):**`);
-      for (const m of recalledMemories) {
-        parts.push(`- **${m.concept}** (${m.score.toFixed(3)}): ${m.content.slice(0, 150)}${m.content.length > 150 ? '...' : ''}`);
-      }
-    }
-
-    // Peer decisions: show recent decisions from other agents (last 30 min)
-    if (coordDb) {
-      try {
-        const myAgent = coordDb.prepare(
-          `SELECT id FROM coord_agents WHERE name = ? AND status != 'dead' ORDER BY last_seen DESC LIMIT 1`
-        ).get(AGENT_ID) as { id: string } | undefined;
-
-        const peerDecisions = coordDb.prepare(
-          `SELECT d.summary, a.name AS author_name, d.created_at
-           FROM coord_decisions d JOIN coord_agents a ON d.author_id = a.id
-           WHERE d.author_id != ? AND d.created_at > datetime('now', '-30 minutes')
-           ORDER BY d.created_at DESC LIMIT 10`
-        ).all(myAgent?.id ?? '') as Array<{ summary: string; author_name: string; created_at: string }>;
-
-        if (peerDecisions.length > 0) {
-          parts.push(`\n**Peer decisions (last 30 min):**`);
-          for (const d of peerDecisions) {
-            parts.push(`- [${d.author_name}] ${d.summary} (${d.created_at})`);
-          }
-        }
-      } catch { /* peer decisions are non-fatal */ }
-    }
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: parts.join('\n'),
-      }],
-    };
-  }
-);
-
-// --- Onboarding Tools (warm-start a cold store) ---
-
-server.tool(
-  'onboard_scan',
-  `Scan a project's documentation + repository and return CANDIDATE memories to seed a cold store.
-
-Use this when the store is empty / you're new to a project. The scan is deterministic
-(real file contents, not guesses) — YOUR job is to refine the candidates into atomic,
-recall-shaped memories, run the interview (onboard_questions), confirm with the user, then
-save the good ones with memory_write (memory_class="canonical"). Nothing is saved by this tool.`,
-  {
-    docs: z.array(z.string()).optional()
-      .describe('Doc files/dirs to scan (Markdown/text). Defaults to the repo (or cwd).'),
-    repo: z.string().optional()
-      .describe('Repo root — also derives stack (package.json) + layout memories.'),
-    project: z.string().optional()
-      .describe('Project name (becomes a tag). Defaults to the repo/dir name.'),
-    purpose: z.string().optional()
-      .describe('The goal of this memory system, if known — becomes the anchor memory.'),
-  },
-  async (params) => {
-    const repo = params.repo;
-    const docs = params.docs && params.docs.length ? params.docs : [repo ?? process.cwd()];
-    const project = params.project ?? basename(resolve(repo ?? docs[0] ?? process.cwd()));
-    const pack = buildPack({ docs, repo, project, agentId: AGENT_ID, purpose: params.purpose });
-    log(AGENT_ID, 'onboard', `scan ${docs.join(',')}${repo ? ' +repo' : ''} → ${pack.memories.length} candidates`);
-    const text = [
-      `Scanned ${docs.join(', ')}${repo ? ` (+repo ${repo})` : ''} → ${pack.memories.length} CANDIDATE memories (NOT saved).`,
-      `Next: refine each into an atomic memory (lead with the fact + identifiers), run onboard_questions,`,
-      `confirm with the user, then save the good ones with memory_write (memory_class="canonical").`,
-      ``,
-      JSON.stringify({ project, candidates: pack.memories, questions: pack.questions }, null, 2),
-    ].join('\n');
-    return { content: [{ type: 'text' as const, text }] };
-  }
-);
-
-server.tool(
-  'onboard_questions',
-  `Return the onboarding interview questions. Ask the user ONE at a time, starting with the
-goal of the memory system, and ask follow-ups for clarity. Turn each answer into a canonical memory.`,
-  {},
-  async () => ({
-    content: [{ type: 'text' as const, text: INTERVIEW_QUESTIONS.map((q, i) => `${i + 1}. ${q}`).join('\n') }],
-  })
-);
-
-// --- Task Management Tools ---
-
-server.tool(
-  'memory_task_add',
-  `Create a task that you need to come back to. Tasks are memories with status and priority tracking.
-
-Use this when:
-- You identify work that needs doing but can't do it right now
-- The user mentions something to do later
-- You want to park a sub-task while focusing on something more urgent
-
-Tasks automatically get high salience so they won't be discarded.`,
-  {
-    concept: z.string().describe('Short task title (3-10 words)'),
-    content: z.string().describe('Full task description — what needs doing, context, acceptance criteria'),
-    tags: z.array(z.string()).optional().describe('Tags for categorization'),
-    priority: z.enum(['urgent', 'high', 'medium', 'low']).default('medium')
-      .describe('Task priority: urgent (do now), high (do soon), medium (normal), low (backlog)'),
-    blocked_by: z.string().optional().describe('ID of a task that must finish first'),
-  },
-  async (params) => {
-    const engram = await store.createEngram({
-      agentId: AGENT_ID,
-      concept: params.concept,
-      content: params.content,
-      tags: [...(params.tags ?? []), 'task'],
-      salience: 0.9, // Tasks always high salience
-      confidence: 0.8,
-      salienceFeatures: {
-        surprise: 0.5,
-        decisionMade: true,
-        causalDepth: 0.5,
-        resolutionEffort: 0.5,
-        eventType: 'decision',
-      },
-      reasonCodes: ['task-created'],
-      taskStatus: params.blocked_by ? 'blocked' : 'open',
-      taskPriority: params.priority as TaskPriority,
-      blockedBy: params.blocked_by,
-    });
-
-    connectionEngine.enqueue(engram.id);
-
-    // Generate embedding asynchronously
-    embed(`${params.concept} ${params.content}`).then(async vec => {
-      await store.updateEmbedding(engram.id, vec);
-    }).catch(() => {});
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Task created: "${params.concept}" (${params.priority})`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_task_update',
-  `Update a task's status or priority. Use this to:
-- Start working on a task (open → in_progress)
-- Mark a task done (→ done)
-- Block a task on another (→ blocked)
-- Reprioritize (change priority)
-- Unblock a task (clear blocked_by)`,
-  {
-    task_id: z.string().describe('ID of the task to update'),
-    status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
-      .describe('New status'),
-    priority: z.enum(['urgent', 'high', 'medium', 'low']).optional()
-      .describe('New priority'),
-    blocked_by: z.string().optional().describe('ID of blocking task (set to empty string to unblock)'),
-  },
-  async (params) => {
-    const engram = await store.getEngram(params.task_id);
-    if (!engram || !engram.taskStatus) {
-      return { content: [{ type: 'text' as const, text: `Task not found: ${params.task_id}` }] };
-    }
-
-    if (params.blocked_by !== undefined) {
-      await store.updateBlockedBy(params.task_id, params.blocked_by || null);
-    }
-    if (params.status) {
-      await store.updateTaskStatus(params.task_id, params.status as TaskStatus);
-    }
-    if (params.priority) {
-      await store.updateTaskPriority(params.task_id, params.priority as TaskPriority);
-    }
-
-    const updated = (await store.getEngram(params.task_id))!;
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Updated: "${updated.concept}" → ${updated.taskStatus} (${updated.taskPriority})`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_task_list',
-  `List tasks with optional status filter. Shows tasks ordered by priority (urgent first).
-
-Use at the start of a session to see what's pending, or to check blocked/done tasks.`,
-  {
-    status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
-      .describe('Filter by status (omit to see all active tasks)'),
-    include_done: z.boolean().optional().default(false)
-      .describe('Include completed tasks?'),
-  },
-  async (params) => {
-    let tasks = await store.getTasks(AGENT_ID, params.status as TaskStatus | undefined);
-    if (!params.include_done && !params.status) {
-      tasks = tasks.filter(t => t.taskStatus !== 'done');
-    }
-
-    if (tasks.length === 0) {
-      return { content: [{ type: 'text' as const, text: 'No tasks found.' }] };
-    }
-
-    const lines = tasks.map((t, i) => {
-      const blocked = t.blockedBy ? ` [blocked by ${t.blockedBy}]` : '';
-      const tags = t.tags?.filter(tag => tag !== 'task').join(', ');
-      return `${i + 1}. [${t.taskStatus}] **${t.concept}** (${t.taskPriority})${blocked}\n   ${t.content.slice(0, 120)}${t.content.length > 120 ? '...' : ''}\n   ${tags ? `Tags: ${tags} | ` : ''}ID: ${t.id}`;
-    });
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Tasks (${tasks.length}):\n\n${lines.join('\n\n')}`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_task_next',
-  `Get the single most important task to work on next.
-
-Prioritizes: in_progress tasks first (finish what you started), then by priority level, then oldest first. Skips blocked and done tasks.
-
-Use this when you finish a task or need to decide what to do next.`,
-  {},
-  async () => {
-    const next = await store.getNextTask(AGENT_ID);
-    if (!next) {
-      return { content: [{ type: 'text' as const, text: 'No actionable tasks. All clear!' }] };
-    }
-
-    const blocked = next.blockedBy ? `\nBlocked by: ${next.blockedBy}` : '';
-    const tags = next.tags?.filter(tag => tag !== 'task').join(', ');
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Next task:\n**${next.concept}** (${next.taskPriority})\nStatus: ${next.taskStatus}\n${next.content}${blocked}\n${tags ? `Tags: ${tags}\n` : ''}ID: ${next.id}`,
-      }],
-    };
-  }
-);
-
-// --- Task Bracket Tools ---
-
-server.tool(
-  'memory_task_begin',
-  `Signal that you're starting a significant task. Auto-checkpoints current state and recalls relevant memories.
-
-CALL THIS when starting:
-- A multi-step operation (doc generation, large refactor, migration)
-- Work on a new topic or project area
-- Anything that might fill the context window
-
-This ensures your state is saved before you start, and primes recall with relevant context.`,
-  {
-    topic: z.string().describe('What task are you starting? (3-15 words)'),
-    files: z.array(z.string()).optional().default([])
-      .describe('Files you expect to work with'),
-    notes: z.string().optional().default('')
-      .describe('Any additional context'),
-  },
-  async (params) => {
-    // 1. Checkpoint current state
-    const checkpoint = await store.getCheckpoint(AGENT_ID);
-    const prevTask = checkpoint?.executionState?.currentTask ?? 'None';
-
-    await store.saveCheckpoint(AGENT_ID, {
-      currentTask: params.topic,
-      decisions: [],
-      activeFiles: params.files,
-      nextSteps: [],
-      relatedMemoryIds: [],
-      notes: params.notes || `Started via memory_task_begin. Previous task: ${prevTask}`,
-      episodeId: null,
-    });
-
-    // 2. Auto-recall relevant memories
-    let recalledSummary = '';
-    try {
-      const results = await activationEngine.activate({
-        agentId: AGENT_ID,
-        context: params.topic,
-        // 3, not 5 — see memory_recall. Push-style auto-recall on task start.
-        limit: 3,
-        minScore: 0.05,
-        useReranker: true,
-        useExpansion: true,
-        workspace: process.env.AWM_WORKSPACE ?? undefined,
-      });
-
-      if (results.length > 0) {
-        const lines = results.map((r, i) => {
-          const tags = r.engram.tags?.length ? ` [${r.engram.tags.join(', ')}]` : '';
-          return `${i + 1}. **${r.engram.concept}** (${r.score.toFixed(3)})${tags}\n   ${r.engram.content.slice(0, 150)}${r.engram.content.length > 150 ? '...' : ''}`;
-        });
-        recalledSummary = `\n\n**Recalled memories (${results.length}):**\n${lines.join('\n')}`;
-
-        // Track recall
-        await store.updateAutoCheckpointRecall(AGENT_ID, params.topic, results.map(r => r.engram.id));
-      }
-    } catch { /* recall failure is non-fatal */ }
-
-    log(AGENT_ID, 'task:begin', `"${params.topic}" prev="${prevTask}"`);
-
-    return {
-      content: [{
-        type: 'text' as const,
-        text: `Started: "${params.topic}" (prev: ${prevTask})${recalledSummary}`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'memory_task_end',
-  `Signal that you've finished a significant task. Writes a summary memory and auto-checkpoints.
-
-CALL THIS when you finish:
-- A multi-step operation
-- Before switching to a different topic
-- At the end of a work session
-
-This captures what was accomplished so future sessions can recall it.`,
-  {
-    summary: z.string().describe('What was accomplished? Include key outcomes, decisions, and any issues.'),
-    tags: z.array(z.string()).optional().default([])
-      .describe('Tags for the summary memory'),
-    supersedes: z.array(z.string()).optional().default([])
-      .describe('IDs of older memories this task summary replaces (marks them as superseded)'),
-  },
-  async (params) => {
-    // 1. Write summary as a memory
-    const salience = evaluateSalience({
-      content: params.summary,
-      eventType: 'decision',
-      surprise: 0.3,
-      decisionMade: true,
-      causalDepth: 0.5,
-      resolutionEffort: 0.5,
-    });
-
-    // Determine the real task name for the summary engram
-    const checkpoint = await store.getCheckpoint(AGENT_ID);
-    const rawTask = checkpoint?.executionState?.currentTask ?? 'Unknown task';
-    // Strip any "Completed: " prefixes to avoid cascading
-    const cleanedTask = rawTask.replace(/^(Completed: )+/, '');
-    // Don't use auto-checkpoint or already-completed tasks as real task names
-    const isNamedTask = !cleanedTask.startsWith('Auto-checkpoint') && cleanedTask !== 'Unknown task';
-    const completedTask = isNamedTask
-      ? cleanedTask
-      : params.summary.slice(0, 60).replace(/\n/g, ' ');
-
-    const engram = await store.createEngram({
-      agentId: AGENT_ID,
-      concept: completedTask.slice(0, 80),
-      content: params.summary,
-      tags: [...params.tags, 'task-summary'],
-      salience: isNamedTask ? Math.max(salience.score, 0.7) : salience.score, // Only floor salience for named tasks
-      confidence: 0.65, // Task summaries are decision-grade (completed work)
-      salienceFeatures: salience.features,
-      reasonCodes: [...salience.reasonCodes, 'task-end'],
-    });
-
-    connectionEngine.enqueue(engram.id);
-
-    // 2. Handle supersessions — mark old memories as outdated
-    let supersededCount = 0;
-    for (const oldId of params.supersedes) {
-      const oldEngram = await store.getEngram(oldId);
-      if (oldEngram) {
-        await store.supersedeEngram(oldId, engram.id);
-        await store.upsertAssociation(engram.id, oldId, 0.8, 'causal', 0.9);
-        await store.updateConfidence(oldId, Math.max(0.2, oldEngram.confidence * 0.4));
-        supersededCount++;
-      }
-    }
-
-    // Generate embedding asynchronously
-    embed(`Task completed: ${params.summary}`).then(async vec => {
-      await store.updateEmbedding(engram.id, vec);
-    }).catch(() => {});
-
-    // 2. Update checkpoint to reflect completion
-    await store.saveCheckpoint(AGENT_ID, {
-      currentTask: `Completed: ${completedTask}`,
-      decisions: checkpoint?.executionState?.decisions ?? [],
-      activeFiles: [],
-      nextSteps: [],
-      relatedMemoryIds: [engram.id],
-      notes: `Task completed. Summary memory: ${engram.id}`,
-      episodeId: null,
-    });
-
-    await store.updateAutoCheckpointWrite(AGENT_ID, engram.id);
-    log(AGENT_ID, 'task:end', `"${completedTask}" summary=${engram.id} salience=${salience.score.toFixed(2)} superseded=${supersededCount}`);
-
-    const supersededNote = supersededCount > 0 ? ` (${supersededCount} old memories superseded)` : '';
-    return {
-      content: [{
-        type: 'text' as const,
-        // D14 (2026-07-30): task end is the recipe moment — invite the host
-        // to distill a skill and/or a failure lesson in separate focused
-        // passes. The host owns the gates; AWM validates the write-backs.
-        text: `Completed: "${completedTask}" [${salience.score.toFixed(2)}]${supersededNote}\n${renderTaskEndInvitation()}`,
-      }],
-    };
-  }
-);
-
-server.tool(
-  'compress_output',
-  `Compress a STRUCTURED tool output (JSON object/array, query rows, log records) into TOON —
-a compact, schema-aware tabular encoding — before putting it in your context. Cuts ~50-65%
-of the tokens on uniform arrays at zero comprehension cost (validated: models read TOON as
-accurately as JSON). Use this on large tool results you need to keep in context.
-
-Output-only and safe: it never changes the data. Non-JSON / prose is returned unchanged.
-TOON is only emitted when it reproduces the input exactly (self-verified round-trip);
-otherwise you get plain JSON back. When compressed, you also get a 'ref' — call
-retrieve_original(ref) to get the verbatim source back if you ever need it.`,
-  {
-    output: z.string().describe('The tool output to compress — JSON text (preferred) or any string. Non-JSON is returned unchanged.'),
-    min_saving_chars: z.number().optional().describe('Only emit TOON if it saves at least this many characters (default 40).'),
-  },
-  async (params) => {
-    const r = liteCompress(params.output, { minSavingChars: params.min_saving_chars });
-    log(AGENT_ID, 'compress', `${r.format} ${r.charsBefore}->${r.charsAfter} chars (${(r.ratio * 100).toFixed(0)}%)${r.ref ? ` ref=${r.ref}` : ''}`);
-    const header = r.format === 'toon'
-      ? `[TOON, ${(r.ratio * 100).toFixed(0)}% smaller — compact lossless JSON; read as data, ref=${r.ref}]\n`
-      : '';
-    return {
-      content: [{ type: 'text' as const, text: header + r.text }],
-    };
-  }
-);
-
-server.tool(
-  'retrieve_original',
-  `Retrieve the verbatim original text for a 'ref' returned by compress_output. Use this when
-you need the exact, uncompressed source (e.g. to pass it to another tool unchanged). Returns
-an error if the ref has expired (originals are kept for the most recent compressions only).`,
-  {
-    ref: z.string().describe('The ref handle returned by compress_output (e.g. "awm_orig_12").'),
-  },
-  async (params) => {
-    const original = retrieveOriginal(params.ref);
-    if (original === undefined) {
-      return {
-        content: [{ type: 'text' as const, text: `Error: ref "${params.ref}" not found or expired.` }],
-      };
-    }
-    return {
-      content: [{ type: 'text' as const, text: original }],
-    };
-  }
-);
-
-// --- Start ---
-
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-
-  // Start hook sidecar (lightweight HTTP for Claude Code hooks)
-  const sidecar = startSidecar({
-    store,
-    agentId: AGENT_ID,
-    secret: HOOK_SECRET,
-    port: HOOK_PORT,
-    portRange: HOOK_PORT_RANGE,
-    version: VERSION,
-    // 0.12.2: warm recall for hooks — the sidecar shares this process's
-    // activation engine and loaded models, so a UserPromptSubmit hook can get
-    // warm-latency recall without any standing server. Trimmed result shape
-    // (no embeddings/phase scores — hooks don't need them and the vectors
-    // alone would 10x the payload).
-    activate: async (q) => {
-      const results = await activationEngine.activate({
-        agentId: AGENT_ID,
-        context: q.context,
-        limit: q.limit,
-        requireConfidence: q.requireConfidence,
-        granularity: q.granularity,
-      });
-      return results.map(r => ({
-        engram: {
-          id: r.engram.id,
-          concept: r.engram.concept,
-          content: r.engram.content,
-          createdAt: r.engram.createdAt instanceof Date
-            ? r.engram.createdAt.toISOString()
-            : (r.engram.createdAt as unknown as string | undefined),
-          memoryClass: r.engram.memoryClass,
-          validTo: r.engram.validTo,
-        },
-        score: r.score,
-        summary: r.summary,
-        confidence: r.confidence,
-      }));
-    },
-    onConsolidate: async (agentId, reason) => {
-      console.error(`[mcp] consolidation triggered: ${reason}`);
-      const result = await consolidationEngine.consolidate(agentId);
-      await store.markConsolidation(agentId, false);
-      console.error(`[mcp] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
-    },
-  });
-
-  // 0.12.2: eager warm — fire-and-forget, mirrors index.ts:208-218. Without
-  // this, every Claude Code session paid the full cold cost (~3s measured on
-  // a 29.7k-engram store: slim cache ~0.9s + three model loads ~1.8s) on its
-  // FIRST recall, which is exactly the "first recall is slow → recall gets
-  // avoided" failure mode. Warming here overlaps session startup instead.
-  // All output is stderr-safe (stdout carries JSON-RPC frames).
-  // Escape hatch: AWM_NO_EAGER_WARM=1 restores lazy loading.
-  if (process.env.AWM_NO_EAGER_WARM !== '1') {
-    getEmbedder().catch(err => console.error('Embedding model unavailable:', err.message));
-    getReranker().catch(err => console.error('Reranker model unavailable:', err.message));
-    getExpander().catch(err => console.error('Query expander model unavailable:', err.message));
-    if (BACKEND === 'sqlite') {
-      setImmediate(() => {
-        try {
-          const t0 = Date.now();
-          (store as unknown as EngramStore).warmSlimCache();
-          const stats = (store as unknown as EngramStore).getSlimCacheStats();
-          console.error(`Slim cache warmed: ${stats.size} entries in ${Date.now() - t0}ms`);
-        } catch (err) {
-          console.error(`Slim cache warm failed: ${(err as Error).message}`);
-        }
-      });
-    }
-  }
-
-  // Coordination MCP tools (opt-in via AWM_COORDINATION=true)
-  // AWM 0.8.x: coordination requires SQLite (uses store.getDb()). On PGlite,
-  // coordination is auto-disabled with a warning; re-enable when coordination
-  // is ported to async/PGlite.
-  const coordRequested = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
-  const coordEnabled = coordRequested && BACKEND === 'sqlite';
-  if (coordEnabled) {
-    const { initCoordinationTables } = await import('./coordination/schema.js');
-    const { registerCoordinationTools } = await import('./coordination/mcp-tools.js');
-    const sqliteStore = store as unknown as EngramStore;
-    initCoordinationTables(sqliteStore.getDb());
-    registerCoordinationTools(server, sqliteStore.getDb());
-    coordDb = sqliteStore.getDb();
-  } else if (coordRequested && BACKEND === 'pglite') {
-    console.error('AWM: coordination requested but disabled — coordination plugin requires SQLite backend');
-  } else {
-    console.error('AWM: coordination tools disabled (set AWM_COORDINATION=true to enable)');
-  }
-
-  // Log to stderr (stdout is reserved for MCP protocol)
-  console.error(`AgentWorkingMemory MCP server started (agent: ${AGENT_ID}, db: ${DB_PATH})`);
-  sidecarHandle = sidecar;
-  console.error(`Hook sidecar preferred 127.0.0.1:${HOOK_PORT} (range ${HOOK_PORT_RANGE})${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
-
-  // Clean shutdown
-  const cleanup = async () => {
-    sidecar.close();
-    consolidationScheduler.stop();
-    stagingBuffer.stop();
-    if (BACKEND === 'sqlite') {
-      try { (store as Partial<EngramStore>).walCheckpoint?.(); } catch { /* non-fatal */ }
-    }
-    try { await (store as any).close?.(); } catch { /* best-effort */ }
-  };
-  process.on('SIGINT', () => { void cleanup().finally(() => process.exit(0)); });
-  process.on('SIGTERM', () => { void cleanup().finally(() => process.exit(0)); });
-}
-
-main().catch(err => {
-  console.error('MCP server failed:', err);
-  process.exit(1);
-});
-
-} // end else (non-incognito)
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * MCP Server — Model Context Protocol interface for AgentWorkingMemory.
+ *
+ * Runs as a stdio-based MCP server that Claude Code connects to directly.
+ * Uses the storage and engine layers in-process (no HTTP overhead).
+ *
+ * Tools exposed (19):
+ *   memory_write       — store a memory (salience filter decides disposition)
+ *   memory_recall      — activate memories by context (cognitive retrieval)
+ *   memory_feedback    — report whether a recalled memory was useful
+ *   memory_retract     — invalidate a wrong memory with optional correction
+ *   memory_supersede   — replace an outdated memory with a current one
+ *   memory_stats       — get memory health metrics
+ *   memory_whoami      — identify this instance, mode, store, and sibling agent spaces
+ *   memory_checkpoint  — save structured execution state (survives compaction)
+ *   memory_restore     — restore state + targeted recall after compaction
+ *   memory_task_add    — create a prioritized task
+ *   memory_task_update — change task status, priority, or blocking
+ *   memory_task_list   — list tasks filtered by status
+ *   memory_task_next   — get the highest-priority actionable task
+ *   memory_task_begin  — start a task (auto-checkpoint + recall)
+ *   memory_task_end    — end a task (write summary + checkpoint)
+ *   compress_output    — encode structured tool output as TOON (token-efficient, lossless)
+ *   retrieve_original  — get the verbatim source for a compress_output ref
+ *
+ * Run: npx tsx src/mcp.ts
+ * Config: add to ~/.claude.json or .mcp.json
+ */
+
+import { readFileSync } from 'node:fs';
+import { deriveAgentFromDir as deriveAgentFromDirShared } from './core/agent-id.js';
+import { resolve, basename } from 'node:path';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// Load .env file if present (no external dependency)
+try {
+  const envPath = resolve(process.cwd(), '.env');
+  const envContent = readFileSync(envPath, 'utf-8');
+  for (const line of envContent.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (!process.env[key]) process.env[key] = val;
+  }
+} catch { /* No .env file */ }
+
+// MCP uses stdout for JSON-RPC. Redirect console.log to stderr so engine
+// startup messages (ConsolidationScheduler, model loading, etc.) don't
+// corrupt the transport. This MUST happen before any engine imports.
+console.log = console.error;
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { EngramStore } from './storage/sqlite.js';
+import { openStore, getConfiguredBackend, type StoreBackend } from './storage/factory.js';
+import type { IEngramStore } from './storage/store.js';
+import { ActivationEngine } from './engine/activation.js';
+import { ConnectionEngine } from './engine/connections.js';
+import { StagingBuffer } from './engine/staging.js';
+import { EvictionEngine } from './engine/eviction.js';
+import { RetractionEngine } from './engine/retraction.js';
+import { EvalEngine } from './engine/eval.js';
+import { ConsolidationEngine } from './engine/consolidation.js';
+import { ConsolidationScheduler } from './engine/consolidation-scheduler.js';
+import { evaluateSalience, computeNovelty, computeNoveltyWithMatch } from './core/salience.js';
+import { performWrite } from './core/write-pipeline.js';
+import type { ConsciousState } from './types/checkpoint.js';
+import type { SalienceEventType } from './core/salience.js';
+import type { TaskStatus, TaskPriority, AbstentionInfo } from './types/engram.js';
+import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
+import { embed, getEmbedder } from './core/embeddings.js';
+import { getReranker } from './core/reranker.js';
+import { getExpander } from './core/query-expander.js';
+import { warmModelDaemon } from './core/ml-worker.js';
+import { isModelDaemonEnabled } from './core/model-daemon.js';
+import { startSidecar } from './hooks/sidecar.js';
+import { initLogger, log, getLogPath } from './core/logger.js';
+import { VERSION } from './version.js';
+import { buildPack, INTERVIEW_QUESTIONS } from './onboard/index.js';
+import { liteCompress, retrieveOriginal } from './core/lite-compress.js';
+import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-decisions.js';
+import { startLoopLagMonitor } from './core/write-telemetry.js';
+import { buildWhoami, formatWhoami } from './core/whoami.js';
+import { renderTaskEndInvitation, validateRecipeWrite, recipeSlug, getRecipe } from './recipes/index.js';
+import { formatRecallResultLine } from './core/format-recall.js';
+import { newestConflicting } from './core/conflicts.js';
+import { missingValueNote } from './core/asked-value.js';
+import { packRecallByBudget, formatTokenFooter, estimateTokens } from './core/token-budget.js';
+
+// --- Incognito Mode ---
+// When AWM_INCOGNITO=1, register zero tools. Claude won't see memory tools at all.
+// No DB, no engines, no sidecar — just a bare MCP server that exposes nothing.
+
+const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO === 'true';
+
+if (INCOGNITO) {
+  console.error('AWM: incognito mode — all memory tools disabled, nothing will be recorded');
+  const server = new McpServer({ name: 'agent-working-memory', version: VERSION });
+  const transport = new StdioServerTransport();
+  server.connect(transport).catch(err => {
+    console.error('MCP server failed:', err);
+    process.exit(1);
+  });
+  // No tools registered — Claude won't see any memory_* tools
+} else {
+
+// --- Setup ---
+
+const BACKEND: StoreBackend = getConfiguredBackend();
+const DB_PATH = process.env.AWM_DB_PATH ?? (BACKEND === 'pglite' ? 'memory-pglite' : 'memory.db');
+
+// Fallback agent selection when AWM_AGENT_ID/WORKER_NAME are unset: derive from
+// the project directory (core/agent-id.ts — one definition shared with `awm setup`
+// and mirrored in the shipped hook scripts, so the server, the installer and the
+// hooks always name the same pool for a given directory).
+const deriveAgentFromDir = () => deriveAgentFromDirShared(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? deriveAgentFromDir();
+const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
+// 0.14.2: ports to try upward from HOOK_PORT when it is busy (see sidecar.ts).
+const HOOK_PORT_RANGE = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE ?? '10', 10) || 10);
+// Set once the sidecar starts; whoami reads the bound port from it.
+let sidecarHandle: { boundPort: () => number | null } | null = null;
+function sidecarPortLabel(): string {
+  const p = sidecarHandle?.boundPort() ?? null;
+  if (p === null) return `not bound (preferred ${HOOK_PORT}; hooks disabled)`;
+  return p === HOOK_PORT ? `127.0.0.1:${p}` : `127.0.0.1:${p} (preferred ${HOOK_PORT} was busy)`;
+}
+const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
+
+initLogger(DB_PATH);
+log(AGENT_ID, 'startup', `MCP server starting (backend: ${BACKEND}, db: ${DB_PATH}, hooks: ${HOOK_PORT})`);
+
+// AWM 0.8.x: openStore() returns either SQLite (sync) or PGlite (async) store.
+// Engines accept either via IEngramStore (MaybePromise<T> contract).
+const { store: storeAny } = await openStore();
+// Engines accept the async contract; SQLite-only call sites must guard on BACKEND.
+const store = storeAny as unknown as IEngramStore & Partial<EngramStore>;
+const activationEngine = new ActivationEngine(store);
+const connectionEngine = new ConnectionEngine(store, activationEngine);
+const stagingBuffer = new StagingBuffer(store, activationEngine);
+const evictionEngine = new EvictionEngine(store);
+const retractionEngine = new RetractionEngine(store);
+const evalEngine = new EvalEngine(store);
+const consolidationEngine = new ConsolidationEngine(store, connectionEngine);
+const consolidationScheduler = new ConsolidationScheduler(store, consolidationEngine);
+
+stagingBuffer.start(DEFAULT_AGENT_CONFIG.stagingTtlMs);
+consolidationScheduler.start();
+startLoopLagMonitor();
+
+// Coordination DB handle — set when AWM_COORDINATION=true, used by memory_write for decision propagation
+let coordDb: import('better-sqlite3').Database | null = null;
+
+const server = new McpServer({
+  name: 'agent-working-memory',
+  version: VERSION,
+});
+
+server.registerResource(
+  'awm-overview',
+  'awm://server/overview',
+  {
+    title: 'AWM Overview',
+    description: 'AgentWorkingMemory MCP server metadata and discovery notes',
+    mimeType: 'text/markdown',
+  },
+  async () => ({
+    contents: [{
+      uri: 'awm://server/overview',
+      text: [
+        '# Agent Working Memory',
+        '',
+        `Agent: ${AGENT_ID}`,
+        `DB: ${DB_PATH}`,
+        `Coordination: ${process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1' ? 'enabled' : 'disabled'}`,
+        '',
+        'This MCP server primarily exposes tools such as `memory_restore`, `memory_recall`, `memory_write`, and task/checkpoint operations.',
+        'The resources below exist so generic MCP clients can discover the server through `resources/list` and `resources/templates/list`.',
+      ].join('\n'),
+      mimeType: 'text/markdown',
+    }],
+  })
+);
+
+server.registerResource(
+  'awm-memory-template',
+  new ResourceTemplate('awm://memory/{id}', { list: undefined }),
+  {
+    title: 'AWM Memory By ID',
+    description: 'Metadata resource template for a memory identifier',
+    mimeType: 'text/markdown',
+  },
+  async (_uri, variables) => ({
+    contents: [{
+      uri: `awm://memory/${variables.id ?? ''}`,
+      text: [
+        '# AWM Memory Reference',
+        '',
+        `Requested memory id: ${variables.id ?? ''}`,
+        '',
+        'Use the AWM memory tools for actual retrieval and mutation:',
+        '- `memory_recall` for cognitive retrieval',
+        '- `memory_restore` for session state',
+        '- `memory_feedback`, `memory_retract`, `memory_supersede` for memory maintenance',
+      ].join('\n'),
+      mimeType: 'text/markdown',
+    }],
+  })
+);
+
+// --- Auto-classification for memory types ---
+
+function classifyMemoryType(content: string): 'episodic' | 'semantic' | 'procedural' | 'unclassified' {
+  const lower = content.toLowerCase();
+  // Procedural: how-to, steps, numbered lists
+  if (/\bhow to\b|\bsteps?:/i.test(content) || /^\s*\d+[\.\)]\s/m.test(content) || /\bthen run\b|\bfirst,?\s/i.test(content)) {
+    return 'procedural';
+  }
+  // Episodic: past tense events, incidents, specific time references
+  if (/\b(discovered|debugged|fixed|encountered|happened|resolved|found that|we did|i did|yesterday|last week|today)\b/i.test(content)) {
+    return 'episodic';
+  }
+  // Semantic: facts, decisions, rules, patterns
+  if (/\b(is|are|should|always|never|must|uses?|requires?|means|pattern|decision|rule|convention)\b/i.test(content) && content.length < 500) {
+    return 'semantic';
+  }
+  return 'unclassified';
+}
+
+// --- Tools ---
+
+server.tool(
+  'memory_write',
+  `Store a memory. The salience filter decides whether it's worth keeping (active), needs more evidence (staging), or should be discarded.
+
+CALL THIS PROACTIVELY — do not wait to be asked. Write memories when you:
+- Discover something about the codebase, bugs, or architecture
+- Make a decision and want to remember why
+- Encounter and resolve an error
+- Learn a user preference or project pattern
+- Complete a significant piece of work
+
+The concept should be a short label (3-8 words). The content should be the full detail.`,
+  {
+    concept: z.string().describe('Short label for this memory (3-8 words)'),
+    content: z.string().describe('Full detail of what was learned'),
+    tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
+    event_type: z.enum(['observation', 'decision', 'friction', 'surprise', 'causal'])
+      .optional().default('observation')
+      .describe('Type of event: observation (default), decision, friction (error/blocker), surprise, causal (root cause)'),
+    surprise: z.number().min(0).max(1).optional().default(0.3)
+      .describe('How surprising was this? 0=expected, 1=very unexpected'),
+    decision_made: z.boolean().optional().default(false)
+      .describe('Was a decision made? True boosts importance'),
+    causal_depth: z.number().min(0).max(1).optional().default(0.3)
+      .describe('How deep is the causal understanding? 0=surface, 1=root cause'),
+    resolution_effort: z.number().min(0).max(1).optional().default(0.3)
+      .describe('How much effort to resolve? 0=trivial, 1=significant debugging'),
+    memory_class: z.enum(['canonical', 'working', 'ephemeral']).optional().default('working')
+      .describe('Memory class: canonical (source-of-truth, never stages), working (default), ephemeral (temporary, decays faster)'),
+    memory_type: z.enum(['episodic', 'semantic', 'procedural', 'unclassified']).optional()
+      .describe('Memory type: episodic (events/incidents), semantic (facts/decisions), procedural (how-to/steps). Auto-classified if omitted.'),
+    supersedes: z.string().optional()
+      .describe('ID of an older memory this one replaces. The old memory is down-ranked, not deleted.'),
+    correction: z.boolean().optional()
+      .describe('This write corrects a fact AWM already holds and you do not have its id. AWM supersedes the closest active memory about the same thing, stores the correction active at no less than that memory\'s confidence, and says what it replaced. Use it whenever a value changed (a time, a price, a status, a decision); written as a plain observation, a changed fact merges into or ranks below the stale version. If nothing close enough exists the write is stored as new and the reply says so. An explicit supersedes outranks this.'),
+    // --- Agent-provided metadata (stored as searchable tags) ---
+    project: z.string().optional()
+      .describe('Project context (e.g., "EquiHub", "AWM"). Becomes a searchable tag.'),
+    topic: z.string().optional()
+      .describe('Subject area (e.g., "database-migration", "auth-flow"). Becomes a searchable tag.'),
+    source: z.enum(['code-reading', 'debugging', 'discussion', 'research', 'testing', 'observation']).optional()
+      .describe('How this knowledge was acquired.'),
+    confidence_level: z.enum(['verified', 'observed', 'assumed']).optional()
+      .describe('Confidence: verified (tested), observed (read in code), assumed (reasoning).'),
+    session_id: z.string().optional()
+      .describe('Session/conversation grouping ID. Memories with same session_id are associated.'),
+    origin_class: z.enum(['user-stated', 'tool-output', 'inference', 'recipe']).optional()
+      .describe('Provenance (D5, log-only): where this knowledge came from. user-stated = the human said it; tool-output = read from a tool/system; inference = your reasoning; recipe = produced by a cognition recipe.'),
+    recipe_id: z.string().optional()
+      .describe('Cognition-recipe id+version when origin_class is recipe.'),
+    valid_from: z.string().optional()
+      .describe('ISO date when the FACT becomes valid (temporal validity, not ingestion time).'),
+    valid_to: z.string().optional()
+      .describe('ISO date when the FACT stops being valid (e.g., a deadline or a superseding change).'),
+    intent: z.enum(['decision', 'question', 'todo', 'finding', 'context']).optional()
+      .describe('What kind of memory this is.'),
+  },
+  async (params) => {
+    // Assemble tags: user-provided + agent metadata (stored as searchable prefixed tags)
+    const userTags = params.tags ?? [];
+    const metaTags: string[] = [];
+    if (params.project) metaTags.push(`proj=${params.project}`);
+    if (params.topic) metaTags.push(`topic=${params.topic}`);
+    if (params.source) metaTags.push(`src=${params.source}`);
+    if (params.confidence_level) metaTags.push(`conf=${params.confidence_level}`);
+    if (params.session_id) metaTags.push(`sid=${params.session_id}`);
+    if (params.intent) metaTags.push(`intent=${params.intent}`);
+
+    // D14 (2026-07-30): recipe write-backs are contract-checked. Provenance
+    // must never claim a recipe that does not exist, and malformed
+    // derivations are rejected with the contract echoed back so the host
+    // can self-correct in one retry.
+    if (params.origin_class === 'recipe') {
+      if (!params.recipe_id) {
+        return { content: [{ type: 'text' as const, text: "Recipe write rejected: origin_class 'recipe' requires recipe_id (e.g. 'skill-derivation@1')." }] };
+      }
+      const v = validateRecipeWrite(params.recipe_id, params.concept, params.content);
+      if (!v.ok) {
+        const contract = getRecipe(params.recipe_id)?.writeBack ?? 'unknown recipe';
+        return { content: [{ type: 'text' as const, text: `Recipe write rejected (${params.recipe_id}): ${v.errors.join('; ')}\nContract: ${contract}` }] };
+      }
+      // Standardize recipe write-backs: canonical class, standard tags.
+      const slug = recipeSlug(params.concept);
+      const ensure = (tag: string) => { if (!userTags.includes(tag) && !metaTags.includes(tag)) metaTags.push(tag); };
+      if (params.recipe_id.startsWith('skill-derivation')) {
+        ensure('topic=skill'); ensure(`skill=${slug}`);
+        params.memory_type = params.memory_type ?? 'procedural';
+      } else if (params.recipe_id.startsWith('friction-lesson')) {
+        ensure('topic=friction'); ensure(`about=${slug}`);
+        // zod defaults event_type to 'observation', so force the recipe's
+        // contract value rather than ??-guarding against undefined.
+        params.event_type = 'friction';
+      }
+      params.memory_class = 'canonical';
+    }
+
+    const memoryType = params.memory_type ?? classifyMemoryType(params.content);
+
+    const result = await performWrite({ store, connectionEngine }, {
+      agentId: AGENT_ID,
+      concept: params.concept,
+      content: params.content,
+      tags: [...userTags, ...metaTags],
+      eventType: params.event_type as SalienceEventType,
+      surprise: params.surprise,
+      decisionMade: params.decision_made,
+      // Passed through so the salience filter sees a declared decision, not just an
+      // `intent=` tag. The mapping lives in write-pipeline.ts; see the measurement there.
+      intent: params.intent,
+      causalDepth: params.causal_depth,
+      resolutionEffort: params.resolution_effort,
+      memoryClass: params.memory_class,
+      memoryType,
+      supersedes: params.supersedes,
+      correction: params.correction,
+      originClass: params.origin_class,
+      writerSession: params.session_id,
+      recipeId: params.recipe_id,
+      validFrom: params.valid_from,
+      validTo: params.valid_to,
+    });
+
+    // Auto-checkpoint — covers create/reinforce/supersede uniformly
+    try { await store.updateAutoCheckpointWrite(AGENT_ID, result.engram.id); } catch { /* non-fatal */ }
+
+    if (result.action === 'reinforce') {
+      log(AGENT_ID, 'write:reinforce', `"${params.concept}" → reinforced "${result.engram.concept}" (conf ${result.reinforce!.previousConfidence.toFixed(2)} → ${result.reinforce!.newConfidence.toFixed(2)}, novelty=${result.noveltyResult.novelty.toFixed(2)})`);
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `Reinforced existing memory "${result.engram.concept}" (confidence ${result.reinforce!.previousConfidence.toFixed(2)} → ${result.reinforce!.newConfidence.toFixed(2)})`,
+        }],
+      };
+    }
+
+    const engram = result.engram;
+    const salience = result.salience!; // create/supersede always have salience
+    const novelty = result.noveltyResult.novelty;
+    const isLowSalience = salience.disposition === 'discard';
+
+    // Decision propagation: when decision_made=true or intent='decision', and coordination is enabled,
+    // broadcast to coord_decisions so other agents can discover it
+    if ((params.decision_made || params.intent === 'decision') && coordDb) {
+      try {
+        const agent = coordDb.prepare(
+          `SELECT id, current_task FROM coord_agents WHERE name = ? AND status != 'dead' ORDER BY last_seen DESC LIMIT 1`
+        ).get(AGENT_ID) as { id: string; current_task: string | null } | undefined;
+        if (agent) {
+          coordDb.prepare(
+            `INSERT INTO coord_decisions (author_id, assignment_id, tags, summary) VALUES (?, ?, ?, ?)`
+          ).run(agent.id, agent.current_task, params.tags ? JSON.stringify(params.tags) : null, params.concept);
+        }
+      } catch { /* decision propagation is non-fatal */ }
+    }
+
+    const logDisposition = isLowSalience ? 'low-salience' : salience.disposition;
+    log(AGENT_ID, `write:${logDisposition}`, `"${params.concept}" salience=${salience.score.toFixed(2)} novelty=${novelty.toFixed(1)} id=${engram.id}`);
+
+    // 2026-10-19: say what a correction replaced, or that it replaced nothing.
+    const correctionNote = params.correction
+      ? (result.correctionOf
+          ? `\nCorrected "${result.correctionOf.concept}" (${result.correctionOf.id}) — it is now superseded by this memory.`
+          : `\nNOTE: no existing memory was close enough to correct, so this was stored as new. If you know which memory it replaces, write again with supersedes: '<id>'.`)
+      : '';
+
+    const trustNote = result.trustBlocked
+      ? `\nNOTE: stored as its own memory, not merged into ${result.trustBlocked.matchedId} — this write is less trusted than that memory (src/core/trust.ts), so it must not replace or be merged into it.`
+      : '';
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Stored (${salience.disposition}) "${params.concept}" [${salience.score.toFixed(2)}]\nID: ${engram.id}`
+          + correctionNote
+          + trustNote
+          + (isLowSalience
+            ? `\nNOTE: low salience — this memory is kept but demoted and may fade first. If it MUST survive and be recallable, retry with memory_class: 'canonical'. (Discards are audited: reason codes ${JSON.stringify(salience.reasonCodes.slice(0, 4))})`
+            : ''),
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_recall',
+  `Recall memories relevant to a query. Uses cognitive activation — not keyword search.
+
+ALWAYS call this when:
+- Starting work on a project or topic (recall what you know)
+- Debugging (recall similar errors and solutions)
+- Making decisions (recall past decisions and outcomes)
+- The user mentions a topic you might have stored memories about
+
+Accepts either "query" or "context" parameter — both work identically.
+Returns the most relevant memories ranked by text relevance, temporal recency, and associative strength.`,
+  {
+    query: z.string().optional().describe('What to search for — describe the situation, question, or topic'),
+    context: z.string().optional().describe('Alias for query (either works)'),
+    limit: z.number().optional().default(3).describe('Max memories to return (default 3). Measured on 400 real-store probes: k=3 is the only token-POSITIVE setting (+115 tok/recall, against -680 at k=5) and is 41% faster at p50, because `limit` sizes the cross-encoder rerank pool (min(limit*8, 40) — so 24 at k=3 against 40 at k=5) and rerank is 83% of warm recall time. It costs ~0.5pp success@1 versus k=5 — about 3 queries in 400, inside noise. Raise it explicitly when you want breadth for orientation rather than a specific fact; that is the case this default deliberately does not optimize for.'),
+    min_score: z.number().optional().default(0.05).describe('Minimum relevance score (default 0.05)'),
+    include_staging: z.boolean().optional().default(false).describe('Include weak/unconfirmed memories?'),
+    use_reranker: z.boolean().optional().default(true).describe('Use cross-encoder re-ranking for better relevance (default true)'),
+    use_expansion: z.boolean().optional().default(true).describe('Expand query with synonyms for better recall (default true)'),
+    memory_type: z.enum(['episodic', 'semantic', 'procedural']).optional().describe('Filter by memory type (omit to search all types)'),
+    workspace: z.string().optional().describe('Search across all agents in this workspace (hive mode). Omit for agent-scoped recall only.'),
+    require_confidence: z.number().optional().default(0.05).describe('Abstain (return nothing) when recall confidence is below this threshold. Defaults to 0.05 — a LIGHT filter, chosen from measurement: it halves the rate of answering off-topic queries at zero cost to hit rate. Raise it only for push-style use where nobody asked (the prime hook uses 0.10 — it was 0.25 until 0.14.6, when 0.25 was measured silencing prompts with a clear winner). Do NOT raise it for ordinary recall: a miss is expensive, because the agent then reads the codebase instead (~2,106 tokens), so aggressive thresholds measurably destroy value — 0.20+ cut net tokens saved by 25% in tests/abstention-eval. Pass 0 to disable. NOTE: this is NOT min_score — it gates on the SHAPE of the score distribution across the whole result set, not per-result relevance, so memories that pass min_score can still be withheld. When that happens the reply says RECALL ABSTAINED and reports how many were withheld; an empty result is only absence when it does not.'),
+    granularity: z.enum(['full', 'compact', 'auto']).optional().describe('Output granularity (Paper 3: cognitive teaming). "full" (default): no change. "compact": every result carries a short summary field. "auto": confidence-adaptive — top result gets a longer summary when there is a clear winner, otherwise everything is compact for scanning.'),
+    max_tokens: z.number().optional().describe('Token budget for the response. `limit` is a COUNT and is token-blind — 5 results may cost 400 tokens or 4,000. Use this when context is tight: results are packed by value-per-token until the budget is reached, the top-scored match always gets first refusal, and the reply reports what it cost and what was withheld. Omit for no budget (everything is returned, still with accounting).'),
+  },
+  async (params) => {
+    const queryText = params.query ?? params.context;
+    if (!queryText) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: 'Error: provide either "query" or "context" parameter with your search text.',
+        }],
+      };
+    }
+    // Use workspace from param, env var, or omit for agent-scoped
+    const workspace = params.workspace ?? process.env.AWM_WORKSPACE ?? undefined;
+    // Set only when a gate WITHHELD results. Distinguishes abstention from absence,
+    // which an empty array cannot.
+    let abstained: AbstentionInfo | undefined;
+    const results = await activationEngine.activate({
+      agentId: AGENT_ID,
+      context: queryText,
+      limit: params.limit,
+      minScore: params.min_score,
+      includeStaging: params.include_staging,
+      useReranker: params.use_reranker,
+      useExpansion: params.use_expansion,
+      memoryType: params.memory_type,
+      workspace,
+      requireConfidence: params.require_confidence,
+      granularity: params.granularity,
+      onAbstain: (info) => { abstained = info; },
+    });
+
+    // Auto-checkpoint: track recall
+    try {
+      const ids = results.map(r => r.engram.id);
+      await store.updateAutoCheckpointRecall(AGENT_ID, queryText, ids);
+    } catch { /* non-fatal */ }
+
+    log(AGENT_ID, 'recall', `"${queryText.slice(0, 80)}" → ${results.length} results`);
+
+    // Peer decisions: append recent decisions by other agents relevant to this query
+    const peerSuffix = coordDb
+      ? formatPeerDecisions(queryPeerDecisions(coordDb, AGENT_ID, queryText))
+      : '';
+
+    if (results.length === 0) {
+      // Two very different conditions used to render identically as
+      // "No relevant memories found." — a claim of absence the system cannot make
+      // when a gate withheld matches. Callers read it as absence and stopped
+      // looking, for memories scoring well above minScore.
+      const text = abstained
+        ? [
+            `RECALL ABSTAINED — this is NOT "no memories exist".`,
+            ``,
+            `${abstained.candidates} candidate${abstained.candidates === 1 ? '' : 's'} matched ` +
+              `(best score ${abstained.topScore.toFixed(3)}) and ${abstained.candidates === 1 ? 'was' : 'were'} ` +
+              `withheld because recall confidence ` +
+              `${abstained.confidence !== undefined ? abstained.confidence.toFixed(3) + ' ' : ''}` +
+              `fell below your require_confidence of ${abstained.threshold ?? '?'}.`,
+            ``,
+            `require_confidence is NOT min_score. It gates on the SHAPE of the score` +
+              ` distribution across the whole result set, not on how relevant any single` +
+              ` memory is — so results that comfortably pass min_score can still be withheld here.`,
+            ``,
+            `To see them: re-run this query with require_confidence: 0.`,
+            `Do not conclude the memories are absent without doing that.`,
+          ].join('\n') + peerSuffix
+        : 'No relevant memories found.' + peerSuffix;
+      return { content: [{ type: 'text' as const, text }] };
+    }
+
+    // Confidence-adaptive output (Paper 3: cognitive teaming) and D8
+    // (2026-07-30) conflict surfacing both live in the shared formatter now —
+    // see core/format-recall.ts for why it's extracted (0.12.1: unit-testable
+    // without booting the server) and why the id sits after the score.
+    // 0.13.3: pack to a token budget (if given) and always report the spend.
+    // `limit` is a count and is token-blind; max_tokens bounds what this call
+    // actually costs the caller's context. See core/token-budget.ts for why the
+    // top-scored result gets first refusal rather than pure density packing.
+    // Reserve what the rest of the reply will cost, so max_tokens bounds the
+    // WHOLE response and not just the result lines. FOOTER_ALLOWANCE is a
+    // fixed upper bound on the accounting line (measured at ~15-25 tokens; the
+    // unit test asserts it stays under 40).
+    // 2026-10-19: recall confidence on every reply (it was printed only on
+    // abstention, so a caller could not tell a clear winner from a toss-up),
+    // and one line when the returned set holds two versions of a fact — see
+    // src/core/conflicts.ts. Both are reserved from the budget like the footer.
+    const topConfidence = results[0]?.confidence;
+    const confidenceFooter = topConfidence !== undefined ? `\n[confidence: ${topConfidence.toFixed(3)}]` : '';
+    const marked = results.filter(r => (r.conflictsWith ?? []).length > 0);
+    const newest = newestConflicting(results, results.map(r => r.conflictsWith ?? []));
+    const conflictFooter = marked.length > 0
+      ? `\n⚠ ${marked.length} of these memories disagree with each other${newest ? ` — the newest is ${newest}` : ''}. Confirm against the source before stating a value; supersede the stale one when you know which it is.`
+      : '';
+    // The near-miss (2026-10-19): memories plainly about the subject, none holding
+    // the kind of value asked for. That is the context shape that invites a made-up
+    // number; say so. See src/core/asked-value.ts.
+    const missingFooter = missingValueNote(queryText ?? '', results);
+    const FOOTER_ALLOWANCE = 40;
+    const reserved = estimateTokens(peerSuffix) + estimateTokens(confidenceFooter) + estimateTokens(conflictFooter) + estimateTokens(missingFooter) + FOOTER_ALLOWANCE;
+    const packed = packRecallByBudget(
+      results, formatRecallResultLine, params.max_tokens, reserved,
+    );
+
+    // A budget too small to admit even the best match must not look like "no
+    // memories found" — that is a different fact and would send the caller off
+    // to read code that AWM could have answered. Say what actually happened so
+    // the fix (raise the budget) is obvious.
+    if (packed.kept === 0 && packed.total > 0) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `${packed.total} memories matched, but none fit a ${params.max_tokens}-token budget `
+              + `(smallest result is ~${packed.withheldTokens} tok across ${packed.total}). `
+              + `Raise max_tokens, or use granularity: 'compact' to shrink each result.`
+              + peerSuffix,
+        }],
+      };
+    }
+
+    // 0.14.3: surface the activation event id once, so memory_feedback can join
+    // to this recall. Rendered after the token footer; cheap (one short line).
+    const evId = results[0]?.activationEventId;
+    const evFooter = evId ? `\n[recall_id: ${evId}]` : '';
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: packed.lines.join('\n') + peerSuffix + conflictFooter + missingFooter + formatTokenFooter(packed, params.max_tokens) + confidenceFooter + evFooter,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_feedback',
+  `Report whether a recalled memory was actually useful. This updates the memory's confidence score — useful memories become stronger, useless ones weaken.
+
+Always call this after using a recalled memory so the system learns what's valuable.`,
+  {
+    engram_id: z.string().describe('ID of the memory (from memory_recall results)'),
+    useful: z.boolean().describe('Was this memory actually helpful?'),
+    context: z.string().optional().describe('Brief note on why it was/wasn\'t useful'),
+    recall_id: z.string().optional().describe(
+      'The [recall_id: …] printed at the end of the memory_recall output that returned this memory. '
+      + 'Pass it so the feedback is joined to that recall; omitted, it defaults to the most recent recall in this session.',
+    ),
+  },
+  async (params) => {
+    // 0.14.3: join feedback to the recall that produced it. Explicit recall_id
+    // wins; otherwise fall back to the engine's most recent logged activation —
+    // the common case is "recall, use, feedback" in one turn. Before this the
+    // MCP path hardcoded null (the HTTP route already accepted the id), which
+    // is why every retrieval_feedback row in the live store was orphaned.
+    const eventId = params.recall_id ?? activationEngine.lastActivationEventId ?? null;
+    await store.logRetrievalFeedback(eventId, params.engram_id, params.useful, params.context ?? '');
+
+    const engram = await store.getEngram(params.engram_id);
+    if (engram) {
+      const delta = params.useful
+        ? DEFAULT_AGENT_CONFIG.feedbackPositiveBoost
+        : -DEFAULT_AGENT_CONFIG.feedbackNegativePenalty;
+      await store.updateConfidence(engram.id, engram.confidence + delta);
+    }
+
+    // Validation-gated Hebbian: resolve pending co-activation pairs for this engram
+    const hebbianUpdated = await activationEngine.resolveHebbianFeedback(params.engram_id, params.useful);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Feedback: ${params.useful ? '+useful' : '-not useful'}${hebbianUpdated > 0 ? ` (${hebbianUpdated} association${hebbianUpdated > 1 ? 's' : ''} ${params.useful ? 'strengthened' : 'weakened'})` : ''}`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_retract',
+  `Retract a memory that turned out to be wrong. Creates a correction and reduces confidence of related memories.
+
+Use this when you discover a memory contains incorrect information.`,
+  {
+    engram_id: z.string().describe('ID of the wrong memory'),
+    reason: z.string().describe('Why is this memory wrong?'),
+    correction: z.string().optional().describe('What is the correct information? (creates a new memory)'),
+  },
+  async (params) => {
+    const result = await retractionEngine.retract({
+      agentId: AGENT_ID,
+      targetEngramId: params.engram_id,
+      reason: params.reason,
+      counterContent: params.correction,
+    });
+
+    const parts = [`Memory ${params.engram_id} retracted.`];
+    if (result.correctionId) {
+      parts.push(`Correction stored as ${result.correctionId}.`);
+    }
+    parts.push(`${result.associatesAffected} related memories had confidence reduced.`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: parts.join(' '),
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_supersede',
+  `Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct.
+
+Use this when:
+- A status or count has changed (e.g., "5 reviews done" → "7 reviews done")
+- Architecture or infrastructure evolved (e.g., "two-repo model" → "three-repo model")
+- A schedule or plan was updated
+
+The old memory stays in the database (searchable for history) but is heavily down-ranked in recall so the current version dominates.`,
+  {
+    old_engram_id: z.string().describe('ID of the outdated memory (from memory_recall results, or memory_write\'s own response if you just wrote it)'),
+    new_engram_id: z.string().describe('ID of the replacement memory'),
+    reason: z.string().optional().describe('Why the old memory is outdated'),
+  },
+  async (params) => {
+    const oldEngram = await store.getEngram(params.old_engram_id);
+    if (!oldEngram) {
+      return { content: [{ type: 'text' as const, text: `Old memory not found: ${params.old_engram_id}` }] };
+    }
+    const newEngram = await store.getEngram(params.new_engram_id);
+    if (!newEngram) {
+      return { content: [{ type: 'text' as const, text: `New memory not found: ${params.new_engram_id}` }] };
+    }
+
+    await store.supersedeEngram(params.old_engram_id, params.new_engram_id);
+
+    // Create supersession association (new → old)
+    await store.upsertAssociation(params.new_engram_id, params.old_engram_id, 0.8, 'causal', 0.9);
+
+    // Reduce old memory's confidence (not to zero — it's historical, not wrong)
+    await store.updateConfidence(params.old_engram_id, Math.max(0.2, oldEngram.confidence * 0.4));
+
+    log(AGENT_ID, 'supersede', `"${oldEngram.concept}" → "${newEngram.concept}"${params.reason ? ` (${params.reason})` : ''}`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Superseded: "${oldEngram.concept}" → "${newEngram.concept}"`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_whoami',
+  `Identify THIS AWM instance — agent id, mode (standalone/hive), backend, store path, code provenance, ports, and the sibling agent spaces present in the same store. Call when unsure which AWM instance or memory space you are talking to.`,
+  {},
+  async () => {
+    const info = await buildWhoami(store, AGENT_ID, 'mcp', sidecarHandle ? sidecarHandle.boundPort() : undefined);
+    return { content: [{ type: 'text', text: formatWhoami(info) }] };
+  },
+);
+
+server.tool(
+  'memory_stats',
+  `Get memory health stats — how many memories, confidence levels, association count, and system performance.
+Also shows the activity log path so the user can tail it to see what's happening.`,
+  {},
+  async () => {
+    const metrics = await evalEngine.computeMetrics(AGENT_ID);
+    const checkpoint = await store.getCheckpoint(AGENT_ID);
+    // 0.14.3: outcome numbers, not activity counters. "Edge utility" (share of
+    // edges ever activated) was monotone — it could only rise — and read as
+    // health when it was not. Latency was a mean over a column that mixes cold
+    // loads and stalls (live store: mean 20 s, median 1.6 s); medians only now.
+    const usage = await evalEngine.computeUsage(AGENT_ID);
+    const lines = [
+      `Agent: ${AGENT_ID}`,
+      `Active memories: ${metrics.activeEngramCount}`,
+      `Staging: ${metrics.stagingEngramCount}`,
+      `Retracted: ${metrics.retractedCount}`,
+      `Avg confidence: ${metrics.avgConfidence.toFixed(3)}`,
+      `Total edges: ${metrics.totalEdges}`,
+      ``,
+      `Write:recall (30d): 1 : ${usage.recallsPerWrite30d.toFixed(2)}  (${usage.writes30d} writes, ${usage.recalls30d} recalls)`,
+      `Never recalled: ${(usage.neverRecalledShare * 100).toFixed(0)}% of active memories`,
+      `Recall→use (7d): ${usage.feedbackLinked7d > 0 ? (usage.usefulShare7d * 100).toFixed(0) + '% useful of ' + usage.feedbackLinked7d + ' judged' : 'no linked feedback yet'}`,
+      `Activations (24h): ${metrics.activationCount}`,
+      `Recall latency (24h): p50 ${metrics.p50LatencyMs.toFixed(0)}ms  p90 ${metrics.p90LatencyMs.toFixed(0)}ms`,
+      ``,
+      `Session writes: ${checkpoint?.auto.writeCountSinceConsolidation ?? 0}`,
+      `Session recalls: ${checkpoint?.auto.recallCountSinceConsolidation ?? 0}`,
+      `Last activity: ${checkpoint?.auto.lastActivityAt?.toISOString() ?? 'never'}`,
+      `Checkpoint: ${checkpoint?.executionState ? checkpoint.executionState.currentTask : 'none'}`,
+      ``,
+      `Activity log: ${getLogPath() ?? 'not configured'}`,
+      // Report the port actually BOUND, not the one configured. Before 0.14.2
+      // this line said 8401 in every session, including the ones whose sidecar
+      // had lost the port and silently disabled hooks.
+      `Hook sidecar: ${sidecarPortLabel()}`,
+    ];
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: lines.join('\n'),
+      }],
+    };
+  }
+);
+
+// --- Checkpointing Tools ---
+
+server.tool(
+  'memory_checkpoint',
+  `Save your current execution state so you can recover after context compaction.
+
+ALWAYS call this before:
+- Long operations (multi-file generation, large refactors, overnight work)
+- Anything that might fill the context window
+- Switching to a different task
+
+Also call periodically during long sessions to avoid losing state. The state is saved per-agent and overwrites any previous checkpoint.`,
+  {
+    current_task: z.string().describe('What you are currently working on'),
+    decisions: z.array(z.string()).optional().default([])
+      .describe('Key decisions made so far'),
+    active_files: z.array(z.string()).optional().default([])
+      .describe('Files you are currently working with'),
+    next_steps: z.array(z.string()).optional().default([])
+      .describe('What needs to happen next'),
+    related_memory_ids: z.array(z.string()).optional().default([])
+      .describe('IDs of memories relevant to current work'),
+    notes: z.string().optional().default('')
+      .describe('Any other context worth preserving'),
+    episode_id: z.string().optional()
+      .describe('Current episode ID if known'),
+  },
+  async (params) => {
+    const state: ConsciousState = {
+      currentTask: params.current_task,
+      decisions: params.decisions,
+      activeFiles: params.active_files,
+      nextSteps: params.next_steps,
+      relatedMemoryIds: params.related_memory_ids,
+      notes: params.notes,
+      episodeId: params.episode_id ?? null,
+    };
+
+    await store.saveCheckpoint(AGENT_ID, state);
+    log(AGENT_ID, 'checkpoint', `"${params.current_task}" decisions=${params.decisions.length} files=${params.active_files.length}`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Checkpoint saved: "${params.current_task}" (${params.decisions.length} decisions, ${params.active_files.length} files)`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_restore',
+  `Restore your previous execution state after context compaction or at session start.
+
+Returns:
+- Your saved execution state (task, decisions, next steps, files)
+- Recently recalled memories for context
+- Your last write for continuity
+- How long you were idle
+
+Use this at the start of every session or after compaction to pick up where you left off.`,
+  {},
+  async () => {
+    const checkpoint = await store.getCheckpoint(AGENT_ID);
+
+    // Cold-store nudge: an empty store means the agent has nothing to recall — offer to warm-start.
+    let coldStoreNudge = '';
+    try {
+      const activeCount = (await store.getEngramsByAgent(AGENT_ID)).length;
+      if (activeCount < 3) {
+        coldStoreNudge = `🌱 **This memory store is nearly empty (${activeCount} ${activeCount === 1 ? 'memory' : 'memories'}).** Warm-start it before other work: recall the "onboard a new project" skill and follow it — or call \`onboard_scan\` on this project's docs/repo, refine the results, and save them with \`memory_write\` (canonical). Recall becomes useful immediately.`;
+      }
+    } catch { /* count is best-effort */ }
+
+    const now = Date.now();
+    const idleMs = checkpoint
+      ? now - checkpoint.auto.lastActivityAt.getTime()
+      : 0;
+
+    // Get last written engram
+    let lastWrite: { id: string; concept: string; content: string } | null = null;
+    if (checkpoint?.auto.lastWriteId) {
+      const engram = await store.getEngram(checkpoint.auto.lastWriteId);
+      if (engram) {
+        lastWrite = { id: engram.id, concept: engram.concept, content: engram.content };
+      }
+    }
+
+    // Recall memories using last context
+    let recalledMemories: Array<{ id: string; concept: string; content: string; score: number }> = [];
+    const recallContext = checkpoint?.auto.lastRecallContext
+      ?? checkpoint?.executionState?.currentTask
+      ?? null;
+
+    if (recallContext) {
+      try {
+        const results = await activationEngine.activate({
+          agentId: AGENT_ID,
+          context: recallContext,
+          // 3, not 5 — measured token-positive (+115/recall vs -680) and 41% faster.
+          // The case is stronger here than for explicit recall: this is push-style, so
+          // nobody asked for these results and every one of them costs context the user
+          // did not request.
+          limit: 3,
+          minScore: 0.05,
+          useReranker: true,
+          useExpansion: true,
+          workspace: process.env.AWM_WORKSPACE ?? undefined,
+        });
+        recalledMemories = results.map(r => ({
+          id: r.engram.id,
+          concept: r.engram.concept,
+          content: r.engram.content,
+          score: r.score,
+        }));
+      } catch { /* recall failure is non-fatal */ }
+    }
+
+    // Consolidation on restore:
+    // - If idle >5min but last consolidation was recent (graceful exit ran it), skip
+    // - If idle >5min and no recent consolidation, run full cycle (non-graceful exit fallback)
+    const MINI_IDLE_MS = 5 * 60_000;
+    const FULL_CONSOLIDATION_GAP_MS = 10 * 60_000; // 10 min — if last consolidation was longer ago, run full
+    let miniConsolidationTriggered = false;
+    let fullConsolidationTriggered = false;
+
+    if (idleMs > MINI_IDLE_MS) {
+      const sinceLastConsolidation = checkpoint?.lastConsolidationAt
+        ? now - checkpoint.lastConsolidationAt.getTime()
+        : Infinity;
+
+      if (sinceLastConsolidation > FULL_CONSOLIDATION_GAP_MS) {
+        // No recent consolidation — graceful exit didn't happen, run full cycle
+        fullConsolidationTriggered = true;
+        try {
+          const result = await consolidationEngine.consolidate(AGENT_ID);
+          await store.markConsolidation(AGENT_ID, false);
+          log(AGENT_ID, 'consolidation', `full sleep cycle on restore (no graceful exit, idle ${Math.round(idleMs / 60_000)}min, last consolidation ${Math.round(sinceLastConsolidation / 60_000)}min ago) — ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
+        } catch { /* consolidation failure is non-fatal */ }
+      } else {
+        // Recent consolidation exists — graceful exit already handled it, just do mini
+        miniConsolidationTriggered = true;
+        consolidationScheduler.runMiniConsolidation(AGENT_ID).catch(() => {});
+      }
+    }
+
+    // Format response
+    const parts: string[] = [];
+    const idleMin = Math.round(idleMs / 60_000);
+    const consolidationNote = fullConsolidationTriggered
+      ? ' (full consolidation — no graceful exit detected)'
+      : miniConsolidationTriggered
+        ? ' (mini-consolidation triggered)'
+        : '';
+    log(AGENT_ID, 'restore', `idle=${idleMin}min checkpoint=${!!checkpoint?.executionState} recalled=${recalledMemories.length} lastWrite=${lastWrite?.concept ?? 'none'}${fullConsolidationTriggered ? ' FULL_CONSOLIDATION' : ''}`);
+    parts.push(`Idle: ${idleMin}min${consolidationNote}`);
+    if (coldStoreNudge) parts.push(`\n${coldStoreNudge}`);
+
+    if (checkpoint?.executionState) {
+      const s = checkpoint.executionState;
+      parts.push(`\n**Current task:** ${s.currentTask}`);
+      if (s.decisions.length) parts.push(`**Decisions:** ${s.decisions.join('; ')}`);
+      if (s.nextSteps.length) parts.push(`**Next steps:** ${s.nextSteps.map((st, i) => `${i + 1}. ${st}`).join(', ')}`);
+      if (s.activeFiles.length) parts.push(`**Active files:** ${s.activeFiles.join(', ')}`);
+      if (s.notes) parts.push(`**Notes:** ${s.notes}`);
+      if (checkpoint.checkpointAt) parts.push(`_Saved at: ${checkpoint.checkpointAt.toISOString()}_`);
+    } else {
+      parts.push('\nNo explicit checkpoint saved.');
+      parts.push('\n**Tip:** Use memory_write to save important learnings, and memory_checkpoint before long operations so you can recover state.');
+    }
+
+    if (lastWrite) {
+      parts.push(`\n**Last write:** ${lastWrite.concept}\n${lastWrite.content}`);
+    }
+
+    if (recalledMemories.length > 0) {
+      parts.push(`\n**Recalled memories (${recalledMemories.length}):**`);
+      for (const m of recalledMemories) {
+        parts.push(`- **${m.concept}** (${m.score.toFixed(3)}): ${m.content.slice(0, 150)}${m.content.length > 150 ? '...' : ''}`);
+      }
+    }
+
+    // Peer decisions: show recent decisions from other agents (last 30 min)
+    if (coordDb) {
+      try {
+        const myAgent = coordDb.prepare(
+          `SELECT id FROM coord_agents WHERE name = ? AND status != 'dead' ORDER BY last_seen DESC LIMIT 1`
+        ).get(AGENT_ID) as { id: string } | undefined;
+
+        const peerDecisions = coordDb.prepare(
+          `SELECT d.summary, a.name AS author_name, d.created_at
+           FROM coord_decisions d JOIN coord_agents a ON d.author_id = a.id
+           WHERE d.author_id != ? AND d.created_at > datetime('now', '-30 minutes')
+           ORDER BY d.created_at DESC LIMIT 10`
+        ).all(myAgent?.id ?? '') as Array<{ summary: string; author_name: string; created_at: string }>;
+
+        if (peerDecisions.length > 0) {
+          parts.push(`\n**Peer decisions (last 30 min):**`);
+          for (const d of peerDecisions) {
+            parts.push(`- [${d.author_name}] ${d.summary} (${d.created_at})`);
+          }
+        }
+      } catch { /* peer decisions are non-fatal */ }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: parts.join('\n'),
+      }],
+    };
+  }
+);
+
+// --- Onboarding Tools (warm-start a cold store) ---
+
+server.tool(
+  'onboard_scan',
+  `Scan a project's documentation + repository and return CANDIDATE memories to seed a cold store.
+
+Use this when the store is empty / you're new to a project. The scan is deterministic
+(real file contents, not guesses) — YOUR job is to refine the candidates into atomic,
+recall-shaped memories, run the interview (onboard_questions), confirm with the user, then
+save the good ones with memory_write (memory_class="canonical"). Nothing is saved by this tool.`,
+  {
+    docs: z.array(z.string()).optional()
+      .describe('Doc files/dirs to scan (Markdown/text). Defaults to the repo (or cwd).'),
+    repo: z.string().optional()
+      .describe('Repo root — also derives stack (package.json) + layout memories.'),
+    project: z.string().optional()
+      .describe('Project name (becomes a tag). Defaults to the repo/dir name.'),
+    purpose: z.string().optional()
+      .describe('The goal of this memory system, if known — becomes the anchor memory.'),
+  },
+  async (params) => {
+    const repo = params.repo;
+    const docs = params.docs && params.docs.length ? params.docs : [repo ?? process.cwd()];
+    const project = params.project ?? basename(resolve(repo ?? docs[0] ?? process.cwd()));
+    const pack = buildPack({ docs, repo, project, agentId: AGENT_ID, purpose: params.purpose });
+    log(AGENT_ID, 'onboard', `scan ${docs.join(',')}${repo ? ' +repo' : ''} → ${pack.memories.length} candidates`);
+    const text = [
+      `Scanned ${docs.join(', ')}${repo ? ` (+repo ${repo})` : ''} → ${pack.memories.length} CANDIDATE memories (NOT saved).`,
+      `Next: refine each into an atomic memory (lead with the fact + identifiers), run onboard_questions,`,
+      `confirm with the user, then save the good ones with memory_write (memory_class="canonical").`,
+      ``,
+      JSON.stringify({ project, candidates: pack.memories, questions: pack.questions }, null, 2),
+    ].join('\n');
+    return { content: [{ type: 'text' as const, text }] };
+  }
+);
+
+server.tool(
+  'onboard_questions',
+  `Return the onboarding interview questions. Ask the user ONE at a time, starting with the
+goal of the memory system, and ask follow-ups for clarity. Turn each answer into a canonical memory.`,
+  {},
+  async () => ({
+    content: [{ type: 'text' as const, text: INTERVIEW_QUESTIONS.map((q, i) => `${i + 1}. ${q}`).join('\n') }],
+  })
+);
+
+// --- Task Management Tools ---
+
+server.tool(
+  'memory_task_add',
+  `Create a task that you need to come back to. Tasks are memories with status and priority tracking.
+
+Use this when:
+- You identify work that needs doing but can't do it right now
+- The user mentions something to do later
+- You want to park a sub-task while focusing on something more urgent
+
+Tasks automatically get high salience so they won't be discarded.`,
+  {
+    concept: z.string().describe('Short task title (3-10 words)'),
+    content: z.string().describe('Full task description — what needs doing, context, acceptance criteria'),
+    tags: z.array(z.string()).optional().describe('Tags for categorization'),
+    priority: z.enum(['urgent', 'high', 'medium', 'low']).default('medium')
+      .describe('Task priority: urgent (do now), high (do soon), medium (normal), low (backlog)'),
+    blocked_by: z.string().optional().describe('ID of a task that must finish first'),
+  },
+  async (params) => {
+    const engram = await store.createEngram({
+      agentId: AGENT_ID,
+      concept: params.concept,
+      content: params.content,
+      tags: [...(params.tags ?? []), 'task'],
+      salience: 0.9, // Tasks always high salience
+      confidence: 0.8,
+      salienceFeatures: {
+        surprise: 0.5,
+        decisionMade: true,
+        causalDepth: 0.5,
+        resolutionEffort: 0.5,
+        eventType: 'decision',
+      },
+      reasonCodes: ['task-created'],
+      taskStatus: params.blocked_by ? 'blocked' : 'open',
+      taskPriority: params.priority as TaskPriority,
+      blockedBy: params.blocked_by,
+    });
+
+    connectionEngine.enqueue(engram.id);
+
+    // Generate embedding asynchronously
+    embed(`${params.concept} ${params.content}`).then(async vec => {
+      await store.updateEmbedding(engram.id, vec);
+    }).catch(() => {});
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Task created: "${params.concept}" (${params.priority})`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_task_update',
+  `Update a task's status or priority. Use this to:
+- Start working on a task (open → in_progress)
+- Mark a task done (→ done)
+- Block a task on another (→ blocked)
+- Reprioritize (change priority)
+- Unblock a task (clear blocked_by)`,
+  {
+    task_id: z.string().describe('ID of the task to update'),
+    status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
+      .describe('New status'),
+    priority: z.enum(['urgent', 'high', 'medium', 'low']).optional()
+      .describe('New priority'),
+    blocked_by: z.string().optional().describe('ID of blocking task (set to empty string to unblock)'),
+  },
+  async (params) => {
+    const engram = await store.getEngram(params.task_id);
+    if (!engram || !engram.taskStatus) {
+      return { content: [{ type: 'text' as const, text: `Task not found: ${params.task_id}` }] };
+    }
+
+    if (params.blocked_by !== undefined) {
+      await store.updateBlockedBy(params.task_id, params.blocked_by || null);
+    }
+    if (params.status) {
+      await store.updateTaskStatus(params.task_id, params.status as TaskStatus);
+    }
+    if (params.priority) {
+      await store.updateTaskPriority(params.task_id, params.priority as TaskPriority);
+    }
+
+    const updated = (await store.getEngram(params.task_id))!;
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Updated: "${updated.concept}" → ${updated.taskStatus} (${updated.taskPriority})`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_task_list',
+  `List tasks with optional status filter. Shows tasks ordered by priority (urgent first).
+
+Use at the start of a session to see what's pending, or to check blocked/done tasks.`,
+  {
+    status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
+      .describe('Filter by status (omit to see all active tasks)'),
+    include_done: z.boolean().optional().default(false)
+      .describe('Include completed tasks?'),
+  },
+  async (params) => {
+    let tasks = await store.getTasks(AGENT_ID, params.status as TaskStatus | undefined);
+    if (!params.include_done && !params.status) {
+      tasks = tasks.filter(t => t.taskStatus !== 'done');
+    }
+
+    if (tasks.length === 0) {
+      return { content: [{ type: 'text' as const, text: 'No tasks found.' }] };
+    }
+
+    const lines = tasks.map((t, i) => {
+      const blocked = t.blockedBy ? ` [blocked by ${t.blockedBy}]` : '';
+      const tags = t.tags?.filter(tag => tag !== 'task').join(', ');
+      return `${i + 1}. [${t.taskStatus}] **${t.concept}** (${t.taskPriority})${blocked}\n   ${t.content.slice(0, 120)}${t.content.length > 120 ? '...' : ''}\n   ${tags ? `Tags: ${tags} | ` : ''}ID: ${t.id}`;
+    });
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Tasks (${tasks.length}):\n\n${lines.join('\n\n')}`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_task_next',
+  `Get the single most important task to work on next.
+
+Prioritizes: in_progress tasks first (finish what you started), then by priority level, then oldest first. Skips blocked and done tasks.
+
+Use this when you finish a task or need to decide what to do next.`,
+  {},
+  async () => {
+    const next = await store.getNextTask(AGENT_ID);
+    if (!next) {
+      return { content: [{ type: 'text' as const, text: 'No actionable tasks. All clear!' }] };
+    }
+
+    const blocked = next.blockedBy ? `\nBlocked by: ${next.blockedBy}` : '';
+    const tags = next.tags?.filter(tag => tag !== 'task').join(', ');
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Next task:\n**${next.concept}** (${next.taskPriority})\nStatus: ${next.taskStatus}\n${next.content}${blocked}\n${tags ? `Tags: ${tags}\n` : ''}ID: ${next.id}`,
+      }],
+    };
+  }
+);
+
+// --- Task Bracket Tools ---
+
+server.tool(
+  'memory_task_begin',
+  `Signal that you're starting a significant task. Auto-checkpoints current state and recalls relevant memories.
+
+CALL THIS when starting:
+- A multi-step operation (doc generation, large refactor, migration)
+- Work on a new topic or project area
+- Anything that might fill the context window
+
+This ensures your state is saved before you start, and primes recall with relevant context.`,
+  {
+    topic: z.string().describe('What task are you starting? (3-15 words)'),
+    files: z.array(z.string()).optional().default([])
+      .describe('Files you expect to work with'),
+    notes: z.string().optional().default('')
+      .describe('Any additional context'),
+  },
+  async (params) => {
+    // 1. Checkpoint current state
+    const checkpoint = await store.getCheckpoint(AGENT_ID);
+    const prevTask = checkpoint?.executionState?.currentTask ?? 'None';
+
+    await store.saveCheckpoint(AGENT_ID, {
+      currentTask: params.topic,
+      decisions: [],
+      activeFiles: params.files,
+      nextSteps: [],
+      relatedMemoryIds: [],
+      notes: params.notes || `Started via memory_task_begin. Previous task: ${prevTask}`,
+      episodeId: null,
+    });
+
+    // 2. Auto-recall relevant memories
+    let recalledSummary = '';
+    try {
+      const results = await activationEngine.activate({
+        agentId: AGENT_ID,
+        context: params.topic,
+        // 3, not 5 — see memory_recall. Push-style auto-recall on task start.
+        limit: 3,
+        minScore: 0.05,
+        useReranker: true,
+        useExpansion: true,
+        workspace: process.env.AWM_WORKSPACE ?? undefined,
+      });
+
+      if (results.length > 0) {
+        const lines = results.map((r, i) => {
+          const tags = r.engram.tags?.length ? ` [${r.engram.tags.join(', ')}]` : '';
+          return `${i + 1}. **${r.engram.concept}** (${r.score.toFixed(3)})${tags}\n   ${r.engram.content.slice(0, 150)}${r.engram.content.length > 150 ? '...' : ''}`;
+        });
+        recalledSummary = `\n\n**Recalled memories (${results.length}):**\n${lines.join('\n')}`;
+
+        // Track recall
+        await store.updateAutoCheckpointRecall(AGENT_ID, params.topic, results.map(r => r.engram.id));
+      }
+    } catch { /* recall failure is non-fatal */ }
+
+    log(AGENT_ID, 'task:begin', `"${params.topic}" prev="${prevTask}"`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Started: "${params.topic}" (prev: ${prevTask})${recalledSummary}`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memory_task_end',
+  `Signal that you've finished a significant task. Writes a summary memory and auto-checkpoints.
+
+CALL THIS when you finish:
+- A multi-step operation
+- Before switching to a different topic
+- At the end of a work session
+
+This captures what was accomplished so future sessions can recall it.`,
+  {
+    summary: z.string().describe('What was accomplished? Include key outcomes, decisions, and any issues.'),
+    tags: z.array(z.string()).optional().default([])
+      .describe('Tags for the summary memory'),
+    supersedes: z.array(z.string()).optional().default([])
+      .describe('IDs of older memories this task summary replaces (marks them as superseded)'),
+  },
+  async (params) => {
+    // 1. Write summary as a memory
+    const salience = evaluateSalience({
+      content: params.summary,
+      eventType: 'decision',
+      surprise: 0.3,
+      decisionMade: true,
+      causalDepth: 0.5,
+      resolutionEffort: 0.5,
+    });
+
+    // Determine the real task name for the summary engram
+    const checkpoint = await store.getCheckpoint(AGENT_ID);
+    const rawTask = checkpoint?.executionState?.currentTask ?? 'Unknown task';
+    // Strip any "Completed: " prefixes to avoid cascading
+    const cleanedTask = rawTask.replace(/^(Completed: )+/, '');
+    // Don't use auto-checkpoint or already-completed tasks as real task names
+    const isNamedTask = !cleanedTask.startsWith('Auto-checkpoint') && cleanedTask !== 'Unknown task';
+    const completedTask = isNamedTask
+      ? cleanedTask
+      : params.summary.slice(0, 60).replace(/\n/g, ' ');
+
+    const engram = await store.createEngram({
+      agentId: AGENT_ID,
+      concept: completedTask.slice(0, 80),
+      content: params.summary,
+      tags: [...params.tags, 'task-summary'],
+      salience: isNamedTask ? Math.max(salience.score, 0.7) : salience.score, // Only floor salience for named tasks
+      confidence: 0.65, // Task summaries are decision-grade (completed work)
+      salienceFeatures: salience.features,
+      reasonCodes: [...salience.reasonCodes, 'task-end'],
+    });
+
+    connectionEngine.enqueue(engram.id);
+
+    // 2. Handle supersessions — mark old memories as outdated
+    let supersededCount = 0;
+    for (const oldId of params.supersedes) {
+      const oldEngram = await store.getEngram(oldId);
+      if (oldEngram) {
+        await store.supersedeEngram(oldId, engram.id);
+        await store.upsertAssociation(engram.id, oldId, 0.8, 'causal', 0.9);
+        await store.updateConfidence(oldId, Math.max(0.2, oldEngram.confidence * 0.4));
+        supersededCount++;
+      }
+    }
+
+    // Generate embedding asynchronously
+    embed(`Task completed: ${params.summary}`).then(async vec => {
+      await store.updateEmbedding(engram.id, vec);
+    }).catch(() => {});
+
+    // 2. Update checkpoint to reflect completion
+    await store.saveCheckpoint(AGENT_ID, {
+      currentTask: `Completed: ${completedTask}`,
+      decisions: checkpoint?.executionState?.decisions ?? [],
+      activeFiles: [],
+      nextSteps: [],
+      relatedMemoryIds: [engram.id],
+      notes: `Task completed. Summary memory: ${engram.id}`,
+      episodeId: null,
+    });
+
+    await store.updateAutoCheckpointWrite(AGENT_ID, engram.id);
+    log(AGENT_ID, 'task:end', `"${completedTask}" summary=${engram.id} salience=${salience.score.toFixed(2)} superseded=${supersededCount}`);
+
+    const supersededNote = supersededCount > 0 ? ` (${supersededCount} old memories superseded)` : '';
+    return {
+      content: [{
+        type: 'text' as const,
+        // D14 (2026-07-30): task end is the recipe moment — invite the host
+        // to distill a skill and/or a failure lesson in separate focused
+        // passes. The host owns the gates; AWM validates the write-backs.
+        text: `Completed: "${completedTask}" [${salience.score.toFixed(2)}]${supersededNote}\n${renderTaskEndInvitation()}`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'compress_output',
+  `Compress a STRUCTURED tool output (JSON object/array, query rows, log records) into TOON —
+a compact, schema-aware tabular encoding — before putting it in your context. Cuts ~50-65%
+of the tokens on uniform arrays at zero comprehension cost (validated: models read TOON as
+accurately as JSON). Use this on large tool results you need to keep in context.
+
+Output-only and safe: it never changes the data. Non-JSON / prose is returned unchanged.
+TOON is only emitted when it reproduces the input exactly (self-verified round-trip);
+otherwise you get plain JSON back. When compressed, you also get a 'ref' — call
+retrieve_original(ref) to get the verbatim source back if you ever need it.`,
+  {
+    output: z.string().describe('The tool output to compress — JSON text (preferred) or any string. Non-JSON is returned unchanged.'),
+    min_saving_chars: z.number().optional().describe('Only emit TOON if it saves at least this many characters (default 40).'),
+  },
+  async (params) => {
+    const r = liteCompress(params.output, { minSavingChars: params.min_saving_chars });
+    log(AGENT_ID, 'compress', `${r.format} ${r.charsBefore}->${r.charsAfter} chars (${(r.ratio * 100).toFixed(0)}%)${r.ref ? ` ref=${r.ref}` : ''}`);
+    const header = r.format === 'toon'
+      ? `[TOON, ${(r.ratio * 100).toFixed(0)}% smaller — compact lossless JSON; read as data, ref=${r.ref}]\n`
+      : '';
+    return {
+      content: [{ type: 'text' as const, text: header + r.text }],
+    };
+  }
+);
+
+server.tool(
+  'retrieve_original',
+  `Retrieve the verbatim original text for a 'ref' returned by compress_output. Use this when
+you need the exact, uncompressed source (e.g. to pass it to another tool unchanged). Returns
+an error if the ref has expired (originals are kept for the most recent compressions only).`,
+  {
+    ref: z.string().describe('The ref handle returned by compress_output (e.g. "awm_orig_12").'),
+  },
+  async (params) => {
+    const original = retrieveOriginal(params.ref);
+    if (original === undefined) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ref "${params.ref}" not found or expired.` }],
+      };
+    }
+    return {
+      content: [{ type: 'text' as const, text: original }],
+    };
+  }
+);
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Start hook sidecar (lightweight HTTP for Claude Code hooks)
+  const sidecar = startSidecar({
+    store,
+    agentId: AGENT_ID,
+    secret: HOOK_SECRET,
+    port: HOOK_PORT,
+    portRange: HOOK_PORT_RANGE,
+    version: VERSION,
+    // 0.12.2: warm recall for hooks — the sidecar shares this process's
+    // activation engine and loaded models, so a UserPromptSubmit hook can get
+    // warm-latency recall without any standing server. Trimmed result shape
+    // (no embeddings/phase scores — hooks don't need them and the vectors
+    // alone would 10x the payload).
+    activate: async (q) => {
+      const results = await activationEngine.activate({
+        agentId: AGENT_ID,
+        context: q.context,
+        limit: q.limit,
+        requireConfidence: q.requireConfidence,
+        granularity: q.granularity,
+      });
+      return results.map(r => ({
+        engram: {
+          id: r.engram.id,
+          concept: r.engram.concept,
+          content: r.engram.content,
+          createdAt: r.engram.createdAt instanceof Date
+            ? r.engram.createdAt.toISOString()
+            : (r.engram.createdAt as unknown as string | undefined),
+          memoryClass: r.engram.memoryClass,
+          validFrom: r.engram.validFrom,
+          validTo: r.engram.validTo,
+          supersededBy: r.engram.supersededBy,
+        },
+        score: r.score,
+        summary: r.summary,
+        confidence: r.confidence,
+        conflictsWith: r.conflictsWith,
+      }));
+    },
+    onConsolidate: async (agentId, reason) => {
+      console.error(`[mcp] consolidation triggered: ${reason}`);
+      const result = await consolidationEngine.consolidate(agentId);
+      await store.markConsolidation(agentId, false);
+      console.error(`[mcp] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
+    },
+  });
+
+  // 0.12.2: eager warm — fire-and-forget, mirrors index.ts:208-218. Without
+  // this, every Claude Code session paid the full cold cost (~3s measured on
+  // a 29.7k-engram store: slim cache ~0.9s + three model loads ~1.8s) on its
+  // FIRST recall, which is exactly the "first recall is slow → recall gets
+  // avoided" failure mode. Warming here overlaps session startup instead.
+  // All output is stderr-safe (stdout carries JSON-RPC frames).
+  // Escape hatch: AWM_NO_EAGER_WARM=1 restores lazy loading.
+  if (process.env.AWM_NO_EAGER_WARM !== '1') {
+    // With the shared model daemon on, the daemon loads them and this process loads none.
+    if (isModelDaemonEnabled()) {
+      void warmModelDaemon();
+    } else {
+      getEmbedder().catch(err => console.error('Embedding model unavailable:', err.message));
+      getReranker().catch(err => console.error('Reranker model unavailable:', err.message));
+      getExpander().catch(err => console.error('Query expander model unavailable:', err.message));
+    }
+    if (BACKEND === 'sqlite') {
+      setImmediate(() => {
+        try {
+          const t0 = Date.now();
+          (store as unknown as EngramStore).warmSlimCache();
+          const stats = (store as unknown as EngramStore).getSlimCacheStats();
+          console.error(`Slim cache warmed: ${stats.size} entries in ${Date.now() - t0}ms`);
+        } catch (err) {
+          console.error(`Slim cache warm failed: ${(err as Error).message}`);
+        }
+      });
+    }
+  }
+
+  // Coordination MCP tools (opt-in via AWM_COORDINATION=true)
+  // AWM 0.8.x: coordination requires SQLite (uses store.getDb()). On PGlite,
+  // coordination is auto-disabled with a warning; re-enable when coordination
+  // is ported to async/PGlite.
+  const coordRequested = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
+  const coordEnabled = coordRequested && BACKEND === 'sqlite';
+  if (coordEnabled) {
+    const { initCoordinationTables } = await import('./coordination/schema.js');
+    const { registerCoordinationTools } = await import('./coordination/mcp-tools.js');
+    const sqliteStore = store as unknown as EngramStore;
+    initCoordinationTables(sqliteStore.getDb());
+    registerCoordinationTools(server, sqliteStore.getDb());
+    coordDb = sqliteStore.getDb();
+  } else if (coordRequested && BACKEND === 'pglite') {
+    console.error('AWM: coordination requested but disabled — coordination plugin requires SQLite backend');
+  } else {
+    console.error('AWM: coordination tools disabled (set AWM_COORDINATION=true to enable)');
+  }
+
+  // Log to stderr (stdout is reserved for MCP protocol)
+  console.error(`AgentWorkingMemory MCP server started (agent: ${AGENT_ID}, db: ${DB_PATH})`);
+  sidecarHandle = sidecar;
+  console.error(`Hook sidecar preferred 127.0.0.1:${HOOK_PORT} (range ${HOOK_PORT_RANGE})${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
+
+  // Clean shutdown
+  const cleanup = async () => {
+    sidecar.close();
+    consolidationScheduler.stop();
+    stagingBuffer.stop();
+    if (BACKEND === 'sqlite') {
+      try { (store as Partial<EngramStore>).walCheckpoint?.(); } catch { /* non-fatal */ }
+    }
+    try { await (store as any).close?.(); } catch { /* best-effort */ }
+  };
+  process.on('SIGINT', () => { void cleanup().finally(() => process.exit(0)); });
+  process.on('SIGTERM', () => { void cleanup().finally(() => process.exit(0)); });
+}
+
+main().catch(err => {
+  console.error('MCP server failed:', err);
+  process.exit(1);
+});
+
+} // end else (non-incognito)