honcho-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Honcho as Memory

将Honcho用作记忆层

Honcho is a memory layer for agents. You feed it the messages from your conversations; in the background it reasons over them and builds a representation of each participant. At any point you can ask it natural-language questions about the user ("How technical are they?", "What are they trying to do?") and get grounded, reasoned answers.

This skill is for when Honcho is already connected to you and you want to use it. If you're instead adding Honcho to a codebase from scratch, use the

honcho-integration

skill.

What's durable vs. what to look up. The concepts and the recall/record loop below change rarely — rely on them. Specifics that change often — the exact set of integrations, tool names, install commands, headers, and defaults — are illustrative here; treat the linked docs (and your own live tool list) as authoritative and fetch them when the details matter.

Honcho是面向Agent的记忆层。你可以将对话中的消息提供给它；它会在后台对这些消息进行推理，为每个参与者构建一份特征描述。你随时可以用自然语言询问关于用户的问题（比如“他们的技术水平如何？”、“他们想要实现什么目标？”），并得到基于事实的推理回答。

本技能适用于Honcho已完成连接的场景，帮助你使用其功能。如果你是从零开始将Honcho添加到代码库中，请使用

honcho-integration

技能。

持久化内容与需查询内容的区别。下文介绍的概念和回忆/记录循环很少变动——可以放心依赖。而经常变动的细节（比如具体的集成列表、工具名称、安装命令、请求头和默认值）仅作示例；当需要这些细节时，请以链接文档（以及你自己的实时工具列表）为准。

The mental model

核心模型

Peer — any participant, human or AI. You and the user are both peers. Honcho builds a representation of peers it observes (typically the user, not you).
Session — one conversation thread; messages live in sessions. Honcho reasons over the messages in a session together, so scope each session to one coherent context (a conversation, channel, task, or project) and keep that context's turns in the same session rather than fragmenting them across many thin ones. For low-volume or trickle inputs, append to one ongoing session rather than spinning up a new one each time. See design patterns and reasoning.
Message — the raw turns you feed in. No messages → no reasoning → no memory.
Conclusion — a fact Honcho derived (or you stored) about a peer. Conclusions power the representation.
Representation / peer card — the synthesized understanding of a peer, queryable via
```
chat
```
. A peer's representation accumulates across every session it appears in — that's the cross-conversation memory. Session-scoped data (recent messages, summaries) stays local to one session.

Reasoning happens asynchronously. After you record a turn, don't poll or wait — the representation updates in the background and is richer next time you ask.

Peer（对等体） — 任何参与者，可以是人类或AI。你和用户都是对等体。Honcho会为它观察到的对等体（通常是用户，而非你）构建一份特征描述。
Session（会话） — 单个对话线程；消息存储在会话中。Honcho会针对同一会话中的消息进行协同推理，因此每个会话应限定在一个连贯的上下文（一次对话、一个频道、一项任务或一个项目）中，并将该上下文的所有对话轮次保留在同一会话中，而非分散到多个零散会话中。对于低频次或零散输入，应追加到一个持续的会话中，而非每次都创建新会话。详见设计模式和推理机制。
Message（消息） — 你输入的原始对话轮次。没有消息就没有推理，也就没有记忆。
Conclusion（结论） — Honcho推导（或你存储）的关于对等体的事实。结论是特征描述的核心支撑。
Representation / peer card（特征描述/对等体卡片） — 对某个对等体的综合理解，可通过
```
chat
```
接口查询。对等体的特征描述会在其参与的所有会话中累积——这就是跨会话记忆。会话范围的数据（近期消息、摘要）仅保留在单个会话中。

推理过程是异步进行的。在你记录一轮对话后，无需轮询或等待——特征描述会在后台更新，下次你查询时会更丰富。

The loop: recall → respond → record

循环流程：回忆 → 响应 → 记录

Do this every conversation. It's the whole skill.

Once per conversation — make sure there's a session with you and the user as peers (observe the user, don't observe yourself).
Before responding, when personalization helps — pull the user's current context (
```
get_session_context
```
/
```
get_representation
```
) or search past messages (
```
search
```
) — these are fast reads. For a reasoned answer to a specific question, ask the dialectic (
```
chat
```
) — that one takes a few seconds, so use it when it earns its keep.
After every exchange — record both the user's message and your reply. This is what makes Honcho learn. Don't skip it.

Optionally, when you learn a durable fact you don't want to wait for background reasoning to surface, store a conclusion directly.

每次对话都遵循此流程，这是本技能的核心内容。

每次对话开始时 — 确保存在一个包含你和用户作为对等体的会话（观察用户，不要观察你自己）。
在需要个性化响应前 — 获取用户的当前上下文（
```
get_session_context
```
/
```
get_representation
```
）或搜索过往消息（
```
search
```
）——这些都是快速读取操作。如果需要针对特定问题的推理回答，请使用辩证查询（
```
chat
```
）——此操作需要几秒时间，因此仅在必要时使用。
每次对话交互后 — 记录用户的消息和你的回复。这是Honcho实现学习的关键步骤，请勿跳过。

可选操作：当你了解到一个无需等待后台推理即可直接使用的持久化事实时，可以直接存储结论。

What you get back when you recall

回忆操作的返回内容

Three ways to pull memory, cheapest first:

Representation (
```
get_representation
```
) — Honcho's synthesized understanding of the user as text, ready to drop straight into a system prompt. Near-instant read.
Context (
```
get_session_context
```
) — the fuller session view: a session summary + recent messages covering the conversation, and — only if you target a peer — that peer's representation folded in. Without a peer target it's session-local (recent turns + summary) and carries no cross-conversation memory. Near-instant read.
Dialectic (
```
chat
```
) — a reasoned natural-language answer to a specific question ("How does this user like to receive feedback?"). Runs live reasoning, so it takes a few seconds. Use it when a plain read won't answer the question.

The dialectic (

chat

) also takes a reasoning level that trades speed for depth — from

minimal

(fast factual lookup) through

low

(the default balance) to

max

(deep synthesis for the hardest questions). Pick the lowest level that answers the question; higher levels are slower and cost more. The full level-by-level table and model routing are in the chat docs.

有三种获取记忆的方式，按成本从低到高排列：

特征描述（
```
get_representation
```
）—— Honcho生成的用户综合理解文本，可直接放入系统提示词中。读取速度近乎即时。
上下文（
```
get_session_context
```
）—— 更完整的会话视图：会话摘要 + 涵盖对话内容的近期消息；如果指定了对等体，还会包含该对等体的特征描述。如果未指定对等体，则仅包含会话本地数据（近期轮次 + 摘要），不包含跨会话记忆。读取速度近乎即时。
辩证查询（
```
chat
```
）—— 针对特定问题的推理式自然语言回答（比如“这位用户希望以何种方式接收反馈？”）。会运行实时推理，因此需要几秒时间。仅当普通读取无法回答问题时使用此方式。

辩证查询（

chat

）还支持设置推理级别，在速度和深度之间进行权衡——从

minimal

（快速事实查询）到

low

（默认平衡级别）再到

max

（针对复杂问题的深度综合）。选择能回答问题的最低级别；级别越高，速度越慢，成本也越高。完整的级别对照表和模型路由规则请查看聊天文档。

Pick your access path

选择你的访问方式

The loop is the same; the mechanics depend on how you reach Honcho. Prefer a purpose-built integration over wiring up raw MCP yourself — they handle sessions, peers, and the record loop for you, stay current, and are tuned per environment.

A first-class integration exists for your environment? Use it. In Claude Code, install the Claude Code plugin (
```
/plugin marketplace add plastic-labs/claude-honcho
```
) for persistent memory out of the box; there are also plugins/integrations for OpenCode, LangGraph, CrewAI, Discord, and more. Browse the always-current list: https://honcho.dev/docs/v3/guides/overview.md.
No integration, but you have MCP tools (
```
create_session
```
,
```
add_messages_to_session
```
,
```
chat
```
, …) → drive them with the loop above. The MCP server injects its own usage guide on connect, so there's nothing extra to load; to connect a client yourself, see Setup below. This is the fallback for connected agents.
honcho
CLI available in a terminal → use the honcho-cli
skill — for the recall/record loop, and for verifying that memory is actually building (did messages land? is the representation growing? why doesn't it remember me?).
Embedding Honcho into your own codebase (not just using a connected instance) → use the honcho-integration
skill.

If you're unsure, list your available tools and look for Honcho memory tools (an MCP connection) before falling back to the CLI. Even on the MCP path, the

honcho-cli

skill is the best way to verify the loop is working if memory seems off.

循环流程是一致的，但具体实现取决于你连接Honcho的方式。优先选择专为你的环境打造的集成方案，而非自行搭建原生MCP——这些集成方案会帮你处理会话、对等体和记录循环，保持更新，并针对不同环境进行优化。

你的环境有一流的集成方案？直接使用即可。 在Claude Code中，安装Claude Code插件（
```
/plugin marketplace add plastic-labs/claude-honcho
```
）即可开箱即用实现持久化记忆；此外还有针对OpenCode、LangGraph、CrewAI、Discord等平台的插件/集成方案。查看最新的集成列表：https://honcho.dev/docs/v3/guides/overview.md。
没有集成方案，但你有MCP工具（
```
create_session
```
,
```
add_messages_to_session
```
,
```
chat
```
等）→ 按照上述循环流程使用这些工具。MCP服务器在连接时会自动注入使用指南，无需额外加载；若要自行连接客户端，请查看下文的设置部分。这是已连接Agent的备用方案。
终端中可使用
honcho
CLI → 使用**
```
honcho-cli
```
**技能——用于执行回忆/记录循环，以及验证记忆是否正常构建（消息是否已存储？特征描述是否在增长？为何无法记住我？）。
将Honcho嵌入你自己的代码库（而非仅使用已连接的实例）→ 使用**
```
honcho-integration
```
**技能。

如果你不确定该选择哪种方式，请先列出你可用的工具，寻找Honcho记忆工具（MCP连接），然后再考虑使用CLI。即使使用MCP方式，当记忆出现异常时，

honcho-cli

技能也是验证循环流程是否正常工作的最佳方式。

Setup (if not connected yet)

设置（若尚未连接）

You need a Honcho API key — get one free at https://app.honcho.dev (starts with

hch-

). Then connect via the path you picked above — a purpose-built integration (recommended), or a raw connection:

MCP — point your client at
```
https://mcp.honcho.dev
```
with
```
Authorization: Bearer hch-your-key-here
```
. Optional
```
X-Honcho-Workspace-ID
```
fills the
```
workspace_id
```
tool argument when omitted; otherwise pass
```
workspace_id
```
on each call (use
```
list_workspaces
```
to discover IDs). Restart the client fully after adding config. Per-client config snippets (Claude Desktop, Cursor, Codex, Windsurf, VS Code, Cline, Zed) are in the MCP integration guide. Once connected, the server tells your assistant how to use the tools automatically.
CLI — use the
```
honcho-cli
```
skill.

你需要一个Honcho API密钥——可在https://app.honcho.dev免费获取（以

hch-

开头）。然后通过你选择的方式进行连接：优先选择专为你的环境打造的集成方案，或使用原生连接：

MCP — 将客户端指向
```
https://mcp.honcho.dev
```
，并设置请求头
```
Authorization: Bearer hch-your-key-here
```
。可选请求头
```
X-Honcho-Workspace-ID
```
可在省略
```
workspace_id
```
工具参数时自动填充；否则请在每次调用时传入
```
workspace_id
```
（使用
```
list_workspaces
```
工具查看可用ID）。添加配置后请完全重启客户端。针对不同客户端的配置示例（Claude Desktop、Cursor、Codex、Windsurf、VS Code、Cline、Zed）请查看MCP集成指南。连接完成后，服务器会自动告诉助手如何使用这些工具。
CLI — 使用
```
honcho-cli
```
技能。

Rules of thumb

经验法则

Always record turns. Memory only grows from messages you feed in. Recording is the one non-optional step.
Modeling the assistant is optional. Setting
```
observe_me: false
```
on the assistant peer skips building a model of it — required only for deterministic bots (scripted output, nothing meaningful to model). For an AI assistant it's fine to leave observation on if you also want a model of the agent.
One stable peer ID per entity. Reuse the same
```
peer_id
```
for a person across every session and channel; splitting them (
```
user
```
,
```
user-web
```
,
```
user-discord
```
) builds separate representations and fragments memory.
Scope sessions to coherent context buckets. Honcho reasons over a session's messages together. Scope a session to one active interaction (per-conversation, per-channel, per-task, per-project); create a new one when context genuinely resets (new topic, new day), reuse it while context should keep accumulating. Keeping a context's turns in one session produces a coherent representation; scattering them fragments it.
Don't block on reasoning. It's asynchronous. Respond now; the representation will be richer next time.
Reads are cheap; reasoning isn't. Fetching the representation/context (
```
get_session_context
```
,
```
get_representation
```
,
```
search
```
) is a near-instant read — use it freely. The dialectic (
```
chat
```
) runs live reasoning and takes a few seconds, so save it for when you genuinely need a reasoned answer, not every turn.
Check before you store. Background reasoning derives most conclusions automatically. Store a conclusion manually only for a durable fact you want available immediately;
```
list
```
/
```
query
```
first to avoid duplicates.
One workspace per app/user-context. Don't scatter the same user's memory across multiple workspaces.
Unify memory across tools with a shared workspace + peer ID. To give one user continuous memory across several apps or agents (e.g. Claude Code, Cursor, your own app), point them at the same workspace and reuse the same peer ID — that shared ID is what links the representation. See Unified Memory Setup.

始终记录对话轮次。记忆只会从你输入的消息中增长。记录是唯一不可省略的步骤。
是否为助手建模可选。在助手对等体上设置
```
observe_me: false
```
可跳过为其构建模型——仅适用于确定性机器人（输出为脚本化内容，没有有意义的模型可构建）。对于AI助手，如果需要为Agent构建模型，可以保持观察开启。
每个实体使用一个稳定的peer ID。在所有会话和频道中为同一个人复用相同的
```
peer_id
```
；如果拆分使用（比如
```
user
```
、
```
user-web
```
、
```
user-discord
```
），会构建出多个独立的特征描述，导致记忆碎片化。
将会话限定在连贯的上下文范围内。Honcho会针对同一会话中的消息进行协同推理。将会话限定在一个活跃的交互场景中（每次对话、每个频道、每项任务、每个项目）；当上下文真正重置时（新主题、新的一天）创建新会话，在上下文需要持续累积时复用现有会话。将同一上下文的对话轮次保留在同一会话中会生成连贯的特征描述；分散存储则会导致特征描述碎片化。
不要等待推理完成。推理是异步进行的。立即响应即可；下次查询时特征描述会更丰富。
读取操作成本低；推理操作成本高。获取特征描述/上下文（
```
get_session_context
```
、
```
get_representation
```
、
```
search
```
）是近乎即时的读取操作——可随意使用。辩证查询（
```
chat
```
）会运行实时推理，需要几秒时间，因此仅在真正需要推理回答时使用，而非每次对话轮次都使用。
存储前先检查。后台推理会自动推导大多数结论。仅当你需要立即使用某个持久化事实时，才手动存储结论；存储前先使用
```
list
```
/
```
query
```
工具查询，避免重复。
每个应用/用户上下文使用一个工作区。不要将同一用户的记忆分散到多个工作区中。
通过共享工作区+peer ID实现跨工具的统一记忆。要让同一用户在多个应用或Agent（比如Claude Code、Cursor、你自己的应用）中拥有连续记忆，请将它们指向同一个工作区，并复用相同的peer ID——这个共享ID是关联特征描述的关键。详见统一记忆设置。

Resources

资源

These are the LLM-friendly Markdown versions (append

.md

to any Honcho docs URL to get the raw Markdown; the full machine-readable index is at https://honcho.dev/docs/llms.txt).

Full docs index (for agents): https://honcho.dev/docs/llms.txt
All integrations & plugins: https://honcho.dev/docs/v3/guides/overview.md
MCP server & client setup: https://honcho.dev/docs/v3/guides/integrations/mcp.md
Full MCP usage walkthrough: https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md
Agent development overview: https://honcho.dev/docs/v3/documentation/introduction/vibecoding.md
CLI reference: https://honcho.dev/docs/v3/documentation/reference/cli.md

以下是适合LLM读取的Markdown版本（在任何Honcho文档URL后追加

.md

即可获取原始Markdown；完整的机器可读索引位于https://honcho.dev/docs/llms.txt）。

完整文档索引（面向Agent）：https://honcho.dev/docs/llms.txt
所有集成与插件：https://honcho.dev/docs/v3/guides/overview.md
MCP服务器与客户端设置：https://honcho.dev/docs/v3/guides/integrations/mcp.md
MCP完整使用指南：https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md
Agent开发概述：https://honcho.dev/docs/v3/documentation/introduction/vibecoding.md
CLI参考文档：https://honcho.dev/docs/v3/documentation/reference/cli.md