claude-mem 中文文档

Appearance

版本： 7.0.0（2025年12月） 目标受众: 构建 claude-mem 集成的开发者（VSCode 扩展、IDE 插件、CLI 工具）

快速参考 ​

Worker 服务基础 ​

typescript
const WORKER_BASE_URL = 'http://localhost:37777';
const DEFAULT_PORT = 37777; // Override with CLAUDE_MEM_WORKER_PORT

最常见的操作 ​

typescript
// Health check
GET /api/health

// Create/get session and queue observation
POST /api/sessions/observations
Body: { claudeSessionId, tool_name, tool_input, tool_response, cwd }

// Queue summary
POST /api/sessions/summarize
Body: { claudeSessionId, last_user_message, last_assistant_message }

// Complete session
POST /api/sessions/complete
Body: { claudeSessionId }

// Search observations
GET /api/search?query=authentication&type=observations&format=index&limit=20

// Get recent context for project
GET /api/context/recent?project=my-project&limit=3

环境变量 ​

bash
CLAUDE_MEM_MODEL=claude-sonnet-4-6          # Model for observations/summaries
CLAUDE_MEM_CONTEXT_OBSERVATIONS=50          # Observations injected at SessionStart
CLAUDE_MEM_WORKER_PORT=37777                # Worker service port
CLAUDE_MEM_PYTHON_VERSION=3.13              # Python version for chroma-mcp

构建命令（本地开发） ​

bash
npm run build                 # Compile TypeScript (hooks + worker)
npm run sync-marketplace      # Copy to ~/.claude/plugins
npm run worker:restart        # Restart worker
npm run worker:logs           # View worker logs
npm run worker:status         # Check worker status

Worker 架构 ​

请求流程 ​

plaintext
Platform Hook/Extension
  → HTTP Request to Worker (localhost:37777)
    → Route Handler (SessionRoutes/DataRoutes/SearchRoutes/etc.)
      → Domain Service (SessionManager/SearchManager/DatabaseManager)
        → Database (SQLite3 + Chroma vector DB)
          → SSE Broadcast (real-time UI updates)

域服务 ​

  • DatabaseManager

SQLite connection management, initialization

  • SessionManager

Event-driven session lifecycle, message queues

  • SearchManager

Search orchestration (FTS5 + Chroma)

  • SSEBroadcaster

Server-Sent Events for real-time updates

  • SDKAgent

Claude Agent SDK for generating observations/summaries

  • PaginationHelper

Query pagination utilities

  • SettingsManager

User settings CRUD

  • FormattingService

Result formatting (index vs full)

  • TimelineService

Unified timeline generation

路线组织 ​

- Health check endpoint
- Viewer UI (React app)
- SSE stream for real-time updates


- Session lifecycle (init, observations, summarize, complete)
- Privacy checks and tag stripping
- Auto-start SDK agent generators


- Data retrieval (observations, summaries, prompts, stats)
- Pagination support
- Processing status


- All search operations
- Unified search API
- Timeline context
- Semantic shortcuts


- User settings
- MCP toggle
- Git branch switching

API参考 ​

会话生命周期（会话路由） ​

创建/获取会话 队列观察（新API） ​

http
POST /api/sessions/observations
Content-Type: application/json

{
  "claudeSessionId": "abc123",      // Claude session identifier (string)
  "tool_name": "Bash",
  "tool_input": { "command": "ls" },
  "tool_response": { "stdout": "..." },
  "cwd": "/path/to/project"
}
json
{ "status": "queued" }
// or
{ "status": "skipped", "reason": "private" }

隐私检查： 如果用户提示完全被 <private> 标签包裹，则跳过。 标签剥离： 在存储之前移除 <private> 和 <claude-mem-context> 标签。 自动启动： 确保 SDK 代理生成器正在运行以处理队列。

队列摘要（新 API） ​

http
POST /api/sessions/summarize
Content-Type: application/json

{
  "claudeSessionId": "abc123",
  "last_user_message": "User's message",
  "last_assistant_message": "Assistant's response"
}
json
{ "status": "queued" }
// or
{ "status": "skipped", "reason": "private" }

完成会话（新 API） ​

http
POST /api/sessions/complete
Content-Type: application/json

{
  "claudeSessionId": "abc123"
}
json
{ "success": true }
// or
{ "success": true, "message": "No active session found" }

效果： 停止 SDK 代理，标记会话完成，广播状态更改。

传统端点（仍受支持） ​

```http
POST /sessions/:sessionDbId/init
Body: { userPrompt, promptNumber }
```


```http
POST /sessions/:sessionDbId/observations
Body: { tool_name, tool_input, tool_response, prompt_number, cwd }
```


```http
POST /sessions/:sessionDbId/summarize
Body: { last_user_message, last_assistant_message }
```


```http
POST /sessions/:sessionDbId/complete
```

新的集成应使用 /api/sessions/* 端点和 claudeSessionId。

数据检索（数据路径） ​

获取分页数据 ​

```http
GET /api/observations?offset=0&limit=20&project=my-project
```


```http
GET /api/summaries?offset=0&limit=20&project=my-project
```


```http
GET /api/prompts?offset=0&limit=20&project=my-project
```
json
{
  "items": [...],
  "hasMore": boolean,
  "offset": number,
  "limit": number
}

通过ID获取 ​

```http
GET /api/observation/:id
```


```http
GET /api/session/:id
```


```http
GET /api/prompt/:id
```

获取数据库统计信息 ​

http
GET /api/stats
json
{
  "worker": {
    "version": "7.0.0",
    "uptime": 12345,
    "activeSessions": 2,
    "sseClients": 1,
    "port": 37777
  },
  "database": {
    "path": "~/.claude-mem/claude-mem.db",
    "size": 1048576,
    "observations": 500,
    "sessions": 50,
    "summaries": 25
  }
}

获取项目列表 ​

http
GET /api/projects
json
{
  "projects": ["claude-mem", "other-project", ...]
}

获取处理状态 ​

http
GET /api/processing-status
json
{
  "isProcessing": boolean,
  "queueDepth": number
}

搜索操作（搜索路线） ​

统一搜索 ​

http
GET /api/search?query=authentication&type=observations&format=index&limit=20

搜索查询文本（可选，仅用于过滤时可省略）

“观察” | “会议” | “提示”

"索引" | "完整"

结果数量

按项目名称筛选

按观察类型筛选（发现、决策、修复、功能、重构）

按概念筛选（用逗号分隔）

按文件路径过滤（用逗号分隔）

ISO 时间戳（过滤开始）

ISO 时间戳（过滤结束）

json
{
  "observations": [...],
  "sessions": [...],
  "prompts": [...]
}

格式选项：

  • index：列表显示的最少字段（id、标题、预览）
  • full：包含所有字段的完整实体

统一时间线 ​

http
GET /api/timeline?anchor=123&depth_before=10&depth_after=10&project=my-project

锚点（观察 ID，会议的“S123”，或 ISO 时间戳）

锚点前的记录

锚点后的记录

按项目筛选

json
[
  { "type": "observation", "id": 120, "created_at_epoch": ..., ... },
  { "type": "session", "id": 5, "created_at_epoch": ..., ... },
  { "type": "observation", "id": 123, "created_at_epoch": ..., ... }
]

语义快捷方式 ​

  • Decisions
http
    GET /api/decisions?format=index&limit=20
    ```

  - **Changes**

```http
    GET /api/changes?format=index&limit=20
    ```

  - **How It Works**

```http
    GET /api/how-it-works?format=index&limit=20
    ```

#### 按概念搜索

```http
GET /api/search/by-concept?concept=discovery&format=index&limit=10&project=my-project

按文件路径搜索 ​

http
GET /api/search/by-file?filePath=src/services/worker-service.ts&format=index&limit=10

按类型搜索 ​

http
GET /api/search/by-type?type=bugfix&format=index&limit=10

获取最近的上下文 ​

http
GET /api/context/recent?project=my-project&limit=3
json
{
  "summaries": [...],
  "observations": [...]
}

上下文预览（用于设置界面） ​

http
GET /api/context/preview?project=my-project

返回带有 ANSI 颜色的纯文本以供终端显示

上下文注入（用于钩子） ​

http
GET /api/context/inject?project=my-project&colors=true

返回预先格式化的上下文字符串，可直接显示

设置与配置（SettingsRoutes） ​

获取/更新用户设置 ​

http
GET /api/settings
json
{
  "sidebarOpen": boolean,
  "selectedProject": string | null
}
http
POST /api/settings
Body: { "sidebarOpen": true, "selectedProject": "my-project" }
json
{ "success": true }

MCP 服务器状态/切换 ​

http
GET /api/mcp/status
json
{ "enabled": boolean }
http
POST /api/mcp/toggle
Body: { "enabled": true }
json
{ "success": true, "enabled": boolean }

Git 分支操作 ​

```http
GET /api/branch/status
```
```json
{
  "current": "main",
  "remote": "origin/main",
  "ahead": 0,
  "behind": 0
}
```


```http
POST /api/branch/switch
Body: { "branch": "feature/new-feature" }
```
```json
{ "success": true }
```


```http
POST /api/branch/update
```
```json
{ "success": true, "updated": boolean }
```

查看器和实时更新（查看器路由） ​

健康检查 ​

http
GET /api/health
json
{ "status": "ok" }

查看器界面 ​

http
GET /

返回用于 React 应用的 HTML

SSE 流 ​

http
GET /stream

服务器发送事件流

事件类型：

  • processing_status: { 类型, 正在处理, 队列深度 }
  • session_started: { 类型, 会话数据库ID, 项目 }
  • observation_queued: { 类型, sessionDbId }
  • summarize_queued: { 类型 }
  • observation_created: { 类型, 观察 }
  • summary_created: { 类型, 摘要 }
  • new_prompt: { 类型, id, claude_session_id, 项目, 提示编号, 提示文本, 创建时间_纪元 }

数据模型 ​

活动会话（内存中） ​

typescript
interface ActiveSession {
  sessionDbId: number;                  // Database ID (numeric)
  claudeSessionId: string;              // Claude session identifier (string)
  sdkSessionId: string | null;          // SDK session ID
  project: string;                      // Project name
  userPrompt: string;                   // Current user prompt text
  pendingMessages: PendingMessage[];    // Queue of pending operations
  abortController: AbortController;     // For cancellation
  generatorPromise: Promise<void> | null; // SDK agent promise
  lastPromptNumber: number;             // Last processed prompt number
  startTime: number;                    // Session start timestamp
  cumulativeInputTokens: number;        // Total input tokens
  cumulativeOutputTokens: number;       // Total output tokens
}

interface PendingMessage {
  type: 'observation' | 'summarize';
  tool_name?: string;
  tool_input?: any;
  tool_response?: any;
  prompt_number?: number;
  cwd?: string;
  last_user_message?: string;
  last_assistant_message?: string;
}

数据库实体 ​

```typescript
interface SDKSessionRow {
  id: number;
  claude_session_id: string;
  sdk_session_id: string;
  project: string;
  user_prompt: string;
  created_at_epoch: number;
  completed_at_epoch?: number;
}
```


```typescript
interface ObservationRow {
  id: number;
  sdk_session_id: string;
  title: string;
  subtitle?: string;
  summary: string;
  facts: string;           // JSON array of fact strings
  concepts: string;        // JSON array of concept strings
  files_touched: string;   // JSON array of file paths
  obs_type: string;        // discovery, decision, bugfix, feature, refactor
  project: string;
  created_at_epoch: number;
  prompt_number: number;
}
```


```typescript
interface SessionSummaryRow {
  id: number;
  sdk_session_id: string;
  summary_text: string;
  facts: string;           // JSON array
  concepts: string;        // JSON array
  files_touched: string;   // JSON array
  project: string;
  created_at_epoch: number;
}
```


```typescript
interface UserPromptRow {
  id: number;
  claude_session_id: string;
  sdk_session_id: string;
  project: string;
  prompt_number: number;
  prompt_text: string;
  created_at_epoch: number;
}
```

搜索结果 ​

typescript
interface ObservationSearchResult {
  id: number;
  title: string;
  subtitle?: string;
  summary: string;
  facts: string[];         // Parsed from JSON
  concepts: string[];      // Parsed from JSON
  files_touched: string[]; // Parsed from JSON
  obs_type: string;
  project: string;
  created_at_epoch: number;
  prompt_number: number;
  rank?: number;           // FTS5 rank score
}

interface SessionSummarySearchResult {
  id: number;
  summary_text: string;
  facts: string[];
  concepts: string[];
  files_touched: string[];
  project: string;
  created_at_epoch: number;
  rank?: number;
}

interface UserPromptSearchResult {
  id: number;
  claude_session_id: string;
  project: string;
  prompt_number: number;
  prompt_text: string;
  created_at_epoch: number;
  rank?: number;
}

时间线项目 ​

typescript
interface TimelineItem {
  type: 'observation' | 'session' | 'prompt';
  id: number;
  created_at_epoch: number;
  // Entity-specific fields based on type
}

集成模式 ​

将 Claude Code钩子映射到 Worker API ​

Not needed for new API - sessions are auto-created on first observation


No API call needed - user_prompt is captured by first observation in the prompt


```typescript
async function onPostToolUse(context: HookContext) {
  const { session_id, tool_name, tool_input, tool_result, cwd } = context;

  const response = await fetch('http://localhost:37777/api/sessions/observations', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      claudeSessionId: session_id,
      tool_name,
      tool_input,
      tool_response: tool_result,
      cwd
    })
  });

  const result = await response.json();
  // result.status === 'queued' | 'skipped'
}
```


```typescript
async function onSummary(context: HookContext) {
  const { session_id, last_user_message, last_assistant_message } = context;

  await fetch('http://localhost:37777/api/sessions/summarize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      claudeSessionId: session_id,
      last_user_message,
      last_assistant_message
    })
  });
}
```


```typescript
async function onSessionEnd(context: HookContext) {
  const { session_id } = context;

  await fetch('http://localhost:37777/api/sessions/complete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      claudeSessionId: session_id
    })
  });
}
```

VSCode 扩展集成 ​

语言模型工具注册 ​

typescript

interface SearchTool extends vscode.LanguageModelChatTool {
  invoke(
    options: vscode.LanguageModelToolInvocationOptions<{ query: string }>,
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.LanguageModelToolResult>;
}

const searchTool: SearchTool = {
  invoke: async (options, token) => {
    const { query } = options.input;

    try {
      const response = await fetch(
        `http://localhost:37777/api/search?query=${encodeURIComponent(query)}&format=index&limit=10`
      );

      if (!response.ok) {
        throw new Error(`Search failed: ${response.statusText}`);
      }

      const results = await response.json();

      // Format results for language model
      return new vscode.LanguageModelToolResult([
        new vscode.LanguageModelTextPart(JSON.stringify(results, null, 2))
      ]);
    } catch (error) {
      return new vscode.LanguageModelToolResult([
        new vscode.LanguageModelTextPart(`Error: ${error.message}`)
      ]);
    }
  }
};

// Register tool
vscode.lm.registerTool('claude-mem-search', searchTool);

聊天参与者实现 ​

typescript
const participant = vscode.chat.createChatParticipant('claude-mem', async (request, context, stream, token) => {
  const claudeSessionId = context.session.id;

  // First message in conversation - no initialization needed
  // Session is auto-created on first observation

  // Process user message
  stream.markdown(`Searching memory for: ${request.prompt}\n\n`);

  const response = await fetch(
    `http://localhost:37777/api/search?query=${encodeURIComponent(request.prompt)}&format=index&limit=5`
  );

  const results = await response.json();

  if (results.observations?.length > 0) {
    stream.markdown('**Found observations:**\n');
    for (const obs of results.observations) {
      stream.markdown(`- ${obs.title} (${obs.project})\n`);
    }
  }

  return { metadata: { command: 'search' } };
});

错误处理与弹性 ​

连接失败 ​

typescript
async function callWorkerWithFallback<T>(
  endpoint: string,
  options?: RequestInit
): Promise<T | null> {
  try {
    const response = await fetch(`http://localhost:37777${endpoint}`, {
      ...options,
      signal: AbortSignal.timeout(5000) // 5s timeout
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error(`Worker unavailable (${endpoint}):`, error);
    return null; // Graceful degradation
  }
}

带指数退避的重试逻辑 ​

typescript
async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 100
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = baseDelay * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
}

Worker 健康检查 ​

typescript
async function isWorkerHealthy(): Promise<boolean> {
  try {
    const response = await fetch('http://localhost:37777/api/health', {
      signal: AbortSignal.timeout(2000)
    });
    return response.ok;
  } catch {
    return false;
  }
}

隐私标签处理 ​

Worker 会在存储前自动去除隐私标签：

  • <private>content</private> - 用户级隐私控制
  • <claude-mem-context>content</claude-mem-context> - 系统级标签（防止递归存储）

隐私检查： 如果整个用户提示被 <private> 标签包裹，则会跳过观察/总结。

自定义错误类 ​

typescript
class WorkerUnavailableError extends Error {
  constructor() {
    super('Claude-mem worker is not running or unreachable');
    this.name = 'WorkerUnavailableError';
  }
}

class WorkerTimeoutError extends Error {
  constructor(endpoint: string) {
    super(`Worker request timed out: ${endpoint}`);
    this.name = 'WorkerTimeoutError';
  }
}

SSE 流错误处理 ​

typescript
function connectToSSE(onEvent: (event: any) => void) {
  const eventSource = new EventSource('http://localhost:37777/stream');

  eventSource.onmessage = (event) => {
    try {
      const data = JSON.parse(event.data);
      onEvent(data);
    } catch (error) {
      console.error('SSE parse error:', error);
    }
  };

  eventSource.onerror = (error) => {
    console.error('SSE connection error:', error);
    eventSource.close();

    // Reconnect after 5 seconds
    setTimeout(() => connectToSSE(onEvent), 5000);
  };

  return eventSource;
}

开发工作流程 ​

项目结构（推荐） ​

plaintext
vscode-extension/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── services/
│   │   ├── WorkerClient.ts       # HTTP client for worker
│   │   └── MemoryManager.ts      # High-level memory operations
│   ├── chat/
│   │   └── participant.ts        # Chat participant implementation
│   └── tools/
│       ├── search.ts             # Search language model tool
│       └── context.ts            # Context injection tool
├── package.json
├── tsconfig.json
└── README.md

构建配置（esbuild） ​

javascript
// build.js
const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'dist/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
  target: 'node18',
  sourcemap: true
}).catch(() => process.exit(1));

package.json（VSCode 扩展） ​

json
{
  "name": "claude-mem-vscode",
  "displayName": "Claude-Mem",
  "version": "1.0.0",
  "engines": {
    "vscode": "^1.95.0"
  },
  "activationEvents": [
    "onStartupFinished"
  ],
  "main": "./dist/extension.js",
  "contributes": {
    "chatParticipants": [
      {
        "id": "claude-mem",
        "name": "memory",
        "description": "Search your persistent memory"
      }
    ],
    "languageModelTools": [
      {
        "name": "claude-mem-search",
        "displayName": "Search Memory",
        "description": "Search persistent memory for observations, sessions, and prompts"
      }
    ]
  },
  "scripts": {
    "build": "node build.js",
    "watch": "node build.js --watch",
    "package": "vsce package"
  },
  "devDependencies": {
    "@types/vscode": "^1.95.0",
    "esbuild": "^0.19.0",
    "typescript": "^5.3.0"
  }
}

本地测试循环 ​

```bash
npm run watch
```


```bash
npm run worker:status
npm run worker:logs
```


```bash
curl http://localhost:37777/api/health
curl "http://localhost:37777/api/search?query=test&limit=5"
```


Press F5 to launch extension host

调试配置 (.vscode/launch.json) ​

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ],
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js"
      ],
      "preLaunchTask": "npm: build"
    }
  ]
}

测试策略 ​

单元测试（工作客户端） ​

typescript

describe('WorkerClient', () => {
  it('should check worker health', async () => {
    const client = new WorkerClient();
    const healthy = await client.isHealthy();
    expect(healthy).toBe(true);
  });

  it('should queue observation', async () => {
    const client = new WorkerClient();
    const result = await client.queueObservation({
      claudeSessionId: 'test-123',
      tool_name: 'Bash',
      tool_input: { command: 'ls' },
      tool_response: { stdout: 'file1.txt' },
      cwd: '/tmp'
    });
    expect(result.status).toBe('queued');
  });

  it('should search observations', async () => {
    const client = new WorkerClient();
    const results = await client.search({ query: 'test', limit: 5 });
    expect(results).toHaveProperty('observations');
  });
});

集成测试（含工作进程生成） ​

typescript

describe('Worker Integration', () => {
  let workerProcess: ReturnType<typeof spawn>;

  beforeAll(async () => {
    // Start worker process
    workerProcess = spawn('node', ['dist/worker-service.js'], {
      env: { ...process.env, CLAUDE_MEM_WORKER_PORT: '37778' }
    });

    // Wait for worker to be ready
    await new Promise(resolve => setTimeout(resolve, 2000));
  });

  afterAll(() => {
    workerProcess.kill();
  });

  it('should respond to health check', async () => {
    const response = await fetch('http://localhost:37778/api/health');
    expect(response.ok).toBe(true);
  });
});

手动测试清单 ​

- [ ] Worker starts successfully (`npm run worker:status`)
- [ ] Health endpoint responds (`curl http://localhost:37777/api/health`)
- [ ] SSE stream connects (`curl http://localhost:37777/stream`)



- [ ] Queue observation creates session
- [ ] Observation appears in database
- [ ] Privacy tags are stripped
- [ ] Private prompts are skipped
- [ ] Queue summary creates summary
- [ ] Complete session stops processing



- [ ] Search observations by query
- [ ] Search sessions by query
- [ ] Search prompts by query
- [ ] Get recent context for project
- [ ] Get timeline around observation
- [ ] Semantic shortcuts (decisions, changes, how-it-works)



- [ ] SSE broadcasts processing status
- [ ] SSE broadcasts new observations
- [ ] SSE broadcasts new summaries
- [ ] SSE broadcasts new prompts



- [ ] Graceful degradation when worker unavailable
- [ ] Timeout handling for slow requests
- [ ] Retry logic for transient failures

代码示例 ​

完整的 WorkerClient 实现 ​

typescript

  private baseUrl: string;

  constructor(port: number = 37777) {
    this.baseUrl = `http://localhost:${port}`;
  }

  async isHealthy(): Promise<boolean> {
    try {
      const response = await fetch(`${this.baseUrl}/api/health`, {
        signal: AbortSignal.timeout(2000)
      });
      return response.ok;
    } catch {
      return false;
    }
  }

  async queueObservation(data: {
    claudeSessionId: string;
    tool_name: string;
    tool_input: any;
    tool_response: any;
    cwd?: string;
  }): Promise<{ status: string; reason?: string }> {
    const response = await fetch(`${this.baseUrl}/api/sessions/observations`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
      signal: AbortSignal.timeout(5000)
    });

    if (!response.ok) {
      throw new Error(`Failed to queue observation: ${response.statusText}`);
    }

    return await response.json();
  }

  async queueSummarize(data: {
    claudeSessionId: string;
    last_user_message?: string;
    last_assistant_message?: string;
  }): Promise<{ status: string; reason?: string }> {
    const response = await fetch(`${this.baseUrl}/api/sessions/summarize`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
      signal: AbortSignal.timeout(5000)
    });

    if (!response.ok) {
      throw new Error(`Failed to queue summary: ${response.statusText}`);
    }

    return await response.json();
  }

  async completeSession(claudeSessionId: string): Promise<void> {
    const response = await fetch(`${this.baseUrl}/api/sessions/complete`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ claudeSessionId }),
      signal: AbortSignal.timeout(5000)
    });

    if (!response.ok) {
      throw new Error(`Failed to complete session: ${response.statusText}`);
    }
  }

  async search(params: {
    query?: string;
    type?: 'observations' | 'sessions' | 'prompts';
    format?: 'index' | 'full';
    limit?: number;
    project?: string;
  }): Promise<any> {
    const queryString = new URLSearchParams(
      Object.entries(params)
        .filter(([_, v]) => v !== undefined)
        .map(([k, v]) => [k, String(v)])
    ).toString();

    const response = await fetch(
      `${this.baseUrl}/api/search?${queryString}`,
      { signal: AbortSignal.timeout(10000) }
    );

    if (!response.ok) {
      throw new Error(`Search failed: ${response.statusText}`);
    }

    return await response.json();
  }

  connectSSE(onEvent: (event: any) => void): EventSource {
    const eventSource = new EventSource(`${this.baseUrl}/stream`);

    eventSource.onmessage = (event) => {
      try {
        const data = JSON.parse(event.data);
        onEvent(data);
      } catch (error) {
        console.error('SSE parse error:', error);
      }
    };

    eventSource.onerror = (error) => {
      console.error('SSE connection error:', error);
    };

    return eventSource;
  }
}

搜索语言模型工具 ​

typescript

  const client = new WorkerClient();

  const searchTool = vscode.lm.registerTool('claude-mem-search', {
    description: 'Search persistent memory for observations, sessions, and prompts',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query text'
        },
        type: {
          type: 'string',
          enum: ['observations', 'sessions', 'prompts'],
          description: 'Type of results to return'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results',
          default: 10
        }
      },
      required: ['query']
    },
    invoke: async (options, token) => {
      const { query, type, limit = 10 } = options.input;

      try {
        const results = await client.search({
          query,
          type,
          format: 'index',
          limit
        });

        // Format results for language model
        let formatted = '';

        if (results.observations?.length > 0) {
          formatted += '## Observations\n\n';
          for (const obs of results.observations) {
            formatted += `- **${obs.title}** (${obs.project})\n`;
            formatted += `  ${obs.summary}\n`;
            if (obs.concepts?.length > 0) {
              formatted += `  Concepts: ${obs.concepts.join(', ')}\n`;
            }
            formatted += '\n';
          }
        }

        return new vscode.LanguageModelToolResult([
          new vscode.LanguageModelTextPart(formatted)
        ]);
      } catch (error) {
        return new vscode.LanguageModelToolResult([
          new vscode.LanguageModelTextPart(`Error: ${error.message}`)
        ]);
      }
    }
  });

  context.subscriptions.push(searchTool);
}

关键实施注意事项 ​

sessionDbId 与 claudeSessionId ​

重要提示： 对于新的 API 端点，请使用 claudeSessionId（字符串），而不是 sessionDbId（数字）。

  • sessionDbId - 数字数据库ID（仅限旧版端点）
  • claudeSessionId - 来自 Claude 平台的字符串标识符（新端点）

JSON 字符串字段 ​

像 facts、concepts 和 files_touched 这样的字段存储为 JSON 字符串，需要进行解析：

typescript
const observation = await client.getObservationById(123);
const facts = JSON.parse(observation.facts); // string[] array
const concepts = JSON.parse(observation.concepts); // string[] array

时间戳 ​

所有 created_at_epoch 字段的单位是 毫秒，而不是秒：

typescript
const date = new Date(observation.created_at_epoch); // ✅ Correct
const date = new Date(observation.created_at_epoch * 1000); // ❌ Wrong (already in ms)

异步处理 ​

Worker 异步处理观察结果/总结。排队后 1-2 秒结果就会出现在数据库中。使用 SSE 事件进行实时通知。

隐私标签 ​

始终将敏感内容用 <private> 标签包裹以防止存储：

typescript
const userMessage = '<private>API key: sk-1234567890</private>';
// This observation will be skipped (entire prompt is private)

附加资源 ​

  • 文档

" Complete claude-mem documentation

  • GitHub

" Source code and issue tracker

  • Worker Service

Worker architecture details

  • Database Schema

Database structure and queries