Claude Code (MCP Client)
    ↕ JSON-RPC over stdio
MCP Server (plugin/scripts/mcp-server.cjs)
    ↕ HTTP
Worker Service (Express API)
    ↕ SQL
SQLite / ChromaDB

1. Claude 决定调用 search 工具
2. Claude Code 向 MCP Server 发送 JSON-RPC 请求：
   {"method":"tools/call","params":{"name":"search","arguments":{"query":"auth bug"}}}
3. MCP Server 将其转换为 HTTP 请求：
   GET http://localhost:37700/api/search?query=auth%20bug
4. Worker 执行 FTS5 查询，返回结果
5. MCP Server 将 HTTP 响应包装为 MCP 响应：
   {"content":[{"type":"text","text":"| ID | Time | Title |..."}]}
6. Claude Code 将结果呈现给 Claude
7. Claude 基于结果决定下一步

search_observations  — 全文搜索
find_by_type        — 按类型过滤
find_by_file        — 按文件过滤
find_by_concept     — 按概念过滤
get_recent_context  — 最近会话
get_observation     — 获取单条
get_session         — 获取会话
get_prompt          — 获取 prompt
help                — API 文档

__IMPORTANT         — 工作流说明（始终可见）
search              — 搜索索引（接受所有参数）
timeline            — 时间线上下文
get_observations    — 批量获取详情

{
  name: '__IMPORTANT',
  description: `3-LAYER WORKFLOW (ALWAYS FOLLOW):
1. search(query) → Get index with IDs (~50-100 tokens/result)
2. timeline(anchor=ID) → Get context around interesting results
3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
NEVER fetch full details without filtering first. 10x token savings.`,
  inputSchema: { type: 'object', properties: {} }
}

// MCP Server 中的 search handler
{
  name: 'search',
  description: 'Step 1: Search memory. Returns index with IDs.',
  inputSchema: {
    type: 'object',
    properties: {},
    additionalProperties: true  // 接受任意参数
  },
  handler: async (args) => {
    const params = new URLSearchParams();
    for (const [key, value] of Object.entries(args)) {
      params.append(key, String(value));
    }
    const response = await fetch(`http://localhost:${port}/api/search?${params}`);
    return await response.json();
  }
}

{
  name: 'timeline',
  description: 'Step 2: Get context around results. Params: anchor OR query, depth_before, depth_after',
  handler: async (args) => {
    const params = new URLSearchParams();
    for (const [key, value] of Object.entries(args)) {
      params.append(key, String(value));
    }
    return await fetch(`http://localhost:${port}/api/timeline?${params}`).then(r => r.json());
  }
}

{
  name: 'get_observations',
  description: 'Step 3: Fetch full details for filtered IDs.',
  inputSchema: {
    type: 'object',
    properties: {
      ids: {
        type: 'array',
        items: { type: 'number' },
        description: 'Array of observation IDs to fetch (required)'
      }
    },
    required: ['ids'],
    additionalProperties: true
  },
  handler: async (args) => {
    return await fetch(`http://localhost:${port}/api/observations/batch`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(args)
    }).then(r => r.json());
  }
}

// 以下为源码逻辑的 ESM 表示（实际分发为编译后的 .cjs 文件）
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
const server = new Server({ name: 'claude-mem-search', version: '1.0.0' });
 
// 注册工具列表
server.setRequestHandler('tools/list', async () => ({
  tools: [
    { name: '__IMPORTANT', description: '...', inputSchema: {...} },
    { name: 'search', description: '...', inputSchema: {...} },
    { name: 'timeline', description: '...', inputSchema: {...} },
    { name: 'get_observations', description: '...', inputSchema: {...} },
  ]
}));
 
// 处理工具调用
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  const handler = toolHandlers[name];
  const result = await handler(args);
  return { content: [{ type: 'text', text: formatResult(result) }] };
});
 
// 通过 stdio 通信
const transport = new StdioServerTransport();
await server.connect(transport);

// 查询前转义特殊字符
function escapeFTS5Query(query: string): string {
  return query.replace(/"/g, '""');
}