HeroPen Documentation - Installation, Configuration, API Reference

Installation

Requires Python 3.10+ on any operating system (Windows / macOS / Linux).

pip install heropen

Optional dependencies:

pip install heropen[all]   # Includes MCP, vector embeddings, Rich terminal UI

pip install heropen[ui]    # Rich terminal UI only
pip install heropen[embedding]  # Vector embedding support only

💡 Recommended: Install the base package pip install heropen first, then add heropen[embedding] when you need vector search.

Upgrade

pip install --upgrade heropen

Check current version:

heropen --version

Quick Start

1. Install

pip install heropen

2. One-Click Setup

heropen auto-setup

Auto-detects installed agents (Cursor, Cline, Claude Code, etc.) and writes MCP configuration.

3. Restart Agent

Close and reopen your agent tool — it will be able to call HeroPen.

4. Try Saving a Memory

heropen add "Project uses Python + SQLite, testing with pytest"

5. Search

heropen search "project tech stack"

🎯 Ultimate Verification: Ask your agent "How many memories does heropen have? Check it." If it answers, you're all set.

Command Reference

heropen

Display help information and available commands.

heropen --help

heropen setup

Interactive initialization. Choose agent name, working mode, and generate configuration file.

heropen setup

heropen install

Interactive installation wizard. Scans installed agent tools, selects edition, and writes configuration.

heropen install

heropen auto-setup

One-click automatic configuration (recommended). Auto-detects Cursor / Cline / Claude Code / Windsurf config paths and injects MCP configuration.

heropen auto-setup

heropen mcp

Start MCP server (stdin/stdout mode). Allows agents to call HeroPen tools via the MCP protocol.

heropen mcp           # stdio mode (default)
heropen-mcp --http    # HTTP SSE mode, listening on 0.0.0.0:8090

heropen status

Display HeroPen runtime status: memory count, agent list, database health.

heropen status

heropen add

Add a memory entry.

heropen add "Remember to use FastAPI for backend, SQLAlchemy for database"

heropen search

Search memories. Supports vector semantic search, full-text search, and fuzzy matching (auto fallback).

heropen search "FastAPI"
heropen search "database" --limit 10

heropen --version

Check current version number.

heropen --version

MCP Integration

Model Context Protocol (MCP) is the standard protocol for agent tool calls. HeroPen uses MCP to let agents search, add, and update memories directly within their conversations.

Standard MCP Configuration

Universal for all agents. Add the following to the corresponding MCP configuration file:

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

Configuration Paths by Agent

WorkBuddy

C:\Users\your-username\.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, or edit
~/.cursor/mcp.json (macOS/Linux) or C:\Users\your-username\.cursor\mcp.json

Claude Code CLI

.claude/settings.json (project root)

Cherry Studio

Settings → MCP Client → Add, command set to heropen, args set to mcp.

Continue.dev

~/.continue/config.json (MCP config goes under the experimental.mcpServers field)

⚠️ You must restart the agent after modifying configuration. Don't just close the window — fully exit the process and reopen.

MCP Tool Reference

Once an agent connects to HeroPen MCP, the following tools become available. These are used automatically by the agent — no manual intervention needed.

Tool	Description	Parameters
search_memory	Search memories (vector → FTS → fuzzy, three-layer auto fallback)	`query`, `limit`, `agent`, `date_from`, `date_to`
add_memory	Add a new memory entry	`section`, `content`, `tags`, `agent`
update_memory	Update an existing memory (only modifies provided fields)	`entry_id`, `section`, `content`, `tags`, `status`
list_memory	List recently added memories	`limit`, `agent`
health	Check service status, returns memory counts per agent	—
session_checkpoint	Save current session snapshot (prevents context loss in long conversations)	`agent`, `context_summary`, `active_task`, `key_decisions`
session_recover	Recover the most recent session snapshot	`agent`, `limit`

💡 Each agent has its own independent memory space. The default agent name is xiaoman. You can switch to another agent using the agent parameter.

FAQ

MCP error -32000: Connection closed

MCP communication connection interrupted. The most common causes are invalid JSON configuration format or an outdated heropen version. First upgrade: pip install --upgrade heropen, then check if the JSON is valid.

heropen command not found

Python might not be in your PATH. Use the full command: python -m heropen mcp. In the MCP configuration, change "command": "heropen" to "command": "python" and "args": ["-m", "heropen", "mcp"].

Configuration changed but not taking effect

Make sure to fully close the agent (not just the window), then reopen it. Some agents cache MCP configuration and need a complete process restart.

JSON configuration error on Windows

Make sure the file is saved as UTF-8 encoding (without BOM). Notepad adds a BOM by default — use VS Code or Notepad++ to save as "UTF-8 without BOM" format.

Where is data stored? Does it need internet?

Data is 100% local — no internet, no cloud. The SQLite database file is located at ~/.heropen/ (macOS/Linux) or C:\Users\your-username\.heropen\ (Windows). Vector search also runs locally — no external API calls.

Is the free version enough?

The free version includes the complete core functionality — nothing is stripped out. It supports 2 independent agent memory banks, unlimited memory entries, three-layer search (vector + full-text + fuzzy), and the MCP protocol. For 90% of individual users, the free version is sufficient.

How to uninstall?

pip uninstall heropen
rm -rf ~/.heropen  # Optional, removes all data

Changelog

v1.4.3 — The last piece of June (2026-06-21)

A Windows user told me it installed but wouldn't run. Tracked it down to a path parsing issue — fixed. Also gave the startup a self-healing layer: even if an agent's memory file gets corrupted somehow, it'll fix itself on boot and pretend nothing happened.

v1.4.0 — The obsession with "just works" (2026-06-21)

Someone told me "pip install is easy, but I don't know how to set it up after." That one stung. That's where auto-setup came from — run it once, it digs through your Cursor, Cline, Claude Code, Windsurf config files, writes what needs writing, and you just restart your agent. Also made the base package lighter: no more forcing the mcp library on everyone who just wants the CLI.

v1.3.1 — If it's searchable, it counts (2026-06-20)

I once searched for something I'd written down. Vector search missed it. Returned empty. I thought — that's not okay. Users don't care if your vector index failed or your model wasn't loaded. If they wrote it down, it needs to be findable. So we added a three-layer fallback: vector fails → full-text search → fuzzy LIKE. If it was recorded, one of them will find it.

v1.3.0 — Anti-amnesia protocol (2026-06-19)

Long conversations get compressed, and the agent forgets what you were talking about. Every LLM user knows this pain. This release shipped two tools: session_checkpoint and session_recover — save a snapshot mid-conversation, restore it after compression. Also added --http SSE mode for MCP clients that don't do stdio. Search results now show similarity scores too — you can tell at a glance how close the match is.

v1.2.0 — First real date (2026-06-14)

The first proper release. Core idea: your agent shouldn't have to meet you from scratch every single time. heropen install walks you through setup in three steps, multiple agents keep their memories separate, and agents can sense how long it's been since your last chat. Rebuilt the CLI too — lazy loading for that instant startup feel.

v1.1.0 — Zero to one (2026-06-10)

The original itch: give local agents long-term memory. Hook it up via MCP, store everything in local SQLite, search by vector or by full-text. Good enough to be useful. A bit rough around the edges, but the direction was set.