memtomem

memtomem

面向 AI 编码 Agent 的 Markdown 优先长期记忆——文件始终由你掌控，核心功能默认无需钩子。

🧪 Beta — 九个核心 MCP 工具、mm CLI，以及记忆文件和配置文件的格式，仅会在 CHANGELOG 中注明 Upgrading 时发生变更；如有可能，也会设置弃用过渡期。标记为 experimental 的功能则可能随时变更或移除——详见稳定性。非常欢迎反馈和问题报告：Issues · Discussions。

memtomem 可将你的 Markdown 笔记、文档和代码转化为可搜索的知识库，供任何 AI 编码 Agent 使用。将笔记保存为纯 .md 文件即可——memtomem 会为其建立索引，并支持按关键词和含义进行搜索。

flowchart LR
    A["Your files\n.md .json .py"] -->|Index| B["memtomem"]
    B -->|Search| C["AI agent\n(Claude Code, Cursor, etc.)"]

初次使用？ 请按照入门指南操作——不到 5 分钟即可完成设置。Claude Code 或 Codex CLI 用户？请参阅韩语氛围编程快速入门。

为什么选择 memtomem？

快速开始

1. 安装

uv tool install 'memtomem[all]'       # or: pipx install 'memtomem[all]'
mm --version                          # verify install

[all] 会捆绑下文介绍的功能——ONNX 稠密嵌入、韩语分词器、代码分块器和 Web UI。Ollama 和 OpenAI 嵌入提供方无需额外安装；任何安装方式均可使用。若要使用更精简的安装方式，避免下载这些组件（安装后约 50 MB，而非约 340 MB，尚未计入任何模型下载），请参阅入门指南中的最小安装选项。

如果安装后 mm --version 显示的版本低于最新发布版本，可能是 uv 使用了缓存的 PyPI 元数据——请使用 uv tool install 'memtomem[all]' --refresh 重新安装，或先清除缓存：uv cache clean memtomem。若要升级现有的 uv 工具安装，请使用 mm upgrade，而不是重新运行 uv tool install；关于此操作会保留和移除哪些内容，请参阅 CLI 参考。

提示 mm: command not found？ uv tool install 会将 shim 放入 ~/.local/bin，而在 macOS/Linux 的新 shell 中，该目录不会自动加入 $PATH。运行 uv tool update-shell，然后打开一个新 shell 并重新运行 mm --version。

2. 设置

升级 Claude 插件后： 重新加载后再次检查 /mcp。 插件会启动 memtomem[onnx]==0.7.0。手动注册的启动配置若与之不同——仅使用基础版 memtomem，或固定到较早版本的 ONNX 启动配置——将无法再通过去重匹配，可能会暴露重复工具。请确认手动条目的名称和作用范围，然后使其启动命令与插件保持一致，或移除冗余注册。

mm init                               # preset picker, then memory_dir + MCP

交互式选择器提供三个预设选项——Minimal（BM25，不下载）、English (Recommended)（ONNX multilingual-e5-small + 英文重排器 + 自动发现提供方）、Korean-optimized（ONNX multilingual-e5-small + kiwipiepy 分词器，不使用重排器）——以及一个会打开完整 10 步向导的 Advanced 选项。预设流程只会询问记忆目录和 MCP 注册；其他设置均采用预设值。

若要最快完成无需下载的首次验证，请选择 Minimal；准备好添加语义搜索后，再运行 mm init。

索引与发现（Claude Code）： 设置流程自动发现的提供方记忆文件夹（例如 ~/.claude/projects/*/memory/）会添加到搜索索引。这与 Web UI 中选择加入的 Context Gateway 扫描 ~/.claude/projects/ 不同；后者会发现项目根目录，用于查找 Skills、自定义命令和子 Agent——有关区别及有损 slug 的注意事项，请参阅 Configuration → Context Gateway。

用于自动化 / CI：

mm init --non-interactive                   # minimal preset, no prompts
mm init --preset korean --non-interactive   # Korean-optimized bundle, no prompts
mm init --advanced                          # force the full 10-step wizard

完整的模型 / 提供方对照表请参阅 Embeddings。

3. 验证完整的记忆往返流程

首次成功验证无需已有笔记目录或已连接的编辑器：

mm status
mm add "Deployment checklist uses blue-green rollout" --tags ops
mm search "blue-green"

mm add 会写入已配置的用户记忆目录，并立即为该条目建立索引。最后一条命令应返回刚刚添加的句子。

然后验证编辑器连接：

"Call the mem_status tool"

若要将现有笔记纳入同一索引，请将 mm index 指向一个已存在的目录：

mm index /path/to/your/notes

mm status --json（或 --format json）会以机器可读格式提供相同的状态信息，供脚本和 CI 使用。

4. 打开 Web UI（可选）

mm web                # polished dashboard on http://127.0.0.1:8080
mm web -b             # run in the background; logs go to ~/.memtomem/logs/web.log
mm web status         # show pid/port/start time
mm web stop           # stop the tracked Web UI process
mm web --dev          # maintainer surface (adds opt-in pages)

默认情况下，mm web 会显示经过优化的页面集。传入 --dev（或在 shell 配置文件中设置 MEMTOMEM_WEB__MODE=dev）可显示 Sessions、Working Memory 和 Health Report 等维护者页面。

uv tool install memtomem             # no extras — no local ONNX model, Web UI or Korean tokenizer until you add them; Ollama/OpenAI embeddings still work

uv add 'memtomem[all]' && uv run mm init    # all commands need `uv run` prefix

claude mcp add memtomem -s user -- uvx --isolated --from "memtomem[all]==0.7.0" memtomem-server

核心功能

• 混合搜索——在一次查询中融合 BM25 关键词搜索、稠密向量搜索和 RRF
• 语义分块——支持识别标题的 Markdown、基于 AST 的 Python、基于 tree-sitter 的 JS/TS，以及结构感知的 JSON/YAML/TOML
• 增量索引——在分块级别执行 SHA-256 差异比较；仅对变更的分块重新生成嵌入
• 命名空间——将记忆整理到不同范围的分组中，自动根据文件夹名称推导；可在 Web UI 的 Settings → Namespaces 中审核并为其添加标签（颜色、描述）
• 维护——近似重复检测、基于时间的衰减、TTL 过期、自动打标签
• Web UI——提供用于搜索、来源、标签、时间线、去重等功能的可视化仪表板（运行 mm web --dev 可使用完整的维护者界面）
• 上下文网关——在项目或用户 Store 中保留规范的 Skills、Commands 和 Subagents，还可选择从单独的 Wiki 安装可复用资源，然后将其推送到受支持的 AI 运行时。参见上下文网关。
• MCP 工具——mem_do 元工具在 core 模式下路由所有非核心操作，以尽量减少上下文占用
• 可预测的核心——通过明确的 CLI/MCP 调用执行记忆操作（mm add、mem_add、mem_index 等）。可单独安装和移除可选的客户端钩子，而非将其设为隐藏的运行时默认行为。
• 可编写脚本的 CLI——为脚本提供 JSON 输出：mm status、写入命令（mm add / mm reset / mm purge）、mm session start / end / list / events、mm schedule list、mm watchdog status / run 和 mm doctor 支持 --json；mm search 和 mm recall 支持 --json（或 --format json）；mm warmup 可预加载本地模型，让首次查询跳过冷启动耗时
• 定时任务——使用 mm schedule add/list/run-now/delete（或 mem_do(action="schedule_*")）执行由 cron 驱动的压缩、重要性衰减、失效链接清理和去重扫描
• 固定上下文——使用 mm pinned compose，在检索结果前保留简短的用户/项目/Agent Markdown 内容块
• LangGraph Store——可选的 MemtomemBaseStore，实现 LangGraph 的元组命名空间长期记忆契约
• 混合 LangGraph Store——MemtomemHybridStore 增加专用的 SQLite 持久化、BM25/稠密向量/RRF 检索、TTL 和诊断功能

稳定性

memtomem 处于 Beta 阶段（0.x）。九个核心 MCP 工具、mm CLI，以及记忆文件和配置文件的格式，只有在 CHANGELOG 中添加 Upgrading 说明时才会更改；在可能的情况下，还会设置弃用过渡期。下方未列出的其他功能均受支持——会持续维护，并在 CHANGELOG 中记录其变更——但不作此保证。

以下功能均为实验性功能——其行为、输出或格式仍可能随时更改或移除，不设过渡期，因为相关设计决策仍未敲定，或者其生成内容由大模型编写：

• 多 Agent 记忆——mem_agent_register、mem_agent_search、mem_agent_share 和按 Agent 划分的会话范围（mem_session_start 中使用 agent_id）。尚未敲定的决策：＃1477、#1478。
• 记忆导出和导入包——mem_export / mem_import 以及 Web 导出/导入。如何恢复 0.7.0 之前创建且包含项目记忆的备份（包 v1–v3），仍未敲定。
• 大模型编写的输出——memtomem 配置的大模型（MEMTOMEM_LLM__ENABLED=true）编写的所有内容：大模型自动标记和实体提取、strategy="llm" 查询扩展、大模型整理和策略摘要、会话自动摘要、来源摘要（indexing.auto_summarize）以及上下文块增强（indexing.enrich_chunk_context）。与之并列的基于规则的模式——关键词自动标记、正则表达式实体提取、tags/headings 扩展、启发式整理摘要——均受支持。
• Context Gateway 中的 Claude 项目扫描（MEMTOMEM_CONTEXT_GATEWAY__EXPERIMENTAL_CLAUDE_PROJECTS_SCAN）。
• Antigravity CLI 插件（packages/memtomem-antigravity-plugin/）。

生态系统

文档

托管于 memtomem.com，也可在此仓库中以 Markdown 格式查看。刚开始使用 memtomem？指南提供了建议的阅读顺序。下表遵循该顺序，并将两个可运行示例放在入门指南之后：

贡献

请参阅 CONTRIBUTING.md，了解设置说明和贡献者指南。

许可证

Apache License 2.0。我们根据贡献者许可协议的条款接受贡献。