HeroPen 文档 - 安装、配置、API 参考

安装

一键安装（推荐）

Windows PowerShell：

irm https://ksmn.cc/install.ps1 | iex

macOS / Linux：

curl -sSL https://ksmn.cc/install.sh | bash

装完自动弹窗，复制文字发给你的 AI 助手即可。
如遇弹窗未出现，请手动运行 heropen。

pip 安装

需要 Python 3.10+，任意操作系统（Windows / macOS / Linux）。

pip install heropen

⚠️ 装完必须设置： 在终端（cmd / PowerShell / 终端）输入 heropen，弹出窗口后复制内容发给你的 AI 助手。AI 会自动完成配置。

可选依赖：

pip install heropen[all]   # 包含 MCP、向量嵌入、Rich 终端 UI

pip install heropen[ui]    # 仅 Rich 终端 UI
pip install heropen[embedding]  # 仅向量嵌入支持

💡 推荐： 先装基础包 pip install heropen，等需要向量搜索再补 heropen[embedding]。

升级

pip install --upgrade heropen

查看当前版本：

heropen --version

快速开始

1. 安装

推荐：Windows PowerShell 一行搞定：

irm https://ksmn.cc/install.ps1 | iex

或者 pip 安装后运行 heropen：

pip install heropen
heropen

2. 弹窗后复制文字发给 AI

AI 会自己读懂并完成配置。重启 AI 助手即可使用。

3. 存一条记忆试试

heropen add "项目用 Python + SQLite，测试用 pytest"

4. 搜索

heropen search "项目技术栈"

🎯 终极验证： 在 agent 对话里问「heropen 有多少条记忆，查一下」。能回答就成功了。

命令参考

heropen

显示帮助信息和可用命令列表。

heropen --help

heropen setup

交互式初始化。选择 agent 名称、工作模式，生成配置文件。

heropen setup

heropen install

交互式安装向导。扫描已安装的 Agent 工具，选择版型，写入配置。

heropen install

heropen auto-setup

一键自动配置（推荐）。自动检测 Cursor / Cline / Claude Code / Windsurf 的配置路径，注入 MCP 配置。

heropen auto-setup

heropen mcp

启动 MCP 服务器（stdin/stdout 模式）。供 Agent 通过 MCP 协议调用 HeroPen 工具。

heropen mcp           # stdio 模式（默认）
heropen-mcp --http    # HTTP SSE 模式，监听 0.0.0.0:8090

heropen status

显示 HeroPen 运行状态：记忆条数、Agent 列表、数据库健康状况。

heropen status

heropen add

添加一条记忆。

heropen add "记得用 FastAPI 写后端，SQLAlchemy 连数据库"

heropen search

搜索记忆。支持向量语义搜索、全文检索、模糊匹配（自动降级）。

heropen search "FastAPI"
heropen search "数据库" --limit 10

heropen --version

查看当前版本号。

heropen --version

MCP 集成

Model Context Protocol (MCP) 是 Agent 工具调用的标准协议。HeroPen 通过 MCP 让 agent 在自己的对话里直接搜索、添加、更新记忆。

标准 MCP 配置

所有 Agent 通用，在对应的 MCP 配置文件中加入：

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

各 Agent 配置路径

WorkBuddy

C:\Users\你的用户名\.workbuddy\mcp.json

Cline (VS Code)

Windows: %APPDATA%\Claude\cline_mcp_settings.json
macOS: ~/Library/Application Support/Claude/cline_mcp_settings.json
Linux: ~/.config/Claude/cline_mcp_settings.json

Cursor

Settings → Features → MCP Servers → Add，或者编辑
~/.cursor/mcp.json (macOS/Linux) 或 C:\Users\你的用户名\.cursor\mcp.json

Claude Code CLI

.claude/settings.json（项目根目录）

Cherry Studio

设置 → MCP 客户端 → 添加，命令填 heropen，参数填 mcp。

Continue.dev

~/.continue/config.json（MCP 配置在 experimental.mcpServers 字段下）

⚠️ 修改配置后必须重启 Agent。 不只是关窗口，要完全退出进程再打开。

MCP 工具参考

Agent 连接上 HeroPen MCP 后，可以调用以下工具。这些是 agent 自动使用的，不需要用户手动操作。

工具	说明	主要参数
search_memory	搜索记忆（向量→FTS→模糊，三层自动降级）	`query`, `limit`, `agent`, `date_from`, `date_to`
add_memory	添加一条新记忆	`section`, `content`, `tags`, `agent`
update_memory	更新已有记忆（只改提供的字段）	`entry_id`, `section`, `content`, `tags`, `status`
list_memory	列出最近添加的记忆	`limit`, `agent`
health	检查服务状态，返回各 agent 记忆条数	—
session_checkpoint	保存当前会话快照（长对话防断片）	`agent`, `context_summary`, `active_task`, `key_decisions`
session_recover	恢复最近的会话快照	`agent`, `limit`

💡 每个 agent 有独立的记忆空间。 默认 agent 名称是 xiaoman，可以通过 agent 参数切换到其他 agent。

常见问题

MCP error -32000: Connection closed

MCP 通信连接中断。最常见原因是 JSON 配置文件格式错误或 heropen 版本过低。先升级：pip install --upgrade heropen，再检查 JSON 是否合法。

找不到 heropen 命令

Python 可能没加到 PATH。用完整命令：python -m heropen mcp 在 MCP 配置里把 "command": "heropen" 改成 "command": "python"， "args": ["-m", "heropen", "mcp"]。

配置改了但没生效

确保完全关闭 Agent（不只关窗口），再重新打开。某些 Agent 会缓存 MCP 配置，需要完全退出进程。

Windows 上 JSON 配置报错

确保文件保存为 UTF-8 编码（不带 BOM）。记事本默认会加 BOM，用 VS Code 或 Notepad++ 保存为「UTF-8 无 BOM」格式。

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

数据 100% 本地存储，不联网不上云。SQLite 数据库文件在 ~/.heropen/（macOS/Linux）或 C:\Users\你的用户名\.heropen\（Windows）。向量搜索也在本地运行，不调用外部 API。

免费版够用吗？

免费版就是完整核心功能，不阉割。支持 2 个独立 agent 记忆库、不限记忆条数、三层搜索（向量+全文+模糊）、MCP 协议。90% 个人用户免费版就够用了。

怎么卸载？

pip uninstall heropen
rm -rf ~/.heropen  # 可选，清除所有数据

更新日志

v1.4.3 — 六月的最后一块拼图 (2026-06-21)

Windows 用户反馈说装上了但跑不起来，查了一圈是路径解析的问题。修了。同时给启动逻辑加了层自愈能力——就算某个 agent 的记忆库文件出了点状况，启动时也能自动修好，假装什么都没发生过。

v1.4.0 — "装完就能用"的执念 (2026-06-21)

有人跟我说「pip install 很简单，但装完我不会配」。这句话扎到了我。auto-setup 就是这么来的——你跑一下，它自己去翻你的 Cursor、Cline、Claude Code、Windsurf 的配置文件，该写的写进去，你只需要重启 agent。另外基础包不再强制依赖 mcp 库了，安装更快，不用的东西不装。

v1.3.1 — 搜得到才算数 (2026-06-20)

有次我搜自己记过的东西，向量搜索没命中，直接给我返回空了。我心想这不行——用户不会管你是向量没建好还是模型没加载，搜不到就是搜不到。所以加了三层降级：向量找不到就全文，全文找不到就模糊 LIKE。只要记过，总有一种方式能找到。

v1.3.0 — 断片修复计划 (2026-06-19)

长对话压缩后 agent 忘了前面聊什么，这是所有大模型用户的痛。这套版本上了两件事：session_checkpoint 和 session_recover——聊天中间可以存个快照，压缩后也能恢复现场。顺便支持了 --http SSE 模式，给那些不走 stdio 的 MCP 客户端一条路。MCP 工具的搜索结果现在也带相似度评分了，匹配度一眼睛看出来。

v1.2.0 — 初次见面 (2026-06-14)

第一个正经版本。核心想法很简单：你的 agent 不该每次都从零开始认识你。heropen install 交互式向导帮你三步配好，多个 agent 互不串记忆，agent 还能感知距离上次聊了多久。CLI 也重构了，该懒加载的懒加载，启动飞快。

v1.1.0 — 从零到一 (2026-06-10)

最早的念头：给本地 agent 装上长期记忆。MCP 协议接上，数据存本地 SQLite，搜记忆能向量能全文——够用了。虽然还有点糙，但方向定了。