Honcho 记忆基础设施
为长期运行的智能体存储交互、异步推理并提供可查询记忆。
- Star 数
- ★ 8k
- 最近更新
- 今天
- License
- AGPL-3.0
- 主语言
- Python
- FA 评分
- 44/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Claude Code · OpenAI API · Claude API
- 费用
- 有免费版，另有付费云服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 为使用 OpenAI Chat Completions 的辅导产品保存学生与导师的长期对话，并将 session.context(...) 注入下一次模型调用。
- 不适合
- 需要同步即时读取最新消息的应用
- 不愿承担 AGPL-3.0 许可义务的闭源产品团队
- 只想用单一客户端、不想部署数据库与后台 worker 的个人
这个 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？
托管服务：先在 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。
这个 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 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Honcho 记忆基础设施 当前 | 44 · 缺口较多 | 代码库 / SDK免费版 + 付费版 | ★ 8k | 今天 | Python | Claude Code · OpenAI API · Claude API |
| Deuz SDK | 69 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 508 | 20 天前 | TypeScript | OpenAI API · Claude API |
| Hindsight | 46 · 缺口较多 | 自托管服务免费版 + 付费版 | ★ 59k | 今天 | Python | OpenAI API · Claude API |
| Composio | 51 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 31k | 今天 | TypeScript | Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 描述了可配置的认证（AUTH_USE_AUTH）和 JWT 密钥生成，表明有权限控制机制，但未明确最小权限原则；用户确认方面，未发现任何用户确认或同意机制；数据流透明度方面，README 描述了数据存储和推理流程，但未明确数据流向用户；敏感数据处理方面，提及了 API 密钥和 JWT 密钥，但未说明加密或脱敏；依赖安全方面，pyproject.toml 列出了依赖，但未提及安全审计或漏洞扫描；外部影响方面，描述了与外部 LLM 提供商的交互，但未明确副作用；回滚方面，未提及任何回滚机制；来源归属方面，作者信息明确，但发布者未验证。扣分原因：缺少用户确认、回滚机制，敏感数据处理和依赖安全证据不足。
证据显示：README 和 pyproject.toml 中的描述一致，版本号一致（3.0.11），依赖列表完整；依赖可用性方面，列出了所有依赖，但未提供锁定文件或完整性校验；失败消息方面，未发现明确的错误处理或用户友好的错误消息。扣分原因：失败消息证据不足。
证据显示：README 明确了目标受众（开发者、产品团队）和多种使用场景（Claude Code、OpenCode 等）；能力边界方面，描述了存储和推理的分离，但未明确限制；触发精度方面，未明确触发条件或事件；环境适配方面，支持 Docker、本地开发、多种 LLM 提供商。扣分原因：触发精度证据不足。
证据显示：README 结构清晰，有目录和详细章节；安装说明详细，包括 Docker 和本地开发；命名稳定性方面，有版本号但未提及命名约定；示例和 FAQ 方面，有快速入门和集成示例，但无 FAQ；已知限制方面，未明确列出；许可证为 AGPL-3.0，明确；版本变更日志方面，未提供 CHANGELOG；维护责任方面，有贡献指南，但未明确维护者。扣分原因：缺少 FAQ、已知限制、CHANGELOG，维护责任不明确。
证据显示：输出可用性方面，提供了多种查询接口和 SDK，输出格式明确；边际价值方面，提供了记忆基础设施，有独特价值；成本效益方面，未提供性能或成本数据。扣分原因：成本效益证据不足。
证据显示：README 中引用了外部资源（evals 页面、博客），但未提供具体数据；交叉来源验证方面，有多个集成示例，但未独立验证；事实与推断分离方面，README 中区分了描述和营销声明，但未明确标注。扣分原因：外部引用未提供具体数据，交叉验证不足。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 发布者身份未验证，需谨慎对待供应链风险。
- 缺少用户确认和回滚机制，可能影响数据操作的可逆性。
- 依赖安全未明确，建议检查依赖漏洞。
- README 中的营销声明（如 Pareto Frontier）缺乏可验证数据。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Added - The workspace session list can report and filter by scope membership. ?include_scopes=true gives each session a scopes list of the scopes it is in ([] for none), fetched in one query per page; without it the response is unchanged. Body scope lists only that scope's sessions (404 if the scope doesn't exist) and in_no_scope: true lists only sessions in no scope; both combine with filters and pagination, and total counts the filtered result. Clients no longer need to list every scope's members to show which scopes a session is in (#1477) …在 GitHub 查看 ↗ -
发布说明摘录
Security - The Docker image ships certifi 2026.10.19, up from 2026.4.22, so outbound TLS from the API and the deriver (LLM providers, embeddings, webhooks) verifies against the current CA bundle. The build's uv moves from 0.9.24 to 0.13.5. Self-hosted deployments that install from uv.lock need uv 0.13.5 or newer: older uv ignores the lockfile's per-package exclude-newer override for certifi and resolves an older bundle (#1439) Fixed …在 GitHub 查看 ↗ -
发布说明摘录
Added - Workspace, peer and session responses carry uid, the immutable identifier Honcho assigns (the row's internal id). id is unchanged and stays the client-chosen name, so clients can start storing uid as a reference that won't move if names become renameable. Every route that returns these objects includes it: get-or-create, list, update, clone, session peers, peer sessions and scope sessions. Additive, no migration (#1394) …在 GitHub 查看 ↗