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

Zengram：构建多智能体共享记忆中枢，解决AI协作信息孤岛

news 2026/4/28 12:47:58

1. 项目概述：为多智能体系统构建共享记忆中枢

如果你正在构建或使用多个AI智能体——比如让Claude Code帮你写代码，用一些自主智能体处理自动化任务，再通过n8n编排复杂的工作流——那你肯定遇到过这个头疼的问题：每个智能体都像得了“健忘症”，它们各自为战，彼此之间毫无记忆共享。笔记本上Claude刚帮你理清的API设计思路，服务器上跑的自主智能体一无所知；n8n工作流里记录的关键错误日志，开发智能体也无法调取复盘。整个系统就像一群失忆的专家在协同工作，效率大打折扣，重复劳动和上下文断裂成了常态。

Zengram就是为了解决这个核心痛点而生的。它本质上是一个为多智能体系统设计的共享记忆服务。你可以把它想象成一个所有智能体共用的“外部大脑”或“中央知识库”。任何智能体（无论它运行在哪台机器、使用何种框架）都可以通过标准的HTTP API向这个大脑存入记忆（比如一个关键事实、一个状态更新、一个决策理由），也可以从中查询、检索相关的历史信息。这样一来，智能体A的发现，就能立刻成为智能体B和C的已知背景，真正实现了跨进程、跨机器、跨时间的上下文同步。

我最初接触这个项目，是因为在一个生产级别的多智能体自动化系统中，我们被“信息孤岛”问题折磨得不轻。市面上要么是仅支持单机的记忆方案，要么是绑定特定云服务的闭源产品，没有一款能让我们在完全自控的环境下，实现灵活、可靠、高性能的跨智能体记忆共享。Zengram的出现，恰好填补了这个空白。它不仅开源、可自托管，其“类型化记忆”、“双存储引擎”、“多路径融合检索”等设计，更是直指生产环境中的实际需求。接下来，我就结合自己的部署和调优经验，带你深入拆解这个项目的设计精髓、实操要点以及那些官方文档里不会写的“坑”与技巧。

2. 核心架构与设计哲学解析

Zengram的架构并非一蹴而就，其每一个设计选择背后，都对应着解决多智能体协作中的特定难题。理解这些设计哲学，能帮助你在使用和二次开发时做出更合理的决策。

2.1 类型化记忆：不只是存储文本，更是管理知识状态

大多数记忆系统只存储“消息”或“片段”。Zengram则引入了四种核心记忆类型，每种类型都有其独特的语义和生命周期管理策略。这不仅仅是分类，更是对知识状态的精细化管理。

事件：代表不可变的、按时间顺序发生的历史记录。比如“用户于14:30提交了订单”、“智能体B在15:00启动了数据备份任务”。事件一旦写入就无法修改或删除（出于审计考虑），它们构成了系统活动的完整时间线。在实际使用中，我们将所有自动化任务的开始、结束、错误日志都存为事件，便于后期追溯和根因分析。

事实：代表关于世界状态的、可更新的断言。它通过一个唯一的key进行标识，遵循“最后写入获胜”的原则。例如，key为“server-db-connection-string”的事实，其content可以从“jdbc:mysql://old-db:3306”更新为“jdbc:mysql://new-db:3306”。新事实会自动“取代”旧事实，但旧版本仍保留历史记录（可通过API查询）。这对于存储配置信息、当前负责人、项目状态等动态信息极其有用。我们用它来管理微服务的端点地址，任何智能体更新了地址，所有其他智能体查询时得到的都是最新版本。

状态：用于追踪某个实体或过程的当前状况。与事实类似，它也通过key更新，但更强调“瞬时状态”。例如，key为“data-pipeline-job-123”的状态，其content可能是“RUNNING”、“SUCCESS”或“FAILED”。状态通常带有时间戳和可选的过期时间（TTL），过期后自动清理。我们常用状态来监控长时间运行任务的健康度。

决策：记录智能体做出的选择及其背后的推理过程。这不仅是记录结果（“选择了方案A”），更重要的是记录“为什么”（“因为方案A的预估成本比方案B低20%”）。决策记忆对于实现可解释的AI、避免重复踩坑以及后续的优化反思至关重要。在我们的系统中，任何涉及资源分配、代码生成策略选择的环节，都会强制要求智能体写入决策记忆。

实操心得：类型选择指南刚开始容易混淆“事实”和“状态”。一个简单的区分原则是：如果这个信息是描述“某个事物是什么”（如API的端口号、数据库的IP），用事实；如果这个信息是描述“某个事物正在经历什么阶段”（如构建进度、审批流程），用状态。对于“决策”，务必要求智能体在content中同时包含“action”（采取的行动）和“reasoning”（推理链），这将极大提升后续LLM反思和总结的质量。

2.2 双存储引擎设计：向量搜索与关系查询的黄金组合

这是Zengram性能与功能强大的基石。它没有将记忆只丢给一个向量数据库，而是采用了Qdrant + SQLite/PostgreSQL的双引擎架构。

Qdrant（向量存储）：负责基于语义的相似性搜索。当你搜索“如何配置数据库连接池”时，Qdrant能帮你找到内容语义上相关的所有记忆，即使它们没有完全相同的字眼。这解决了基于关键词匹配的局限性，实现了“意图搜索”。

SQLite/PostgreSQL（关系型存储）：负责一切需要精确匹配、关系遍历和复杂过滤的查询。例如：

“给我key为‘prod-api-endpoint’的所有历史事实版本。”
“找出过去一小时内所有类型为‘event’且来源代理是‘monitor-agent’的记忆。”
“通过全文检索（BM25），找出所有提到‘OOM错误’的记忆。”

这种设计带来了巨大优势：单一系统，两种查询能力。你不再需要自己维护一个向量库和一个关系库，再费力地同步两者之间的数据。Zengram在写入时自动同步到两个后端，在查询时并行检索并融合结果。

踩坑记录：生产环境存储选型开发环境用内置的SQLite完全没问题，轻量快捷。但一旦上生产，尤其是记忆量较大（超过10万条）或需要高可用时，强烈建议使用PostgreSQL。原因有三：1) PostgreSQL的全文检索（tsvector）功能比SQLite的FTS5更强大、更稳定；2) 便于做水平扩展和连接池管理；3) 与容器化、云原生环境的集成更成熟。我们在迁移到PostgreSQL后，复杂查询的稳定性提升了不止一个量级。

2.3 多路径融合检索：让相关记忆无所遁形

这是检索准确率高达98.4%的秘密武器。当执行一次搜索时，Zengram并非只走一条路，而是三条路径并发执行：

向量路径：在Qdrant中计算查询语句与记忆内容的余弦相似度，返回最相似的Top-K条结果。
关键词路径：在关系数据库中，利用BM25算法进行全文检索，找出关键词匹配度高的记忆。
实体图路径：如果查询中或上下文里包含已知实体（如“用户Alice”、“订单#123”），系统会在预先构建的实体关系图中进行广度优先搜索，找出与这些实体相关联的所有记忆。

关键在于，这三条路径的结果不是简单拼接，而是通过倒数排名融合算法进行智能融合。简单来说，如果一个记忆条目在向量搜索结果里排第1，在关键词结果里排第3，那么它的最终得分会很高。这种机制能有效提升召回率，确保无论是语义相关、字面匹配还是通过实体关联的记忆，都有机会被检索到，且被多条路径同时认可的“强相关”记忆会排名更靠前。

3. 从零开始的部署与核心配置实战

理解了原理，我们动手把它跑起来。Zengram提供了Docker Compose的一键部署方案，对新手非常友好，但其中几个关键配置项决定了系统的能力和稳定性。

3.1 基础环境部署与验证

首先，把代码拉下来并进入目录：

git clone https://github.com/ZenSystemAI/zengram.git cd zengram

项目根目录下有一个.env.example文件，这是所有配置的入口。复制它并重命名为.env：

cp .env.example .env

现在，打开.env文件进行编辑。以下是我认为最需要关注的几个配置，直接决定了系统能否工作以及工作得怎么样：

# 1. 核心API密钥：这是访问Zengram服务本身的密钥，务必修改为一个强密码。 # 所有智能体SDK或MCP连接都需要使用这个密钥。 BRAIN_API_KEY=your_super_strong_api_key_here_change_immediately # 2. 向量模型提供商：Zengram默认使用OpenAI的text-embedding-3-small来生成向量。 # 你需要一个OpenAI的API Key。 EMBEDDING_PROVIDER=openai OPENAI_API_KEY=sk-your-openai-api-key-here # 3. 数据库选择：默认使用SQLite，适合开发和测试。 # 生产环境建议注释掉SQLite，启用下面的PostgreSQL配置。 DATABASE_PROVIDER=sqlite DATABASE_URL=file:./data/brain.db # 取消注释以下行以使用PostgreSQL # DATABASE_PROVIDER=postgres # DATABASE_URL=postgresql://username:password@postgres-host:5432/zengram # 4. Qdrant向量数据库配置：默认使用容器内的Qdrant。 # 如果已有外部Qdrant集群，可以修改此处。 QDRANT_URL=http://qdrant:6333

配置完成后，使用Docker Compose启动所有服务：

docker compose up -d

这个命令会启动三个核心服务：Zengram主API服务（默认端口8084）、PostgreSQL（如果配置了）和Qdrant。等待几十秒后，可以通过健康检查接口验证服务是否就绪：

curl http://localhost:8084/health

如果返回{"status":"ok"}，恭喜你，服务已经跑起来了。

3.2 写入你的第一条记忆：理解API语义

让我们通过最基础的HTTP API来感受一下记忆的写入。假设我们有一个运维智能体发现生产数据库的主机变了：

curl -X POST http://localhost:8084/memory \ -H "Content-Type: application/json" \ -H "X-Api-Key: your_super_strong_api_key_here_change_immediately" \ -d '{ "type": "fact", "content": "生产数据库的主机已迁移至 db-cluster-prod-002.aws.internal，端口仍为5432。", "source_agent": "ops-monitor-agent", "key": "prod-database-host", "metadata": { "priority": "high", "environment": "production" } }'

这个请求体包含了几个关键字段：

type: 指定为“fact”，因为这是一个可更新的客观信息。
content: 记忆的具体内容。
source_agent:至关重要。这是智能体的唯一标识符。所有后续的“跨智能体简报”功能都依赖于此来区分信息源。请为每个智能体规划一个清晰、唯一的名称。
key: 事实的唯一标识符。其他智能体可以通过这个key来精确获取或更新此事实。
metadata: 可选的扩展字段。你可以在这里存放任何结构化的额外信息，比如优先级、标签、关联的项目ID等。这些信息也可以被搜索和过滤。

执行成功后，你会收到一个JSON响应，包含新创建记忆的id、timestamp等信息。这条记忆现在已经同时存在于Qdrant（用于语义搜索）和SQLite/PostgreSQL（用于按key查询和全文检索）中了。

3.3 适配器集成：让智能体真正“连接”大脑

仅仅有API还不够，我们需要让各种智能体工具能方便地调用它。Zengram的强大之处在于其丰富的适配器生态。

对于Claude Code、Cursor、Windsurf用户（MCP协议）：这是最无缝的集成方式。MCP（Model Context Protocol）允许这些编辑器直接调用外部工具。Zengram提供了一个功能完整的MCP服务器。

你可以通过npm全局安装：npm install -g @zensystemai/zengram-mcp。
然后在编辑器的MCP配置文件中（例如Claude Code的claude_desktop_config.json）添加如下配置：

{ "mcpServers": { "zengram": { "command": "npx", "args": ["-y", "@zensystemai/zengram-mcp"], "env": { "BRAIN_API_URL": "http://localhost:8084", "BRAIN_API_KEY": "your_super_strong_api_key_here_change_immediately" } } } }

配置完成后重启编辑器，你的AI助手就能直接使用brain_search、brain_store等14个工具来读写共享记忆了。

对于Python智能体：使用官方Python SDK是最佳选择。

pip install zengram

from zengram import BrainClient import asyncio async def main(): client = BrainClient( base_url="http://localhost:8084", api_key="your_key" ) # 存储记忆 memory_id = await client.store( type="decision", content="选择使用Redis缓存用户会话，因为其读写延迟低于Memcached，且本项目需要数据结构支持。", source_agent="architect-agent", key="session-cache-selection" ) print(f"Memory stored with ID: {memory_id}") # 搜索记忆 results = await client.search( query="缓存方案选择", limit=5 ) for mem in results.memories: print(f"- {mem.content[:100]}...") asyncio.run(main())

对于Shell脚本或Cron任务：项目提供了一个Bash CLI适配器（adapters/bash/brain.sh），你可以将其加入PATH，之后就能在命令行中直接操作记忆：

# 存储一个事件 ./brain.sh store --type event --content "每日数据备份于03:00开始执行" --source-agent "cron-backup" # 获取一个简报（某个智能体离开后发生的所有相关事情） ./brain.sh briefing --for-agent "claude-code" --last-hours 24

注意事项：API密钥与权限隔离在生产环境中，切勿让所有智能体使用同一个BRAIN_API_KEY。Zengram支持agent-scoped API keys（虽然当前版本主API仍用同一个，但可通过网关或未来版本实现）。一个临时的安全实践是，在调用API的客户端（如你的Python智能体脚本）层面，在请求头中添加X-Source-Agent来标识自己，并在服务端日志中审计该字段。真正的细粒度密钥管理可以结合API网关（如Kong, Tyk）来实现，为每个source_agent颁发不同的令牌。

4. 高级特性与生产环境运维指南

当系统跑起来，并且有了一定量的记忆数据后，以下几个高级功能和管理操作将变得至关重要。

4.1 实体提取与图谱构建：从文本到知识网络

Zengram不止于存储文本，它能自动从文本中提取实体（如人名、项目名、服务器名、错误代码），并构建它们之间的关系图谱。这个功能是默认开启的。

它是如何工作的？

写入时实时提取：每当一条记忆被存入时，系统会先用一组预定义的正则表达式（如匹配邮箱、版本号、JIRA任务号）和别名缓存进行快速实体提取。
后台LLM精炼：一个低优先级的后台进程（“合并器”）会定期运行，使用LLM对近期记忆进行深度分析，识别更复杂的实体（如“微服务A与数据库B之间的耦合问题”），并合并重复的实体指代（如“小张”、“Zhang San”、“张工”可能指向同一人）。
图谱查询：你可以通过/entities端点或brain_entitiesMCP工具，查询某个实体（如“项目Alpha”）关联的所有记忆，或者可视化实体之间的关系网络。这对于事故排查（找到所有涉及“服务器S-101”的错误）或知识梳理（某位同事参与的所有项目）非常有用。

4.2 LLM驱动的记忆合并与反思

这是防止记忆库变成“垃圾场”的核心机制。随着时间推移，记忆库中会出现大量重复、矛盾或碎片化的信息。Zengram的consolidate（合并）功能就是来解决这个问题的。

你可以手动触发，也可以配置为定时任务：

curl -X POST http://localhost:8084/consolidate \ -H "X-Api-Key: YOUR_KEY"

这个过程会：

去重：识别内容高度相似的事实或状态，将其合并，并建立“取代”关系链。
矛盾检测：发现关于同一key或同一实体相互矛盾的陈述（例如，一个事实说“服务状态是健康的”，而5分钟前的一个事件说“服务崩溃了”），并打上flagged标签供人工审查。
发现联系：找出不同记忆之间潜在的隐性关联，并建议新的实体关系。

运维建议：合并策略与成本控制合并过程会调用LLM（默认使用配置的OPENAI_API_KEY），因此有成本和时间开销。在生产中，建议：
设置频率：对于记忆写入量大的系统，可以每小时运行一次“轻量合并”（只处理过去一小时的记忆）；每天凌晨执行一次“全量合并”。
控制范围：通过API参数限制合并操作的时间范围或记忆类型，避免一次性处理海量历史数据。
监控结果：定期检查合并作业的日志，关注它合并和标记的矛盾数量，这能反映智能体之间协作的一致性问题。

4.3 凭证擦除：至关重要的安全防线

这是一个看似简单却无比重要的安全特性。智能体在对话或日志中，很容易不小心泄露API密钥、数据库密码、JWT令牌等敏感信息。如果这些信息被原样存入记忆库，将造成严重的安全漏洞。

Zengram在记忆写入管道中内置了凭证擦除模块。它会使用模式匹配（正则表达式）识别常见凭证格式（如sk-...、ghp_...、eyJ...等），并将其自动替换为[REDACTED]占位符。

但是，你不能完全依赖它！我的经验是：

将其视为最后一道防线：首先应该在智能体输出层面避免泄露敏感信息。
自定义模式：检查项目中的凭证匹配模式（通常在源代码的security模块），根据你公司的特定凭证格式（如内部令牌格式）进行补充。
定期审计：可以写一个脚本，定期用brain_search搜索一些敏感词根（如“key”,“password”,“token”），手动确认没有漏网之鱼。

4.4 监控、备份与灾难恢复

对于生产系统，稳定性高于一切。

监控指标：

API健康度：持续监控/health端点。
存储层：监控PostgreSQL和Qdrant的连接数、磁盘空间、慢查询。
业务指标：通过/stats端点获取记忆总数、各类型分布、每日增量，这有助于容量规划。
错误率：关注API的4xx/5xx错误率，特别是写入失败。

备份策略： Zengram的状态存在于两个地方：

PostgreSQL/SQLite数据库：包含所有记忆的元数据、文本内容和关系。这是必须定期备份的核心数据。可以使用标准的pg_dump或SQLite备份工具，结合你的现有数据库备份流程。
Qdrant向量集合：包含记忆的向量嵌入。虽然可以从文本重新生成向量，但为了快速恢复，建议也备份Qdrant的存储卷。Qdrant支持快照功能。

灾难恢复步骤：

恢复PostgreSQL数据。
恢复Qdrant快照。
启动Zengram服务，并运行一个完整性检查脚本（例如，随机抽样一些记忆ID，分别从PostgreSQL的API和Qdrant的API查询，确保数据一致）。

5. 典型问题排查与性能优化实录

在实际部署和重度使用过程中，我遇到并解决了一些典型问题，这里分享出来帮你避坑。

5.1 检索结果不相关或遗漏

症状：搜索“数据库连接失败”，却返回了一些关于“用户登录”的记忆，而明明存在相关的“数据库超时”事件没被找到。

排查思路与解决：

检查嵌入模型：首先确认.env中配置的EMBEDDING_PROVIDER和OPENAI_API_KEY是否正确。错误的模型或API故障会导致向量质量低下。可以尝试用一个小样本（已知相关的记忆内容）手动调用嵌入API，看看生成的向量是否正常。
验证搜索策略：默认搜索是“多路径融合”。但有时，对于非常字面化的查询（如精确错误码“ERR-502”），语义搜索（向量）可能会引入噪声。你可以尝试在搜索API中指定search_strategy: "keyword"，强制使用BM25全文检索，看结果是否改善。
调整融合权重：Zengram的RRF融合算法中，三条路径的权重是可配置的（需要查阅高级配置或源码）。如果你们的记忆内容专业术语多、缩写多，可以适当提升keyword路径的权重。
审视记忆内容质量：如果智能体存入的记忆内容本身过于冗长、模糊或包含大量无关信息，也会影响检索。可以建立“记忆写入规范”，要求智能体提炼核心事实，并使用清晰的metadata进行标记。

5.2 写入或查询延迟高

症状：存储一条记忆需要好几秒，搜索时响应缓慢。

排查与优化：

数据库瓶颈：
- SQLite：如果使用SQLite且数据量增大，写入会变慢。这是SQLite的天然局限。解决方案：迁移到PostgreSQL。
- PostgreSQL：检查是否有慢查询。为memories表在source_agent,type,created_at等常用查询字段上建立索引。使用EXPLAIN ANALYZE分析查询计划。
Qdrant瓶颈：
- 检查Qdrant容器的资源使用（CPU/内存）。向量搜索是计算密集型操作。确保为Qdrant容器分配了足够的资源（例如，2核以上CPU，4GB以上内存）。
- 考虑调整Qdrant的hnsw索引参数（如ef_construct和m），在构建速度和搜索精度/速度之间取得平衡。这需要对Qdrant有更深了解，建议先使用默认值。
网络延迟：如果Zengram服务、PostgreSQL和Qdrant部署在不同的机器或网络区域，网络延迟会成为主要瓶颈。尽量让这三个服务部署在同一个低延迟的网络内，最好是在同一台宿主机或同一个Kubernetes节点上。
批量操作：如果需要一次性写入大量历史数据，不要用循环调用单条写入API。应该使用/memories/batch端点（如果提供）或自己实现一个简单的批量客户端，减少HTTP开销。

5.3 “跨智能体简报”功能返回内容过多或过少

症状：调用/briefing为某个智能体获取“上次离开后发生的事”，结果要么是信息爆炸，要么是啥也没有。

理解与调整：简报功能的逻辑是：找出所有source_agent不等于当前智能体，且在当前智能体最后一次活动时间之后创建或更新的记忆。问题的核心在于“当前智能体最后一次活动时间”如何确定。

默认机制：系统通过查找该智能体最近一条记忆（任何类型）的created_at时间戳，来判定其“最后活动时间”。如果这个智能体从未写入过记忆，系统就无法计算。
手动指定：因此，最可靠的方式是在调用/briefing接口时，显式地传入last_active_after参数，告诉系统“请给我在这个时间点之后的所有更新”。例如，你的智能体可以在每次启动时，将当前时间戳存入一个只有自己知道的key（如“agent:my-agent:last-boot-time”）作为事实，然后在请求简报时，就用这个时间戳作为last_active_after的值。
过滤与聚焦：简报API支持types和metadata过滤。如果你的智能体只关心“事实”和“决策”，或者只关心某个特定project_id下的更新，务必在请求中加上这些过滤条件，以获取最精要的信息。

5.4 容器部署下的数据持久化问题

症状：重启Docker Compose后，之前存储的记忆全部丢失。

原因与解决： Docker容器默认是无状态的，停止后其内部文件系统的更改会丢失。查看docker-compose.yml文件，你会发现它已经配置了卷映射来持久化数据：

services: zengram: # ... 其他配置 volumes: - ./data:/app/data # 将宿主机./data目录映射到容器内/app/data qdrant: volumes: - qdrant_storage:/qdrant/storage volumes: qdrant_storage:

确保：

宿主机上的./data目录存在且有写权限。
使用docker compose down时，不要带-v参数（该参数会删除定义的卷）。如果误删了，你备份的数据就派上用场了。
对于生产部署，强烈建议将./data和qdrant_storage指向更稳定、容量更大的存储路径，并纳入你的整体备份体系。

经过这些深入的解析、实战和排错，你应该对Zengram这个“多智能体共享记忆中枢”有了从理论到实践的全面认识。它的价值在于提供了一个统一、健壮、功能丰富的“记忆层”，将各自为战的智能体连接成一支有记忆、可协作的团队。开始动手部署吧，先从一个小型的智能体组合开始试验，感受跨上下文协作带来的效率提升，再逐步扩展到更复杂的生产场景中去。

查看全文

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