Memkeeper 是一个面向 AI 智能体的本地优先记忆存储引擎，以单个 SQLite 数据库为核心，不需要服务器、云服务或遥测，也不要求网络或 LLM 调用。其目标是让智能体拥有持久、可检索的上下文，而不是“金鱼般的记忆”。该仓库是 memkeeper 记忆引擎的核心，属于一个更大控制平面的一部分，该控制平面还涵盖持久记忆、项目上下文、协调式任务交接和默认拒绝的权限，全部在本地确定性运行。
用途与定位 Memkeeper 用来存储、排序和检索智能体的持久上下文记忆，适合希望在本地保留可复用事实、决策、偏好和经验的场景。它是一个有意的、精心维护的记忆库，而不是自动转录日志。记忆可以通过 CLI 直接写入（memkeeper remember --json '{"content":"…"}'），也可以由 MCP 客户端在会话期间调用 remember 自动捕获。
主要能力
- 本地优先：单个 SQLite 数据库，无服务器、无云端、无遥测。
- 提示时快速检索：确定性 BM25/FTS 检索，可选 ONNX 语义嵌入和交叉编码器重排序。
- 设计上持久：原子写入、模式版本化存储，以及将高信号重复记忆提升到持久层的保留模型。
- 空间模型：智能体调用 remember 捕获持久事实，search 召回；检索与 CLI 一致，跨会话可用。
- 检索模式：本地语义（默认，ONNX 完全在设备上）、离设备语义（OpenAI 兼容嵌入 API，无需下载模型）和词法回退（BM25/FTS，零网络零模型）。本地语义为推荐模式，需先运行 pull-models 获取模型；模型缺失时不会静默降级，会记录缺失并标记 semantic-unavailable，同时回退到词法检索；设置 MEMKEEPER_REQUIRE_SEMANTIC=1 可强制失败而非降级。嵌入在记忆写入时计算，已有记忆需用 reindex --embed 回填。
- 文档存储（RAG）：独立于精选记忆层的文档分块层，默认位于 documents 空间，支持 ingest、document-search、document-get、document-duplicates、document-prune、promotion-candidates 等命令，用于将整份文档导入并检索。
- 实体图：MCP 的 remember 在主机智能体提供图字段时捕获有界实体、别名和类型化关系，并原子提交；原始 CLI 调用也可以传递同样的图结构。图可视化与裸记忆是不同层。
- MCP 适配：memkeeper 支持 MCP（stdio 上 JSON-RPC 2.0），任何 MCP 客户端（如 Claude Code、Cursor）都能在会话中读写记忆。另有 Claude Code UserPromptSubmit 钩子客户端 hook retrieve，可将相关记忆注入提示。
- HTTP 仪表盘：memkeeper serve --http 启动只读本地仪表盘（默认 http://127.0.0.1:7777），用于浏览记忆与实体图；写入需设置 MEMKEEPER_HTTP_WRITE_TOKEN。
- 记忆粒度建议：每条 remember 应是一条能自我成立的记忆，保留上下文与意图（例如存“用户喜欢披萨上加菠萝”，而不是只存“菠萝”）。避免过小（裸关键词）或过大（整篇文档），因为精选记忆层不做分块，嵌入器只看到条目开头约 512 个 token。
使用方式 安装：发布页提供了自包含二进制，无需运行时网络、LLM 或 API 密钥，也提供 .sha256 校验；默认存储路径为 ~/.memkeeper/store.sqlite（可用 --store 覆盖）。--json 值也可为 @<file> 或 -（标准输入），便于避免 shell 引号问题（Windows PowerShell 下尤其有用）。 升级：v0.3.0 引入了 schema 5 到 6 的升级，v0.4.0 至 v0.5.3 保持 schema 6 不变。迁移是事务性的，但 schema 6 存储无法被 v0.2.x 打开；升级前建议停止长时间运行的 memkeeper 进程并用 v0.2.x 二进制备份存储，升级后显式运行迁移并验证。init 可安全重跑；回滚需先恢复 schema 5 备份。 MCP 使用：将客户端 MCP 配置指向原生二进制（无需 Python、无额外依赖）。 语义模型：pull-models 将模型写入 ~/.memkeeper/models/（可用 MEMKEEPER_MODELS_DIR 或 --dir 覆盖），这正是默认查找路径，之后运行搜索即可启用语义。若不想下载本地模型，也可配置 OpenAI 兼容 API（OpenAI、OpenRouter 或兼容代理）。切换嵌入模型（本地与离设备之间，或模型间）需修改嵌入环境变量并执行一次 reindex --embed，旧向量会被清除并记录新模型，不支持部分混合。 从源码构建：可选。需要 Rust 稳定工具链（edition 2021，Rust 1.56+）和 C 工具链（内置 SQLite 及 ONNX 运行时）；macOS 需 Xcode Command Line Tools，Debian/Ubuntu 需 build-essential。首次构建会从 crates.io 获取依赖，之后可离线。使用 --no-default-features 可构建更精简的纯词法版二进制。
适用场景
- 需要本地、无云依赖的智能体长期记忆。
- 在 Claude Code、Cursor 等 MCP 客户端中跨会话记住事实、决策与偏好。
- 需要混合检索（词法 + 语义 + 重排序）并配有独立 RAG 文档层的项目。
- 对隐私敏感、要求记忆内容不离开设备的环境。
限制与状态 当前为预发布状态 v0.5.3，1.0 前 API 和线上协议可能变化；该仓库为从私有开发仓库生成的发布镜像，主分支可能被重新生成，建议固定到标签发布或发布制品。预构建二进制发布在 macOS（Apple Silicon）和 Linux x86_64；Windows 为实验性，无预构建二进制，可从源码构建运行，serve --socket 在 Windows 上仅限 Unix（HTTP 仪表盘与 stdio serve 跨平台）。离设备语义会将记忆文本发送到嵌入服务商，仅在可接受时使用；两种设备上模式不会外发内容。在 LoCoMo 基准（10 段多会话对话、1982 个含证据问题）上，默认语义检索有公开成绩；在热 serve 守护进程（ONNX 模型已加载）上提示时搜索约 25 ms p50/p95，比每次调用冷启动重载模型快约 32 倍。更多设计说明、基准与复现脚本见仓库文档与博客。
