memory-mcp-1file 是一个为 AI 智能体提供持久记忆的高性能 MCP 服务器，使用纯 Rust 编写。
【用途】 它解决的是 AI 智能体在会话重启或上下文压缩后丢失状态的问题，为智能体提供持久化、语义化和基于图的记忆存储，使其从「无状态聊天机器人」变成能跨重启存活、保留当前任务完整上下文的「有状态工作者」。
【核心优势（All-in-One）】 不同于需要「Python + 向量数据库 + 图数据库」复杂技术栈的其他记忆方案，本项目是单个自包含可执行文件：SurrealDB 内嵌；无需外部数据库；无需 API Key、无需云、无需 Python，全部通过内嵌的 ONNX 运行时 100% 本地运行，嵌入模型烘焙进二进制并在 CPU 上运行，数据不离开本机；零配置，只需运行一个 Docker 容器或二进制文件。
【主要能力】
- 语义记忆：以向量嵌入（默认 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 日期。
- 混合检索（Reciprocal Rank Fusion）以获得最佳结果。
- 后端：SurrealDB（快速、内嵌、单文件数据库）。
【架构与传输】 服务器使用 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 协商。
【使用方式】 1）通用 Docker 配置：-v mcp-data:/data 持久化图、嵌入和缓存的模型权重；-v $(pwd):/project:ro 让服务器读取并索引代码；--init 保证干净关闭。一个卷持久化一切：单个 -v mcp-data:/data 挂载同时覆盖 SurrealDB 数据库和约 1.2 GB 的嵌入模型（存放于 /data/models/）。若不使用命名卷，Docker 每次 docker run 都会创建新的匿名卷，导致模型每次重新下载（约 1.2 GB）。 2）Cursor：在 Cursor Settings > Features > MCP Servers 中点击 + Add New MCP Server，命令为 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（切换工作区需要代码索引时更新项目路径）。 3）NPX / Bunx（无需 Docker）：可直接通过 npx 或 bunx 运行，npm 包会自动下载适配平台的预编译二进制。在 claude_desktop_config.json 中配置命令 npx -y memory-mcp-1file；不同于 Docker，npx / bunx 在本地运行二进制，本身已可访问文件系统，无需挂载目录。可通过 args 传入 --data-dir 自定义数据存储路径。 4）Codex：仓库包含可信项目 .codex/config.toml，通过本地 STDIO 启动 memory-mcp-1file@0.9.2，数据存于 .codex/data，并暴露 16 个工具的项目允许列表。破坏性工具 delete_memory、delete_project、reset_all_memory 被有意排除在项目配置之外。原生 Codex 索引由 MEMORY_MCP_ALLOWED_INDEX_ROOT 限制在当前仓库。项目级 Codex 配置只有在你显式信任该仓库后才会加载；在 Windows 上先独立验证包再运行。required = true 设置会让 Memory MCP 启动失败可见，而不是静默运行。工具允许列表控制 Codex 加载哪些 MCP 工具，它不是进程沙箱。启用该配置前请先信任仓库和 npm 包。 5）Gemini 配置：可加入 ~/.gemini/settings.json，或使用 Docker。
【智能体集成（系统提示）】 记忆只有在智能体主动查询时才有用。仓库提供经过实战检验的 Memory Protocol（AGENTS.md）供参考改编。建议把 AGENTS.md 作为唯一事实来源，在智能体基础系统提示中指示其在每次会话开始时读取 AGENTS.md 并遵循其中协议。协议实现的工作流包括：会话启动时智能体必须立即搜索 TASK: in_progress 以恢复上次会话或上下文压缩前的完整上下文；Auto-Continue 安全机制，智能体向用户展示找到的任务并等待（或自动继续），避免臆造新任务；Triple Sync 同时更新 Memory、Todo List 和文件，若其一失败其他作为备份；前缀系统（TASK:、DECISION:、RESEARCH:）让语义搜索能精确定位正确类型的信息，减少噪声。
【工具与配置】 服务器向 AI 模型暴露 19 个工具，分为核心记忆管理、搜索与检索、知识图谱、代码库智能、系统与维护等类别。配置通过环境变量或 CLI 参数进行。
【可用模型】 可通过 --model 参数或 EMBEDDING_MODEL 环境变量切换嵌入模型。两者都未提供时使用 Granite。配置优先级：显式 --model 参数、EMBEDDING_MODEL、内置 Granite 默认值。granite 产生原生 384 维、L2 归一化的 CLS 嵌入；当前 Candle CPU 路径将输入限制为 512 token 以约束二次注意力内存开销，而模型本身支持最多 32K token。标记为 (MRL) 的模型支持将输出嵌入向量动态截断为更小维度（如 512、256、128），精度损失极小，可节省数据库存储并加速向量搜索，用 --mrl-dim 参数指定目标大小，省略时默认为模型的本地基础维度（如 Qwen3 为 1024）。警告：数据库一旦以特定维度创建，不擦除数据目录就无法更改。
【受限模型与认证（Gemma）】 默认使用 Granite（Apache 2.0，无需认证自动下载）。若选择 Gemma（--model gemma），由于它是专有许可的受限模型，必须认证：在 Hugging Face 上访问 google/embeddinggemma-300m，登录并点击 Agree to access repository，在 HF Tokens 生成访问令牌（读权限即可），再带令牌启动服务器。
【模型更换与数据兼容性】 全新安装默认使用 granite（384 维）。使用 e5_multi（768 维）创建的现有数据目录只有在显式以 --model e5_multi 启动时仍可用。切换到不同维度的模型需要新的数据目录（或清空卷）并完整重新索引。即使切换到相同维度的模型（如 e5_multi 与 nomic 之间）也不推荐，因为它们的语义空间不同。
【未来路线图（研究与想法）】 基于对 Hindsight 等高级记忆系统的分析，团队正在探索以下认知架构特性：1）元认知反思（整合），实现 reflect 后台进程或工具，定期扫描近期记忆以去重、解决冲突、把低级事实综合为高级洞察；2）时间衰减与「存在感」，把时间衰减整合进 RRF 算法，对暗示「当前状态」的查询给予近期记忆计算加成，允许智能体动态地优先「工作记忆」而非「历史档案」；3）命名空间记忆库，代码索引已支持显式 project_id 过滤，未来把命名空间/项目作用域扩展到记忆和图操作，使一个共享服务器能隔离多个智能体工作区；4）认知置信度评分，为记忆模式添加 0.0-1.0 的置信度分数，允许存储假设（如置信度 0.3），检索工具在回答事实性问题时可过滤低置信度记忆。
【限制】 需要 MCP 兼容客户端；通过 stdio 运行，每个本地工作区一个进程；本版本未启用 Streamable HTTP；数据库维度一旦创建不可更改，切换模型需重新索引；Gemma 模型需 Hugging Face 认证；不使用 Roots 协商。其余如价格、收费模式等信息暂未提供。
