heropen 文档

01安装

heropen 是一个 Python 包，一条命令装好。核心版自带 MCP 服务与全文检索；可选装本地向量模型以启用语义检索。

# 核心：MCP 服务 + 全文检索
pip install heropen

# 可选：本地语义检索（会下载 bge-small-zh-v1.5，约 95MB）
pip install 'heropen[embedding]'

一键脚本

不想自己配 Python 环境，可以直接跑安装脚本：

# macOS / Linux
curl -fsSL https://heropen.net/install.sh | bash

# Windows PowerShell
irm https://heropen.net/install.ps1 | iex

确认装好了

heropen --version      # 打印版本号
heropen doctor         # 自检：写入纪律 / 容量 / 端口 / Embedding 状态

装不上时

02快速开始

四步，从零到 agent 真的记得住你。

1. 安装
   见上一节。
2. 绑定到你的 Agent
   装好后运行一次，按屏幕提示把配置片段贴进 Agent 的 MCP 配置文件，然后完全重启 Agent。

   heropen            # 首次运行：初始化 + 自动打开浏览器视图
   heropen auto-setup # 自动检测 Cursor / Cline / Claude Code / Windsurf 并写入配置

3. 存一条记忆
   一条一事，写清楚到「以后的自己不看聊天也能懂」。

   heropen add --content "部署目标是局域网 Ubuntu 主站" --tags "部署,Ubuntu" --section "项目"

4. 搜出来
   支持语义、全文、模糊逐级降级，写法随意。

   heropen search "部署目标"
   heropen search "Ubuntu" --tag 部署 --limit 5

03核心概念

两层记忆，一个事实库

多数 Agent 有两层「记忆」，heropen 的定位是把其中一层变成唯一事实源。

多 Agent：私有域与共享域

heropen 支持多个相互隔离的 Agent 域。每个域有独立的记忆库，互不串味。

数据存在哪里

默认全部落在用户目录下的 ~/.heropen/：

检索是怎么走的

查询会按能力逐级降级，永远不会「查不了」：

• 有本地向量模型 → 语义检索优先
• 语义不可用 → 知识图谱 / 全文检索（FTS）
• 还可按时间维度直接取：--last N（最近 N 条）、--today、--date

04使用纪律（SSOT）

这一节是 heropen 真正生效的关键：把「记不记得住」从模型自觉，变成可执行的纪律。

写什么进 heropen

• 稳定偏好、约定、身份与关系
• 项目事实、技术选型、路径与账号偏好（不含密钥正文）
• 决策与结论（含日期 / 原因）
• 任何需要跨会话、跨 Agent 复用的事实

写入原则

• 一条一事，写清楚到「以后的自己不看聊天也能懂」
• 主打自由标签 tags，少纠结固定分类
• section 只做可选大桶（如「用户偏好」「项目」「约定」），允许空或粗分
• 更新已有事实优先 update_memory，避免平行再插一条导致漂移

热层该留什么

1. 铁律——下面那段精简版铁律
2. 高频热记忆——最近反复用到、短、值得常驻上下文的几条
3. 检索指针——指向 heropen 的 entry_id / 关键词 / 标签，而不是事实全文双写

下沉（热 → 冷）

热层变满或整理时，优先搬走低频、很长、已过时效的内容，热层只留一行指针，例如 项目栈 → heropen tags:tech-stack 或 entry_id=42。不要按「字符占用率到了就整页清空」一刀切。

可贴进 Agent 的铁律

把下面整段放进宿主的 system prompt 或记忆铁律（可按产品改名，语义勿删）：

【heropen 铁律 v2 · SSOT】
1. 事实只存 heropen。宿主热记忆只保留：本铁律、少量高频短句、
   指向 heropen 的指针（entry_id / tags）。禁止同一事实双写全文。
2. 每次开场：先 prime_conversation，再按本轮主题 search_memory；
   不搜就当作库里没有。
3. 用户给出偏好 / 约定 / 项目事实时主动 add_memory，不要等「记住」。
4. 写入主打自由 tags；section 只是可选大桶，允许粗分或省略。
5. 热层将满时：优先把低频、长、过时内容下沉到 heropen，热层改留指针。
6. 更新已有事实用 update_memory，避免平行插入导致漂移。
7. 密钥 / 密码不要写入记忆正文。

05开场协议

每一次新对话开场，在寒暄或办事之前，按顺序做两件事。

1. prime_conversation
   拿到本地时间、距上次对话的间隔、时段词。
2. search_memory
   按本轮主题关键词检索，把 top 结果读进上下文，然后再开始回答。

手动跑一遍看看效果：

heropen session          # 保存 / 恢复会话断点
heropen bootstrap        # 生成 Agent 启动摘要（人也能读）
heropen recall "上次定的方案" --limit 5

06CLI 命令参考

终端里 heropen --help 可随时查看。以下按用途分组。

安装与配置

读写记忆

常用参数

heropen add --content "记忆内容" [--section 分类] [--tags 标签] [--agent 名称]
heropen recall "查询词" [--agent 名称] [--limit 数量] [--tag 标签]
              [--last N] [--today] [--date YYYY-MM-DD] [--fts] [--graph]

--agent 指定写入或检索哪个 Agent 域，省略则用默认域。

查看与诊断

界面

备份与迁移

07MCP 集成

MCP（Model Context Protocol）是 Agent 工具调用的标准协议。heropen 通过 MCP 让 Agent 在自己的对话里直接搜索、添加、更新记忆——你不需要手动敲命令。

标准配置（所有 Agent 通用）

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

各 Agent 的配置文件位置

Hermes

Hermes 用 YAML，且 command 建议写 绝对路径——隔离安装（如 uv tool）时 PATH 里常常找不到 heropen-mcp。

mcp_servers:
  heropen:
    command: 'C:/path/to/heropen-mcp.exe'
    args: []
    env:
      HF_HUB_OFFLINE: '1'          # 模型已就位后建议打开
      HEROPEN_NO_UPDATE_CHECK: '1'
    connect_timeout: 60
    timeout: 120

08MCP 工具参考

Agent 连上 heropen MCP 后可以调用以下 9 个工具。这些由 Agent 自动使用，用户无需手动操作。

09常见问题

MCP error -32000: Connection closed

Agent 启动 MCP 进程失败。依次排查：

1. 终端里能跑通 heropen-mcp 吗？跑不通先修安装。
2. 配置里的 command 是否在 PATH 里？隔离安装时改成绝对路径。
3. 改完配置有没有完全重启 Agent？

找不到 heropen 命令

Python 的 Scripts 目录不在 PATH 里。临时可用 python -m heropen；长期解决是把 Scripts 目录加入 PATH。

配置改了但没生效

Agent 只在启动时读一次配置文件。完全退出进程（不是关窗口）再打开。

Windows 上 JSON 配置报错

Windows 反斜杠在 JSON 里是转义字符，路径要写双反斜杠 C:\\Users\\...，或统一用正斜杠 C:/Users/...。

语义检索没生效 / 模型下载很慢

说明本地向量模型没就位，此时会自动降级到全文检索，功能不受影响。要启用语义检索，可用官方离线包（见下节），它会跳过联网下载。

免费版够用吗？

免费版包含基础记忆（搜索 / 写入 / 更新）、MCP 协议、本地存储、托盘工作台、会话断点保护、时间感知，可用 8 个 Agent，不设时限、无需注册。

数据存在哪里？需要联网吗？

全部在本地 ~/.heropen/。日常读写完全离线；只有首次下载向量模型（可选）和检查新版本时会联网。

怎么卸载？

pip uninstall heropen        # 卸载程序
# 记忆数据不会被自动删除。确认不要了再手动删：
rm -rf ~/.heropen            # Windows: 删除 C:\Users\你\.heropen

10隐私与数据

heropen 负责「记」，不负责「陪」。配置人设时请勿把它包装成情感伙伴。

11版本与升级

当前最新版本：正在获取…（自动从 PyPI 读取）

升级

pip install -U heropen

升级前会自动备份记忆库到 ~/.heropen/backups/，不会覆盖你已有的记忆。

离线向量模型包

内网环境或下载太慢时，用官方离线包，解压后按包里 install_model.py 的说明执行，跳过联网下载：

前往最新 Release 下载 heropen-model-offline-bundle.zip

包内含 BAAI/bge-small-zh-v1.5（中文小模型，约 53MB），断网可用。

发布节奏

heropen 遵循固定发布窗口：周一 / 周四扫描变更，周五评审发布；无代码变更不发版。所有版本同步到 PyPI 与 GitHub。