agent-working-memory 0.3.1 → 0.4.0

package/src/hooks/sidecar.ts

@@ -0,0 +1,231 @@
+/**
+ * Hook Sidecar — lightweight HTTP server that runs alongside the MCP process.
+ *
+ * Claude Code hooks (PreCompact, SessionEnd, etc.) send POST requests here.
+ * Since we share the same process as the MCP server, there's zero SQLite
+ * contention — we use the same store/engines directly.
+ *
+ * Endpoints:
+ *   POST /hooks/checkpoint   — auto-checkpoint (called by PreCompact, SessionEnd hooks)
+ *   GET  /health             — health check
+ *
+ * Security:
+ *   - Binds to 127.0.0.1 only (localhost)
+ *   - Bearer token auth via AWM_HOOK_SECRET
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { readFileSync } from 'node:fs';
+import type { EngramStore } from '../storage/sqlite.js';
+import type { ConsciousState } from '../types/checkpoint.js';
+import { log } from '../core/logger.js';
+
+export interface SidecarDeps {
+  store: EngramStore;
+  agentId: string;
+  secret: string | null;
+  port: number;
+  onConsolidate?: (agentId: string, reason: string) => void;
+}
+
+interface HookInput {
+  session_id?: string;
+  transcript_path?: string;
+  hook_event_name?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+}
+
+interface TranscriptContext {
+  currentTask: string;
+  activeFiles: string[];
+  recentTools: string[];
+  lastUserMessage: string;
+}
+
+/**
+ * Parse the Claude Code transcript to extract context for auto-checkpointing.
+ * Reads the JSONL transcript file and extracts recent tool calls, files, and user messages.
+ */
+function parseTranscript(transcriptPath: string): TranscriptContext {
+  const ctx: TranscriptContext = {
+    currentTask: '',
+    activeFiles: [],
+    recentTools: [],
+    lastUserMessage: '',
+  };
+
+  try {
+    const raw = readFileSync(transcriptPath, 'utf-8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+
+    const files = new Set<string>();
+    const tools: string[] = [];
+    let lastUserMsg = '';
+
+    // Parse last 100 lines max to avoid huge transcripts
+    const recent = lines.slice(-100);
+
+    for (const line of recent) {
+      try {
+        const entry = JSON.parse(line);
+
+        // Extract user messages
+        if (entry.role === 'user' && typeof entry.content === 'string') {
+          lastUserMsg = entry.content.slice(0, 200);
+        }
+        if (entry.role === 'user' && Array.isArray(entry.content)) {
+          for (const part of entry.content) {
+            if (part.type === 'text' && typeof part.text === 'string') {
+              lastUserMsg = part.text.slice(0, 200);
+            }
+          }
+        }
+
+        // Extract tool uses
+        if (entry.role === 'assistant' && Array.isArray(entry.content)) {
+          for (const part of entry.content) {
+            if (part.type === 'tool_use') {
+              tools.push(part.name);
+              // Extract file paths from tool inputs
+              const input = part.input;
+              if (input?.file_path) files.add(String(input.file_path));
+              if (input?.path) files.add(String(input.path));
+              if (input?.command && typeof input.command === 'string') {
+                // Try to extract file paths from bash commands
+                const pathMatch = input.command.match(/["']?([A-Z]:[/\\][^"'\s]+|\/[^\s"']+\.\w+)["']?/g);
+                if (pathMatch) pathMatch.forEach((p: string) => files.add(p.replace(/["']/g, '')));
+              }
+            }
+          }
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    ctx.lastUserMessage = lastUserMsg;
+    ctx.activeFiles = [...files].slice(-20); // Last 20 unique files
+    ctx.recentTools = tools.slice(-30); // Last 30 tool calls
+    ctx.currentTask = lastUserMsg || 'Unknown task (auto-checkpoint)';
+  } catch {
+    ctx.currentTask = 'Auto-checkpoint (transcript unavailable)';
+  }
+
+  return ctx;
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.on('error', reject);
+  });
+}
+
+function json(res: ServerResponse, status: number, body: Record<string, unknown>) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+export function startSidecar(deps: SidecarDeps): { close: () => void } {
+  const { store, agentId, secret, port, onConsolidate } = deps;
+
+  const server = createServer(async (req, res) => {
+    // CORS preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Health check — no auth required
+    if (req.url === '/health' && req.method === 'GET') {
+      json(res, 200, { status: 'ok', sidecar: true, agentId });
+      return;
+    }
+
+    // Auth check
+    if (secret) {
+      const auth = req.headers.authorization;
+      if (auth !== `Bearer ${secret}`) {
+        json(res, 401, { error: 'Unauthorized' });
+        return;
+      }
+    }
+
+    // POST /hooks/checkpoint — auto-checkpoint from hook events
+    if (req.url === '/hooks/checkpoint' && req.method === 'POST') {
+      try {
+        const body = await readBody(req);
+        const hookInput: HookInput = body ? JSON.parse(body) : {};
+        const event = hookInput.hook_event_name ?? 'unknown';
+
+        // Parse transcript for rich context
+        let ctx: TranscriptContext | null = null;
+        if (hookInput.transcript_path) {
+          ctx = parseTranscript(hookInput.transcript_path);
+        }
+
+        // Build checkpoint state
+        const state: ConsciousState = {
+          currentTask: ctx?.currentTask ?? `Auto-checkpoint (${event})`,
+          decisions: [],
+          activeFiles: ctx?.activeFiles ?? [],
+          nextSteps: [],
+          relatedMemoryIds: [],
+          notes: `Auto-saved by ${event} hook.${ctx?.recentTools.length ? ` Recent tools: ${[...new Set(ctx.recentTools)].join(', ')}` : ''}`,
+          episodeId: null,
+        };
+
+        store.saveCheckpoint(agentId, state);
+        log(agentId, `hook:${event}`, `auto-checkpoint files=${state.activeFiles.length} task="${state.currentTask.slice(0, 80)}"`);
+
+        // On SessionEnd: run full consolidation (sleep cycle) before process dies
+        let consolidated = false;
+        if (event === 'SessionEnd' && onConsolidate) {
+          try {
+            onConsolidate(agentId, `SessionEnd hook (graceful exit)`);
+            consolidated = true;
+            log(agentId, 'consolidation', 'full sleep cycle on graceful exit');
+          } catch { /* consolidation failure is non-fatal */ }
+        }
+
+        // Return context for Claude (stdout from hooks is visible)
+        json(res, 200, {
+          status: 'checkpointed',
+          event,
+          task: state.currentTask,
+          files: state.activeFiles.length,
+          consolidated,
+        });
+      } catch (err) {
+        json(res, 500, { error: 'Checkpoint failed', detail: String(err) });
+      }
+      return;
+    }
+
+    // 404
+    json(res, 404, { error: 'Not found' });
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    console.error(`AWM hook sidecar listening on 127.0.0.1:${port}`);
+  });
+
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`AWM hook sidecar: port ${port} in use, hooks disabled`);
+    } else {
+      console.error('AWM hook sidecar error:', err.message);
+    }
+  });
+
+  return {
+    close: () => {
+      server.close();
+    },
+  };
+}

package/src/mcp.ts

@@ -51,17 +51,41 @@ 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 } from './core/salience.js';
+import { evaluateSalience, computeNovelty } from './core/salience.js';
 import type { ConsciousState } from './types/checkpoint.js';
 import type { SalienceEventType } from './core/salience.js';
 import type { TaskStatus, TaskPriority } from './types/engram.js';
 import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
 import { embed } from './core/embeddings.js';
+import { startSidecar } from './hooks/sidecar.js';
+import { initLogger, log, getLogPath } from './core/logger.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: '0.4.0' });
+  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 DB_PATH = process.env.AWM_DB_PATH ?? 'memory.db';
 const AGENT_ID = process.env.AWM_AGENT_ID ?? 'claude-code';
+const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
+const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
+
+initLogger(DB_PATH);
+log(AGENT_ID, 'startup', `MCP server starting (db: ${DB_PATH}, hooks: ${HOOK_PORT})`);
 
 const store = new EngramStore(DB_PATH);
 const activationEngine = new ActivationEngine(store);
@@ -78,7 +102,7 @@ consolidationScheduler.start();
 
 const server = new McpServer({
   name: 'agent-working-memory',
-  version: '0.3.0',
+  version: '0.4.0',
 });
 
 // --- Tools ---
@@ -87,11 +111,12 @@ 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.
 
-Use this when you learn something that might be useful later:
-- Discoveries about the codebase, bugs, or architecture
-- Decisions you made and why
-- Errors encountered and how they were resolved
-- User preferences or project patterns
+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.`,
   {
@@ -111,6 +136,9 @@ The concept should be a short label (3-8 words). The content should be the full
       .describe('How much effort to resolve? 0=trivial, 1=significant debugging'),
   },
   async (params) => {
+    // Check novelty — is this new information or a duplicate?
+    const novelty = computeNovelty(store, AGENT_ID, params.concept, params.content);
+
     const salience = evaluateSalience({
       content: params.content,
       eventType: params.event_type as SalienceEventType,
@@ -118,13 +146,15 @@ The concept should be a short label (3-8 words). The content should be the full
       decisionMade: params.decision_made,
       causalDepth: params.causal_depth,
       resolutionEffort: params.resolution_effort,
+      novelty,
     });
 
     if (salience.disposition === 'discard') {
+      log(AGENT_ID, 'write:discard', `"${params.concept}" salience=${salience.score.toFixed(2)} novelty=${novelty.toFixed(1)}`);
       return {
         content: [{
           type: 'text' as const,
-          text: `Memory discarded (salience ${salience.score.toFixed(2)} below threshold). Not worth storing.`,
+          text: `Memory discarded (salience ${salience.score.toFixed(2)} below threshold, novelty ${novelty.toFixed(1)}). Not worth storing.`,
         }],
       };
     }
@@ -154,6 +184,8 @@ The concept should be a short label (3-8 words). The content should be the full
     // Auto-checkpoint: track write
     try { store.updateAutoCheckpointWrite(AGENT_ID, engram.id); } catch { /* non-fatal */ }
 
+    log(AGENT_ID, `write:${salience.disposition}`, `"${params.concept}" salience=${salience.score.toFixed(2)} novelty=${novelty.toFixed(1)} id=${engram.id}`);
+
     return {
       content: [{
         type: 'text' as const,
@@ -165,16 +197,19 @@ The concept should be a short label (3-8 words). The content should be the full
 
 server.tool(
   'memory_recall',
-  `Recall memories relevant to a context. Uses cognitive activation — not keyword search.
+  `Recall memories relevant to a query. Uses cognitive activation — not keyword search.
 
-Use this when you need to remember something:
-- Starting a new task (recall relevant past experience)
+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
 
-Returns the most relevant memories ranked by a composite score of text relevance, temporal recency, and associative strength.`,
+Accepts either "query" or "context" parameter — both work identically.
+Returns the most relevant memories ranked by text relevance, temporal recency, and associative strength.`,
   {
-    context: z.string().describe('What are you thinking about? Describe the current situation or question'),
+    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(5).describe('Max memories to return (default 5)'),
     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?'),
@@ -182,9 +217,18 @@ Returns the most relevant memories ranked by a composite score of text relevance
     use_expansion: z.boolean().optional().default(true).describe('Expand query with synonyms for better recall (default true)'),
   },
   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.',
+        }],
+      };
+    }
     const results = await activationEngine.activate({
       agentId: AGENT_ID,
-      context: params.context,
+      context: queryText,
       limit: params.limit,
       minScore: params.min_score,
       includeStaging: params.include_staging,
@@ -195,9 +239,11 @@ Returns the most relevant memories ranked by a composite score of text relevance
     // Auto-checkpoint: track recall
     try {
       const ids = results.map(r => r.engram.id);
-      store.updateAutoCheckpointRecall(AGENT_ID, params.context, ids);
+      store.updateAutoCheckpointRecall(AGENT_ID, queryText, ids);
     } catch { /* non-fatal */ }
 
+    log(AGENT_ID, 'recall', `"${queryText.slice(0, 80)}" → ${results.length} results`);
+
     if (results.length === 0) {
       return {
         content: [{
@@ -286,10 +332,12 @@ Use this when you discover a memory contains incorrect information.`,
 
 server.tool(
   'memory_stats',
-  `Get memory health stats — how many memories, confidence levels, association count, and system performance.`,
+  `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 = evalEngine.computeMetrics(AGENT_ID);
+    const checkpoint = store.getCheckpoint(AGENT_ID);
     const lines = [
       `Agent: ${AGENT_ID}`,
       `Active memories: ${metrics.activeEngramCount}`,
@@ -300,6 +348,14 @@ server.tool(
       `Edge utility: ${(metrics.edgeUtilityRate * 100).toFixed(1)}%`,
       `Activations (24h): ${metrics.activationCount}`,
       `Avg latency: ${metrics.avgLatencyMs.toFixed(1)}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'}`,
+      `Hook sidecar: 127.0.0.1:${HOOK_PORT}`,
     ];
 
     return {
@@ -317,12 +373,12 @@ server.tool(
   'memory_checkpoint',
   `Save your current execution state so you can recover after context compaction.
 
-Use this when:
-- You're about to do something that might fill the context window
-- You've made important decisions you don't want to lose
-- You want to preserve your working state before a long operation
+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
 
-The state is saved per-agent and overwrites any previous checkpoint.`,
+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([])
@@ -350,6 +406,7 @@ The state is saved per-agent and overwrites any previous checkpoint.`,
     };
 
     store.saveCheckpoint(AGENT_ID, state);
+    log(AGENT_ID, 'checkpoint', `"${params.current_task}" decisions=${params.decisions.length} files=${params.active_files.length}`);
 
     return {
       content: [{
@@ -414,18 +471,44 @@ Use this at the start of every session or after compaction to pick up where you
       } catch { /* recall failure is non-fatal */ }
     }
 
-    // Trigger mini-consolidation if idle >5min
+    // 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) {
-      miniConsolidationTriggered = true;
-      consolidationScheduler.runMiniConsolidation(AGENT_ID).catch(() => {});
+      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 = consolidationEngine.consolidate(AGENT_ID);
+          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);
-    parts.push(`Idle: ${idleMin}min${miniConsolidationTriggered ? ' (mini-consolidation triggered)' : ''}`);
+    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 (checkpoint?.executionState) {
       const s = checkpoint.executionState;
@@ -437,6 +520,7 @@ Use this at the start of every session or after compaction to pick up where you
       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) {
@@ -620,16 +704,182 @@ Use this when you finish a task or need to decide what to do next.`,
   }
 );
 
+// --- 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 = store.getCheckpoint(AGENT_ID);
+    const prevTask = checkpoint?.executionState?.currentTask ?? 'None';
+
+    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,
+        limit: 5,
+        minScore: 0.05,
+        useReranker: true,
+        useExpansion: true,
+      });
+
+      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
+        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: `Task started: ${params.topic}\nCheckpoint saved (previous: ${prevTask}).${params.files.length ? `\nFiles: ${params.files.join(', ')}` : ''}${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'),
+  },
+  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,
+    });
+
+    const engram = store.createEngram({
+      agentId: AGENT_ID,
+      concept: 'Task completed',
+      content: params.summary,
+      tags: [...params.tags, 'task-summary'],
+      salience: Math.max(salience.score, 0.7), // Always high salience for task summaries
+      salienceFeatures: salience.features,
+      reasonCodes: [...salience.reasonCodes, 'task-end'],
+    });
+
+    connectionEngine.enqueue(engram.id);
+
+    // Generate embedding asynchronously
+    embed(`Task completed: ${params.summary}`).then(vec => {
+      store.updateEmbedding(engram.id, vec);
+    }).catch(() => {});
+
+    // 2. Update checkpoint to reflect completion
+    const checkpoint = store.getCheckpoint(AGENT_ID);
+    const completedTask = checkpoint?.executionState?.currentTask ?? 'Unknown task';
+
+    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,
+    });
+
+    store.updateAutoCheckpointWrite(AGENT_ID, engram.id);
+    log(AGENT_ID, 'task:end', `"${completedTask}" summary=${engram.id} salience=${salience.score.toFixed(2)}`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Task completed and saved.\nSummary memory: ${engram.id}\nSalience: ${salience.score.toFixed(2)}\nCheckpoint updated.`,
+      }],
+    };
+  }
+);
+
 // --- 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,
+    onConsolidate: (agentId, reason) => {
+      console.error(`[mcp] consolidation triggered: ${reason}`);
+      const result = consolidationEngine.consolidate(agentId);
+      store.markConsolidation(agentId, false);
+      console.error(`[mcp] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
+    },
+  });
+
   // Log to stderr (stdout is reserved for MCP protocol)
   console.error(`AgentWorkingMemory MCP server started (agent: ${AGENT_ID}, db: ${DB_PATH})`);
+  console.error(`Hook sidecar on 127.0.0.1:${HOOK_PORT}${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
+
+  // Clean shutdown
+  const cleanup = () => {
+    sidecar.close();
+    consolidationScheduler.stop();
+    stagingBuffer.stop();
+    store.close();
+  };
+  process.on('SIGINT', () => { cleanup(); process.exit(0); });
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
 }
 
 main().catch(err => {
   console.error('MCP server failed:', err);
   process.exit(1);
 });
+
+} // end else (non-incognito)