当前位置：首页 > news >正文

Honcho开源智能体记忆库：构建有状态AI的长期记忆与状态管理

news 2026/5/2 21:17:20

1. 项目概述：构建有状态的智能体，从记忆开始

如果你正在开发基于大语言模型的智能体应用，无论是客服助手、个性化导师还是游戏NPC，一个核心的挑战很快就会浮现：如何让智能体“记住”用户？不是简单地记住上一条消息，而是记住用户的偏好、习惯、历史对话的上下文，甚至是在长期互动中形成的“性格”认知。这就是所谓的“状态管理”或“长期记忆”问题。没有它，每次对话都像是与一个失忆的陌生人重新开始，体验割裂，更谈不上真正的个性化。

市面上有不少方案试图解决这个问题，比如在提示词里硬塞历史对话，或者用向量数据库做简单的相似性检索。但前者受限于上下文长度，后者则缺乏深度的推理和归纳能力，难以从零散的对话中提炼出稳定、可用的“用户画像”。今天要聊的Honcho，就是冲着这个痛点来的。它是一个开源的、专为智能体设计的记忆库及托管服务，其核心目标是为你的AI应用提供一个持续学习、深度理解实体的记忆系统。这里的“实体”可以是用户、其他智能体、群组，甚至是一个抽象的概念。

我花了一段时间深入研究了Honcho的架构和源码，也在自己的几个实验性项目里做了集成。我的体会是，它不仅仅是一个存储聊天记录的数据库，更是一个“记忆推理引擎”。它通过后台的异步处理管道，持续分析对话，自动为每个“对等体”（Peer）生成并更新其“表征”，从而让智能体能够基于对用户的长期、动态的理解来做出响应。接下来，我会拆解它的设计哲学、核心概念，并分享从零部署到实际集成的完整实操经验，包括我踩过的一些坑和优化技巧。

2. 核心概念与架构拆解：为什么是“对等体”？

要理解Honcho，首先要抛弃传统的“用户-助手”二元论。Honcho引入了一个称为“对等体”的核心范式。在这个模型里，无论是人类用户还是AI智能体，都被统一抽象为Peer。这是一个非常巧妙的设计，它带来了几个关键优势：

1. 支持复杂的多参与者会话：一个会话（Session）可以包含多个对等体。想象一个群聊场景，里面有多个用户和多个AI助手参与讨论。Honcho可以清晰地建模谁对谁说了什么，并为每个参与者维护独立的视角和记忆。

2. 灵活的观察关系：你可以配置哪些对等体可以“观察”到会话中的哪些消息。例如，一个“教练”AI可能观察所有“学员”的对话，但学员们彼此之间可能看不到对方的私聊。这为构建具有不同权限和视角的复杂多智能体系统提供了基础。

3. 统一的身份管理：无论是处理用户数据还是管理你自己的多个AI助手，都使用同一套API和数据结构，极大简化了系统复杂度。

理解了“对等体”之后，我们来看Honcho的整体数据模型，它主要由以下几个层级构成：

工作区：这是顶级隔离单元。你可以为不同的应用、不同的测试环境创建不同的Workspace，实现数据隔离和多租户支持。
对等体：工作区内的核心实体，代表一个参与者。
会话：对等体之间发生交互的容器。一个对等体可以参与多个会话，一个会话也可以包含多个对等体（多对多关系）。
消息：交互的基本单元，由某个对等体在某个会话中创建。
集合与文档：用于实现RAG功能。每个对等体可以拥有多个Collection，每个集合内包含多个向量化的Document。这不仅可以用于存储用户上传的文件，也被Honcho内部用来存储对等体的“表征”数据。

这种设计使得Honcho既能处理线性的对话记忆，也能处理结构化的知识存储，并将两者通过“对等体”这个核心概念有机联系起来。

3. 本地开发环境搭建与配置详解

官方文档给出了指引，但在实际搭建过程中，有很多细节需要注意。下面是我从零开始，在Linux开发机上部署Honcho服务端的完整过程。

3.1 基础环境与依赖安装

Honcho的核心服务使用Python和FastAPI编写，包管理推荐使用uv，这是一个速度极快的Python包安装器和解析器。

# 1. 确保系统已安装Python 3.10或更高版本 python3 --version # 2. 安装uv（如果尚未安装） curl -LsSf https://astral.sh/uv/install.sh | sh # 安装完成后，重启终端或执行 source ~/.bashrc uv --version # 3. 克隆代码库 git clone https://github.com/plastic-labs/honcho.git cd honcho

3.2 数据库准备：PostgreSQL与pgvector

Honcho使用PostgreSQL作为主数据库，并且依赖pgvector扩展来支持向量运算。这里我选择使用Docker快速拉起一个包含pgvector的PostgreSQL实例。

# 在honcho项目根目录下，复制并启动Docker Compose配置 cp docker-compose.yml.example docker-compose.yml docker compose up -d database

这个命令会启动一个名为honcho-db的PostgreSQL 16容器，并自动创建pgvector扩展。默认用户/密码/数据库均为postgres，端口映射到5432。你可以通过docker compose logs database查看日志确认启动成功。

注意：生产环境强烈建议使用云托管的PostgreSQL服务（如AWS RDS、Supabase等），并确保实例支持pgvector扩展。

3.3 配置管理：环境变量与config.toml

Honcho的配置系统优先级是：环境变量 >.env文件 >config.toml> 默认值。对于本地开发，使用.env文件最方便。

# 复制环境变量模板 cp .env.template .env

接下来编辑.env文件，以下是最低限度的必需配置：

# 数据库连接字符串，注意前缀必须是 postgresql+psycopg DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres # LLM提供商API密钥（至少配置一个用于推理和嵌入） LLM_OPENAI_API_KEY=sk-your-openai-api-key-here # LLM_ANTHROPIC_API_KEY=your-claude-key-here # LLM_GEMINI_API_KEY=your-gemini-key-here # 关闭认证和监控以简化本地开发 AUTH_USE_AUTH=false SENTRY_ENABLED=false

关键点解析：

DB_CONNECTION_URI: 格式必须严格遵循postgresql+psycopg://[user]:[password]@[host]:[port]/[database]。这是SQLAlchemy异步驱动asyncpg的要求。
LLM密钥：Honcho的不同功能模块默认使用不同的LLM提供商。例如，deriver（后台推理引擎）的默认低强度任务使用Gemini，高强度任务使用Claude，而文本嵌入默认使用OpenAI。如果你只配置了OpenAI，需要修改config.toml来调整默认的提供商分配，否则部分功能会因缺少API密钥而失败。一个简单的做法是先在.env中把几个主要提供商的密钥都配齐。
认证：本地开发时，将AUTH_USE_AUTH设为false可以跳过JWT令牌验证，直接调用API，方便测试。

3.4 安装依赖与数据库迁移

使用uv同步依赖并激活虚拟环境：

# 安装项目依赖，uv会自动创建虚拟环境 uv sync # 激活虚拟环境（后续命令都需要在此环境下运行） source .venv/bin/activate

运行数据库迁移，创建所有必要的表：

uv run alembic upgrade head

执行成功后，连接到你的PostgreSQL数据库，应该能看到一系列以honcho_为前缀的表被创建出来，例如honcho_workspaces,honcho_peers,honcho_sessions等。

3.5 启动服务：API服务器与后台Deriver

Honcho服务由两个主要进程组成：

API服务器：提供主要的RESTful API。
Deriver（后台工作器）：异步处理消息，生成对等体表征、会话摘要等。

启动API服务器（开发模式，支持热重载）：

uv run fastapi dev src/main.py

服务器默认会在http://127.0.0.1:8000启动。访问http://127.0.0.1:8000/docs可以看到完整的Swagger API文档。

启动Deriver（在新终端中）：

# 确保在项目根目录，且虚拟环境已激活 source .venv/bin/activate uv run python -m src.deriver

Deriver会开始监听任务队列。当你通过API创建消息后，Deriver会自动处理这些消息，进行推理和表征更新。你可以启动多个Deriver进程来提高处理能力。

4. SDK集成与核心API实战

服务跑起来后，我们通过官方SDK来实际体验一下Honcho的核心功能。这里以Python SDK为例。

4.1 初始化与基础数据操作

首先安装SDK并初始化客户端。

pip install honcho-ai

from honcho import Honcho # 初始化客户端，指向本地服务 honcho = Honcho( base_url="http://127.0.0.1:8000", # 本地服务地址 workspace_id="my-tutor-app", # 你的应用名称，用于数据隔离 api_key="dev-key" # 本地开发时，如果AUTH关闭，可传任意值 ) # 创建两个对等体：学生Alice和AI导师Tutor alice = honcho.peer("alice") tutor = honcho.peer("tutor") # 创建一个会话，并让这两个对等体加入 session = honcho.session("math-homework-session-001") # 在创建会话时关联对等体，或之后通过session.add_peer添加

添加消息到会话中：消息是构建记忆的原材料。添加消息时，需要指定发送者和内容。

# 添加一系列对话消息 session.add_messages([ alice.message("嘿，能帮我看看这道几何题吗？已知三角形ABC..."), tutor.message("当然可以。我们先从勾股定理开始分析..."), alice.message("我算出来斜边是10，但答案说是5√3。"), tutor.message("检查一下你的计算过程，是不是把边长代错了？"), alice.message("啊！我看错了，直角边是5，不是10。所以是5√3，我明白了！"), tutor.message("很好！记住要仔细审题。"), ])

4.2 核心功能体验：从记忆到洞察

单纯存储消息只是第一步，Honcho的强大之处在于其异步推理和便捷的查询能力。

1. 获取会话上下文（解决长上下文问题）：这是最常用的功能之一。LLM的上下文窗口有限，Honcho可以帮你智能地选取与当前对话最相关的历史消息和结论，并自动生成摘要，拼装成一个不超过指定token数的上下文包。

# 获取最近、最相关的上下文，限制在4000 token以内 context = session.context(tokens=4000, summary=True) print(f"本次获取了 {len(context.messages)} 条消息和摘要。") # 转换为OpenAI API所需的格式 openai_messages = context.to_openai(assistant=tutor) # openai_messages 是一个列表，包含system prompt（内含摘要和结论）、历史消息等 # 可以直接用于调用ChatCompletion

2. 使用Chat API进行自然语言查询：你可以像问一个知心朋友一样，用自然语言询问关于某个对等体的任何问题。Honcho会综合所有历史交互，给出推理后的答案。

# 向Honcho提问关于Alice的学习特点 response = alice.chat("这个学生在学习数学时，表现出哪些典型的思维习惯或常见错误？") print(response.content) # 可能的输出："该学生在几何题中容易看错已知条件，特别是在有图形辅助时。但ta在意识到错误后纠正速度很快，说明理解能力不错。倾向于通过具体计算来验证猜想，而非先进行逻辑推导。"

这个功能非常适合用来动态生成个性化的提示词。例如，在AI导师准备回复前，先问一句：“基于Alice最近三次的提问，她现在最可能卡在哪个知识点上？”

3. 语义搜索：在所有历史消息中，快速找到与特定主题相关的对话片段。

# 在Alice的所有消息中搜索与“函数”相关的内容 results = alice.search("三角函数 公式", limit=5) for msg in results: print(f"[{msg.created_at}] {msg.content[:100]}...")

4. 获取对等体表征：表征是Honcho后台为每个对等体生成的、结构化的“人物卡片”，包含其特点、偏好、行为模式等。获取表征的速度很快，适合需要低延迟注入上下文的场景。

# 获取Alice在当前会话背景下的表征文档 representation_doc = session.representation(alice) print(representation_doc.content) # 输出是一段结构化的文本描述，可以直接拼接到你的系统提示词中。

4.3 后台处理机制解析

当你调用session.add_messages()后，消息不仅被存入数据库，还会触发后台的Deriver任务。这个过程是异步的：

任务入队：系统会为这条消息创建一个representation推导任务，放入该会话专属的任务队列。这保证了同一会话内消息的处理顺序。
Deriver处理：后台Deriver进程从队列中取出任务，调用配置的LLM（如Gemini或Claude）对消息进行分析。
更新结论：LLM会分析这条消息是否揭示了关于发送者（Alice）的新信息（例如：“她提到了自己养猫”、“她对快速回复有强烈偏好”）。这些结论会被提炼成简短的陈述句。
存储与向量化：这些结论作为Document存储到该对等体专用的内部Collection中，并被向量化。
表征合成：当需要生成或更新“表征”时，系统会从该集合中检索出最相关、最新的结论，组合成一段连贯的描述。

你可以通过检查数据库中的honcho_peer_documents表，或调用alice.collections()来查看内部集合，观察这个过程的结果。

5. 高级配置与生产部署考量

本地开发顺利后，若想用于生产或深度定制，需要理解其配置系统。

5.1 配置文件深度解析

项目根目录的config.toml.example是一个完整的配置模板。复制并修改它：

cp config.toml.example config.toml

重点需要关注的几个部分：

[llm]节：配置各LLM提供商的API密钥和基础URL。你可以在这里统一设置，优先级低于环境变量。
[deriver]节：控制后台推理引擎的行为。
- provider：指定默认的LLM提供商（如gemini）。
- levels：定义不同推理强度（minimal,low,medium,high,max）分别使用哪个模型。这让你可以为不同重要性的任务分配不同成本的模型。
[dialectic]节：配置Chat API（即Dialectic API）的推理强度等级。等级越高，LLM的思考链越长，答案越精细，但也越慢、越昂贵。
[dream]节：这是Honcho一个很有趣的功能——“梦境”。系统会定期（例如每天）在后台对低活跃度的对等体进行深度分析，尝试发现更深层次、更抽象的模式和洞察。可以在这里配置触发频率和使用的模型。

5.2 生产环境部署要点

1. 数据库：使用高可用的云数据库，并做好连接池配置（在[db]节中设置pool_size和max_overflow）。

2. 启用认证：生产环境必须开启JWT认证。 - 在.env中设置AUTH_USE_AUTH=true。 - 生成一个强密钥：openssl rand -hex 32，并设置为AUTH_JWT_SECRET环境变量。 - SDK调用时，需要使用在Honcho管理界面创建的API Key。

3. 部署Deriver：Deriver是无状态的，可以水平扩展。使用像Celery或Django Q这样的成熟任务队列或许更利于管理，但Honcho目前内置了基于数据库的简单队列。生产环境建议至少运行2-3个Deriver实例，并通过进程管理器（如Supervisor或systemd）管理。

4. 向量存储：默认使用pgvector。对于海量数据，可以评估配置中的[vector_store]节，切换到像turbopuffer或lancedb这样的专用向量数据库。

5. 使用托管服务：如果你不想管理基础设施，可以直接使用Honcho的官方托管服务（app.honcho.dev）。只需将SDK中的base_url改为https://api.honcho.dev，并使用你账户下的API Key即可。这对于快速启动和原型验证非常方便。

6. 常见问题与排查实录

在实际集成和测试中，我遇到了几个典型问题，这里分享排查思路和解决方案。

问题1：Deriver进程报错，提示缺少API密钥。

现象：启动Deriver后，控制台不断输出错误日志，提示LLM provider [gemini] not configured或类似信息。
原因：Deriver默认使用Gemini处理低强度推理任务，但.env中没有配置LLM_GEMINI_API_KEY。
解决：
1. 方案A：在.env中补全所有可能用到的LLM API密钥（OpenAI, Anthropic, Gemini）。
2. 方案B：修改config.toml，将deriver的默认provider和各个level的模型都指向你已配置的提供商（如OpenAI）。
```
[deriver] provider = "openai" [deriver.levels] minimal = {model = "gpt-4o-mini"} # 使用OpenAI模型 low = {model = "gpt-4o-mini"} # ... 其他等级也相应修改
```

问题2：调用peer.chat()接口响应慢或超时。

现象：通过Chat API提问，需要等待十几秒甚至更久才有返回。
原因：Chat API（Dialectic）默认可能使用了较高推理等级（如medium或high），这些等级配置的模型可能较大（如Claude-3 Opus），且思考链长。另外，如果该对等体历史消息很多，检索相关结论也需要时间。
解决：
1. 降低推理等级：调用时指定等级。response = alice.chat("...", level="low")。等级从minimal到max，速度递减，深度递增。
2. 优化检索范围：如果问题只关心近期行为，可以在提问时指明，例如“根据最近一周的对话...”。
3. 检查Deriver积压：如果Deriver处理速度跟不上消息产生速度，会导致结论生成延迟，进而影响Chat API的质量。确保Deriver进程正常运行，且数量足够。

问题3：session.context()返回的token数远少于设定值。

现象：设置了tokens=4000，但返回的上下文消息可能只占用了1000多个token。
原因：session.context()的算法是优先保证“信息密度”和“相关性”。它会从最近的消息开始，结合向量检索到的相关历史消息和结论，并加上自动生成的会话摘要，直到接近token限制。如果历史对话本身相关性分散，或者摘要已经概括了大部分内容，那么它就不会塞入过多的原始消息。
解决：这是设计行为，旨在提供最精炼的上下文。如果你需要更多原始消息，可以尝试：
1. 调高tokens限制。
2. 设置summary=False，不生成摘要，腾出token给原始消息。
3. 手动组合：先通过session.get_messages()获取原始消息，再通过alice.search()获取相关结论，然后自己在应用层做拼接和裁剪。

问题4：如何清理测试数据？

现象：开发过程中产生了大量测试用的对等体和会话，想清空。
解决：Honcho API目前没有提供批量删除工作区的功能。最直接的方式是通过数据库操作（生产环境慎用！）：

-- 连接到你的Honcho数据库后执行 BEGIN; -- 按依赖关系顺序删除，注意这会将整个workspace的数据清空！ DELETE FROM honcho_peer_documents WHERE ...; DELETE FROM honcho_documents WHERE ...; DELETE FROM honcho_messages WHERE ...; DELETE FROM honcho_sessions WHERE ...; DELETE FROM honcho_peers WHERE ...; DELETE FROM honcho_workspaces WHERE workspace_id = 'your-test-workspace-id'; COMMIT;

对于本地开发，更简单的方法是直接删除Docker卷，重建数据库：docker compose down -v && docker compose up -d database，然后重新运行alembic upgrade head。

7. 性能调优与最佳实践

经过一段时间的试用，我总结出一些能让Honcho运行更高效、更经济的实践。

1. 会话生命周期管理：不要无限制地让一个会话增长。对于明确的“任务”或“场景”，在结束后关闭会话（标记为inactive）。这有助于：

提高session.context()的相关性检索精度。
让后台的“梦境”分析更有针对性（针对已关闭的会话进行深度复盘）。
更清晰地管理数据。可以通过session.update(is_active=False)来关闭会话。

2. 消息的元数据利用：创建消息时，可以附加metadata字典。善用这个字段，可以为后续的检索和推理提供强大线索。

session.add_message( alice.message( "我喜欢《三体》这本书。", metadata={"entity_type": "book", "entity_name": "《三体》", "sentiment": "positive"} ) )

未来，你可以通过过滤metadata来搜索，例如：“找出Alice评价为正面的所有书籍”。

3. 控制Deriver的计算成本：Deriver是API调用成本的主要来源。通过config.toml精细控制：

将[deriver.levels]中的minimal和low等级分配给便宜、快速的模型（如GPT-3.5-Turbo, Gemini Flash）。
只为真正重要的会话或高价值用户启用[dream]（深度分析）功能，并降低其运行频率（如cron_expression = "0 2 * * *"表示每天凌晨2点运行）。

4. 监控与观测：启用配置中的[metrics]和[telemetry]，将指标接入Prometheus和Grafana，监控API延迟、Deriver队列长度、LLM调用错误率等关键指标。这对于生产环境至关重要。

5. 混合使用查询方式：

低延迟、高频场景：使用session.representation()获取预计算好的表征，直接拼进提示词。
复杂、深度查询：使用peer.chat()进行自然语言问答，获取LLM推理后的洞察。
基于时间的检索：使用session.get_messages()进行分页的时间线浏览。
基于语义的检索：使用peer.search()进行跨会话的语义搜索。根据不同的业务场景，灵活组合这些接口，以达到最佳效果。

Honcho为AI智能体带来的“记忆”能力，确实是从“玩具”走向“工具”的关键一步。它把复杂的记忆建模、异步推理和高效检索封装成了简单的API，让开发者能更专注于智能体本身的逻辑和交互设计。当然，它目前更偏向于为对话式应用提供长期记忆，对于需要记忆复杂、结构化事件流的场景（例如游戏剧情），可能需要在其基础上进行一些定制开发。不过，其“对等体”范式和可扩展的架构，为这些可能性留出了充足的空间。如果你正在构建一个需要“认人”、“记事”的AI应用，Honcho绝对值得你花时间深入探索一番。

查看全文

http://www.jsqmd.com/news/740344/