@yun-zero/claw-memory 0.1.0

package/docs/plans/2026-03-03-llm-generic-config-design.md

@@ -0,0 +1,43 @@
+# LLM配置通用化设计
+
+## 概述
+
+将LLM配置从固定供应商改为通用格式，支持任意OpenAI兼容API。
+
+## 配置结构
+
+```typescript
+export interface LLMConfig {
+  format: 'openai' | 'anthropic' | 'openai-compatible';
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| LLM_FORMAT | 格式类型 | openai |
+| LLM_BASE_URL | API基础URL | https://api.openai.com/v1 |
+| LLM_API_KEY | API密钥 | - |
+| LLM_MODEL | 模型名称 | gpt-4o-mini |
+
+## 请求格式
+
+- `openai`: OpenAI官方API `/v1/chat/completions`
+- `anthropic`: Anthropic API `/v1/messages`
+- `openai-compatible`: 兼容格式，使用OpenAI格式调用其他API
+
+## 实现步骤
+
+1. 修改 `LLMConfig` 接口
+2. 更新 `getLLMConfig()` 读取新环境变量
+3. 添加 `generateWithOpenAICompatible()` 函数
+4. 更新 `generateSummaryWithLLM()` 路由逻辑
+5. 测试验证
+
+## 向后兼容
+
+现有使用 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 的代码需要迁移到新格式。

package/docs/plans/2026-03-03-llm-generic-config-implementation.md

@@ -0,0 +1,186 @@
+# LLM配置通用化实现计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 将LLM配置从固定供应商改为通用格式，支持任意OpenAI兼容API
+
+**Architecture:** 通过format字段区分请求格式，baseUrl灵活配置API端点，实现最大兼容性
+
+**Tech Stack:** TypeScript, 环境变量配置
+
+---
+
+### Task 1: 修改LLMConfig接口
+
+**Files:**
+- Modify: `src/config/llm.ts:1-115`
+
+**Step 1: 修改接口定义**
+
+```typescript
+export interface LLMConfig {
+  format: 'openai' | 'anthropic' | 'openai-compatible';
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+```
+
+**Step 2: 更新getLLMConfig函数**
+
+```typescript
+export function getLLMConfig(): LLMConfig {
+  const format = (process.env.LLM_FORMAT as LLMConfig['format']) || 'openai';
+  const baseUrl = process.env.LLM_BASE_URL || getDefaultBaseUrl(format);
+  const apiKey = process.env.LLM_API_KEY || process.env.OPENAI_API_KEY || '';
+  const model = process.env.LLM_MODEL || getDefaultModel(format);
+
+  if (!apiKey) {
+    throw new Error('No LLM API key configured. Set LLM_API_KEY environment variable.');
+  }
+
+  return { format, baseUrl, apiKey, model };
+}
+
+function getDefaultBaseUrl(format: LLMConfig['format']): string {
+  switch (format) {
+    case 'anthropic':
+      return 'https://api.anthropic.com';
+    case 'openai':
+    case 'openai-compatible':
+    default:
+      return 'https://api.openai.com/v1';
+  }
+}
+
+function getDefaultModel(format: LLMConfig['format']): string {
+  switch (format) {
+    case 'anthropic':
+      return 'claude-3-haiku-20240307';
+    case 'openai':
+    case 'openai-compatible':
+    default:
+      return 'gpt-4o-mini';
+  }
+}
+```
+
+**Step 3: 提交代码**
+
+```bash
+git add src/config/llm.ts
+git commit -m "refactor: update LLMConfig to generic format"
+```
+
+---
+
+### Task 2: 添加OpenAI兼容API支持
+
+**Files:**
+- Modify: `src/config/llm.ts`
+
+**Step 1: 添加generateWithOpenAICompatible函数**
+
+```typescript
+async function generateWithOpenAICompatible(
+  systemPrompt: string,
+  userPrompt: string,
+  config: LLMConfig
+): Promise<string> {
+  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.apiKey}`
+    },
+    body: JSON.stringify({
+      model: config.model,
+      max_tokens: 1024,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt }
+      ]
+    })
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`OpenAI Compatible API error: ${error}`);
+  }
+
+  const data = await response.json() as { choices: { message: { content: string } }[] };
+  return data.choices[0]?.message?.content || '总结生成失败';
+}
+```
+
+**Step 2: 更新generateSummaryWithLLM路由逻辑**
+
+修改 `generateSummaryWithLLM` 函数：
+
+```typescript
+export async function generateSummaryWithLLM(
+  report: string,
+  config?: LLMConfig
+): Promise<string> {
+  const llmConfig = config || getLLMConfig();
+
+  const systemPrompt = `你是一个智能助手...`; // 现有prompt
+
+  if (llmConfig.format === 'anthropic') {
+    return generateWithAnthropic(systemPrompt, report, llmConfig);
+  } else if (llmConfig.format === 'openai-compatible') {
+    return generateWithOpenAICompatible(systemPrompt, report, llmConfig);
+  } else {
+    return generateWithOpenAI(systemPrompt, report, llmConfig);
+  }
+}
+```
+
+**Step 3: 提交代码**
+
+```bash
+git add src/config/llm.ts
+git commit -m "feat: add OpenAI compatible API support"
+```
+
+---
+
+### Task 3: 验证与测试
+
+**Files:**
+- Test: `src/config/llm.ts`
+
+**Step 1: 验证配置解析**
+
+```bash
+# 临时设置环境变量测试
+LLM_FORMAT=openai-compatible \
+LLM_BASE_URL=https://api.minimax.chat/v1 \
+LLM_API_KEY=test-key \
+LLM_MODEL=abab6.5s-chat \
+node -e "import('./src/config/llm.js').then(m => console.log(m.getLLMConfig()))"
+```
+
+**Step 2: 运行现有测试**
+
+```bash
+npm test
+```
+
+**Step 3: 提交**
+
+```bash
+git commit -m "test: verify LLM config works"
+```
+
+---
+
+## 执行选项
+
+**Plan complete and saved to `docs/plans/2026-03-03-llm-generic-config-design.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?**

package/docs/plans/2026-03-03-memory-e2e-stress-test-design.md

@@ -0,0 +1,110 @@
+# Memory E2E & Stress Test Design
+
+**Date:** 2026-03-03
+**Status:** Draft
+
+## Overview
+
+Design for testing claw-memory component through simulated OpenClaw usage, including end-to-end functional tests and stress tests with large-scale knowledge domain conversations.
+
+## Goals
+
+1. **End-to-End Test (A)**: Verify complete workflow with real conversation logs
+2. **Stress Test (B)**: Test batch writing with different knowledge domains and evaluate retrieval accuracy
+
+---
+
+## Part A: End-to-End Test
+
+### Test Flow
+
+```
+Real conversation logs → Parser → MemoryService → MCP Tools → Verify
+                              ↓
+                        Database Storage
+                              ↓
+                        Retrieve/Summary → Compare with expected
+```
+
+### Test Steps
+
+1. **Data Preparation**: Read real conversation samples from `test/fixtures/`
+2. **Save Memory**: Call `save_memory` for each conversation
+3. **Search Verification**: Call `search_memory` with different queries, verify relevance
+4. **Context Verification**: Call `get_context`, verify context contains relevant memories
+5. **Summary Verification**: Call `get_summary`, verify summary accuracy and completeness
+
+### Test Data
+
+- Source: Real conversation logs from project test directory
+- Format: JSON with conversation messages, metadata
+
+---
+
+## Part B: Stress Test
+
+### 1. Batch Writing Optimization
+
+**Problem**: LLM API calls for each memory are expensive
+
+**Solution**: Batch multiple memories into single LLM call
+
+```typescript
+// Before: N LLM calls
+for (const msg of messages) {
+  await llm.extractMetadata(msg);
+}
+
+// After: 1 LLM call per batch (50-100 messages)
+const batchResult = await llm.extractMetadataBatch(messages);
+```
+
+**Expected Reduction**: 1000 memories → ~10-20 API calls instead of 1000
+
+### 2. Knowledge Domains
+
+Write conversations from diverse domains:
+
+- **Technology/Programming**: React, Python, Database, APIs
+- **Product/Design**: UI/UX, Requirements Analysis
+- **Daily Office**: Meeting notes, Task management
+- **Random Mixed**: Various domains
+
+### 3. Retrieval Accuracy Metrics
+
+| Metric | Description |
+|--------|-------------|
+| **Recall@K** | Ratio of relevant memories retrieved in top K |
+| **Precision@K** | Ratio of retrieved results that are relevant |
+| **MRR** | Mean Reciprocal Rank of first relevant result |
+| **NDCG@K** | Normalized Discounted Cumulative Gain considering ranking position |
+
+### 4. Test Queries
+
+| Query | Expected Domain |
+|-------|-----------------|
+| "React 组件开发" | React-related memories |
+| "数据库优化" | Database-related memories |
+| "项目进度" | Task/progress-related memories |
+
+### 5. Test Method
+
+```
+Write 1000 memories from different domains
+       ↓
+For each test query:
+  - Execute search_memory
+  - Mark results as relevant/irrelevant (using ground truth)
+  - Calculate Recall@K, Precision@K, MRR, NDCG@K
+       ↓
+Output evaluation report
+```
+
+---
+
+## Acceptance Criteria
+
+1. E2E test covers full flow: save → search → context → summary
+2. Stress test writes 1000+ memories with batch LLM calls
+3. Retrieval accuracy metrics calculated and reported
+4. Test results reproducible and automated