冥想盆 · memleaf：本地优先的 AI Agent 共享记忆核心

memleaf（冥想盆）是一个本地优先、Markdown 驱动的 AI Agent 共享记忆系统。它将 AI 对话过程中产生的长期记忆以用户自有的本地 Markdown 文件形式保存，并支持多个 AI Agent 共享同一个 Vault。与依赖向量数据库或云端服务的方案不同，memleaf 完全运行在本地，不要求账号、云端同步或遥测数据。

核心能力

• 本地 Markdown 存储：记忆以纯文本 Markdown 保存在本地目录，可用 Obsidian、VS Code、Vim 等普通工具直接查看和编辑
• 本地 stdio MCP 服务：通过本地 MCP 接口提供主动检索、读取、记忆维护等能力，Agent 无需联网即可访问
• 多 Agent 共享 Vault：多个 AI Agent（当前支持 Hermes 和 Codex）可以读写同一个 Vault，实现跨 Agent 记忆共享
• 受控检索流程：采用「Scope Map → 候选目录 → 受控读取正文」三层检索链路，避免将整段历史上下文塞进模型
• 记忆提炼规则：内置原子化记忆原则——每条记忆必须独立可理解，支持 CREATE / UPDATE / NO_CHANGE 三种处理状态
• 零外部依赖：核心运行时仅使用 Python 标准库，要求 Python 3.11+

安装配置

Windows（PowerShell）

已安装 Hermes 的 Windows 10/11 用户，在 PowerShell 中执行：

irm https://raw.githubusercontent.com/miffyblueboo/memleaf/main/install.ps1 | iex

安装器会优先使用 Hermes 自带的 Python 环境，自动完成 memleaf 安装和 Hermes MemoryProvider 接入。

通用安装（pip）

pip install memleaf

安装后查看帮助：

memleaf --help

初始化 Vault

memleaf init

这会在用户目录创建 Vault 结构，包括 inbox/（原始捕获）、knowledge/（结构化记忆）、history/（历史版本）三个子目录。

使用步骤

1. 安装 memleaf：通过 pip 或 PowerShell 安装脚本完成安装
2. 初始化 Vault：运行 memleaf init，创建本地记忆存储目录结构
3. 配置 Agent 集成：在目标 AI Agent（Hermes / Codex）的配置中启用 memleaf MemoryProvider
4. 对话触发捕获：正常对话时 Agent 自动将相关内容捕获到 inbox，无需手动操作
5. 受控检索与读取：通过 MCP 接口的 search 工具搜索候选，read 工具按需读取少量关键正文
6. 提炼写入知识库：Agent 判断有价值的内容通过 remember 工具写入 knowledge/，形成长期记忆

适用场景

• 跨会话项目记忆：AI 编程助手记住每个项目的架构决策、待办事项和技术债务，避免每次从头开始
• 多 Agent 协作：同一项目中的多个 AI Agent（代码助手 + 审查助手 + 文档助手）共享同一个 Vault，保持信息一致
• 个人知识管理：用 AI 整理阅读笔记、会议纪要和研究资料，所有数据保存在本地 Obsidian 知识库
• 隐私敏感场景：医疗、法律、金融等行业的 AI 辅助应用中，所有对话数据不出本地，满足数据合规要求

适用人群

• 使用 Claude Code、Cursor 等本地 AI 编程工具的开发者
• 有隐私要求的 AI 应用开发者和企业技术团队
• 希望用 Obsidian 等本地工具管理 AI 生成记忆的高级用户
• 多 Agent 协作系统的架构师和开发者

工作原理

memleaf 的核心是一个基于 Python 标准库的本地运行时，不依赖任何外部服务。对话过程中，可见文本通过 capture 流程脱敏后写入 inbox/ 下的 Markdown 文件。自动检索路径由 Scope Map 驱动——它描述了当前有效记忆的分类结构，单页最多 20 项。Agent 执行搜索时，先通过 Scope Map 确定范围，返回候选列表（包含 memory_id 和标题），只有需要引用时才会用 read 工具按需读取正文，严格避免全量历史注入上下文。记忆提炼遵循原子化原则，Agent 判断每段内容是否有独立复用价值后，通过 remember 写入 knowledge/，状态更新时旧版本自动移入 history/。

官方链接

• PyPI：https://pypi.org/project/memleaf/
• GitHub：https://github.com/miffyblueboo/memleaf