create-walle 0.9.13 → 0.9.15

package/template/wall-e/mcp-server.js

@@ -4,23 +4,249 @@ const path = require('node:path');
 const { v4: uuidv4 } = require('uuid');
 const brain = require('./brain');
 const { createSessionIngestService } = require('./memory/session-ingest-service');
+const ctmSessionContext = require('./memory/ctm-session-context');
+const ctmContextClient = require('./memory/ctm-context-client');
 const { collectIngestRecords } = require('./sources/base');
 const { ensureBuiltinSourceAdapters } = require('./sources/builtin');
 const sourceRegistry = require('./sources/registry');
 const { RECORD_TYPES } = require('./sources/record-types');
+const { wallEAgentMemoryInstructions } = require('./lib/mcp-integration');
 let _embeddings;
 try { _embeddings = require('./embeddings'); } catch { _embeddings = null; }
 
 const PROTOCOL_VERSION = '2025-03-26';
 
+const MCP_RESOURCES = [
+  {
+    uri: 'walle://status/session-memory',
+    name: 'Wall-E session memory status',
+    description: 'Operational status for Wall-E brain memory and CTM cached session-context access.',
+    mimeType: 'application/json',
+  },
+];
+
+const MCP_RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: 'walle-session://ctm/{session_id}/full',
+    name: 'CTM session full context',
+    description: 'Full cached CTM session context from session_conversations/session_messages. Use for explicit session transfer.',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'walle-session://ctm/{session_id}/compact',
+    name: 'CTM session compact context',
+    description: 'Prompt-friendly markdown view of cached CTM session context.',
+    mimeType: 'text/markdown',
+  },
+  {
+    uriTemplate: 'walle-context://task/{query}',
+    name: 'Task-scoped CTM context pack',
+    description: 'Search cached CTM sessions for a task prompt and return a deduplicated context pack.',
+    mimeType: 'text/markdown',
+  },
+];
+
+const MCP_PROMPTS = [
+  {
+    name: 'walle_memory_routing',
+    title: 'Wall-E Memory Routing Policy',
+    description: 'Instructions for when to use Wall-E MCP memory, CTM session context, live tools, or public web search.',
+    arguments: [
+      { name: 'walle_port', description: 'Optional Wall-E port used in the instruction text', required: false },
+    ],
+  },
+  {
+    name: 'walle_coding_resume',
+    title: 'Resume With Wall-E Session Context',
+    description: 'Prompt template for resuming coding work using Wall-E CTM session memory and diary context.',
+    arguments: [
+      { name: 'task', description: 'Current coding task or user request', required: false },
+      { name: 'session_id', description: 'Optional CTM or agent session id to inspect first', required: false },
+    ],
+  },
+];
+
+const ANY_OBJECT_SCHEMA = { type: 'object', additionalProperties: true };
+
+const MEMORY_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    source: { type: 'string' },
+    source_id: { type: 'string' },
+    memory_type: { type: 'string' },
+    content: { type: 'string' },
+    timestamp: { type: 'string' },
+  },
+  additionalProperties: true,
+};
+
+const ROUTE_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    route: { type: 'string' },
+    should_use_walle: { type: 'boolean' },
+    primary_tools: { type: 'array', items: { type: 'string' } },
+    secondary_tools: { type: 'array', items: { type: 'string' } },
+    avoid_tools: { type: 'array', items: { type: 'string' } },
+    avoid_until_memory_miss: { type: 'array', items: { type: 'string' } },
+    reason: { type: 'string' },
+    matched: { type: 'array', items: ANY_OBJECT_SCHEMA },
+  },
+  required: ['route', 'should_use_walle', 'reason', 'matched'],
+  additionalProperties: true,
+};
+
+const SEARCH_MEMORIES_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    results: { type: 'array', items: MEMORY_RESULT_SCHEMA },
+    filters_applied: ANY_OBJECT_SCHEMA,
+    vector_search_used: { type: 'boolean' },
+  },
+  required: ['results', 'filters_applied', 'vector_search_used'],
+  additionalProperties: true,
+};
+
+const LOOKUP_CONTEXT_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    route: ROUTE_OUTPUT_SCHEMA,
+    query: { type: 'string' },
+    memory_results: { type: 'array', items: MEMORY_RESULT_SCHEMA },
+    session_results: { type: 'array', items: ANY_OBJECT_SCHEMA },
+    entity_results: { type: 'array', items: ANY_OBJECT_SCHEMA },
+    context_pack: { anyOf: [ANY_OBJECT_SCHEMA, { type: 'null' }] },
+    sources: ANY_OBJECT_SCHEMA,
+  },
+  required: ['route', 'query', 'sources'],
+  additionalProperties: true,
+};
+
+const TOOL_OUTPUT_SCHEMAS = {
+  walle_route_query: ROUTE_OUTPUT_SCHEMA,
+  walle_lookup_context: LOOKUP_CONTEXT_OUTPUT_SCHEMA,
+  search_memories: SEARCH_MEMORIES_OUTPUT_SCHEMA,
+  remember: {
+    type: 'object',
+    properties: {
+      stored: { type: 'boolean' },
+      id: { type: 'string' },
+    },
+    required: ['stored', 'id'],
+    additionalProperties: true,
+  },
+  walle_memory_status: ANY_OBJECT_SCHEMA,
+  walle_search_sessions: ANY_OBJECT_SCHEMA,
+  walle_get_session: ANY_OBJECT_SCHEMA,
+  walle_context_pack: ANY_OBJECT_SCHEMA,
+  walle_diary_write: ANY_OBJECT_SCHEMA,
+  walle_diary_read: ANY_OBJECT_SCHEMA,
+};
+
+const READ_ONLY_TOOL_ANNOTATION = Object.freeze({
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+});
+
+const ADDITIVE_WRITE_TOOL_ANNOTATION = Object.freeze({
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false,
+});
+
+const IDEMPOTENT_WRITE_TOOL_ANNOTATION = Object.freeze({
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+});
+
+const TOOL_ANNOTATIONS = {
+  walle_route_query: READ_ONLY_TOOL_ANNOTATION,
+  walle_lookup_context: READ_ONLY_TOOL_ANNOTATION,
+  search_memories: READ_ONLY_TOOL_ANNOTATION,
+  remember: ADDITIVE_WRITE_TOOL_ANNOTATION,
+  list_knowledge: READ_ONLY_TOOL_ANNOTATION,
+  list_people: READ_ONLY_TOOL_ANNOTATION,
+  get_brief: READ_ONLY_TOOL_ANNOTATION,
+  ask_walle: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  entity_search: READ_ONLY_TOOL_ANNOTATION,
+  entity_graph: READ_ONLY_TOOL_ANNOTATION,
+  knowledge_timeline: READ_ONLY_TOOL_ANNOTATION,
+  knowledge_query: READ_ONLY_TOOL_ANNOTATION,
+  dedup_scan: READ_ONLY_TOOL_ANNOTATION,
+  export_brain: READ_ONLY_TOOL_ANNOTATION,
+  brain_stats: READ_ONLY_TOOL_ANNOTATION,
+  walle_memory_status: READ_ONLY_TOOL_ANNOTATION,
+  walle_list_sources: READ_ONLY_TOOL_ANNOTATION,
+  walle_source_ingest: ADDITIVE_WRITE_TOOL_ANNOTATION,
+  walle_search_sessions: READ_ONLY_TOOL_ANNOTATION,
+  walle_get_session: READ_ONLY_TOOL_ANNOTATION,
+  walle_context_pack: READ_ONLY_TOOL_ANNOTATION,
+  walle_diary_write: IDEMPOTENT_WRITE_TOOL_ANNOTATION,
+  walle_diary_read: READ_ONLY_TOOL_ANNOTATION,
+  walle_reconnect: IDEMPOTENT_WRITE_TOOL_ANNOTATION,
+  walle_repair_status: READ_ONLY_TOOL_ANNOTATION,
+  walle_rebuild_ctm_message_index: IDEMPOTENT_WRITE_TOOL_ANNOTATION,
+  walle_rebuild_source_index: IDEMPOTENT_WRITE_TOOL_ANNOTATION,
+};
+
 const MCP_TOOLS = [
+  {
+    name: 'walle_route_query',
+    description: 'Classify whether a user request should use Wall-E memory/session tools, live source tools, or public web search. Use when unsure before choosing web/search for private, remembered, work, or prior-session context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The user request or task to route' },
+        context: { type: 'string', description: 'Optional nearby conversation context' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'walle_lookup_context',
+    description: 'One-stop Wall-E context lookup. Routes the request, then returns the most relevant private memory, entity, and CTM session context when Wall-E should be used. Use before public web search for ambiguous private/work-context requests.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The user request or task to look up' },
+        context: { type: 'string', description: 'Optional nearby conversation context' },
+        limit: { type: 'number', description: 'Max memories/session snippets/entities per source (default 5, max 20)' },
+        include_memories: { type: 'boolean', description: 'Include Wall-E memory search results (default true when route needs Wall-E)' },
+        include_sessions: { type: 'boolean', description: 'Include CTM coding-session context (default true for session routes)' },
+        include_entities: { type: 'boolean', description: 'Include knowledge-graph entity matches (default true for people/work routes)' },
+        entity_name: { type: 'string', description: 'Optional explicit entity/person/project/tool name to look up' },
+        force_memory: { type: 'boolean', description: 'Search Wall-E memory even when routing says live/public/direct' },
+        prefer_db: { type: 'boolean', description: 'Prefer cached CTM DB for session context (default true)' },
+        source: { type: 'string', description: 'Optional memory source filter' },
+        memory_type: { type: 'string', description: 'Optional memory_type filter' },
+        since: { type: 'string', description: 'Optional inclusive ISO timestamp lower bound for memory results' },
+        until: { type: 'string', description: 'Optional inclusive ISO timestamp upper bound for memory results' },
+      },
+      required: ['query'],
+    },
+  },
   {
     name: 'search_memories',
-    description: "Search across all of Wall-E's ingested memories (Slack, email, calendar, files). Returns matching memories sorted by recency.",
+    description: "Search Wall-E's private/user memory across ingested Slack, email, calendar, files, and work context. Use before public web search for remembered context, prior discussions, decisions, preferences, people, projects, tools, or 'do you know' / 'what did we discuss' questions.",
     inputSchema: {
       type: 'object',
       properties: {
         query: { type: 'string', description: 'Search query (space-separated terms, all must match)' },
+        source: { type: 'string', description: 'Optional source filter, e.g. slack, email, calendar, ctm, walle-diary, codex-jsonl' },
+        memory_type: { type: 'string', description: 'Optional memory_type filter, e.g. message, email, agent_diary, coding_session_user_message' },
+        since: { type: 'string', description: 'Optional inclusive ISO timestamp lower bound' },
+        until: { type: 'string', description: 'Optional inclusive ISO timestamp upper bound' },
         limit: { type: 'number', description: 'Max results to return (default 20, max 200)' },
       },
       required: ['query'],
@@ -72,7 +298,7 @@ const MCP_TOOLS = [
   },
   {
     name: 'ask_walle',
-    description: 'Ask Wall-E a question. Uses the full chat pipeline with context from memories, knowledge, and conversation history. Good for complex questions that need reasoning across stored information.',
+    description: 'Ask Wall-E a question through the full memory-aware chat pipeline. Use for complex private/work-context questions that need reasoning across stored memories, knowledge, people, projects, and conversation history.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -83,7 +309,7 @@ const MCP_TOOLS = [
   },
   {
     name: 'entity_search',
-    description: 'Search for entities (people, projects, tools, orgs) in Wall-E\'s knowledge graph by name or type.',
+    description: 'Search for entities (people, projects, tools, orgs, concepts) in Wall-E\'s private knowledge graph by name or type. Use for user-context lookups before public web search.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -181,7 +407,7 @@ const MCP_TOOLS = [
   },
   {
     name: 'walle_source_ingest',
-    description: 'Ingest a source file through a Wall-E source adapter. Use dry_run first when inspecting an unfamiliar source.',
+    description: 'Ingest a source file through a Wall-E source adapter. Use dry_run first when inspecting an unfamiliar source; set confirm_write=true for non-dry-run ingestion.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -192,6 +418,7 @@ const MCP_TOOLS = [
         privacy_class: { type: 'string', description: 'Optional source privacy class' },
         privacy_floor: { type: 'string', description: 'Optional maximum privacy class allowed to write' },
         dry_run: { type: 'boolean', description: 'Parse and validate without writing memories' },
+        confirm_write: { type: 'boolean', description: 'Required when dry_run is false because ingestion writes Wall-E memories' },
         metadata: { type: 'object', description: 'Optional adapter metadata' },
       },
       required: ['adapter_id', 'uri'],
@@ -199,30 +426,54 @@ const MCP_TOOLS = [
   },
   {
     name: 'walle_search_sessions',
-    description: 'Search ingested coding sessions and Wall-E diary entries. Returns attributed snippets plus session pointers.',
+    description: 'Search coding-session history. Tries cached CTM DB session messages first, then ingested Wall-E memories/diary entries. Returns deduplicated attributed snippets plus session pointers.',
     inputSchema: {
       type: 'object',
       properties: {
         query: { type: 'string', description: 'Search query' },
         limit: { type: 'number', description: 'Max session snippets (default 10, max 50)' },
+        prefer_db: { type: 'boolean', description: 'Try cached CTM DB tables before Wall-E memory (default true)' },
+        include_memory: { type: 'boolean', description: 'Also search Wall-E ingested memories and diary entries (default true)' },
       },
       required: ['query'],
     },
   },
   {
     name: 'walle_get_session',
-    description: 'Retrieve session snippets from ingested memory, or parse a JSONL session directly when adapter_id and uri are provided.',
+    description: 'Retrieve cached CTM session context by session id/source id, or parse a JSONL session directly when adapter_id and uri are provided. DB tables are preferred for full context transfer.',
     inputSchema: {
       type: 'object',
       properties: {
+        session_id: { type: 'string', description: 'CTM session id or agent session id to retrieve from cached DB tables' },
+        session_ids: { type: 'array', items: { type: 'string' }, description: 'Several CTM/agent session ids to retrieve together' },
         source_id: { type: 'string', description: 'Stable source/session id to retrieve from memory' },
         adapter_id: { type: 'string', description: 'Optional adapter id for direct JSONL parse' },
         uri: { type: 'string', description: 'Optional JSONL path for direct parse' },
-        limit: { type: 'number', description: 'Max records (default 50, max 200)' },
+        limit: { type: 'number', description: 'Max records/messages (default 50 for memory, 200 for CTM DB; use 0/full/all for all cached DB messages)' },
+        cursor: { type: 'number', description: 'Message offset for cached DB pagination' },
+        format: { type: 'string', description: 'Cached DB output format: messages, markdown, or compact' },
+        dedupe: { type: 'boolean', description: 'Deduplicate repeated message content (default true)' },
+        prefer_db: { type: 'boolean', description: 'Use cached CTM DB tables before Wall-E memory fallback (default true)' },
         include_raw: { type: 'boolean', description: 'Include raw content when available' },
       },
     },
   },
+  {
+    name: 'walle_context_pack',
+    description: 'Build a deduplicated task-scoped context pack from cached CTM session history. Use before answering or starting a coding task when the user references prior attempts, old bugs, branches, decisions, restarts, or past agent work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'Current user prompt or task description' },
+        query: { type: 'string', description: 'Optional explicit search query; defaults to task' },
+        session_ids: { type: 'array', items: { type: 'string' }, description: 'Optional CTM/agent session ids to force include' },
+        limit: { type: 'number', description: 'Max sessions to include (default 5, max 50)' },
+        token_budget: { type: 'number', description: 'Approximate context-pack token budget (default 12000)' },
+        mode: { type: 'string', description: 'auto, compact, or full' },
+        include_raw: { type: 'boolean', description: 'Include raw cached messages when mode/full transfer needs exact source payloads' },
+      },
+    },
+  },
   {
     name: 'walle_diary_write',
     description: 'Write an idempotent agent diary entry for a coding session stop, handoff, or compaction boundary.',
@@ -272,26 +523,72 @@ const MCP_TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'walle_rebuild_ctm_message_index',
+    description: 'Ask the CTM API to backfill session_messages and FTS rows from cached session_conversations. Use dry_run first to inspect planned work; set confirm_write=true for writes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Max session_conversations rows to repair (default 100, max 1000)' },
+        dry_run: { type: 'boolean', description: 'Plan the repair without writing (default false)' },
+        confirm_write: { type: 'boolean', description: 'Required when dry_run is false because rebuild writes CTM index rows' },
+      },
+    },
+  },
   {
     name: 'walle_rebuild_source_index',
-    description: 'Rebuild the memory/source index from stored memories. Use dry_run to inspect expected work without writing.',
+    description: 'Rebuild the memory/source index from stored memories. Use dry_run to inspect expected work without writing; set confirm_write=true for writes.',
     inputSchema: {
       type: 'object',
       properties: {
         source_id: { type: 'string', description: 'Optional stable source/session id to rebuild' },
         dry_run: { type: 'boolean', description: 'Return current index status without rebuilding' },
+        confirm_write: { type: 'boolean', description: 'Required when dry_run is false because rebuild writes Wall-E source-index rows' },
       },
     },
   },
 ];
 
+function toolTitle(name) {
+  return String(name || '')
+    .split('_')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function applyMcpToolMetadata(tools) {
+  for (const tool of tools) {
+    const annotations = TOOL_ANNOTATIONS[tool.name] || READ_ONLY_TOOL_ANNOTATION;
+    tool.annotations = { title: toolTitle(tool.name), ...annotations };
+    if (TOOL_OUTPUT_SCHEMAS[tool.name]) {
+      tool.outputSchema = TOOL_OUTPUT_SCHEMAS[tool.name];
+    }
+  }
+}
+
+applyMcpToolMetadata(MCP_TOOLS);
+
 async function executeTool(name, args) {
   switch (name) {
+    case 'walle_route_query': {
+      return routeWallEQuery(args.query, { context: args.context });
+    }
+    case 'walle_lookup_context': {
+      return lookupWallEContext(args);
+    }
     case 'search_memories': {
       const limit = args.limit || 20;
-      let results = brain.searchMemories({ query: args.query, limit });
+      const filters = {
+        source: args.source,
+        memory_type: args.memory_type,
+        since: args.since,
+        until: args.until,
+      };
+      const hasFilters = Object.values(filters).some(Boolean);
+      let results = brain.searchMemories({ query: args.query, limit, ...filters });
       // Hybrid: merge with vector results if embeddings available
-      if (_embeddings && _embeddings.isAvailable()) {
+      if (!hasFilters && _embeddings && _embeddings.isAvailable()) {
         try {
           const queryEmb = await _embeddings.computeEmbedding(args.query);
           if (queryEmb) {
@@ -302,7 +599,11 @@ async function executeTool(name, args) {
           }
         } catch {}
       }
-      return { results: results.map(m => ({ id: m.id, source: m.source, content: m.content, timestamp: m.timestamp })) };
+      return {
+        results: results.map(formatMemoryResult),
+        filters_applied: Object.fromEntries(Object.entries(filters).filter(([, value]) => Boolean(value))),
+        vector_search_used: Boolean(!hasFilters && _embeddings && _embeddings.isAvailable()),
+      };
     }
     case 'remember': {
       const result = brain.insertKnowledge({
@@ -412,6 +713,11 @@ async function executeTool(name, args) {
       return {
         ok: true,
         stats,
+        ctm_db: await getCtmDbStatus(),
+        resources: {
+          static: MCP_RESOURCES.map((resource) => resource.uri),
+          templates: MCP_RESOURCE_TEMPLATES.map((template) => template.uriTemplate),
+        },
         source_adapters: sourceRegistry.list().map(formatSourceAdapter),
         diary_count: countDiaryEntries(),
         tools: MCP_TOOLS.filter((tool) => tool.name.startsWith('walle_')).map((tool) => tool.name),
@@ -428,6 +734,7 @@ async function executeTool(name, args) {
     }
     case 'walle_source_ingest': {
       ensureBuiltinSourceAdapters();
+      requireWriteConfirmation('walle_source_ingest', args);
       assertJsonlPath(args.uri);
       const sourceRef = {
         adapterId: args.adapter_id,
@@ -446,11 +753,52 @@ async function executeTool(name, args) {
     }
     case 'walle_search_sessions': {
       const limit = clampLimit(args.limit, 10, 50);
-      const results = brain.searchMemories({ query: args.query, limit: limit * 4 })
-        .filter(isSessionMemory)
-        .slice(0, limit)
-        .map(formatSessionMemory);
-      return { results };
+      const ctmResults = args.prefer_db === false
+        ? { ok: false, results: [], skipped: true, reason: 'prefer_db_false' }
+        : await safeCtmSearchSessions({ query: args.query, limit });
+      const memoryResults = args.include_memory === false
+        ? []
+        : brain.searchMemories({ query: args.query, limit: limit * 4 })
+          .filter(isSessionMemory)
+          .slice(0, limit * 2)
+          .map((memory, index) => ({
+            ...formatSessionMemory(memory),
+            source_layer: 'wall-e-memory',
+            rank: 10000 + index,
+          }));
+      const ctmSourceLayer = ctmResults.source === 'ctm-api' ? 'ctm-api' : 'ctm-db';
+      const dbResults = (ctmResults.results || []).map((result, index) => ({
+        ...result,
+        source_layer: ctmSourceLayer,
+        rank: Number.isFinite(result.rank) ? result.rank : index,
+      }));
+      const results = ctmSessionContext.dedupeItems([...dbResults, ...memoryResults], {
+        limit,
+        contentFields: ['snippet', 'content'],
+        keyPrefix: (item) => `${item.session_id || item.source_id || ''}:${item.role || item.memory_type || ''}`,
+      }).map(stripRank);
+      return {
+        results,
+        sources: {
+          ctm_db: {
+            ok: Boolean(ctmResults.ok),
+            unavailable: Boolean(ctmResults.unavailable),
+            source: ctmResults.source || '',
+            backend_source: ctmResults.backend_source || '',
+            api_transport: ctmResults.api_transport || null,
+            db_path: ctmResults.db_path || '',
+            active_source: ctmResults.active_source || '',
+            fallback_used: Boolean(ctmResults.fallback_used),
+            reason: ctmResults.reason || '',
+            count: (ctmResults.results || []).length,
+          },
+          wall_e_memory: {
+            searched: args.include_memory !== false,
+            count: memoryResults.length,
+          },
+        },
+        deduped: true,
+      };
     }
     case 'walle_get_session': {
       const limit = clampLimit(args.limit, 50, 200);
@@ -475,12 +823,47 @@ async function executeTool(name, args) {
             .map((record) => formatSourceRecord(record, { includeRaw: Boolean(args.include_raw) })),
         };
       }
+      const wantsDb = args.prefer_db !== false;
+      const dbSessionIds = args.session_ids || args.session_id || args.source_id;
+      if (wantsDb && dbSessionIds) {
+        const dbContext = await safeCtmSessionContext({
+          session_ids: args.session_ids,
+          session_id: args.session_id,
+          source_id: args.source_id,
+          limit: args.limit ?? 200,
+          cursor: args.cursor || 0,
+          include_raw: Boolean(args.include_raw),
+          dedupe: args.dedupe !== false,
+          format: args.format || 'messages',
+        });
+        if (dbContext.ok && (dbContext.sessions.length > 0 || dbContext.messages.length > 0)) {
+          return dbContext;
+        }
+        if (args.session_id || args.session_ids) return dbContext;
+      }
       if (!args.source_id) throw new Error('source_id is required when adapter_id and uri are not provided');
       return {
         source_id: args.source_id,
+        transfer: {
+          full_context_supported: false,
+          served_from: 'wall-e-memory',
+          jsonl_fallback_used: false,
+          ctm_db_preferred: wantsDb,
+        },
         records: getSessionMemories(args.source_id, { limit }).map(formatSessionMemory),
       };
     }
+    case 'walle_context_pack': {
+      return await safeCtmContextPack({
+        task: args.task || '',
+        query: args.query || '',
+        session_ids: args.session_ids,
+        limit: args.limit || 5,
+        token_budget: args.token_budget || 12000,
+        mode: args.mode || 'auto',
+        include_raw: Boolean(args.include_raw),
+      });
+    }
     case 'walle_diary_write': {
       return writeDiaryEntry(args);
     }
@@ -495,7 +878,15 @@ async function executeTool(name, args) {
       const repair = require('./utils/repair');
       return repair.scanIntegrity();
     }
+    case 'walle_rebuild_ctm_message_index': {
+      requireWriteConfirmation('walle_rebuild_ctm_message_index', args);
+      return ctmContextClient.backfillMessageIndex({
+        limit: args.limit || 100,
+        dry_run: Boolean(args.dry_run),
+      });
+    }
     case 'walle_rebuild_source_index': {
+      requireWriteConfirmation('walle_rebuild_source_index', args);
       const { rebuildSourceIndex } = require('./memory/source-indexer');
       return rebuildSourceIndex({
         brain,
@@ -508,12 +899,281 @@ async function executeTool(name, args) {
   }
 }
 
+function routeWallEQuery(query, opts = {}) {
+  const text = `${query || ''}\n${opts.context || ''}`.toLowerCase();
+  const has = (patterns) => patterns.some(pattern => pattern.test(text));
+  const matched = [];
+  const add = (name, patterns) => {
+    const hits = patterns.filter(pattern => pattern.test(text)).map(pattern => pattern.source);
+    if (hits.length) matched.push({ name, hits });
+    return hits.length > 0;
+  };
+
+  const explicitWalle = add('explicit_wall_e', [/\bwall-?e\b/, /\bwalle\b/, /\bmcp\b/, /\bmemory\b/, /\bctm\b/]);
+  const priorContext = add('prior_context', [/\blast time\b/, /\bprevious(ly)?\b/, /\bremember\b/, /\bwhat did we (discuss|decide)\b/, /\bwhat happened\b/, /\bfollow.?up\b/, /\bcontext\b/]);
+  const sessionContext = add('session_context', [/\bsession\b/, /\bagent\b/, /\bbranch\b/, /\brestart\b/, /\bresume\b/, /\bhandoff\b/, /\bdiary\b/, /\bbug\b/, /\bregression\b/, /\btitle\b/, /\bcommit\b/]);
+  const workMemory = add('work_memory', [/\bslack\b/, /\bemail\b/, /\bcalendar\b/, /\bcolleague\b/, /\bmanager\b/, /\bteam\b/, /\bproject\b/, /\bdoc(ument)?\b/, /\btool\b/, /\bdecision\b/, /\bpreference\b/]);
+  const personLookup = add('person_lookup', [/\bwho is\b/, /\bdo you know\b/, /\bwhat is .* role\b/, /\breports? to\b/]);
+  const liveAction = add('live_action', [/\bsend\b/, /\bpost\b/, /\bcreate\b/, /\bschedule\b/, /\bopen\b/, /\bdelete\b/, /\bupdate\b/, /\bunread\b/, /\binbox\b/, /\btoday'?s calendar\b/, /\btomorrow'?s calendar\b/]);
+  const publicCurrent = add('public_current', [/\bweb\b/, /\bpublic\b/, /\bnews\b/, /\blatest\b/, /\bcurrent\b/, /\bprice\b/, /\bstock\b/, /\bweather\b/, /\bdocs?\b/, /\bofficial\b/]);
+
+  if (liveAction && !priorContext && !explicitWalle) {
+    return {
+      route: 'live_source_or_action',
+      should_use_walle: false,
+      primary_tools: ['calendar/email/slack/action tools exposed by the host'],
+      secondary_tools: ['search_memories only if the user asks for remembered context'],
+      avoid_tools: ['walle_context_pack', 'walle_search_sessions'],
+      reason: 'The request appears to need live source data or a side-effecting action rather than stored memory.',
+      matched,
+    };
+  }
+
+  if (sessionContext || (explicitWalle && priorContext)) {
+    return {
+      route: 'walle_session_context',
+      should_use_walle: true,
+      primary_tools: ['walle_context_pack', 'walle_search_sessions', 'walle_get_session'],
+      secondary_tools: ['walle_diary_read', 'search_memories'],
+      avoid_until_memory_miss: ['web_search', 'web_fetch'],
+      reason: 'The request appears to depend on prior coding-agent, CTM, branch, bug, restart, or handoff context.',
+      matched,
+    };
+  }
+
+  if (priorContext || workMemory || personLookup || explicitWalle) {
+    return {
+      route: 'walle_private_memory',
+      should_use_walle: true,
+      primary_tools: personLookup ? ['entity_search', 'search_memories', 'ask_walle'] : ['search_memories', 'knowledge_query', 'ask_walle'],
+      secondary_tools: ['entity_graph', 'knowledge_timeline'],
+      avoid_until_memory_miss: ['web_search', 'web_fetch'],
+      reason: 'The request appears to depend on private, remembered, or work-context data Wall-E owns.',
+      matched,
+    };
+  }
+
+  if (publicCurrent) {
+    return {
+      route: 'public_or_current_fact',
+      should_use_walle: false,
+      primary_tools: ['web_search', 'web_fetch', 'official docs or public data tools'],
+      secondary_tools: ['search_memories only if the user asks for personal/work context'],
+      avoid_tools: ['walle_context_pack'],
+      reason: 'The request appears to ask for public/current information rather than private memory.',
+      matched,
+    };
+  }
+
+  return {
+    route: 'answer_directly_or_clarify',
+    should_use_walle: false,
+    primary_tools: [],
+    secondary_tools: ['walle_route_query again with more context if uncertain'],
+    reason: 'No strong signal that Wall-E memory, live tools, or public web are required.',
+    matched,
+  };
+}
+
+async function lookupWallEContext(args = {}) {
+  const query = String(args.query || '').trim();
+  if (!query) throw new Error('query is required');
+  const route = routeWallEQuery(query, { context: args.context });
+  const limit = clampLimit(args.limit, 5, 20);
+  const shouldUseWallE = Boolean(route.should_use_walle || args.force_memory);
+  const includeMemories = args.include_memories === true || (args.include_memories !== false && shouldUseWallE);
+  const includeSessions = args.include_sessions === true
+    || (args.include_sessions !== false && route.route === 'walle_session_context');
+  const includeEntities = args.include_entities === true
+    || (args.include_entities !== false && (route.route === 'walle_private_memory' || args.force_memory));
+  const inferredEntityName = String(args.entity_name || inferEntityName(query) || '').trim();
+  const memoryQuery = inferredEntityName || query;
+  const result = {
+    route,
+    query,
+    memory_results: [],
+    session_results: [],
+    entity_results: [],
+    context_pack: null,
+    sources: {
+      memories: { searched: false, count: 0 },
+      ctm_sessions: { searched: false, count: 0 },
+      entities: { searched: false, count: 0 },
+    },
+  };
+
+  if (includeSessions) {
+    const sessionSearch = await safeCtmSearchSessions({
+      query,
+      limit,
+      prefer_db: args.prefer_db !== false,
+    });
+    result.session_results = (sessionSearch.results || []).slice(0, limit).map(stripRank);
+    result.sources.ctm_sessions = {
+      searched: true,
+      ok: Boolean(sessionSearch.ok),
+      source: sessionSearch.source || '',
+      reason: sessionSearch.reason || '',
+      count: result.session_results.length,
+    };
+    result.context_pack = await safeCtmContextPack({
+      task: query,
+      query,
+      limit: Math.min(limit, 5),
+      token_budget: 6000,
+      mode: 'compact',
+      include_raw: false,
+    });
+  }
+
+  if (includeMemories) {
+    const filters = {
+      source: args.source,
+      memory_type: args.memory_type,
+      since: args.since,
+      until: args.until,
+    };
+    result.memory_results = brain.searchMemories({ query: memoryQuery, limit, ...filters }).map(formatMemoryResult);
+    result.sources.memories = {
+      searched: true,
+      query: memoryQuery,
+      filters_applied: Object.fromEntries(Object.entries(filters).filter(([, value]) => Boolean(value))),
+      count: result.memory_results.length,
+    };
+  }
+
+  if (includeEntities) {
+    if (inferredEntityName) {
+      result.entity_results = searchEntitiesForContext(inferredEntityName, limit);
+      result.sources.entities = {
+        searched: true,
+        query: inferredEntityName,
+        count: result.entity_results.length,
+      };
+    } else {
+      result.sources.entities = {
+        searched: false,
+        reason: 'no_entity_name_inferred',
+        count: 0,
+      };
+    }
+  }
+
+  return result;
+}
+
+function inferEntityName(query) {
+  const text = String(query || '').trim();
+  for (const pattern of [
+    /\bdo you know\s+(.+?)[?.!]?$/i,
+    /\bwho is\s+(.+?)[?.!]?$/i,
+    /\bwhat is\s+(.+?)'s role[?.!]?$/i,
+    /\bwhat is the role of\s+(.+?)[?.!]?$/i,
+  ]) {
+    const match = text.match(pattern);
+    if (match?.[1]) {
+      return match[1].replace(/^["']|["']$/g, '').trim();
+    }
+  }
+  return '';
+}
+
+function searchEntitiesForContext(name, limit) {
+  const results = [];
+  const exact = brain.findEntity(name);
+  if (exact) results.push(exact);
+  if (results.length === 0) {
+    const fuzzy = brain.findEntityFuzzy(name);
+    if (fuzzy) results.push(fuzzy);
+  }
+  if (results.length === 0) {
+    const lower = String(name || '').toLowerCase();
+    results.push(...brain.listEntities({ limit }).filter(entity =>
+      String(entity.canonical_name || '').toLowerCase().includes(lower)
+    ));
+  }
+  return results.slice(0, limit).map(entity => ({
+    id: entity.id,
+    name: entity.canonical_name,
+    type: entity.entity_type,
+    aliases: entity.aliases,
+  }));
+}
+
 function clampLimit(value, fallback, max) {
   const n = Number(value || fallback);
   if (!Number.isFinite(n)) return fallback;
   return Math.min(Math.max(Math.trunc(n), 1), max);
 }
 
+function formatMemoryResult(memory) {
+  return {
+    id: memory.id,
+    source: memory.source,
+    source_id: memory.source_id,
+    memory_type: memory.memory_type,
+    content: memory.content,
+    timestamp: memory.timestamp,
+  };
+}
+
+function requireWriteConfirmation(toolName, args = {}) {
+  if (args.dry_run === true || args.confirm_write === true) return;
+  throw new Error(`${toolName} writes Wall-E or CTM state. Run with dry_run=true first, or set confirm_write=true to apply changes.`);
+}
+
+function stripRank(item) {
+  if (!item || typeof item !== 'object') return item;
+  const { rank, ...rest } = item;
+  return rest;
+}
+
+async function getCtmDbStatus() {
+  const health = await ctmContextClient.getHealth();
+  return {
+    available: !health.unavailable,
+    db_path: health.db_path,
+    active_source: health.active_source || '',
+    fallback_used: Boolean(health.fallback_used),
+    serving_priority: health.source === 'ctm-api' ? 'ctm-api-first' : 'ctm-db-first',
+    source: health.source || 'ctm-db',
+    backend_source: health.backend_source || health.source || 'ctm-db',
+    api_transport: health.api_transport || null,
+    schema_ok: Boolean(health.ok),
+    reason: health.reason || '',
+    error: health.error || '',
+    cached_tables: health.tables || [],
+    expected_tables: ctmSessionContext.CTM_SESSION_TABLES || [],
+    missing_tables: health.missing_tables || [],
+    table_counts: health.table_counts || {},
+    attempts: health.attempts || [],
+  };
+}
+
+async function safeCtmSearchSessions(args) {
+  try {
+    return await ctmContextClient.searchSessions(args);
+  } catch (err) {
+    return { ok: false, source: 'ctm-db', results: [], reason: err.message };
+  }
+}
+
+async function safeCtmSessionContext(args) {
+  try {
+    return await ctmContextClient.getSessionContext(args);
+  } catch (err) {
+    return { ok: false, source: 'ctm-db', sessions: [], messages: [], reason: err.message };
+  }
+}
+
+async function safeCtmContextPack(args) {
+  try {
+    return await ctmContextClient.buildContextPack(args);
+  } catch (err) {
+    return { ok: false, source: 'ctm-db', sessions: [], messages: [], reason: err.message };
+  }
+}
+
 function assertJsonlPath(filePath) {
   if (!filePath || typeof filePath !== 'string') throw new Error('uri must be a JSONL file path');
   if (filePath.split(/[\\/]+/).includes('..')) throw new Error('uri cannot contain traversal segments');
@@ -748,6 +1408,137 @@ function jsonResponse(res, data, status = 200) {
   res.end(body);
 }
 
+async function readMcpResource(uri) {
+  if (!uri || typeof uri !== 'string') throw new Error('resource uri is required');
+
+  if (uri === 'walle://status/session-memory') {
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(await executeTool('walle_memory_status', {})),
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new Error(`Invalid resource uri: ${uri}`);
+  }
+
+  if (parsed.protocol === 'walle-session:' && parsed.hostname === 'ctm') {
+    const [rawSessionId, rawMode] = parsed.pathname.split('/').filter(Boolean);
+    if (!rawSessionId) throw new Error('walle-session resource requires a session id');
+    const sessionId = decodeURIComponent(rawSessionId);
+    const mode = rawMode || 'full';
+    const context = await ctmContextClient.getSessionContext({
+      session_id: sessionId,
+      limit: mode === 'full' || mode === 'messages' ? 0 : 200,
+      format: mode === 'compact' || mode === 'summary' ? 'compact' : 'messages',
+      dedupe: true,
+    });
+    if (mode === 'compact' || mode === 'summary') {
+      return {
+        uri,
+        mimeType: 'text/markdown',
+        text: context.text || ctmSessionContext.renderContextMarkdown(context, { compact: true }),
+      };
+    }
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(context),
+    };
+  }
+
+  if (parsed.protocol === 'walle-context:' && parsed.hostname === 'task') {
+    const task = decodeURIComponent(parsed.pathname.replace(/^\/+/, ''));
+    if (!task) throw new Error('walle-context task resource requires an encoded task query');
+    const pack = await ctmContextClient.buildContextPack({ task, mode: 'compact' });
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: pack.text || ctmSessionContext.renderContextMarkdown(pack, { compact: true }),
+    };
+  }
+
+  throw new Error(`Unknown resource uri: ${uri}`);
+}
+
+function memoryRoutingPromptText(wallePort) {
+  return wallEAgentMemoryInstructions(wallePort)
+    .replace(/<!-- wall-e-memory-routing:start -->\n?/g, '')
+    .replace(/<!-- wall-e-memory-routing:end -->\n?/g, '')
+    .trim();
+}
+
+function readMcpPrompt(name, args = {}) {
+  if (name === 'walle_memory_routing') {
+    const port = Number(args.walle_port || process.env.WALL_E_PORT || 3457);
+    return {
+      description: 'Wall-E MCP memory routing policy',
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: memoryRoutingPromptText(port) },
+      }],
+    };
+  }
+  if (name === 'walle_coding_resume') {
+    const task = String(args.task || '').trim();
+    const sessionId = String(args.session_id || '').trim();
+    const lines = [
+      'Resume this coding work using Wall-E MCP session memory before relying on web search or raw files.',
+      '',
+      'Steps:',
+      '1. If Wall-E health is uncertain, call `walle_memory_status`.',
+      '2. Call `walle_context_pack` with the current task to recover prior attempts, decisions, changed files, and next steps.',
+      '3. If a session id is provided, call `walle_get_session` for exact source context.',
+      '4. Use `walle_search_sessions` for targeted follow-up searches and `walle_diary_read` for recent handoff notes.',
+      '5. Cite returned session ids/timestamps when using retrieved context. Use public web only for public/current facts or after Wall-E misses.',
+    ];
+    if (task) lines.push('', `Task: ${task}`);
+    if (sessionId) lines.push(`Session id: ${sessionId}`);
+    return {
+      description: 'Resume coding work with Wall-E CTM session context',
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: lines.join('\n') },
+      }],
+    };
+  }
+  return null;
+}
+
+function buildToolResourceLinks(toolName, result) {
+  if (!result || typeof result !== 'object') return [];
+  const links = [];
+  const addSession = (sessionId, title) => {
+    if (!sessionId || links.some(link => link.uri.includes(encodeURIComponent(sessionId)))) return;
+    links.push({
+      type: 'resource_link',
+      uri: `walle-session://ctm/${encodeURIComponent(sessionId)}/compact`,
+      name: title || `CTM session ${sessionId}`,
+      description: 'Compact CTM session context linked from Wall-E tool output',
+      mimeType: 'text/markdown',
+      annotations: { audience: ['assistant'], priority: 0.85 },
+    });
+  };
+
+  if (toolName === 'walle_search_sessions') {
+    for (const item of result.results || []) {
+      if (item.source_layer === 'ctm-db' || item.source_layer === 'ctm-api') {
+        addSession(item.session_id, item.title);
+      }
+    }
+  }
+  if (toolName === 'walle_context_pack') {
+    for (const item of result.sessions || []) {
+      addSession(item.session_id || item.id, item.title);
+    }
+  }
+  return links.slice(0, 5);
+}
+
 async function handleMcp(req, res) {
   let msg;
   try {
@@ -775,7 +1566,7 @@ async function handleMcp(req, res) {
         jsonrpc: '2.0', id,
         result: {
           protocolVersion: PROTOCOL_VERSION,
-          capabilities: { tools: {} },
+          capabilities: { tools: {}, resources: {}, prompts: {} },
           serverInfo: { name: 'wall-e', version: (() => { try { return require('./package.json').version; } catch { return '0.0.0'; } })() },
         },
       });
@@ -788,6 +1579,56 @@ async function handleMcp(req, res) {
       });
     }
 
+    case 'resources/list': {
+      return jsonResponse(res, {
+        jsonrpc: '2.0', id,
+        result: { resources: MCP_RESOURCES },
+      });
+    }
+
+    case 'resources/templates/list': {
+      return jsonResponse(res, {
+        jsonrpc: '2.0', id,
+        result: { resourceTemplates: MCP_RESOURCE_TEMPLATES },
+      });
+    }
+
+    case 'prompts/list': {
+      return jsonResponse(res, {
+        jsonrpc: '2.0', id,
+        result: { prompts: MCP_PROMPTS },
+      });
+    }
+
+    case 'prompts/get': {
+      const prompt = readMcpPrompt(params?.name, params?.arguments || {});
+      if (!prompt) {
+        return jsonResponse(res, {
+          jsonrpc: '2.0', id,
+          result: { content: [{ type: 'text', text: `Unknown prompt: ${params?.name}` }], isError: true },
+        });
+      }
+      return jsonResponse(res, {
+        jsonrpc: '2.0', id,
+        result: prompt,
+      });
+    }
+
+    case 'resources/read': {
+      try {
+        const content = await readMcpResource(params?.uri);
+        return jsonResponse(res, {
+          jsonrpc: '2.0', id,
+          result: { contents: [{ uri: content.uri, mimeType: content.mimeType, text: content.text }] },
+        });
+      } catch (err) {
+        return jsonResponse(res, {
+          jsonrpc: '2.0', id,
+          result: { contents: [{ uri: params?.uri || '', mimeType: 'text/plain', text: `Error: ${err.message}` }], isError: true },
+        });
+      }
+    }
+
     case 'tools/call': {
       const toolName = params?.name;
       const toolArgs = params?.arguments || {};
@@ -799,9 +1640,10 @@ async function handleMcp(req, res) {
             result: { content: [{ type: 'text', text: `Unknown tool: ${toolName}` }], isError: true },
           });
         }
+        const content = [{ type: 'text', text: JSON.stringify(result) }].concat(buildToolResourceLinks(toolName, result));
         return jsonResponse(res, {
           jsonrpc: '2.0', id,
-          result: { content: [{ type: 'text', text: JSON.stringify(result) }] },
+          result: { content, structuredContent: result },
         });
       } catch (err) {
         return jsonResponse(res, {
@@ -819,4 +1661,15 @@ async function handleMcp(req, res) {
   }
 }
 
-module.exports = { handleMcp, MCP_TOOLS, executeTool };
+module.exports = {
+  handleMcp,
+  MCP_TOOLS,
+  MCP_RESOURCES,
+  MCP_RESOURCE_TEMPLATES,
+  MCP_PROMPTS,
+  executeTool,
+  lookupWallEContext,
+  readMcpPrompt,
+  readMcpResource,
+  routeWallEQuery,
+};