Vector Memory Mcp Server

向量记忆 MCP 服务

面向 Claude Desktop 的安全向量记忆服务，使用 sqlite-vec 和 sentence-transformers。该 MCP 服务提供持久化语义记忆功能，通过记住并检索相关的编码经验、解决方案和知识，增强 AI 编码助手的能力。

✨ 功能

• 🔍 语义搜索：使用 384 维嵌入进行基于向量的相似度搜索
• 🏷️ 语义规范化：自动合并相似标签、规范化类别、使用结构化冒号标签
• 📊 IDF 标签权重：基于频率的加权，提升搜索相关性
• 💾 持久化存储：通过 sqlite-vec 使用支持向量索引的 SQLite 数据库
• 🔒 安全优先：输入验证、路径清理和资源限制
• ⚡ 高性能：使用 sentence-transformers 快速生成嵌入
• 🧹 自动清理：智能记忆管理和清理工具
• 📈 丰富的统计信息：全面分析记忆数据库
• 🔄 自动去重：SHA-256 内容哈希可防止存储重复记忆
• 🧠 智能清理算法：根据时效性、访问模式和重要性优先保留记忆

🛠️ 技术栈

组件	技术	用途
向量数据库	sqlite-vec	向量存储和相似度搜索
嵌入	sentence-transformers/all-MiniLM-L6-v2	384 维文本嵌入
规范化	语义相似度 + 防护机制	自动合并标签/类别
MCP 框架	FastMCP	高级仅工具型服务
依赖项	uv 脚本头部	自包含部署
安全性	自定义验证	路径/输入清理
测试	pytest + coverage	全面的测试套件

📁 项目结构

vector-memory-mcp/
├── main.py                              # Main MCP server entry point
├── README.md                            # This documentation
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Modern Python project config
├── .python-version                      # Python version specification
├── claude-desktop-config.example.json  # Claude Desktop config example
│
├── src/                                # Core package modules
│   ├── __init__.py                    # Package initialization
│   ├── models.py                      # Data models & configuration
│   ├── security.py                    # Security validation & sanitization
│   ├── embeddings.py                  # Sentence-transformers wrapper
│   ├── memory_store.py                # SQLite-vec operations
│   ├── README_AGENTS.md               # Agent documentation (4 levels)
│   └── CASES_AGENTS.md                # Use cases for Brain ecosystem
│
└── .gitignore                         # Git exclusions

🗂️ 组织指南

本项目经过精心组织，便于理解和使用：

• main.py - 从这里开始！服务主入口
• src/ - 核心实现（安全、嵌入、记忆存储）
• claude-desktop-config.example.json - 配置模板

初次使用？ 从 main.py 和 claude-desktop-config.example.json 开始

🚀 快速开始

前提条件

• Python 3.10 或更高版本（推荐：3.11）
• uv 包管理器
• Claude Desktop 应用

安装 uv（如果尚未安装）：

macOS 和 Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

验证安装：

uv --version

安装

选项 1：通过 uvx 快速安装（推荐）

使用此 MCP 服务最简单的方式——无需克隆或设置！

发布到 PyPI 后，即可直接使用：

# Run without installation (like npx)
uvx vector-memory-mcp --working-dir /path/to/your/project

Claude Desktop 配置（使用 uvx）：

{
  "mcpServers": {
    "vector-memory": {
      "command": "uvx",
      "args": [
        "vector-memory-mcp",
        "--working-dir",
        "/absolute/path/to/your/project",
        "--memory-limit",
        "100000"
      ]
    }
  }
}

注意： --memory-limit 为可选项。不指定时，默认使用 10,000 条记录。

注意：目前正在进行 PyPI 发布。详情请参阅 PUBLISHING.md。

选项 2：从源代码安装（用于开发）

1. 克隆项目：

   git clone <repository-url>
   cd vector-memory-mcp
   

2. 安装依赖项（使用 uv 自动完成）： 依赖项通过 main.py 中的内联元数据自动管理，无需手动安装。

   验证依赖项：

   uv pip list
   

3. 测试服务：

   # Test with sample working directory
   uv run main.py --working-dir ./test-memory
   

4. 配置 Claude Desktop：

   复制示例配置：

   cp claude-desktop-config.example.json ~/path/to/your/config/
   

   打开 Claude Desktop 设置 → 开发者 → 编辑配置，并添加以下内容（将路径替换为绝对路径）：

   {
     "mcpServers": {
       "vector-memory": {
         "command": "uv",
         "args": [
           "run",
           "/absolute/path/to/vector-memory-mcp/main.py",
           "--working-dir",
           "/your/project/path",
           "--memory-limit",
           "100000"
         ]
       }
     }
   }
   

   重要提示：

   • 使用绝对路径，不要使用相对路径
   • --memory-limit 为可选项（默认值：10,000）
   • 对于大型项目，请设置为 100,000-1,000,000

5. 重启 Claude Desktop，并查找 MCP 集成图标。

选项 3：使用 pipx 安装（替代方案）

# Install globally (once published to PyPI)
pipx install vector-memory-mcp

# Run
vector-memory-mcp --working-dir /path/to/your/project

Claude Desktop 配置（使用 pipx）：

{
  "mcpServers": {
    "vector-memory": {
      "command": "vector-memory-mcp",
      "args": [
        "--working-dir",
        "/absolute/path/to/your/project",
        "--memory-limit",
        "100000"
      ]
    }
  }
}

📚 使用指南

可用工具

1. store_memory - 存储知识

存储编码经验、解决方案和见解：

Please store this memory:
Content: "Fixed React useEffect infinite loop by adding dependency array with [userId, apiKey]. The issue was that the effect was recreating the API call function on every render."
Category: bug-fix
Tags: ["react", "useEffect", "infinite-loop", "hooks"]

2. search_memories - 语义搜索

使用自然语言查找相关记忆：

Search for: "React hook dependency issues"

3. list_recent_memories - 浏览近期记忆

查看最近存储的内容：

Show me my 10 most recent memories

4. get_memory_stats - 数据库健康状况

查看记忆数据库统计信息：

Show memory database statistics

5. clear_old_memories - 清理

清理过时且未使用的记忆：

Clear memories older than 30 days, keep max 1000 total

6. get_by_memory_id - 检索特定记忆

通过 ID 获取特定记忆的完整详情：

Get memory with ID 123

返回所有字段，包括内容、类别、标签、时间戳、访问次数和元数据。

7. delete_by_memory_id - 删除记忆

从数据库中永久删除特定记忆：

Delete memory with ID 123

以原子方式从元数据表和向量表中删除该记忆。

8. get_unique_tags - 列出所有标签

获取记忆中当前使用的所有唯一标签：

Show all unique tags

返回记忆元数据中的标签列表，并按顺序排序。

9. get_canonical_tags - 列出规范标签

获取所有规范（归一化）标签：

Show canonical tags

返回语义合并后的归一化标签形式。可用于了解标签整合情况。

10. get_tag_frequencies - 标签使用统计

获取所有规范标签的出现频次：

Show tag frequencies

显示每个标签的使用频率。频率越高，标签越常见。

11. get_tag_weights - IDF 权重

获取用于搜索相关性计算的 IDF 权重：

Show tag weights

返回按 1 / log(1 + frequency) 计算的权重：

• 常见标签（api、auth）→ 权重较低（区分度较低）
• 少见标签（module:terminal）→ 权重较高（区分度较高）

12. cookbook - 知识库（关键）

关键：在使用任何其他工具之前，请先阅读此内容。没有它，你就如同盲目操作。

# FIRST: Initialize context (READ THIS FIRST)
mcp__vector-memory__cookbook()

# List available categories with keys
mcp__vector-memory__cookbook(include="categories")

# Cases by key (exact match)
mcp__vector-memory__cookbook(include="cases", case_category="gates-rules")
mcp__vector-memory__cookbook(include="cases", case_category="search")

# Search in cookbook
mcp__vector-memory__cookbook(include="cases", query="JWT token")
mcp__vector-memory__cookbook(include="docs", query="tag normalization", level=2)

# Pagination
mcp__vector-memory__cookbook(include="cases", query="task", limit=5, offset=0)

# Documentation by level
mcp__vector-memory__cookbook(include="docs", level=0)  # Quick start
mcp__vector-memory__cookbook(include="docs", level=2)  # Advanced patterns

# Full debug info
mcp__vector-memory__cookbook(include="all", level=3)

参数：

参数	取值	描述
include	"init", "docs", "cases", "categories", "all"	要返回的内容（默认值为 "init"）
level	0-3	文档详尽程度（默认值为 0）
case_category	string	按键（精确匹配）或标题（部分匹配）筛选用例
query	string	在内容中进行文本搜索
limit	1-50	结果数量上限（默认值为 10）
offset	int	分页偏移量（默认值为 0）

包含模式：

模式	返回内容
init	首次阅读——快速入门 + 可用资源
docs	按级别返回文档
cases	用例场景（按类别/查询筛选）
categories	类别列表，包含键和描述
all	合并返回所有内容

文档级别：

级别	内容
0	身份信息与快速入门
1	实用用法
2	高级模式
3	架构与内部机制

类别键：

键	描述
cookbook-usage	如何使用 cookbook() 工具
store	存储记忆并进行去重
search	多探针搜索、任务前挖掘
statistics	记忆统计、标签频次
task-management	将记忆与 Task MCP 集成
brain-docs	CLI 文档索引
agent-coordination	Brain 委派、多 Agent 协作
integration	多源知识、错误恢复
debugging	通过捕获记忆进行调试
cleanup	删除操作、按时间清理
gates-rules	关键/高优先级规则
task-integration	Memory-Task 工作流模式

**用例类别：**知识库用法、存储、搜索、统计、任务创建、任务分解、任务状态、Brain 文档、Agent 协作、集成、调试、清理

**包含内容：**4 个文档级别 + 12 个用例类别 + Brain 生态系统参考。

记忆类别

类别	用例
code-solution	可用的代码片段、实现
bug-fix	Bug 修复和调试方法
architecture	系统设计决策和模式
learning	新概念、教程、见解
tool-usage	工具配置、CLI 命令
debugging	调试技巧和发现
performance	优化策略和结果
security	安全注意事项和修复
other	其他所有内容

🏷️ 语义规范化

服务会根据语义相似度自动规范化标签和类别，以保持一致性。

标签规范化

存储记忆时，相似的标签会合并为规范标签：

输入标签	规范结果
api v2.0、api 2、API version 2	api v2.0
php8、PHP 8、php-8	php8
laravel、laravel framework	laravel（带子字符串加权）

合并规则

✅ 以下情况会合并：

• 版本相同：api v2.0 ↔ api 2（阈值 0.85）
• 高度相似：php8 ↔ php 8（阈值 0.90）
• 子字符串加权：laravel ⊂ laravel framework（相似度 +0.03）

❌ 以下情况绝不会合并：

• 版本不同：api v1 ≠ api v2
• 数字不同：php7 ≠ php8
• 结构化与普通标签：type:refactor ≠ refactor
• 前缀相同、后缀不同：type:refactor ≠ type:bug
• 停用词：api ≠ rest api、ui ≠ web ui

结构化标签（冒号标签）

使用结构化标签进行精细分类：

["type:refactor", "priority:high", "domain:api", "module:auth"]

允许的前缀： type、domain、strict、cognitive、batch、module、vendor、priority、scope、layer

无效前缀会被拒绝：random:stuff → 已移除

类别规范化

类别也会根据语义进行规范化。较短的输入会使用词典回退：

输入	输出
bugfix、bug、fix	bug-fix
auth、sec	security
perf、opt	performance
debug	debugging
arch、design	architecture

阈值

阈值	数值	用途
标签合并	0.90	默认合并相似度
版本相同	0.85	同版本标签使用较低阈值
子字符串加权	+0.03	对子集标签进行加权
类别	0.50	类别匹配阈值
子字符串最小长度	4	子字符串加权所需的最小长度

停用词（不进行子字符串加权）

这些标签不会进行子字符串加权（过于通用）：

api, ui, db, test, auth, infra, ci, cd, app, lib, sdk, cli, gui, web, sql, orm, log, cfg, env, dev, prod, stg

标签规范指南

良好的标签（描述主题/领域）：

["authentication", "laravel", "middleware", "api v2"]

不好的标签（描述工具/活动）：

["phpstan", "ci", "tests", "run-migration"]  # Don't use these

IDF 标签权重

标签使用 IDF（逆文档频率）进行加权：

weight = 1 / log(1 + frequency)

标签	频率	权重	说明
api	50	0.26	非常常见，区分能力较弱
laravel	10	0.43	较常见，区分能力中等
module:terminal	2	1.44	少见，区分能力较强

使用 get_tag_weights 查看所有权重。少见标签对搜索相关性的提升高于常见标签。

🔧 配置

命令行参数

服务支持以下参数：

# Run with uv (recommended) - default 10,000 memory limit
uv run main.py --working-dir /path/to/project

# With custom memory limit for large projects
uv run main.py --working-dir /path/to/project --memory-limit 100000

# Working directory is where memory database will be stored
uv run main.py --working-dir ~/projects/my-project --memory-limit 500000

可用选项：

• --working-dir（必需）：存储记忆数据库的目录
• --memory-limit（可选）：记忆条目的最大数量
  • 默认值：10,000 条
  • 最小值：1,000 条
  • 最大值：10,000,000 条
  • 大型项目建议值：100,000-1,000,000 条

工作目录结构

your-project/
├── memory/
│   └── vector_memory.db    # SQLite database with vectors
├── src/                    # Your project files
└── other-files...

安全限制

• 记忆内容上限：10,000 个字符
• 记忆总数上限：可通过 --memory-limit 配置（默认：10,000 条）
• 搜索结果上限：每次查询 50 条
• 每条记忆的标签数上限：10 个
• 路径验证：阻止可疑字符

🎯 用例

个人开发者

# Store a useful code pattern
"Implemented JWT refresh token logic using axios interceptors"

# Store a debugging discovery  
"Memory leak in React was caused by missing cleanup in useEffect"

# Store architecture decisions
"Chose Redux Toolkit over Context API for complex state management because..."

团队工作流

# Store team conventions
"Team coding style: always use async/await instead of .then() chains"

# Store deployment procedures
"Production deployment requires running migration scripts before code deploy"

# Store infrastructure knowledge
"AWS RDS connection pooling settings for high-traffic applications"

用于学习与成长

# Store learning insights
"Understanding JavaScript closures: inner functions have access to outer scope"

# Store performance discoveries
"Using React.memo reduced re-renders by 60% in the dashboard component"

# Store security learnings
"OWASP Top 10: Always sanitize user input to prevent XSS attacks"

🔍 语义搜索的工作原理

服务使用 sentence-transformers 将你的记忆转换为 384 维向量，以捕捉语义含义：

搜索示例

查询	可找到的相关记忆
"authentication patterns"	JWT、OAuth、登录系统、会话管理
"database performance"	SQL 优化、索引、查询调优、缓存
"React state management"	useState、Redux、Context API、状态模式
"API error handling"	HTTP 状态码、重试逻辑、错误响应

相似度评分

• 0.9+ 相似度：极其相关，几乎完全匹配
• 0.8-0.9：高度相关，语义相似度很强
• 0.7-0.8：中度相关，匹配度较好
• 0.6-0.7：有一定相关性，可能有用
• <0.6：相关性较低，可能没有帮助

📊 数据库统计信息

get_memory_stats 工具可提供全面的统计信息：

{
  "total_memories": 247,
  "memory_limit": 100000,
  "usage_percentage": 0.25,
  "categories": {
    "code-solution": 89,
    "bug-fix": 67,
    "learning": 45,
    "architecture": 23,
    "debugging": 18,
    "other": 5
  },
  "recent_week_count": 12,
  "database_size_mb": 15.7,
  "health_status": "Healthy"
}

统计字段说明

• total_memories：数据库当前存储的记忆数量
• memory_limit：允许存储的记忆数量上限（可通过 --memory-limit 配置，默认值：10,000）
• usage_percentage：数据库容量使用率（total_memories / memory_limit * 100）
• categories：按类别划分的记忆数量明细
• recent_week_count：过去 7 天内创建的记忆数量
• database_size_mb：SQLite 数据库文件在磁盘上的实际大小
• health_status：根据使用情况和性能指标得出的数据库整体健康状况

🛡️ 安全功能

输入验证

• 清理所有用户输入，防止注入攻击
• 移除控制字符和空字节
• 对所有内容强制实施长度限制

路径安全

• 验证并规范化所有文件路径
• 防止目录遍历攻击
• 阻止可疑的字符模式

资源限制

• 限制记忆总数和单条记忆的大小
• 防止数据库膨胀和内存耗尽
• 实施旧数据清理机制

SQL 安全

• 仅使用参数化查询
• 不根据用户输入动态构造 SQL
• 使用 SQLite WAL 模式确保并发访问安全

🔧 故障排除

常见问题

服务无法启动

# Check if uv is installed
uv --version

# Test server manually
uv run main.py --working-dir ./test

# Check Python version
python --version  # Should be 3.10+

Claude Desktop 无法连接

1. 确认配置中使用的是绝对路径
2. 检查 Claude Desktop 日志：~/Library/Logs/Claude/
3. 修改配置后重启 Claude Desktop
4. 配置 Claude 之前，先手动测试服务

记忆搜索无法正常工作

• 确认 sentence-transformers 模型已成功下载
• 检查 memory/ 目录中的数据库文件权限
• 尝试使用范围更广的搜索词
• 检查记忆内容是否相关

性能问题

• 运行 get_memory_stats 检查数据库健康状况
• 使用 clear_old_memories 清理旧条目
• 考虑增加硬件资源，以加快嵌入向量生成

调试模式

手动运行服务以查看详细日志：

uv run main.py --working-dir ./debug-test

🚀 高级用法

批量存储记忆

通过 Claude Desktop 界面多次调用工具，以存储多条相关记忆。

记忆整理策略

按项目整理

使用标签按项目整理：

• ["project-alpha", "frontend", "react"]
• ["project-beta", "backend", "node"]
• ["project-gamma", "devops", "docker"]

按技术栈整理

• ["javascript", "react", "hooks"]
• ["python", "django", "orm"]
• ["aws", "lambda", "serverless"]

按问题领域整理

• ["authentication", "security", "jwt"]
• ["performance", "optimization", "caching"]
• ["testing", "unit-tests", "mocking"]

与开发工作流集成

代码审查经验

"Code review insight: Extract validation logic into separate functions for better testability and reusability"

Sprint 回顾

"Sprint retrospective: Using feature flags reduced deployment risk and enabled faster rollbacks"

技术债务跟踪

"Technical debt: UserService class has grown too large, needs refactoring into smaller domain-specific services"

📈 性能基准测试

基于不同数据集大小的测试结果：

记忆数量	搜索时间	存储大小	RAM 使用量
1,000	<50ms	~5MB	~100MB
5,000	<100ms	~20MB	~200MB
10,000	<200ms	~40MB	~300MB

在搭载 sentence-transformers/all-MiniLM-L6-v2 的 MacBook Air M1 上测试

🔧 高级实现细节

数据库索引

记忆存储使用 4 个经过优化的索引来提升性能：

1. idx_category：加快基于类别的筛选和统计
2. idx_created_at：优化时间查询和近期记忆检索
3. idx_content_hash：通过 SHA-256 哈希查找实现快速去重
4. idx_access_count：通过跟踪使用模式提升清理算法的效率

去重系统

内容去重使用 SHA-256 哈希，防止存储相同的记忆：

• 基于规范化内容（去除首尾空格并转换为小写）计算哈希
• 在插入前执行检查
• 对重复内容的写入尝试会返回现有记忆 ID
• 减少存储开销并保持数据质量

访问跟踪

每条记忆都会跟踪使用统计信息，以便进行智能管理：

• access_count：通过搜索或直接访问检索记忆的次数
• last_accessed_at：最近一次访问的时间戳
• created_at：原始创建时间戳
• 清理算法会使用这些信息来识别有价值和过时的记忆

清理算法

智能清理会根据多个因素优先保留记忆：

1. 近期程度：较新的记忆优先于较旧的记忆
2. 访问模式：保护经常访问的记忆
3. 年龄阈值：可配置的 days_old 参数，用于设置硬性截止条件
4. 数量限制：通过移除价值最低的条目，将记忆数量维持在 max_memories 上限内
5. 评分系统：结合 access_count 和近期程度来决定保留哪些记忆

🤝 贡献

这是一个面向个人或团队使用的独立 MCP 服务。如需改进：

1. Fork 此仓库
2. 根据需要针对你的使用场景进行修改
3. 根据你的具体需求进行全面测试
4. 通过拉取请求分享改进

📄 许可证

本项目基于 MIT 许可证发布。

🙏 致谢

• sqlite-vec：Alex Garcia 出色的 SQLite 向量扩展
• sentence-transformers：Nils Reimers 的语义嵌入库
• FastMCP：Anthropic 的高级 MCP 框架
• Claude Desktop：提供 MCP 集成平台

---

为希望拥有持久化 AI 记忆、又不想面对专用向量数据库复杂性的开发者打造。