heropen — AI Agent Memory

heropen

English · 简体中文

旨在解决遗忘问题。用得越多，它就越了解你。

面向 AI Agent 的本地优先记忆系统。记忆保存在你自己的设备上——绝不上传、绝不同步，也不会被带走。heropen 会自动整理和精简记忆，让检索随着时间推移变得更精准、更贴合你。

⭐ 觉得有帮助？给我们点个星标 → 点击右上角的 ★ Star，让更多 Agent 用户发现它。

30 秒了解

• 一行命令安装：pip install heropen。无需 Docker、Postgres 或 API 密钥。常见客户端会自动写入 MCP 配置；Hermes 等客户端则需要手动配置 heropen-mcp。
• 让你的 Agent 获得长期记忆：它能跨会话记住人物、事件和上下文——每次对话都不必从零开始。
• 数据 100% 保留在你的设备上：没有遥测、没有云同步、没有账单。记忆保存在你的磁盘上，只有你能将其带走。

安装

pip install heropen                 # Core: MCP + full-text search, pure-Python deps, any architecture (incl. ARM64)
pip install 'heropen[embedding]'    # Optional: local embeddings (pulls in onnxruntime / fastembed)
pip install 'heropen[tray]'         # Optional: Windows system tray badge (always-visible presence + workbench)

ARM64 说明

平台	建议
Apple Silicon（macOS arm64）	通常运行 pip install 'heropen[embedding]' 即可
Windows ARM64	同上；请确保使用 ARM64 版本的 Python
Linux aarch64	先安装核心组件，再尝试安装 embedding。如果没有匹配的 onnxruntime wheel，请将 EMBEDDING_ENDPOINT 指向可自托管的端点，或仅使用 FTS

没有本地 embedding 时，search / recall 会优雅地退化为全文搜索——记忆的存储和检索仍可正常工作。

重启你的 Agent——完成。首次启动时，heropen 会探测常见客户端（Claude Code、Cursor、Windsurf、WorkBuddy 等）的已知配置路径，并注册记忆工具。不会自动写入 Hermes 等自定义 mcp_servers 配置；请按照下方“连接你的 Agent”中的说明手动配置。

30 秒快速开始

heropen add "Project uses FastAPI + SQLAlchemy, tests run on pytest"   # store a memory
heropen search "project tech stack"                                    # search memories
heropen status                                                         # check status
heropen diagnose                                                       # diagnose problems

如何让它真正发挥作用：阅读官方使用指南（唯一信息源）——docs/usage-ssot-zh.md （中文）。 简而言之：只有事实才写入 heropen；热层用于存放硬性规则、高频内容和指针；每次会话都从 prime 开始，然后使用 search；自由格式标签是主要机制。

首次执行 add 不会下载约 95 MB 的 embedding 模型——写入会直接使用全文搜索。需要本地语义检索时，请明确运行：

pip install 'heropen[embedding]'
heropen embed          # download the model and generate embeddings for existing entries

连接你的 Agent（MCP）

使用专用的 heropen-mcp 入口点（stdio）。heropen mcp 也可以，但建议在 MCP 客户端配置中使用以下形式：

{
  "mcpServers": {
    "heropen": { "command": "heropen-mcp", "args": [] }
  }
}

如果 heropen-mcp 不在你的 PATH 中（例如，通过 uv tool install 安装到了隔离环境），请将 command 替换为该环境中的绝对路径。

对于 Claude Code / Cursor / Windsurf / WorkBuddy：heropen auto-setup 会尝试写入已知配置路径。对于 Hermes 和其他自定义配置格式，请将上面的配置块添加到自己的 mcp_servers 中，然后重启 Agent。

重启 Agent，它就拥有记忆了。只需保存一次错误修复，它就会在后续会话中永久记住。

托盘徽标（Windows 系统托盘，heropen[tray]）

安装 heropen[tray] 后，运行 heropen tray，即可将原生 heropen 图标固定在任务栏托盘中（与微信 / 蓝牙 / 输入法位于同一区域）——不会遮挡任何窗口内容。它解决了“一个没有存在感的记忆系统，很容易被误认为是垃圾软件并被卸载”的问题。

pip install 'heropen[tray]'   # Windows only
heropen tray                  # start the badge (auto-starts on boot by default)

右键菜单：

项目	功能
状态行	运行中 · Free / Plus · N 个 Agent · N 条记忆
版本 vX.Y.Z	打开更新日志
存储模式（每个 Agent）	每个 Agent 可独立选择批量存储 / 每轮存储 / 自动检测
打开工作台	左键单击图标也会执行此操作——打开实时数据工作台页面
打开主页	打开 heropen.net
检查更新	pip install -U heropen
开机启动	切换开关（默认开启；写入注册表 Run 项）
重启 / 退出	重启以加载最新代码 / 完全退出

将鼠标悬停在图标上会显示四项一目了然的状态：身份（heropen Agent 记忆系统）、存储模式、已存储条目数和已使用天数。

真实数据，不作伪造：徽标和工作台读取本地 ~/.heropen/*.db 中实际的 entries 表。没有任何硬编码内容。如果无法读取数据库，则显示“无数据 / 0”，绝不会编造数字（--mock 仅用于演示）。它只反映本地数据库——另一台机器上的记忆（例如，另一台电脑上另一个 Agent 的记忆）不会显示在这里，这是预期行为（每台机器的徽标相互独立）。

存储模式（已接入核心）：三种模式控制记忆提交到 heropen 的频率和粒度——批量存储会对记忆进行批量处理；每轮存储会在每轮结束时写入；自动检测则会根据“记住 / 已决定 / 路径 / 偏好”等触发词进行智能选择。可按 Agent 设置。该模式只控制提交——不控制检索，也不影响托盘显示内容；写入的内容仍是本地事实存储。详见 docs/2.0-开场签名与存储内核.md（中文）。

界面语言（自 2.0.4 起）：托盘菜单中的“语言”项可切换简体中文 / English / 日本語 / 한국어 / Español / Français / Deutsch / Português / Русский。菜单、悬停提示、通知和工作台页面都会即时切换，所选语言会保存在本地（~/.heropen/_tray_state.json）。

不提供删除功能：徽标、工作台和 CLI 均完全没有删除入口。

开场签名

每次对话开始前——在 Agent 真正开始工作之前——heropen 会在上下文中写入一行状态信息。无需输入命令，也无需打开面板：

heropen ready · 187 local memories · ~3 hours since last conversation · agent=xiaokai

它会附加到 MCP prime_conversation 返回值的开头（CLI 的 bootstrap 也会打印该信息）。

2.0 版的存在感 = 开场签名 + 托盘：签名让“你在聊天时能看到它”，托盘则让“即使你不在聊天，它也在任务栏中”。

为什么选择 heropen

	heropen（免费）	其他选项
存储	无限	通常有限制
检索	无限	按调用次数计费
是否需要网络	否	是
数据所有权	你的机器	他们的服务器
安装	一条 pip install 命令	服务端 + 配置

免费版 = 完整的核心功能集，没有任何功能被阉割。

heropen 的定位

本地优先并非 heropen 独有——十几个类似项目都使用 SQLite + MCP。heropen 真正具备、而其他项目尚未提供的优势有三点：

• 跨多个 Agent 的私有域 / 共享域分层。免费版提供 8 个完全私有的 Agent（Hermes 和 WorkBuddy 这类高频常驻 Agent 各自使用独立数据库），还提供可选的共享域（_shared），供 Agent 按需交换知识。免费版和 Plus 的区别在于功能，而非数量（Plus 增加技能收集与共享等实用功能）。大多数竞品只提供单一的扁平命名空间。
• 对话开始前感知时间（自 v1.8.7 起）。每次会话开始时，Agent 都会自动获取本地时间、时段描述、距离上次对话的间隔，以及期间是否经历了睡眠周期——这为交互侧提供了时间基准，目前没有其他产品做到这一点。
• 零依赖安装方式。只需一行 pip install heropen，无需 Docker、Postgres 或 Ollama。

隐私承诺

数据留在你的设备上。无遥测数据，无心跳请求。 所有记忆都保存在本地 SQLite 数据库中。向量检索默认使用本地嵌入模型（fastembed；pip install heropen[embedding]）——完全离线且免费。你也可以将 EMBEDDING_ENDPOINT 和 EMBEDDING_API_KEY 环境变量指向你自己的可自托管嵌入端点（兼容 OpenAI 的 /v1/embeddings），这样就无需向第三方云服务付费。

如果既未配置本地嵌入，也未配置自托管端点，搜索就会回退到快速的全文（FTS）匹配——仍然完全离线且免费。pip install heropen 无需任何配置即可使用；嵌入模型只会提升检索质量，不会妨碍基本功能的使用。

本地能力目前始终保留在本地：在当前版本中，本地记忆的读写、检索和面板功能不会迁移到需要网络访问的服务中；免费版已提供的能力在后续版本中也不会减少。

为什么选择本地

当记忆成为云端功能时，你的对话历史和工作上下文最终都会落在别人的服务器上。heropen 选择了相反的做法：记忆写入 ~/.heropen/，每个 Agent 对应一个 SQLite 文件，数据永远不会离开你的设备。

云端提供的是便利；本地提供的是只有你才能将其带走。

记忆归你所有

记忆保存在本地 ~/.heropen/ 目录中，每个 Agent 对应一个 SQLite 文件。你随时可以：

• 备份 / 导出：heropen export 会将所有记忆导出到本地 JSON 文件（使用 heropen import 可将其导回）；
• 不提供删除功能：heropen 不提供删除 / 清空入口——记忆由你在本地掌控，也可以导出，但我们特意没有设置任何“删除”按钮，以避免无法挽回的误操作（没有云端副本；删除即永久消失）。如果确实需要清理，只需删除 ~/.heropen/ 下对应的 SQLite 文件——无需联系我们，也无需联网。

更易读的 Markdown + YAML 导出（人类可读、无损往返、可重新导入）已列入路线图。

如何选择

选择记忆方案时，不要只关注召回效果，还要考虑以下五点：

1. 部署成本：运行它是否只需执行一次 pip install，还是需要 Docker / Postgres / Ollama / API 密钥？
2. 依赖和成本：写入流程是否会消耗大模型 Token？是否没有任何外部依赖？
3. 可移植性：记忆能否导出为可读文件、转移到其他地方并重新导入？
4. 安全默认设置：监听端口默认绑定到 loopback 还是 0.0.0.0？是否不收集遥测数据？
5. 工程负担：写入规范和失效机制是否清晰？是否兼容提示词缓存？如何处理跨模型容量限制？

运行 heropen doctor，它会自动检查以上五项，并为每项给出通过 / 提示 / 警告的判定。

版本与定位

版本	定位	适用对象
Free	专注做好记忆这一件事：本地、私密，使用越久效果越好	希望为 Agent 提供长期记忆，并在自己的机器上运行的所有人
Plus	出色的记忆功能 + 为你的工作提供服务：首项功能是技能的收集与分享，让你记住的内容能在不同 Agent 间复用	愿意为持续推出的新功能付费的独立创始人 / 独立开发者
Enterprise	为许多员工 × 许多客户打造的记忆基础（可自托管 + 隔离 + 审计）	需要由许多员工服务许多客户的组织

Free 版本完全开源（Apache-2.0）；Plus / Enterprise 为闭源版本。

合规声明

heropen 是一款本地优先的记忆与上下文工具：你的数据始终保留在自己的机器上，完全由你掌控。本地优先架构天然满足用户数据控制与透明度相关要求——其运行过程对你透明且可控。

开源范围

Free 版本完全开源（Apache-2.0）。商业版本（Plus / Enterprise）为闭源版本。

链接与支持

• 主页：heropen.net
• 文档：heropen.net/docs
• GitHub：github.com/Koradji77/heropen

⭐ 如果你喜欢它，请点星标——这是你能给予我们最大的支持：点击 ★ Star。

路线图

• 目前专注于桌面端和本地使用。目前暂不考虑移动端 / 跨设备同步——这与“数据永不离开你的机器”这一默认承诺相冲突。如果将来推出此功能，也必然会采用用户自有存储 + 端到端加密 + 默认关闭的形式。
• 支持以 Markdown + YAML 格式导出记忆（无损往返）。
• 为不同 Agent 提供更多产品化的私有域 / 共享域功能。

许可证

Apache-2.0