Claude Conversation Logger

🚀 🤖 Claude Conversation Logger v3.1.0

Claude Conversation Logger v3.1.0 是一個智能對話管理平臺，配備 4 個與 Claude Code 兼容的代理，具備深度語義分析、自動文檔生成等功能，可實現 70% 的令牌優化，有效提升技術對話的處理效率和質量。

🚀 快速開始

第 1 步：啟動系統

# 克隆並啟動
git clone https://github.com/LucianoRicardo737/claude-conversation-logger.git
cd claude-conversation-logger

# 使用 Docker 啟動（包含代理）
docker compose up -d --build

# 驗證系統是否正常運行
curl http://localhost:3003/health

第 2 步：配置 Claude Code

# 複製 MCP 配置
cp examples/claude-settings.json ~/.claude/settings.json

# 複製日誌鉤子
cp examples/api-logger.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/api-logger.py

第 3 步：使用代理

# 在 Claude Code 中搜索相似對話
search_conversations({
  query: "payment integration error",
  days: 30,
  includePatterns: true
})

# 對當前對話進行智能分析
analyze_conversation_intelligence({
  session_id: "current_session",
  includeRelationships: true
})

# 自動生成文檔
auto_document_session({
  session_id: "completed_troubleshooting"
})

🎉 系統已準備就緒！代理將自動分析您的所有對話。

✨ 主要特性

⭐ 4 個 Claude Code 代理系統

🧠 核心功能

Claude Conversation Logger 包含一個經過優化的 4 個與 Claude Code 兼容的代理系統，可在技術對話中提供智能分析、自動文檔生成和模式發現功能。

🎭 4 個 Claude Code 代理

🚀 智能能力

# 🔍 智能語義搜索
"authentication error" → 查找所有與身份驗證相關的對話

# 📝 上下文自動文檔生成
完成的會話 → 自動生成結構化文檔

# 🔗 智能關係映射
當前問題 → 找到 5 個帶有解決方案的相似對話

# 📊 預測模式分析
"API timeout" → 識別 15 個相似案例 + 最有效的解決方案

# 🌍 多語言支持
混合西班牙語/英語對話 → 檢測兩種語言中的模式

⚡ 關鍵優勢

• ✅ 令牌優化：與手動分析相比，減少 70% 的令牌使用量
• ✅ 即時分析：多代理完整分析時間小於 3 秒
• ✅ 高精度：模式和狀態檢測準確率達 95% 以上
• ✅ 多語言支持：支持西班牙語/英語，框架可擴展
• ✅ 智能緩存：緩存命中率達 85% 以上，實現快速響應
• ✅ 自學習：隨著使用不斷改進

🔌 Claude Code 集成（MCP）

5 個原生代理工具

系統為 Claude Code 提供 5 個原生 MCP 工具：

Claude Code 配置

~/.claude/settings.json

{
  "mcp": {
    "mcpServers": {
      "conversation - logger": {
        "command": "node",
        "args": ["src/mcp - server.js"],
        "cwd": "/path/to/claude - conversation - logger",
        "env": {
          "API_URL": "http://localhost:3003",
          "API_KEY": "claude_api_secret_2024_change_me"
        }
      }
    }
  },
  "hooks": {
    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/api - logger.py"}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/api - logger.py"}]}]
  }
}

Claude Code 使用示例

🔍 智能搜索

// 使用語義分析搜索相似問題
search_conversations({
  query: "React hydration mismatch SSR",
  days: 60,
  includePatterns: true,
  minConfidence: 0.75
})

// 結果：相關對話 + 模式 + 已驗證的解決方案

📊 模式分析

// 識別項目中反覆出現的問題
analyze_conversation_patterns({
  days: 30,
  project: "my - api - service",
  minFrequency: 3
})

// 結果：主要問題 + 成功率 + 建議

📝 自動文檔生成

// 從完成的會話生成文檔
export_conversation({
  session_id: "current_session",
  format: "markdown",
  includeCodeExamples: true
})

// 結果：帶有問題 + 解決方案 + 代碼的結構化 Markdown

🧠 完整的多代理分析

// 使用所有代理進行深度分析
analyze_conversation_intelligence({
  session_id: "complex_debugging_session",
  includeSemanticAnalysis: true,
  includeRelationships: true,
  generateInsights: true
})

// 結果：完整分析 + 見解 + 建議

🛠️ 代理 REST API

5 個 Claude Code 端點

分析與協調

# 完整的多代理分析
POST /api/agents/orchestrator
Content - Type: application/json
X - API - Key: claude_api_secret_2024_change_me

{
  "type": "deep_analysis",
  "data": {"session_id": "sess_123"},
  "options": {
    "includeSemanticAnalysis": true,
    "generateInsights": true,
    "maxTokenBudget": 150
  }
}

模式發現

# 查找反覆出現的模式
GET /api/agents/patterns?days = 30&minFrequency = 3&project = api - service

# 響應：已識別的模式 + 頻率 + 解決方案

關係映射

# 搜索相關對話
GET /api/agents/relationships/sess_123?minConfidence = 0.7&maxResults = 10

# 響應：相似對話 + 關係類型 + 置信度

自動文檔生成

# 生成智能文檔
POST /api/agents/document
{
  "session_id": "sess_123",
  "options": {
    "autoDetectPatterns": true,
    "includeCodeExamples": true
  }
}

主要 API 端點

對話管理

# 記錄對話（由鉤子使用）
POST /api/conversations

# 使用語義分析進行搜索
GET /api/conversations/search?q = authentication&days = 30&semantic = true

# 導出帶有自動文檔的對話
GET /api/conversations/{session_id}/export?format = markdown&enhanced = true

分析與指標

# 項目統計
GET /api/projects/stats

# 代理指標
GET /api/agents/metrics

# 系統健康狀態
GET /health

🏗️ 技術架構

代理架構

graph TB
    subgraph "🔌 Claude Code 集成"
        CC[Claude Code] -->|MCP 工具| MCP[MCP 服務器]
        CC -->|鉤子| HOOK[Python 鉤子]
    end
    
    subgraph "🤖 Claude Code 代理系統"
        MCP --> CO[conversation - orchestrator - agent]
        CO --> SA[semantic - analyzer - agent]
        CO --> PD[pattern - discovery - agent]
        CO --> AD[auto - documentation - agent]
    end
    
    subgraph "💾 數據層"
        SA --> MONGO[(MongoDB<br/>8 個集合)]
        CO --> REDIS[(Redis<br/>智能緩存)]
    end
    
    subgraph "🌐 API 層"
        HOOK --> API[REST API 服務器]
        API --> CO
    end
    
    style CO fill:#9c27b0,color:#fff
    style SA fill:#2196f3,color:#fff
    style MONGO fill:#4caf50,color:#fff

系統組件

數據流

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP 服務器
    participant CO as conversation - orchestrator - agent
    participant AG as 代理 (SA/PD/AD)
    participant DB as MongoDB/Redis
    
    CC->>MCP: search_conversations()
    MCP->>CO: 處理請求
    CO->>AG: 協調分析
    AG->>DB: 查詢數據 + 緩存
    AG->>CO: 專業結果
    CO->>MCP: 集成響應
    MCP->>CC: 對話 + 見解

⚙️ 代理配置

42 個配置參數

代理系統可通過 Docker Compose 進行完全配置：

🌍 語言配置

# docker - compose.yml
environment:
  # 主要語言
  AGENT_PRIMARY_LANGUAGE: "es"
  AGENT_SECONDARY_LANGUAGE: "en" 
  AGENT_MIXED_LANGUAGE_MODE: "true"
  
  # 西班牙語 + 英語關鍵詞（JSON 數組）
  AGENT_WRITE_KEYWORDS: '["documentar","guardar","document","save","create doc"]'
  AGENT_READ_KEYWORDS: '["buscar","encontrar","similar","search","find","lookup"]'
  AGENT_RESOLUTION_KEYWORDS: '["resuelto","funcionando","resolved","fixed","working"]'
  AGENT_PROBLEM_KEYWORDS: '["error","problema","falla","bug","issue","crash"]'

🎯 性能參數

environment:
  # 檢測閾值
  AGENT_SIMILARITY_THRESHOLD: "0.75"
  AGENT_CONFIDENCE_THRESHOLD: "0.80"
  AGENT_MIN_PATTERN_FREQUENCY: "3"
  
  # 令牌優化
  AGENT_MAX_TOKEN_BUDGET: "100"
  AGENT_CACHE_TTL_SECONDS: "300"
  
  # 功能標誌
  AGENT_ENABLE_SEMANTIC_ANALYSIS: "true"
  AGENT_ENABLE_AUTO_DOCUMENTATION: "true"
  AGENT_ENABLE_RELATIONSHIP_MAPPING: "true"
  AGENT_ENABLE_PATTERN_PREDICTION: "true"

8 個代理 MongoDB 集合

主要集合

// conversations - 基礎對話
{
  _id: ObjectId("..."),
  session_id: "sess_123",
  project: "api - service",
  user_message: "Payment integration failing",
  ai_response: "Let me help debug the payment flow...",
  timestamp: ISODate("2025 - 08 - 25T10:00:00Z"),
  metadata: {
    resolved: true,
    complexity: "intermediate",
    topics: ["payment", "integration", "debugging"]
  }
}

// conversation_patterns - 代理檢測到的模式
{
  pattern_id: "api_timeout_pattern",
  title: "API Timeout Issues",
  frequency: 23,
  confidence: 0.87,
  common_solution: "Increase timeout + add retry logic",
  affected_projects: ["api - service", "payment - gateway"]
}

// conversation_relationships - 會話連接
{
  source_session: "sess_123",
  target_session: "sess_456",
  relationship_type: "similar_problem",
  confidence_score: 0.89,
  detected_by: "semantic - analyzer - agent"
}

// conversation_insights - 生成的見解
{
  insight_type: "recommendation", 
  priority: "high",
  title: "Frequent Database Connection Issues",
  recommendations: ["Add connection pooling", "Implement retry logic"]
}

📦 安裝指南

要求

• Docker 20.0+ 及 Docker Compose
• Python 3.8+（用於鉤子）
• 已安裝並配置 Claude Code
• 可用內存 4GB 以上

完整安裝

1. 克隆並設置

# 克隆倉庫
git clone https://github.com/LucianoRicardo737/claude-conversation-logger.git
cd claude-conversation-logger

# 驗證結構
ls -la  # 應顯示：src/, config/, examples/, docker - compose.yml

2. Docker 部署

# 構建並啟動完整系統
docker compose up -d --build

# 驗證服務（應顯示 1 個運行中的容器）
docker compose ps

# 驗證系統健康狀態
curl http://localhost:3003/health
# 預期結果：{"status":"healthy","services":{"api":"ok","mongodb":"ok","redis":"ok"}}

3. Claude Code 配置

# 如果鉤子目錄不存在，則創建
mkdir -p ~/.claude/hooks

# 複製日誌鉤子
cp examples/api - logger.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/api - logger.py

# 配置 Claude Code 設置
cp examples/claude - settings.json ~/.claude/settings.json
# 或與現有設置合併

4. 系統驗證

# API 測試
curl -H "X - API - Key: claude_api_secret_2024_change_me" \
     http://localhost:3003/api/conversations | jq .

# 代理測試
curl -H "X - API - Key: claude_api_secret_2024_change_me" \
     http://localhost:3003/api/agents/health

# 鉤子測試（模擬）
python3 ~/.claude/hooks/api - logger.py

環境變量

基礎配置

# 必需
MONGODB_URI=mongodb://localhost:27017/conversations
REDIS_URL=redis://localhost:6379
API_KEY=your_secure_api_key_here
NODE_ENV=production

# 可選性能參數
API_MAX_CONNECTIONS=100
MONGODB_POOL_SIZE=20
REDIS_MESSAGE_LIMIT=10000

代理配置（42 個變量）

# 語言和關鍵詞
AGENT_PRIMARY_LANGUAGE=es
AGENT_MIXED_LANGUAGE_MODE=true
AGENT_WRITE_KEYWORDS='["documentar","document","save"]'

# 性能和閾值
AGENT_MAX_TOKEN_BUDGET=100
AGENT_SIMILARITY_THRESHOLD=0.75
AGENT_CACHE_TTL_SECONDS=300

# 功能標誌
AGENT_ENABLE_SEMANTIC_ANALYSIS=true
AGENT_ENABLE_AUTO_DOCUMENTATION=true

💻 使用示例

🔍 場景 1：反覆調試

// 問題："Payments fail sporadically"
// 在 Claude Code 中，使用 MCP 工具：
search_conversations({
  query: "payment failed timeout integration",
  days: 90,
  includePatterns: true
})

// semantic - analyzer - agent + pattern - discovery - agent 返回：
// - 找到 8 個相似對話
// - 識別的模式："Gateway timeout after 30s"（頻率：23 次）
// - 已驗證的解決方案："Increase timeout to 60s + add retry"（成功率：94%）
// - 相關對話：sess_456, sess_789, sess_012

📝 場景 2：自動文檔生成

// 解決複雜錯誤後
// auto - documentation - agent 生成上下文相關的文檔：
export_conversation({
  session_id: "debugging_session_456",
  format: "markdown",
  includeCodeExamples: true,
  autoDetectPatterns: true
})

// 系統自動生成：
/* 
# 解決方案：支付網關超時問題

## 問題識別
- 30 秒後網關超時
- 高峰時段影響支付
- 日誌中的錯誤："ETIMEDOUT"

## 調查過程
1. Nginx 日誌分析
2. 超時配置審查
3. 網絡延遲監控

## 實施的解決方案
```javascript
const paymentConfig = {
  timeout: 60000, // 從 30 秒增加到 60 秒
  retries: 3,     // 添加重試邏輯
  backoff: 'exponential'
};

驗證

• ✅ 測試通過：payment - integration.test.js
• ✅ 超時錯誤從每天 23 次減少到 0 次
• ✅ 成功率：99.2%

標籤

#payment #timeout #gateway #production - fix */

### 📊 場景 3：項目分析
```javascript
// 使用 pattern - discovery - agent 分析項目健康狀況
analyze_conversation_patterns({
  project: "e - commerce - api",
  days: 30,
  minFrequency: 3,
  includeSuccessRates: true
})

// 系統自動識別：
{
  "top_issues": [
    {
      "pattern": "Database connection timeouts",
      "frequency": 18,
      "success_rate": 0.89,
      "avg_resolution_time": "2.3 小時",
      "recommended_action": "Implement connection pooling"
    },
    {
      "pattern": "Redis cache misses",
      "frequency": 12,
      "success_rate": 0.92,
      "avg_resolution_time": "45 分鐘",
      "recommended_action": "Review cache invalidation strategy"
    }
  ],
  "trending_topics": ["authentication", "api - rate - limiting", "database - performance"],
  "recommendation": "Focus on database optimization - 60% of issues stem from DB layer"
}

🔗 場景 4：智能上下文搜索

// 處理新問題時，搜索相似上下文
// semantic - analyzer - agent 找到智能連接：
search_conversations({
  query: "React component not rendering after state update",
  days: 60,
  includeRelationships: true,
  minConfidence: 0.7
})

// 帶有關係分析的結果：
{
  "direct_matches": [
    {
      "session_id": "sess_789",
      "similarity": 0.94,
      "relationship_type": "identical_problem",
      "solution_confidence": 0.96,
      "quick_solution": "Add useEffect dependency array"
    }
  ],
  "related_conversations": [
    {
      "session_id": "sess_234",
      "similarity": 0.78,
      "relationship_type": "similar_context",
      "topic_overlap": ["React", "state management", "useEffect"]
    }
  ],
  "patterns_detected": {
    "common_cause": "Missing useEffect dependencies",
    "frequency": 15,
    "success_rate": 0.93
  }
}

🧠 場景 5：完整的多代理分析

// 對於複雜對話，激活所有代理：
analyze_conversation_intelligence({
  session_id: "complex_debugging_session",
  includeSemanticAnalysis: true,
  includeRelationships: true,
  generateInsights: true,
  maxTokenBudget: 200
})

// conversation - orchestrator - agent 協調所有代理：
{
  "semantic_analysis": {
    "topics": ["microservices", "docker", "kubernetes", "monitoring"],
    "entities": ["Prometheus", "Grafana", "Helm charts"],
    "complexity": "advanced",
    "resolution_confidence": 0.91
  },
  "session_state": {
    "status": "completed",
    "quality_score": 0.87,
    "documentation_ready": true
  },
  "relationships": [
    {
      "session_id": "sess_345",
      "similarity": 0.82,
      "type": "follow_up"
    }
  ],
  "patterns": {
    "recurring_issue": "Kubernetes resource limits",
    "frequency": 8,
    "trend": "increasing"
  },
  "insights": [
    {
      "type": "recommendation",
      "priority": "high", 
      "description": "Consider implementing HPA for dynamic scaling",
      "confidence": 0.85
    }
  ]
}

📖 完整的代理文檔

如需高級使用和詳細配置，請參考代理文檔：

• 🤖 Claude Code 代理文件 - 以 Markdown 格式提供的完整代理配置
• [🎭 conversation - orchestrator - agent](./.claude/agents/conversation - orchestrator - agent.md) - 主要協調器配置
• [🧠 semantic - analyzer - agent](./.claude/agents/semantic - analyzer - agent.md) - 語義分析代理
• [🔍 pattern - discovery - agent](./.claude/agents/pattern - discovery - agent.md) - 模式發現配置
• [📝 auto - documentation - agent](./.claude/agents/auto - documentation - agent.md) - 文檔生成代理
• 📋 上下文系統 - 知識庫和故障排除指南

📚 詳細文檔

📚 項目結構

claude - conversation - logger/
├── 📄 README.md                     # 主文檔
├── 🚀 QUICK_START.md                # 快速設置指南  
├── 🐳 docker - compose.yml            # 完整編排
├── 📦 package.json                  # 依賴項和腳本

├── 🔧 config/                       # 服務配置
│   ├── supervisord.conf             # 進程管理
│   ├── mongodb.conf                 # MongoDB 配置
│   └── redis.conf                   # Redis 配置

├── 🔌 src/                          # 源代碼
│   ├── server.js                    # 主 API 服務器
│   ├── mcp - server.js               # 用於 Claude Code 的 MCP 服務器
│   │
│   ├── 💾 database/                 # 數據層
│   │   ├── mongodb - agent - extension.js  # MongoDB + 代理集合
│   │   ├── redis.js                 # 智能緩存
│   │   └── agent - schemas.js         # 代理模式
│   │
│   ├── 🔧 services/                 # 業務服務
│   │   ├── conversationService.js   # 對話管理
│   │   ├── searchService.js         # 語義搜索
│   │   └── exportService.js         # 帶代理的導出
│   │
│   └── 🛠️ utils/                    # 實用工具
│       └── recovery - manager.js      # 數據恢復

├── 🤖 .claude/                      # Claude Code 集成
│   ├── agents/                      # 代理定義（Markdown 格式）
│   │   ├── conversation - orchestrator - agent.md  # 主要協調器
│   │   ├── semantic - analyzer - agent.md          # 語義分析
│   │   ├── pattern - discovery - agent.md          # 模式檢測
│   │   └── auto - documentation - agent.md         # 文檔生成
│   └── context/                     # 知識庫和故障排除

├── 💡 examples/                     # 示例和配置
│   ├── claude - settings.json         # 完整的 Claude Code 配置
│   ├── api - logger.py               # 日誌鉤子
│   └── mcp - usage - examples.md       # MCP 使用示例

└── 🧪 tests/                       # 測試套件
    ├── agents.test.js              # 代理測試
    ├── api.test.js                 # API 測試
    └── integration.test.js         # 集成測試

📈 指標與性能

🎯 代理指標

• 語義分析：主題檢測準確率達 95% 以上
• 狀態檢測：完成/活躍狀態檢測準確率達 90% 以上
• 關係映射：相似度準確率達 85% 以上
• 令牌優化：與手動分析相比，減少 70% 的令牌使用量
• 響應時間：完整分析時間小於 3 秒

⚡ 系統性能

• 啟動時間：完整容器啟動時間小於 30 秒
• API 響應時間：平均小於 100 毫秒
• 緩存命中率：頻繁查詢的緩存命中率達 85% 以上
• 內存使用：典型情況下約 768MB
• 併發用戶數：支持 100 個以上併發用戶

📊 代碼庫統計

• 代碼行數：3800 行以上（優化的代理系統）
• JavaScript 文件：15 個以上核心文件
• 代理文件：4 個與 Claude Code 兼容的文件
• API 端點：28 個以上端點（23 個核心 + 5 個代理工具）
• MCP 工具：5 個原生工具
• MongoDB 集合：8 個專用集合

🛡️ 安全與維護

🔐 安全

• API 密鑰認證：所有端點都需要 API 密鑰認證
• Helmet.js 安全：提供安全頭和保護
• 速率限制：生產環境中 15 分鐘內限制 200 個請求
• 可配置 CORS：跨域策略可配置
• 數據加密：數據在靜止和傳輸時均加密

🔧 故障排除

系統無法啟動

# 查看日誌
docker compose logs -f

# 檢查資源
docker stats

代理無響應

# 代理健康檢查
curl http://localhost:3003/api/agents/health

# 檢查配置
curl http://localhost:3003/api/agents/config

鉤子不工作

# 手動測試鉤子
python3 ~/.claude/hooks/api - logger.py

# 檢查權限
chmod +x ~/.claude/hooks/api - logger.py

# 測試 API 連接性
curl -X POST http://localhost:3003/api/conversations \
  -H "X - API - Key: claude_api_secret_2024_change_me" \
  -H "Content - Type: application/json" \
  -d '{"test": true}'

📞 支持與貢獻

🆘 獲取幫助

• 📖 技術文檔：請參閱 Claude Code 代理
• 🐛 報告錯誤：通過 GitHub Issues 報告
• 💡 功能請求：通過 GitHub Discussions 提出

🤝 貢獻

# 分叉並克隆
git clone https://github.com/your - username/claude - conversation - logger.git

# 創建功能分支
git checkout -b feature/agent - improvements

# 開發和測試
npm test
npm run test:agents

# 提交拉取請求
git push origin feature/agent - improvements

🧪 本地開發

# 安裝依賴項
npm install

# 配置開發環境
cp examples/claude - settings.json ~/.claude/settings.json

# 以開發模式啟動
npm run dev

# 運行代理測試
npm run test:agents

📄 許可證

MIT 許可證 - 詳情請參閱 LICENSE。

作者：Luciano Emanuel Ricardo
版本：3.1.0 - 與 Claude Code 兼容的代理系統
倉庫：https://github.com/LucianoRicardo737/claude - conversation - logger

🎉 總結

✅ 4 個與 Claude Code 兼容的代理 - 優化的多維智能分析
✅ 原生 Claude Code 集成 - 5 個即用型 MCP 工具
✅ 70% 令牌優化 - 分析效率最大化
✅ 多語言支持 - 支持西班牙語/英語，框架可擴展
✅ 深度語義分析 - 真正理解技術內容
✅ 自動文檔生成 - 上下文相關的指南生成
✅ 模式發現 - 主動識別反覆出現的問題
✅ 關係映射 - 智能對話連接
✅ 智能緩存 - 緩存命中率達 85% 以上，實現即時響應
✅ 完整的 REST API - 28 個以上端點，包括 Claude Code 代理工具
✅ Docker 部署 - 生產就緒的整體系統
✅ 42 個可配置參數 - 通過 Docker Compose 實現完全定製

🚀 擁有智能代理系統，可立即部署！