🧠 MCP ChromaDB内存服务器-认知状态管理平台

![MCP](https://modelcontextprotocol.io) ![ChromaDB](https://www.trychroma.com/) ![TypeScript](https://www.typescriptlang.org/) ](https://www.docker.com/) ![License](LICENSE)

全面 认知状态管理平台 这改变了开发人员保存上下文、管理知识以及在项目、会话和团队之间保持连续性的方式。

特性 • 平台愿景 • 安装 • 用法 • API • 建筑 • 贡献

______________________________________________________________________

🌟 概述

MCP ChromaDB内存服务器已经从一个简单的内存存储工具发展成为一个全面的 认知状态管理平台 与革命 双保险库架构.

🎯 关键创新：双保险库架构

维护两个独立但相互关联的知识库：

🧠 核心保险库：你的个人“第二大脑”随着每个项目的发展而成长
📦 项目金库：每个特定项目的干净、独立的上下文

永远不要再失去宝贵的见解——学习一次，到处应用！

🚀 平台愿景

该项目实现了一个完整的认知平台，该平台：

保留上下文：切换任务或设备时，永远不要失去精神状态
从使用中学习：自动从开发会话中提取模式和见解
智能扩展：针对性能优化的分层存储系统
深度融合：与您现有的开发工作流程无缝协作

看平台方法为了获得详细的视觉效果。

平台能力

🌟 标题功能

🎯 双保险库架构 -将核心知识与项目背景分开，同时保持联系
🚀 性能提升60倍 -PostgreSQL混合存储消除了ChromaDB限制
🧠 智能分类 -自动将内存路由到相应的保管库
🔄 跨保险库搜索 -使用加权相关结果查询两个保管库
📈 记忆提升 -将项目洞察力提升为永久核心知识

特点

🤖 自主存储 -人工智能评估的重要性决定了存储的内容
🔍 智能检索 -多因素评分结合了语义相似性、近因性、重要性和访问频率
🎯 上下文感知 -支持不同的内存上下文（一般、用户偏好、关键任务、笔记）
📊 智能评分 -检索使用加权评分：语义（40%）、最近性（30%）、重要性（20%）、频率（10%）
🔎 精确搜索 -快速字符串匹配和关键字索引，实现精确查找
🔀 混合搜索 -将精确搜索和语义搜索与可配置权重相结合
🗜️ 令牌优化 -智能压缩（减少50-90%），同时保留重要内容
📈 访问模式分析 -通过等级推荐追踪热/暖/冷记忆
📝 黑曜石融合 -使用语义搜索在黑曜石金库中读取、写入和搜索笔记
📚 会话日志记录 -自动将Claude Code对话记录到Obsidian，并附上摘要和代码亮点
📋 模板系统 -使用Handlebars支持从webhooks导入和管理文档模板
🏗️ 分层保险库结构 -具有自动文件夹生成和挂钩的通用开发人员文档系统
🏥 健康监测 -通过可视化仪表板和启动验证进行实时系统健康检查
📊 保险库索引 -全面的保险库统计和导航系统，可自动更新
🏗️ 分级存储系统 -具有自动迁移功能的三层架构（工作、会话、长期）
🔄 保险库管理 -即时上下文切换的多项目支持
💾 状态捕获 -跨设备保存和恢复完整的工作上下文
🧠 代码智能 -具有符号跟踪和关系的自动代码库索引
🔍 代码感知搜索 -基于流的符号搜索，立即找到实现和模式
📊 代码模式识别 -检测编码模式并从中学习，提出改进建议
⚡ 流媒体响应 -针对Claude Code和大型代码库优化的快速增量结果
🚀 混合存储 -PostgreSQL+ChromaDB实现最佳性能（644个符号/秒，比单独使用ChromaDB快60倍）✅
🔄 双写迁移 -安全迁移，同时写入两个数据库，可配置读取比率✅
⚡ 无油门 -仅使用ChromaDB，批量操作在1秒以内完成，而60秒以上完成✅

平台实施

🎯 CoachNTT -具有语音合成和VSCode集成的专业会话AI实现

- ElevenLabs支持人工智能的文本转语音 - 具有音频控制的丰富VSCode扩展 - 会话感知记忆评分 - 看 CoachNTT文档

平台增强功能（即将推出）

🧬 高级模式识别 -从跨项目的开发模式中进行深度学习
🔄 记忆巩固 -智能重复数据删除和内存合并
🔀 Git集成 -将内存链接到提交、分支和拉取请求

📋 需求

Node.js 20+
Docker&Docker编写
PostgreSQL 16+，带pgvector扩展（包含在docker compose中）
OpenAI API密钥（用于嵌入）
最低4GB RAM（PostgreSQL增加了）
Windows/macOS/Linux

📖 快速参考

🎯 开始使用双保险库

双保险库快速入门 -在5分钟内设置双保险库
双保险库迁移指南 -从单个vault迁移

核心文档

内存使用指南 -学习如何有效地使用内存系统
混合存储指南 -PostgreSQL+ChromaDB混合架构
代码智能指南 -代码感知功能和符号索引
双实例设置 -设置隔离的开发环境
开发状态 -当前进展和路线图
CoachNTT实施 -具有语音合成功能的对话式人工智能

📚 新用户指南

综合使用指南 -克劳德代码和桌面与WSL/Windows路径的完整指南
快速参考卡 -一页上的基本命令和提示
平台价值最大化 -先进技术和生产力模式

🚀 快速开始

使用Docker Compose（推荐）

克隆仓库

   git clone https://github.com/stevenjjobson/mcp-chromadb-memory.git
   cd mcp-chromadb-memory

设置环境

   cp .env.example .env
   # Edit .env and add your OpenAI API key

启动服务

   # For Claude Desktop - start ChromaDB and PostgreSQL (both required)
   docker-compose up -d coachntt-chromadb coachntt-postgres

   # Or use the convenience script (Windows)
   .\start-chromadb.ps1

备注：Claude Desktop会自动创建自己的MCP容器。混合存储架构现在需要ChromaDB和PostgreSQL。

验证安装

   docker-compose logs -f coachntt-chromadb

备注：独立运行时，MCP服务器容器将立即退出。这是正常行为——MCP服务器通过stdio通信，需要客户端连接。使用下面的Claude Desktop配置正确连接到服务器。

🎯 双保险库架构

转变您的开发工作流程

双保险库架构彻底改变了您跨项目管理知识的方式：

┌─────────────────────┐         ┌─────────────────────┐
│    Core Vault       │         │   Project Vault     │
│  (Your Brain 🧠)    │◄────────│  (Current Work 📦)  │
├─────────────────────┤         ├─────────────────────┤
│ • Best Practices    │         │ • Project Decisions │
│ • Code Patterns     │         │ • Local Config      │
│ • Personal Prefs    │         │ • Client Context    │
│ • Learned Wisdom    │         │ • Session Logs      │
└─────────────────────┘         └─────────────────────┘
         ▲                                 ▲
         └─────────────┬───────────────────┘
                       │
                  Smart Search
                  Categorization
                  Memory Promotion

快速设置（2分钟）

启用双保险库 在 .env.PRODUCTION:

   VAULT_MODE=dual
   CORE_VAULT_PATH=C:/Users/YourName/Obsidian/YourVault
   PROJECT_VAULT_PATH=./vault

更新克劳德桌面 配置以装载两个保险库

开始使用 -记忆会自动转移到正确的保险库！

看双保险库快速入门指南完成设置。

地方发展设置

安装依赖项

   npm install

启动所需服务

   # Both ChromaDB and PostgreSQL are required
   docker-compose up -d coachntt-chromadb coachntt-postgres

构建并运行

   npm run build
   npm run dev

🚀 WSL快速入门

使用启动脚本（推荐）

对于WSL用户，我们提供了一个全面的启动脚本，确保所有服务正常运行：

# Make the script executable (first time only)
chmod +x start-mcp-platform.sh

# Run the startup script
./start-mcp-platform.sh

脚本将：

✅ 验证Docker是否正在运行
✅ 检查ChromaDB状态，必要时启动
✅ 验证环境配置
✅ 如果需要，构建TypeScript
✅ 运行健康检查
✅ 显示可视化仪表板
✅ 准备就绪后，可选择启动Claude Desktop

看 WSL启动指南了解详细信息。

🔧 配置

环境变量

创建一个 .env 项目根目录中的文件：

# ChromaDB Configuration
CHROMA_HOST=coachntt-chromadb  # Use 'localhost' for local development
CHROMA_PORT=8000

# OpenAI Configuration (required for embeddings)
# API key is stored securely in Docker secrets - see Security section below

# Obsidian Integration (optional)
OBSIDIAN_VAULT_PATH=/path/to/your/vault

# Memory Configuration
MEMORY_IMPORTANCE_THRESHOLD=0.7    # Minimum importance score to store (0-1)
MEMORY_COLLECTION_NAME=coachntt_memories
MAX_MEMORY_RESULTS=10

# Server Configuration
MCP_SERVER_NAME=coachntt-cognitive-server
MCP_SERVER_VERSION=1.0.0

Claude桌面集成

找到配置文件:

- 窗户： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

添加MCP服务器配置:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "mcp-chromadb-memory_coachntt-platform-network",
        "-v", "C:/Users/Steve/Dockers/mcp-chromadb-memory/vault:/vault:rw",
        "-e", "DOCKER_CONTAINER=true",
        "-e", "CHROMA_HOST=coachntt-chromadb",
        "-e", "CHROMA_PORT=8000",
        "-e", "POSTGRES_HOST=coachntt-postgres",
        "-e", "POSTGRES_PORT=5432",
        "-e", "POSTGRES_USER=coachntt_user",
        "-e", "POSTGRES_PASSWORD=coachntt_pass",
        "-e", "POSTGRES_DATABASE=coachntt_cognitive_db",
        "-e", "USE_HYBRID_STORAGE=true",
        "-e", "OBSIDIAN_VAULT_PATH=/vault",
        "-e", "AUTO_START_SESSION_LOGGING=true",
        "-e", "SESSION_LOGGING_PROJECT_NAME=CoachNTT Cognitive Platform",
        "mcp-chromadb-memory-mcp-memory"
      ]
    }
  }
}

重新启动克劳德桌面 加载新配置

对于没有Docker的本地开发：

{
  "mcpServers": {
    "memory-local": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-chromadb-memory\\dist\\index.js"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "coachntt_cognitive_db",
        "POSTGRES_USER": "coachntt_user",
        "POSTGRES_PASSWORD": "coachntt_pass",
        "USE_HYBRID_STORAGE": "true"
      }
    }
  }
}

📚 api参考

工具

`store_memory`

根据人工智能评估的重要性存储信息。

{
  content: string;      // The information to store
  context?: string;     // Context category (general, user_preference, task_critical, obsidian_note)
  metadata?: object;    // Additional metadata
}

答复：

{
  "stored": true,
  "id": "mem_1234567890_abc",
  "importance": 0.85
}

`recall_memories`

使用上下文感知过滤检索相关内存。

{
  query: string;        // Search query
  context?: string;     // Optional context filter
  limit?: number;       // Max results (default: 5)
}

答复：

[
  {
    "content": "User prefers dark mode interfaces",
    "context": "user_preference",
    "importance": "0.80",
    "timestamp": "2024-01-15T10:30:00Z",
    "scores": {
      "total": "0.825",
      "semantic": "0.920",
      "recency": "0.750",
      "importance": "0.800",
      "frequency": "0.600"
    }
  }
]

`health_check`

验证服务器状态和ChromaDB连接。

答复：

{
  "status": "ok",
  "chromadb_connected": true,
  "server_version": "1.0.0",
  "platform": "linux",
  "docker": true
}

会话日志工具

`start_session_logging`

开始将Claude Code会话记录到Obsidian。

{
  project?: string;     // Project name (default: "General")
}

`save_session_log`

将当前会话保存到Obsidian，并自动生成摘要。

{
  summary?: string;     // Optional manual summary
}

`log_session_event`

在会话期间手动记录特定事件。

{
  type: string;         // Event type: user, assistant, tool, decision, achievement
  content: string;      // Event content
  metadata?: object;    // Additional metadata
}

自动会话日志记录：设置 AUTO_START_SESSION_LOGGING=true 在您的环境中，当Claude Code连接时，会自动开始日志记录。如果出现以下情况，会话将在退出时自动保存 SESSION_LOGGING_SAVE_ON_EXIT=true （默认）。

看会话_博客.md 详细用法。

模板管理工具

`import_template`

从外部webhook源导入文档模板。

{
  source: string;        // URL of the template to import
  category?: string;     // Template category (session, decision, pattern, etc.)
  variables?: object;    // Variables to apply immediately
  saveAs?: string;       // Filename to save generated document
}

`list_templates`

列出系统中所有可用的模板。

{
  category?: string;     // Filter by category
  source?: string;       // Filter by source URL
}

`apply_template`

应用带有变量的模板来生成文档。

{
  templateId: string;    // ID of the template
  variables: object;     // Variables to apply
  outputPath: string;    // Where to save the document
}

`configure_template_webhook`

配置webhook源以导入模板。

{
  name: string;          // Name for this webhook
  url: string;           // Webhook URL
  authType?: string;     // Authentication type (none, bearer, api-key, oauth)
  authCredentials?: string; // Auth credentials
  syncInterval?: number; // Auto-sync interval in minutes
}

`sync_templates`

同步所有已配置的webhook源中的模板。

// No parameters required

看模板系统设计详细的架构。

Vault结构管理工具

`import_vault_structure`

使用模板和挂钩导入完整的vault结构定义。

{
  source: string;              // URL or path to structure definition
  applyImmediately?: boolean;  // Apply structure after import
  targetPath?: string;         // Target path (defaults to vault)
}

`generate_vault_structure`

从加载的结构模板生成文件夹层次结构。

{
  structureId?: string;        // Structure name/ID
  targetPath: string;          // Where to generate
  options?: {
    skipExisting?: boolean;    // Skip existing folders
    dryRun?: boolean;          // Preview without changes
    applyTemplates?: boolean;  // Apply folder templates
  }
}

`apply_folder_hooks`

将钩子应用于现有文件夹以进行自动操作。

{
  folderPath: string;          // Folder to apply hooks to
  hookIds?: string[];          // Specific hooks (or all)
}

看分层保险库结构系统以获取完整的文档。

分级存储系统

该平台现在具有复杂的三层内存架构，可以自动管理内存生命周期：

内存层

工作记忆 （48小时）

- 存储即时上下文和活动任务 - 最快检索速度 - 自动将旧内存迁移到会话层

会话记忆 （14天）

- 包含最近的开发会话 - 平衡性能和保留率 - 将重要记忆迁移到长期层

长期记忆 （永久）

- 保存关键知识和模式 - 针对重要信息进行了优化 - 永不过期

层级管理工具

get_tier_stats -查看跨层的内存分布
analyze_access_patterns -获取分层优化建议
get_memories_for_migration -预览待处理的层迁移

配置

在您的 .env:

# Tier Configuration
TIER_ENABLED=true
TIER_WORKING_RETENTION=48      # Hours
TIER_SESSION_RETENTION=336     # Hours (14 days)
TIER_LONGTERM_RETENTION=8760   # Hours (1 year)
TIER_MIGRATION_INTERVAL=3600000 # Milliseconds (1 hour)

迁移服务在后台自动运行，根据年龄和访问模式在层之间移动内存。

代码智能系统

该平台包括针对Claude code和开发工作流程优化的高级代码智能功能：

代码智能工具

index_codebase -支持流媒体的快速符号提取和存储
find_symbol -跨代码库的基于流的符号搜索
get_symbol_context -丰富的上下文检索，包括导入、使用和关系
analyze_code_patterns -检测模式、反模式和改进机会

代码存储器功能

自动符号索引

- 函数、类、方法和变量 - 导入关系和依赖关系 - 文件结构和组织 - 文件更改时的自动更新

流媒体架构

- 结果在找到时即流式传输（第一个结果\ B1 A2 --> B2 A3 --> B3 B1 --> C1 B2 --> C2 B3 --> C3 C1 --> D1 C2 --> D2 C3 --> D3 D1 --> E1 D1 --> E2 D2 --> E1 D2 --> E2 D3 --> E1 D3 --> E2 C2 --> E3 C4 --> E3 C3 --> E4


看 [实施路线图](./vault/Planning/roadmaps/Implementation%20Roadmap.md) 有关转换的详细信息。

### 内存评分算法

检索系统使用复杂的多因素评分方法：

- **语义相似性（40%）**：查询和内存嵌入之间的余弦相似性
- **近期得分（30%）**：基于自上次访问以来的时间的指数衰减
- **重要性得分（20%）**：AI评估了存储期间的重要性
- **频率得分（10%）**：访问计数的对数缩放

## 🛠️ 发展

### 双实例开发

为了安全测试新功能，请使用隔离的开发环境：

Start development environment

./scripts/env-manager.sh start-dev

Check status

./scripts/env-manager.sh status

Run in development mode

./scripts/test-hierarchical.sh


这在端口8001上创建了一个完全独立的ChromaDB实例，该实例具有自己的数据和配置。

### 可用脚本

npm run build # Compile TypeScript npm run dev # Run with hot reload npm run test # Run test suite npm run inspect # Test with MCP Inspector npm run docker:build # Build Docker image npm run docker:run # Run in Docker


### MCP检验员测试

npm run inspect


然后在检查员中：

1. 呼叫 `health_check` 验证连接
1. 使用 `store_memory` 保存测试记忆
1. 使用 `recall_memories` 测试检索

## 🔧 故障排除

### 快速诊断

运行配置验证器以检查常见问题：

./scripts/validate-config.sh


### MCP服务器未加载

#### Claude桌面问题

1. **验证配置文件位置**:

   - 窗户： `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Linux： `~/.config/Claude/claude_desktop_config.json`

1. **常见配置错误**:

   - JSON语法错误（使用 `python -m json.tool < config.json` 验证）
   - 容器名称错误（应为 `coachntt-chromadb` 和 `coachntt-postgres`)
   - 硬编码API密钥（安全风险，但Claude Desktop需要）
   - Windows路径问题（使用正斜杠： `C:/Users/...`)

1. **快速设置脚本**:

./scripts/setup-claude-desktop.sh


#### Claude代码CLI问题

1. **未设置环境变量**:

export OPENAI_API_KEY="your-api-key-here" # Add to ~/.bashrc for persistence


1. **配置问题**:

   - `.mcp.json` 必须位于项目根目录中
   - 检查配置中的空环境变量
   - 确保 `.env.PRODUCTION` 具有正确的设置

1. **直接测试服务器**:

OPENAI_API_KEY="your-key" node dist/index.js


### 数据库连接错误

1. **检查服务名称是否匹配**:

# docker-compose.yml should have: coachntt-postgres: container_name: coachntt-postgres coachntt-chromadb: container_name: coachntt-chromadb


1. **验证凭据是否匹配**:

   - PostgreSQL： `coachntt_user` / `coachntt_pass` / `coachntt_cognitive_db`
   - 这些必须在所有配置文件中保持一致

1. **检查服务是否健康**:

docker ps # Look for (healthy) or (unhealthy) status


### 路径和环境问题

1. **未找到保险库路径**:

   - 检查 `.env.PRODUCTION` 有 `OBSIDIAN_VAULT_PATH=./vault`
   - 确保vault目录存在
   - 对于双保险库：确保两条路径都存在且可访问

1. **环境文件加载**:

   - 系统负载 `.env.PRODUCTION` 默认情况下
   - 中的设置 `.env` 除非设置了ENVIRONMENT_NAME，否则将被忽略
   - 缺少的设置不会回退到其他文件

### 常见问题及解决方法

|问题|原因|解决方案|
|-------|-------|----------|
|“容器立即退出”|MCP正常行为|MCP服务器按需运行|
|“无法连接到ChromaDB”|容器不正常| `docker-compose restart chromadb` |
|“缺少OpenAI API密钥”|不在环境中|设置 `OPENAI_API_KEY` 有人是。
|“在./Vault中找不到Vault”|路径配置错误|确保Vault目录存在并且可访问|
|“JSON中的转义字符错误”|Windows路径问题|在路径中使用正斜杠|
|“postgres角色不存在”|凭据错误|检查docker-compose.yml是否与配置匹配|

### 配置参考

查看综合 [MCP配置指南](docs/guides/mcp-configuration-guide.md) 用于：

- Claude Desktop与Claude Code CLI的详细差异
- 平台特定设置说明
- 环境变量引用
- 安全最佳实践

## 🤝 贡献

欢迎投稿！请随时提交拉取请求。

### 🚀 平台v2.0开发

我们正在积极开发下一个主要版本，将其转化为认知状态管理平台。贡献：

Platform development branch

git checkout feature/platform-transformation git pull origin feature/platform-transformation


### 贡献过程

1. 分叉存储库
1. 切换到平台分支(`git checkout feature/platform-transformation`)
1. 创建功能分支(`git checkout -b feature/AmazingFeature`)
1. 提交您的更改(`git commit -m 'Add some AmazingFeature'`)
1. 推到分支(`git push origin feature/AmazingFeature`)
1. 打开拉取请求

## 📄 许可证

此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。

## 🙏 致谢

- 建立在 [模型上下文协议](https://modelcontextprotocol.io) 通过Anthropic
- 由...驱动 [色度数据库](https://www.trychroma.com/) 用于矢量存储
- 用途 [OpenAI嵌入](https://platform.openai.com/docs/guides/embeddings) 用于语义搜索

## 📞 支持

- 🐛 [报告错误](https://github.com/stevenjjobson/mcp-chromadb-memory/issues)
- 💡 [请求功能](https://github.com/stevenjjobson/mcp-chromadb-memory/issues)
- 📖 [文档](https://github.com/stevenjjobson/mcp-chromadb-memory/wiki)

## 📚 附加文档

该项目采用双重文档结构：

**技术文档** (`docs/`):

- API参考
- 入门指南
- 建筑说明
- 路线图和现状

**知识库** (`vault/`):

- 人工智能背景下的黑曜石金库
- 会话日志和开发历史
- 架构决策
- 知识和设置指南
- 模板和规划文件

关键位置：

- **设置指南**: `vault/Knowledge/Setup/`
- **建筑**: `vault/Architecture/`
- **会话日志**: `vault/Sessions/`
- **模板**: `vault/Templates/`

______________________________________________________________________

Made with ❤️ for the MCP ecosystem

MCP Chromadb Memory

快速接入

详细介绍

🧠 MCP ChromaDB内存服务器-认知状态管理平台

🌟 概述

🎯 关键创新：双保险库架构

🚀 平台愿景

平台能力

🌟 标题功能

特点

平台实施

平台增强功能（即将推出）

📋 需求

📖 快速参考

🎯 开始使用双保险库

核心文档

📚 新用户指南

🚀 快速开始

使用Docker Compose（推荐）

🎯 双保险库架构

转变您的开发工作流程

快速设置（2分钟）

地方发展设置

🚀 WSL快速入门

使用启动脚本（推荐）

🔧 配置

环境变量

Claude桌面集成

📚 api参考

工具

store_memory

recall_memories

health_check

会话日志工具

start_session_logging

save_session_log

log_session_event

模板管理工具

import_template

list_templates

apply_template

configure_template_webhook

sync_templates

Vault结构管理工具

import_vault_structure

generate_vault_structure

apply_folder_hooks

分级存储系统

内存层

层级管理工具

配置

代码智能系统

代码智能工具

代码存储器功能

Start development environment

Check status

Run in development mode

Platform development branch

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`store_memory`

`recall_memories`

`health_check`

`start_session_logging`

`save_session_log`

`log_session_event`

`import_template`

`list_templates`

`apply_template`

`configure_template_webhook`

`sync_templates`

`import_vault_structure`

`generate_vault_structure`

`apply_folder_hooks`