Honcho 记忆基础设施
为长期运行的智能体存储交互、异步推理并提供可查询记忆。
这个 Agent 能做什么，适合哪些场景？
Honcho 是用于构建有状态智能体的记忆基础设施，核心服务以 FastAPI 服务器实现，并提供 Python 与 TypeScript SDK。它以 workspace、peer、session 和 message 组织数据：会话消息可由人类或 AI peer 发送，peer 与 session 为多对多关系。消息写入后，后台 deriver 进程异步生成表示、会话摘要、Peer Card 和结论，并通过 Chat Endpoint、representation、context 与 search 接口返回结果。开发者可使用托管的 api.honcho.dev，也可在本地或 Docker 环境中自托管完整服务。其适用边界是为现有模型调用或智能体框架补充记忆与上下文，不是一个自行执行任务的智能体运行时。
应用通过 Honcho SDK 创建或取得 peer 与 session，再调用 session.add_messages(...) 写入对话、事件、文档或工具轨迹。服务将推理任务放入按 session 排序的后台队列，deriver 处理 representation 和 summary 等任务，并将洞见经 Conclusions API、Peer Cards、representation 与 POST /peers/{peer_id}/chat 暴露。读取时，可调用 peer.chat(...) 获取基于推理的自然语言回答，调用 session.context(summary=True, tokens=10_000) 取得可转换为 OpenAI 或 Anthropic 消息格式的上下文，或用 peer.search(...)、session.search(...)、honcho.search(...) 执行 BM25 与向量混合搜索。文档可通过 session.upload_file(...) 导入，honcho.queue_status(...) 可检查后台处理状态。
- 为使用 OpenAI Chat Completions 的辅导产品保存学生与导师的长期对话，并将 session.context(...) 注入下一次模型调用。
- 为 Claude Code 使用者通过 Honcho 插件或 HTTP MCP 配置提供跨编码会话的持久记忆。
- 为多人协作型应用建立 workspace，在同一 session 中记录人类与 AI peer 的消息，并按观察关系建模 peer 对另一 peer 的认知。
- 为需要低延迟提示词补充的应用调用 peer.representation(...) 或 session.representation(...)，避免等待 Chat Endpoint 的模型响应。
- 为需要回溯历史互动的产品在 peer、session 或 workspace 范围执行混合搜索，并用过滤条件缩小结果。
- 为自托管团队在 PostgreSQL 与 pgvector 上部署服务，控制工作区数据隔离和运行配置。
这个 Agent 有哪些优点和局限？
- 以 peer 为核心统一表示人类与 AI 参与者，并支持按 observer/observed peer 对建立跨 peer 认知。
- 将同步存储与异步 Insights 管线分离，消息写入后可生成表示、摘要、结论和 Peer Card。
- 同时提供 Chat Endpoint、低延迟 representation、提示词上下文与 BM25 加向量的混合搜索，覆盖多种读取方式。
- 提供 Python、TypeScript SDK 和 HTTP MCP 接入，并明确支持 Claude Code、OpenCode、OpenClaw 与 Hermes 集成。
- 可选择托管 API 或在 FastAPI、PostgreSQL/pgvector 与 Docker 环境中自托管。
- 推理在后台异步运行；新写入的消息可能不会立刻反映在 chat 或 representation 响应中。
- 自托管除数据库外还必须持续运行 API 服务与 deriver 后台进程，并配置多个 LLM 提供商密钥。
- 本地开发依赖 Python 3.10+、uv 0.5.0+、PostgreSQL 和 pgvector，部署复杂度高于纯 SDK 服务。
- 仓库采用 AGPL-3.0，采用前需要评估与自身分发和部署模式的许可兼容性。
- README 未提供托管服务的完整定价说明；仅说明注册组织可获得 100 美元免费额度。
如何安装或部署这个 Agent？
托管服务：先在 app.honcho.dev 获取 HONCHO_API_KEY，然后执行 pip install honcho-ai，或执行 npm install @honcho-ai/sdk。Python 最小示例：from honcho import Honcho; honcho = Honcho(workspace_id="my-app-testing", api_key=os.environ["HONCHO_API_KEY"])。自托管：git clone https://github.com/plastic-labs/honcho.git && cd honcho && cp docker-compose.yml.example docker-compose.yml && cp .env.template .env，然后在 .env 配置 DB_CONNECTION_URI 与 LLM_GEMINI_API_KEY、LLM_ANTHROPIC_API_KEY、LLM_OPENAI_API_KEY，最后运行 docker compose up。无需 Docker 的开发环境要求 Python 3.10+、uv 0.5.0+ 和带 pgvector 的 PostgreSQL；运行 uv sync、uv run alembic upgrade head、uv run fastapi dev src/main.py，并在另一终端运行 uv run python -m src.deriver。
如何使用这个 Agent？
创建 workspace 对应的客户端后，调用 alice = honcho.peer("alice")、tutor = honcho.peer("tutor")、session = honcho.session("session-1")，再以 session.add_messages([alice.message("..."), tutor.message("...")]) 写入消息。后台推理完成后，使用 alice.chat("What learning styles does the user respond to best?") 查询洞见，或用 session.context(summary=True, tokens=10_000) 取得提示词上下文；该上下文可经 context.to_openai(assistant=tutor) 传给 OpenAI，或转换为 Anthropic 格式。自托管 SDK 需要将 base_url 设为 http://localhost:8000，或设置 HONCHO_URL。