memo

<div align="center"> <img src="docs/logo.png" alt="memo" width="128" height="128" /> # memo **本地优先的 AI 智能体语义记忆，具备时间旅行、矛盾雷达和自动合成能力。** [](https://pypi.org/project/mlx-memo/) [](https://pypi.org/project/mlx-memo/) [](LICENSE) [](https://modelcontextprotocol.io) </div> <!-- mcp-name: io.github.jagoff/memo --> `memo` 为任何支持 MCP 的智能体（Claude Code、Codex、Devin、OpenCode、Cursor、Cline、Continue 等）提供长期记忆，这些记忆**完全在您自己的机器上运行** —— 通过 [Apple MLX](https://github.com/ml-explore/mlx) 在 **Apple Silicon 上的 macOS**，或通过 **Linux / Ubuntu 上的 CPU `sentence-transformers`后端**（`pipx install "mlx-memo[cpu]"`，参见 [docs/ubuntu.md](docs/ubuntu.md)）。每个记忆都是一个纯 Markdown 文件；嵌入式记忆存储在一个单独的 sqlite 文件中；嵌入器、重排器和 LLM 在进程中运行 —— 无需 Ollama、无需 Qdrant、无需云 API、无需密钥。您的提示和记忆永远不会离开机器。 <div align="center"> <img src="docs/diagram-loop.svg" alt="Save a fact once and any later session recalls it automatically, all stored locally on your own machine." width="760" /> </div> <div align="center"> <img src="docs/demo.gif" alt="memo in a terminal: save a fact once, then a later session recalls it automatically." width="760" /> </div> ## memo 与其他产品的区别 | 功能 | memo | mem0 | letta | cognee | engram | basic-memory | cipher | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | 100% 本地（无云 API） | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ | | **时间机器** （回溯语料库到任意日期） | ✅ | ❌ | ⚠️ | ❌ | ❌ | ⚠️ | ⚠️ | | **矛盾雷达** （检测 + 解决冲突） | ✅ | ⚠️ | ⚠️ | ❌ | ⚠️ | ❌ | ❌ | | **合成管道** （自动推断跨集群洞察） | ✅ | ❌ | ✅ | ⚠️ | ❌ | ❌ | ⚠️ | | **跨 Mac git 同步** （共享语料库，无服务器） | ✅ | ❌ | ⚠️ | ❌ | ✅ | ✅ | ⚠️ | | 云同步（可选复制） | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **终端 UI** | ✅ | ❌ | ⚠️ | ❌ | ✅ | ❌ | ✅ | | Obsidian 作为源头 | ✅ | ❌ | ⚠️ | ❌ | ❌ | ✅ | ❌ | | 知识图谱 + 实体提取 | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ⚠️ | | 评估回归门控（预提交 wireable） | ✅ | ⚠️ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | | 多模态（图像、音频 OCR） | ✅ | ⚠️ | ⚠️ | ✅ | ❌ | ❌ | ❌ | | MCP 表面配置文件（代币经济） | ✅ | ❌ | ❌ | ⚠️ | ⚠️ | ✅ | ❌ | | **被动捕获** （自动从记录中提取） | ✅ | ⚠️ | ✅ | ✅ | ✅ | ❌ | ⚠️ | | 会话时间线（上下文前后） | ✅ | ❌ | ❌ | ❌ | ✅ | ⚠️ | ⚠️ | _{✅ 一流 · ⚠️ 部分、配置门控或附加 · ❌ 缺失。于 2026 年中期针对每个项目的文档/仓库进行验证： [mem0](https://github.com/mem0ai/mem0)、 [letta](https://github.com/letta-ai/letta) （前身 MemGPT）、 [cognee](https://github.com/topoteretes/cognee)、 [engram](https://github.com/Gentleman-Programming/engram)、 [basic-memory](https://github.com/basicmachines-co/basic-memory)、 [cipher](https://github.com/campfirein/cipher)。最接近的比较： **basic-memory** （本地优先 + Obsidian + MCP — memo 的确切论文）和 **cipher** （编码代理的内存层）。} ## 为什么它能为您带来价值 —— 在代币方面 memo 旨在 **减少代币消耗，而不是增加**。 - **92% 更小的 MCP 表面。** 默认的 `agent` 配置文件公开 **10 个工具 / 约 1.2k 架构代币**，而完整的表面则有 **126 个工具 / 约 15k 代币** —— 这个开销在每次会话中每个客户端都会支付。memo 将其削减到几乎为零。 - **回忆注入答案，而不是重新推导。** 环境回忆会在智能体回答之前浮现顶级记忆，预算紧张 **约 160 代币**。智能体会停止重解释它已经在上周计算过的内容。 在约 200 个记忆的语料库中，`memo roi` 估计 **约 80k 代币的模型工作被避免** 每会话。数字特定于语料库；随着 memo 的学习，它会增长。 | 技术 | 如何启用 | 典型节省 | |---|---|---| | 紧凑回忆格式 | `export MEMO_RECALL_FORMAT=compact` | 每次注入约 65% | | 微不足道提示门控 | 默认启用 | 减少约 25% 的注入 | | 上下文文件压缩 | `memo compress-context CLAUDE.md` | 30–40% 更小的上下文 | ## 用例 - **跨会话的连续性。** 今天决定“我们使用 Postgres，而不是 Mongo”；明天，在新的会话中，智能体会自动回忆它 —— 回忆在智能体回答之前注入，因此您永远不会重新解释它。 - **跨智能体的共享内存。** 在 Claude Code 中工作时保存某些内容；Codex、Cursor 或 Cline 稍后会取用它们。它们都通过 MCP 读取相同的本地存储。 - **跨 Mac 的记忆。** 在笔记本电脑上开始，在台式机上继续。语料库通过无服务器的 git 同步进行传输，智能体会以相同的上下文开始在两个设备上。 - **坚持偏好和约定。** “测试优先”，“提交消息为英文”，“不要触摸身份验证模块” —— 说一次，智能体会将其应用于未来的每个会话。 - **矛盾雷达。** 改变旧决策时，memo 会标记现在过时的版本 —— 智能体不会重新引入您已经废弃的内容。 - **时间机器 / 审计。** “我们上个月对这个 bug 了解什么？” 回溯语料库到任意日期，查看当时的知识状态。 - **即时项目上线。** 冷启动的智能体会通过会话开始简报获得项目的持久决策、事实和偏好。 - **更少的代币，而不是更多。** 与其重新推导上周的内容，不如回忆注入答案，预算紧张 —— 默认的 MCP 表面约为 10 个工具，而不是 120 个。 ## 要求 - **Apple Silicon 上的 macOS** （M1–M4）—— MLX 是承载负载的部分，唯一具有重排器 + LLM 功能的路径（询问 / 合成 / 梦想）。 - **Linux / Ubuntu / Intel Mac** —— 作为 **独立** 安装通过 CPU `sentence-transformers` 后端（搜索 + 回忆 + 保存，无 MLX）。一条命令：`pipx install "mlx-memo[cpu]"`。参见 **[docs/ubuntu.md](docs/ubuntu.md)** 以了解其工作原理和权衡取舍。 - **约 8 GB** 空闲磁盘用于默认模型集（安装程序下载它）。 - *可选：* Obsidian 保险库。没有它，memo 默认使用 `~/Documents/memo/`。 > 如果您不使用 uv，则需要 Python ≥ 3.13 。`curl | bash` 安装程序会自动检测到它并使用其托管的 Python，如果 PATH 上没有系统 Python ≥ 3.13 。 ## 安装 — 步骤 1 ```bash curl -fsSL https://raw.githubusercontent.com/jagoff/memo/master/install.sh | bash ``` 安装程序会自动检测 **uv** （首选）或回退到 **pipx**。它会下载 MLX 模型，并将 memo 绑定到它找到的每个代理客户端（Claude Code、Codex、Devin、Devin Desktop、OpenCode）。 如果您更喜欢手动安装？以下任意一种方法都提供相同的两个二进制文件 — `memo` （CLI）和 `memo-mcp` （MCP 服务器）： ```bash uv tool install mlx-memo # 推荐 pipx install mlx-memo brew tap jagoff/memo && brew install mlx-memo ``` > 将 memo **隔离为其自己的工具** （uv 工具 / pipx / Homebrew）。不要将其包含在另一个项目的 `.venv` 中。`memo doctor --strict-runtime` 验证安装。 **在 Linux 上，或想在不安装任何内容的情况下试用？** 运行 Docker 镜像（CPU 后端，跨平台 — 搜索/回忆/保存；重排器 + `ask`/ `synthesize`/ `dream` 动词仅限 Apple Silicon）： ```bash docker run --rm ghcr.io/jagoff/memo:latest memo doctor ``` 更多信息请参见 **[docs/docker.md](docs/docker.md)**。 首次安装会下载约 8 GB 的 MLX 模型（5–15 分钟）；后续安装会访问 HuggingFace 缓存。完整的安装程序旋钮和“移动到新 Mac”步骤： **[docs/reference.md › Install](docs/reference.md#install-detail)**。 **迁移自另一台 Mac？** 安装完成后，恢复您的语料库： ```bash curl -fsSL https://raw.githubusercontent.com/jagoff/memo/master/install.sh | bash memo sync bootstrap git@github.com:yourname/memo-sync.git # 从 git 恢复 ``` ## 交给您的代理 memo 如果您将仓库（或仅安装行）交给 AI 代理，则会自行安装： ```bash curl -fsSL https://raw.githubusercontent.com/jagoff/memo/master/install.sh | bash memo doctor --strict-runtime # 验证运行时是否健康 ``` 安装后，工具表面显示为 `mcp__memo__memo_*` （`memo_save`、`memo_search`、`memo_ask`、`memo_get`、`memo_unified_briefing`）。每个客户端的设置（Claude Desktop、Cursor、Cline、Continue、手动 JSON）位于 **[docs/reference.md › MCP setup](docs/reference.md#mcp-setup)**。 ## 快速入门 ```bash memo doctor # 自我检查：模型、保险库、sqlite-vec memo save 'MLX prefill ~30% faster than Ollama on M3 Max' --title 'MLX bench' -t mlx -t bench memo search 'how fast was the MLX benchmark' # 按含义搜索，而不是关键词 memo list --limit 5 # 最近的 5 条 memo ask 'what changed in the embedder this month?' # RAG — 按 ID 引用记忆 ``` ## 核心功能 - **环境回忆** — 每次提示都会悄悄地咨询记忆，并将顶部命中作为上下文注入。温暖回忆守护进程使其保持在 **<200 毫秒**。无需 `/remember` 调用。 - **自动捕获** — `Stop` 钩子通过质量门控从每次交换中提取持久的洞察。语料库会自行增长。 - **会话简报** — `SessionStart` 浮现开放环、每日记忆和一行崩溃恢复。 ## 关键能力 ### 🕰️ 时间机器 将语料库回溯到过去的任何日期并查询当时的状态： ```bash memo as-of ask "what was the deployment strategy?" --date 2026-02-01 memo as-of search "redis config" --date 2026-01-15 memo diff --from 2026-01-01 --to 2026-03-01 # 有何变化 ``` 没有其他代理内存系统提供此功能。通过 `history.db` 进行完整的历史重建。 ### ⚡ 矛盾雷达 ```bash memo contradict scan # 检测冲突事实（语料库范围） memo contradict triage # 交互式解决：融合 / 新的获胜 / 忽略 ``` LLM 对每个候选对进行分类。结果存储在 `contradictions.db` 中；已解决的冲突会告知未来的保存。 ### 🔮 合成管道 ```bash memo synthesize # 生成跨集群洞察（LLM） memo dream # 夜间：信号收集 → 剪枝 → 定位 ``` `MEMO_SYNTHESIS_ENABLED=1` 在 `memo maintain` 期间自动运行合成。夜间 `memo dream` 还可以 **自我调整回忆** （`MEMO_DREAM_TUNE_ENABLED=1`）：它挖掘真实使用中的地面实况标签，调整回忆阈值，并在评估基准下降时自动恢复。 ### 🌐 跨 Mac 的 Git 同步 ```bash memo sync bootstrap git@github.com:yourname/memo-sync.git # 配置共享语料库 memo sync once # 推送/拉取 ``` 拉取-变基-推送。基于 `flock` 的单个所有者每台机器。异步的异步钩子在不阻塞的情况下保持语料库最新。 ### 📚 Obsidian 保险库作为源头 ```bash MEMO_MEMORIES_IN_VAULT=1 memo init # 将记忆存储在您的保险库中 memo migrate --into-vault # 非破坏性迁移 ``` 人类在 Obsidian 中的编辑会在下一个 `memo reindex` 时生效。sqlite 索引始终可以从 `.md` 文件中重建。 ### 🕸️ 知识图谱 ```bash memo graph neighbors "MLX" # 什么是相关的 memo graph path "embedder" "reranker" # 两个概念如何连接 memo entities # 提取的实体 memo links --id abc123 # 反向链接和出站链接 ``` 实体提取使用依赖项免费的正则表达式后端。对于大量代码-heavy 语料库，memo 可以合并 **[codegraph](https://github.com/colbymchenry/codegraph) 符号图**作为图的主要层（可选，`MEMO_GRAPH_USE_CODEGRAPH`）—— 调用者，调用者和导入成为一流的边缘，因此回忆和 `memo graph path` 原因超过实际代码结构，而不是简单的文本相似性。合并后的图还支持 `memo_graph` MCP 工具和实体中心的“知识地图”简报。 ### 🏥 健康评分和评估门控 ```bash memo health # 基础速率，ROI，有用性判决 memo eval recall --labels eval/regression_labels.json --k 5 memo eval recall --gate # 以非零退出 memo eval recall --update-baseline # 快照当前最佳 ``` 将 `--gate` 编入预提交钩子以捕获提交前检索回归。`memo feedback` 记录每个来源的 👍/👎 票数，教导检索器哪些记忆应该浮现（或隐藏）以供类似查询。 ### 🖼️ 多模态摄入 ```bash memo ocr-image screenshot.png # macOS Vision OCR memo multimodal add-image photo.jpg --title "whiteboard" memo search "whiteboard diagram" # 找到它 ``` ### 守护进程 memo 运行四个后台守护进程： | 守护进程 | 命令 | 目的 | |---|---|---| | recall-daemon | `memo recall-daemon start` | 暖 MLX 嵌入器通过套接字 (<200 ms 回忆) | | idle-daemon | 自动启动 `memo-mcp` | 自动捕获仅限 MCP 的客户端（Devin, OpenCode） | | ingest-daemon | `memo ingest-daemon start` | 批量保险库摄入 | | maint-daemon | `memo maint-daemon start` | 后台清理 + 合成 | ### 所有 104 个 CLI 命令 <details> <summary>点击展开</summary> **核心：** `save` `search` `ask` `get` `edit` `delete` `list` **回忆和钩子：** `recall` `recall-hook` `briefing` `continuity` `prewarm` `capture-tick` `capture-stop` **会话和历史：** `history` `as-of` `diff` `record-history` `session` `resume` `reflect` `mine-history` `episodes` **维护：** `reindex` `maintain` `dream` `consolidate` `synthesize` `dedupe` `cross-dedup` `retier` `contradict` `temporal` `compress-context` **分析和质量：** `health` `stats` `doctor` `lint` `analytics` `eval` `roi` `tokens` `token-savings` `usefulness` `gaps` `outcome` `profile` **知识图谱：** `graph` `entities` `entity` `extract-entities` `links` `version` `related` **高级搜索：** `embed` `rerank` `contextual` `chat` `chat-ask` `multimodal` `repo` **导入/导出/同步：** `import` `export` `backup` `restore` `sync` `ingest` **可视化：** `tui` `dashboard` `map` `logs` `hook-log` **设置和配置：** `init` `config` `install-mcp` `install-watcher` `uninstall-watcher` `install-slash` `install-statusline` `install-recall-hook` `install-shell-wrapper` `install-shims` `startup-banner` `migrate` `migrate-vault` `update` `watch` `release` `mcp-command` **守护进程：** `recall-daemon` `ingest-daemon` `maint-daemon` `embed-daemon` `idle-daemon` **其他：** `feedback` `query` `provenance` `mandate` `sleep-cycle` `ocr-image` `http-api` `codex-badge` `backend-native` `collaborative` </details> ### MCP 表面配置文件 | 配置文件 | 工具 | 架构代币 | 适用场景 | |---|---|---|---| | `agent`（默认） | 10 | 约 1.2k | 标准代理工作 — 最大代币经济 | | `core` | 30 | 约 2.8k | 受限客户端（Codex，OpenCode） | | `full` | 123 | 约 15k | 高级用户，调试 | 通过 `MEMO_MCP_PROFILE=full` 或每个客户端的 MCP 环境配置进行设置。 非 MCP 客户端：`memo http-api` 提供相同的操作作为 localhost REST API（纯 JSON）。 ## 检索架构 **混合搜索：** 矢量腿（Apple Silicon 上的 MLX 嵌入，Linux 上的 CPU `sentence-transformers`）+ BM25 腿（FTS5/Tantivy，带有重音符号折叠，用于西班牙语）通过互惠排名融合 → 可选的 MLX 跨编码器重排序（Apple Silicon）。 <div align="center"> <img src="docs/diagram-recall.svg" alt="A prompt runs a vector search and a keyword search in parallel; results are fused, reranked, and the top memory is injected." width="820" /> </div> **Markdown 是真相的来源。** `.md` 文件是规范的；sqlite 是可重建的索引。可以手动编辑 Obsidian 获胜在下一个 `memo reindex`。`delete()` 删除索引首先，然后是文件 — 没有静默数据丢失。 <div align="center"> <img src="docs/diagram-storage.svg" alt="Markdown files are canonical; the sqlite index is derived and can be rebuilt from them at any time." width="760" /> </div> **嵌入模型： | 模型 | 维度 | 磁盘 | 用途 | |---|---|---|---| | `Qwen3-Embedding-0.6B-4bit` | 1024 | 约 0.4 GB | 默认（快速，良好） | | `Qwen3-Embedding-4B-4bit` | 2560 | 约 2.5 GB | 较高的回忆质量 | | `Qwen3-Embedding-8B-4bit` | 4096 | 约 5 GB | 最大质量 | 通过 `MEMO_EMBEDDER_MODEL` + `MEMO_EMBEDDER_DIMS` 切换（需要 `memo reindex --rebuild`）。 ## 文档 | 主题 | 哪里 | |---|---| | 完整的安装细节，安装程序旋钮，新 Mac 迁移 | [docs/reference.md › Install](docs/reference.md#install-detail) | | 每个客户端的 MCP 设置 + `/memo` 斜杠命令 | [docs/reference.md › MCP setup](docs/reference.md#mcp-setup) | | 所有 MCP 工具参考 | [docs/reference.md › MCP tools](docs/reference.md#mcp-tools) | | 环境记忆，回忆守护进程，捕获和回忆调优 | [docs/reference.md › Ambient memory](docs/reference.md#ambient-memory) | | 时间机器，会话简报，语义地图 | [docs/reference.md › Surfaces](docs/reference.md#surfaces) | | 完整的 CLI 参考 + 实时仪表盘（`memo tui`） | [docs/reference.md › CLI](docs/reference.md#cli-reference) | | 所有 `MEMO_*` 标志，模型配置文件，升级嵌入器 | [docs/reference.md › Configuration](docs/reference.md#configuration) | | 架构，同步层，设计笔记 | [docs/reference.md › Design & comparison](docs/reference.md#design-and-comparison) | 贡献者：`git clone https://github.com/jagoff/memo && cd memo && uv pip install -e '.[dev]'`。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证和出处 MIT — 参见 [LICENSE](LICENSE)。从 [`mem-vault`](https://github.com/jagoff/mem-vault) （存储布局 + 前面元数据模式）哲学继承；MLX 后端部分移植自 [`obsidian-rag`](https://github.com/jagoff/rag-obsidian)。memo 是具有开放许可的更广泛栈中的三个主权系统之一（[Memflow](https://github.com/jagoff/memflow)，Synapse）—— 集成在所有地方都是可选的；单个 Mac 用户看到零行为变化。