Memory Mcp 1file

请使用 https://github.com/tenatarika/vex

🧠 Memory MCP 服务

一款高性能、纯 Rust 的模型上下文协议（MCP）服务，为 AI Agent 提供持久化、语义化和基于图的记忆。

与以下产品完美配合：

• Claude Desktop
• Claude Code（CLI）
• Gemini CLI
• OpenAI Codex（CLI / IDE）
• Cursor
• OpenCode
• Cline / Roo Code
• 任何其他兼容 MCP 的客户端。

🏆「一体化」优势

与需要复杂技术栈（Python + 向量数据库 + 图数据库）的其他记忆解决方案不同，本项目是单个独立的可执行文件。

• ✅ 无需外部数据库（内嵌 SurrealDB）
• ✅ 无需 API 密钥、无需云服务、无需 Python —— 所有内容均通过内嵌 ONNX 运行时完全在本地运行。嵌入模型已内置于二进制文件中，并在 CPU 上运行。任何数据都不会离开你的设备。
• ✅ 零配置（只需运行一个 Docker 容器或二进制文件）

它结合了：

1. 向量搜索（FastEmbed），用于语义相似度检索。
2. 知识图谱（PetGraph），用于表示实体关系。
3. 代码索引，包含符号图（调用、扩展、实现），深入理解代码库。
4. 混合检索（倒数排名融合），以获得最佳结果。

🏗️ 架构

graph TD
    User[AI Agent / IDE]
    
    subgraph "Memory MCP Server"
        MS[MCP Server]
        
        subgraph "Core Engines"
            ES[Embedding Service]
            GS[Graph Service]
            CS[Codebase Service]
        end
        
        MS -- "Store / Search" --> ES
        MS -- "Relate Entities" --> GS
        MS -- "Index" --> CS
        
        ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
        GS -- "Knowledge Graph" --> SDB
        CS -- "AST Chunks" --> SDB
    end

    User -- "MCP Protocol" --> MS

点击此处查看详细架构文档

---

MCP 协议与传输方式

该服务使用 rmcp 3.2，并支持两种协议生命周期：

• MCP 2026-07-28 无状态请求： 客户端可以从 server/discover 开始；每个请求都会在 _meta 中携带协议版本和客户端 元数据。进程不会存储 MCP 会话、Mcp-Session-Id 或 可变的 currentProject。
• 兼容 MCP 2025-11-25： 仍支持使用旧版 initialize/initialized 生命周期的客户端。

此二进制文件通过 stdio 提供 MCP。每个本地工作区运行一个进程；使用 Docker 时，将该工作区挂载到 /project。此版本未启用或声明支持 Streamable HTTP，因此不会引入 HTTP 会话 管理或共享服务的身份验证面。代码索引通过 index_project 接收明确的路径；如果单个进程包含多个已索引项目， 可使用 project_id 缩小代码搜索范围。不会使用 Roots 协商。

---

🤖 Agent 集成（系统提示词）

如果 Agent 不检查记忆，记忆就毫无用处。要实现「长期记忆」效果，必须指示 Agent 遵循严格的协议。

我们提供了一份经过实战检验的**记忆协议（AGENTS.md）**，你可以据此进行调整。

🛡️ 核心工作流（上下文保护）

该协议实现了特定流程来处理 上下文窗口压缩 和 会话重启：

1. 🚀 会话启动：Agent 必须 立即搜索 TASK: in_progress。这会恢复上一次会话结束或上下文被压缩之前所发生事情的全部上下文。
2. ⏳ 自动继续：一种安全机制，Agent 将找到的任务呈现给用户并等待（或自动继续），确保它不会幻觉出一个新任务。
3. 🔄 三重同步：同时更新 记忆、待办列表 和 文件。如果其中一个失败（例如上下文丢失），其他两个可作为备份。
4. 🧱 前缀系统：所有记忆都使用前缀（TASK:、DECISION:、RESEARCH:），以便语义搜索能够精确针对正确类型的信息，减少噪声。

这些工作流将 Agent 从“无状态聊天机器人”转变为能够经受重启和上下文清空的“有状态工作者”。

推荐的系统提示词片段

与其将指令分散在特定于 IDE 的文件（如 .cursorrules）中，不如将 AGENTS.md 确立为 唯一事实来源。

指示你的 Agent（在其基础系统提示词中）：

1. 在每次会话开始时 读取 AGENTS.md。
2. 遵循其中定义的协议。

以下是一个用于引导此行为的最小参考提示词：

# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

为什么这很重要？

没有此协议，Agent 会在上下文压缩或会话重启后丢失上下文。有了此协议，它就能保持 当前任务的完整上下文，确保即使聊天历史被清空，也不会丢失任何步骤或细节。

---

🔌 客户端配置

通用 Docker 配置（任何 IDE/CLI）

要将此 MCP 服务与任何客户端（Claude Code、OpenCode、Cline 等）一起使用，请使用以下 Docker 命令结构。

关键要求：

1. 记忆卷：-v mcp-data:/data（持久化你的图、嵌入 以及缓存的模型权重）
2. 项目卷：-v $(pwd):/project:ro（允许服务读取并索引你的代码）
3. Init 进程：--init（确保服务干净地关闭）

提示

一个卷即可持久化所有内容：单个 -v mcp-data:/data 挂载同时涵盖 SurrealDB 数据库 和 约 1.2 GB 的嵌入模型（存储在 /data/models/ 下）。无需为 /data/models 单独设置卷——它已经是 /data 的子目录，并会自动保留。如果没有命名卷，Docker 会在每次 docker run 时创建一个新的匿名卷，导致模型每次都重新下载（约 1.2 GB）。

JSON 配置（Claude Desktop 等）

将此添加到你的配置文件（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "-i",
        "--rm",
        "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "/absolute/path/to/your/project:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

注意： 将 /absolute/path/to/your/project 替换为你想要索引的实际路径。在某些环境（如 Cursor 或 VSCode 扩展）中，你可能可以使用像 ${workspaceFolder} 这样的变量，但绝对路径对 Docker 来说最可靠。

Cursor（具体说明）

1. 转到 Cursor Settings > Features > MCP Servers。
2. 点击 + Add New MCP Server。
3. Type：stdio
4. Name：memory
5. Command：

   docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest
   

   （如果你需要代码索引，切换工作区时记得更新项目路径）

OpenCode / CLI

docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX / Bunx（无需 Docker）

你可以直接通过 npx 或 bunx 运行该服务。npm 包会自动为你的平台下载正确的预编译二进制文件。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Claude Code（CLI）

claude mcp add memory -- npx -y memory-mcp-1file

Cursor

1. 前往 Cursor Settings > Features > MCP Servers。
2. 点击 + Add New MCP Server。
3. Type：command
4. Name：memory
5. Command：npx -y memory-mcp-1file

或添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Windsurf / VS Code

添加到你的 MCP 设置：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun

{
  "mcpServers": {
    "memory": {
      "command": "bunx",
      "args": ["memory-mcp-1file"]
    }
  }
}

OpenAI Codex CLI（项目级）

此仓库包含一个受信任项目级的 .codex/config.toml，它通过本地 STDIO 启动 [email protected]，将数据存储在 .codex/data，并 暴露一个包含 16 个工具的项目允许列表。破坏性工具 delete_memory、delete_project 和 reset_all_memory 被有意 排除在项目配置之外。原生 Codex 索引由 MEMORY_MCP_ALLOWED_INDEX_ROOT 限制在当前仓库范围内。

项目级 Codex 配置仅在你明确信任该仓库后才会加载。 在 Windows 上，请先独立验证该包：

npx -y [email protected] -- --help

然后从仓库运行 codex，并用以下命令验证服务：

/mcp

或：

codex mcp list
codex mcp get memory

required = true 设置会让 Memory MCP 启动失败变得可见，而不是 在静默中运行没有记忆工作流的项目。 工具允许列表控制 Codex 加载哪些 MCP 工具；它不是进程 沙箱。在启用此配置之前，请先信任该仓库和 npm 包。

note: 与 Docker 不同，npx/bunx 在本地运行二进制文件——它已经可以访问你的文件系统，因此无需挂载目录。要自定义数据存储路径，请通过 args 传入 --data-dir：

"args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"]

Gemini CLI

添加到你的 ~/.gemini/settings.json：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

---

✨ 主要特性

• 语义记忆：使用向量嵌入（默认 granite）存储文本，以实现“基于感觉”的检索。
• 图谱记忆：跟踪实体（User、Project、Tech）及其关系（uses、likes）。支持基于 PageRank 的遍历。
• 代码智能：为本地项目目录建立索引（基于 AST 的分块），支持 Rust、Python、TypeScript、JavaScript、Go、Java 和 Dart/Flutter。跟踪符号之间的 calls、imports、extends、implements 和 mixin 关系。
• 时间有效性：记忆可以带有 valid_from 和 valid_until 日期。
• SurrealDB 后端：快速、嵌入式、单文件数据库。

---

🛠️ 可用工具

该服务向 AI 模型暴露 19 个工具，按逻辑类别组织。

🧠 核心记忆管理

工具	描述
store_memory	存储一条带有内容和可选元数据的新记忆。
update_memory	更新记忆字段。
delete_memory	按 ID 删除记忆。
list_memories	列出记忆（最新优先）。
get_memory	按 ID 获取完整记忆。
invalidate	软删除记忆，可选链接替代项。
get_valid	获取有效记忆。可选 timestamp（ISO 8601）用于时间点查询。

🔎 搜索与检索

工具	描述
recall	混合搜索（通过 RRF 结合向量 + 关键词 + 图谱）。记忆的默认选项。
search_memory	搜索记忆。mode：vector（默认）或 bm25。

🕸️ 知识图谱

工具	描述
knowledge_graph	统一的知识图谱操作。action：create_entity | create_relation | get_related | detect_communities。

💻 代码库智能

工具	描述
index_project	为代码搜索建立代码库目录索引。
delete_project	删除已索引项目。
recall_code	代码检索。mode：vector 或 hybrid（默认）。hybrid 使用向量 + BM25 + 图谱融合。
search_symbols	按名称搜索代码符号。
symbol_graph	浏览符号图谱。action：callers | callees | related。
project_info	项目信息。action：list | status | stats。

⚙️ 系统与维护

工具	描述
get_status	获取系统状态与启动进度。
reset_all_memory	危险：重置所有数据库数据（需要 confirm=true）。
how_to_use	显示工具用法示例与参数组合。

---

⚙️ 配置

环境变量或命令行参数：

参数	环境变量	默认值	描述
--data-dir	DATA_DIR	./data	数据库位置
--model	EMBEDDING_MODEL	granite	嵌入模型（granite、e5_multi、qwen3、gemma、bge_m3、nomic、e5_small）
--mrl-dim	MRL_DIM	（原生）	支持 MRL 的模型的输出维度（例如 Qwen3 的 64、128、256、512、1024）。默认值为模型的原生最大维度（Granite 为 384，Qwen3 为 1024）。
--batch-size	BATCH_SIZE	8	嵌入推理的最大批大小
--cache-size	CACHE_SIZE	1000	嵌入的 LRU 缓存容量
--timeout	TIMEOUT_MS	30000	超时时间（毫秒）
--idle-timeout	IDLE_TIMEOUT	0	空闲超时（分钟）。0 = 禁用
--log-level	LOG_LEVEL	info	详细程度
（无）	HF_TOKEN	（无）	HuggingFace Token（仅对 gemma 等门控模型需要）
（无）	EMBEDDING_QUEUE_CAPACITY	256	后台嵌入队列的最大大小
（无）	EMBEDDING_BATCH_SIZE	8	每个嵌入块处理多少个文件
（无）	INDEX_BATCH_SIZE	20	每个增量块处理多少个文件
（无）	INDEX_DEBOUNCE_MS	2000	刷新索引事件前等待的毫秒数（防抖）
（无）	MANIFEST_DIFF_INTERVAL_MINS	10	定期检查缺失文件的间隔分钟数

🧠 可用模型

你可以使用 --model 参数或 EMBEDDING_MODEL 环境变量切换嵌入模型。

当两者均未提供时，二进制文件使用 Granite。配置优先级为： 显式 --model 参数，然后是 EMBEDDING_MODEL，最后是内置的 Granite 默认值。

参数值	HuggingFace 仓库	维度	大小	使用场景
granite	ibm-granite/granite-embedding-97m-multilingual-r2	384	~195 MB	默认。使用 ModernBERT 和 CLS 池化的多语言与代码检索。
e5_multi	intfloat/multilingual-e5-base	768	1.1 GB	旧版多语言模型，质量与性能平衡良好。
qwen3	Qwen/Qwen3-Embedding-0.6B	1024（MRL）	1.2 GB	2026 年顶级开源模型，32K 上下文，支持 MRL。
gemma	onnx-community/embeddinggemma-300m-ONNX	768（MRL）	~195 MB	支持 MRL 的更轻量替代方案。（需要专有许可协议）
bge_m3	BAAI/bge-m3	1024	2.3 GB	最先进的多语言混合检索。较重。
nomic	nomic-ai/nomic-embed-text-v1.5	768	1.9 GB	高质量长上下文，兼容 BERT。
e5_small	intfloat/multilingual-e5-small	384	134 MB	最快，内存占用最低。适合开发/测试。

granite 生成原生 384 维、L2 归一化的 CLS 嵌入。当前 Candle CPU 路径将输入上限设为 512 个 token，以限制二次注意力内存开销；模型本身支持最多 32K 个 token。

📉 Matryoshka 表示学习（MRL）

标记为 (MRL) 的模型支持将输出嵌入向量动态截断为更小的维度（例如 512、256、128），而精度损失极小。这可以节省数据库存储并加速向量搜索。

使用 --mrl-dim 参数指定所需的大小。如果省略，默认值为模型的原生基础维度（例如 Qwen3 为 1024）。

警告： 一旦你的数据库以特定维度创建，不擦除数据目录就无法更改该维度。

🔒 受限模型与身份验证 (Gemma)

默认情况下，该服务使用 Granite，这是一个 Apache 2.0 模型，无需任何身份验证即可自动下载。

但是，如果你选择使用 Gemma（--model gemma），则必须进行身份验证，因为它是一个具有专有许可证的“受限模型”。

要使用 Gemma：

1. 前往 Hugging Face 上的 google/embeddinggemma-300m。
2. 登录并点击 “Agree to access repository”。
3. 在 HF Tokens 生成访问令牌（Read 权限即可）。
4. 使用该令牌启动服务：

# Using environment variable
HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

# Or via .env file (see .env.example)

警告

更换模型与数据兼容性

全新安装默认使用 granite（384 维）。使用 e5_multi（768 维）创建的现有数据目录仅在显式使用 --model e5_multi 启动时仍可使用。

切换到具有不同维度的模型需要新的数据目录（或清空卷）并重新完整索引。

即使是在具有相同维度的模型之间切换（例如 e5_multi <-> nomic）也不推荐，因为它们的语义空间不同。

🔮 未来路线图（研究与想法）

基于对 Hindsight 等高级记忆系统的分析（有关这些机制的详细信息，请参阅其文档），我们正在为未来版本探索以下“认知架构”功能：

1. 元认知反思（整合）

• 问题： 原始记忆会随着时间推移积累噪声（例如，关于修复同一个 bug 的 10 条独立记忆）。
• 解决方案： 实现一个 reflect 后台进程（或工具），定期扫描近期记忆以：
  • 去重冗余条目。
  • 解决冲突（如果两条记忆相互矛盾，保留较新的一条或标记以供审核）。
  • 综合低层事实为高层“洞察”（例如，从 5 次代码选择中推导出“用户更喜欢 Rust 而非 Python”）。

2. 时间衰减与“临场感”

• 问题： 旧记忆有时会在语义搜索中淹没当前上下文。
• 解决方案： 将时间衰减集成到倒数排名融合（RRF）算法中。
  • 对于暗示“当前状态”的查询，为近期记忆提供计算后的加权提升。
  • 允许 Agent 动态地将“工作记忆”优先于“历史档案”。

3. 命名空间记忆库

• 当前边界： 代码索引已支持显式的 project_id 过滤，而记忆记录仍保持进程级。
• 未来工作： 将命名空间/项目范围扩展到记忆和图操作，以便一个共享服务可以隔离多个 Agent 工作区。

4. 认知置信度评分

• 问题： Agent 将猜测与已验证的事实同等对待。
• 解决方案： 在记忆模式中添加 confidence 分数（0.0 - 1.0）。
  • 允许存储假设（“我认为 bug 在 auth.rs 中”，置信度：0.3）。
  • 检索工具在回答事实性问题时可以过滤掉低置信度的记忆。

---

License

MIT