Cognee + Hermes 实战：给 AI Agent 装上真正的长期记忆

大多数 AI Agent 的记忆本质上只是一个回滚缓冲区——它会记住当前会话的内容，但一旦关闭终端再回来，它就不记得你的 API 限速是多少、后端跑的是什么数据库了。Hermes 内置的记忆能应付短期对话，但它不会构建结构化的长期知识图景。Cognee 恰好填补了这个空白：把 Hermes 当大脑，Cognee 当海马体，Agent 就不再遗忘你的世界。本文完整记录了从零安装、配置到实际压力测试的全过程。

Cognee + Hermes 实战

为什么要把 Cognee 接到 Hermes 上？

Agent 的默认记忆机制就像一个滚动窗口：当前会话的内容还在，但对话一长，早期内容就被摘要或丢弃了。这在单次对话中没问题，但当你关掉终端、第二天回来期望它还记得"staging 环境限速是每分钟 47 次请求"或"后端跑在 Postgres 上"时，它就彻底失效了。

Hermes 自带的记忆系统能处理短期信息，但无法自行构建结构化的长期记忆——那种把"Alice""工程团队""Falcon 项目"作为节点、并在它们之间建立边的知识图谱。Cognee 正是为此而生：它把你喂给它的任何内容吸收进来，在后台默默构建知识图谱，让检索可以沿着关系走，而不是返回一堆孤立的文本块。

好消息是 Hermes 本身就设计了内存提供者插件系统，Cognee 可以干净地接入其中。整个方案不需要 GPU、不需要付费图数据库、不需要云基础设施——一切都在本地运行。

知识图谱（Knowledge Graph） 是一种以图结构组织信息的数据模型：实体（如人、团队、项目）作为节点，实体之间的关系（如“属于”“负责”“依赖”）作为边。相较于把文本切成孤立块再靠向量相似度检索的传统 RAG，知识图谱允许检索沿关系链游走——比如从“Alice”出发找到“工程团队”，再找到该团队负责的“Falcon 项目”。这让 Agent 能回答多跳、需要推理关联的问题，而不是只返回与提问字面最接近的文本片段。代价是构建成本更高：需要从原始文本中抽取实体和关系，这正是 Cognee 在后台借用 LLM 完成的工作。

安装前的准备与步骤

Hermes 安装程序会检查以下依赖工具是否在 PATH 中：

工具	用途
uv	快速 Python 包管理和虚拟环境
Python 3.11	Hermes 和 Cognee 的运行时
Git	克隆仓库和插件发现
Node.js	工具链部分组件需要
ripgrep	Agent 的快速仓库内搜索
ffmpeg	媒体处理
LLM API Key	仅本地模式需要——Cognee 用 LLM 在构建图谱时提取实体和关系

最后一项有个值得提前知道的注意点：LLM 密钥只在本地运行 Cognee 时需要。如果走 Cognee Cloud 路线，你不需要 LLM 密钥，而是需要从 Cognee Cloud 面板获取租户 URL 和 API 密钥，租户会替你运行模型。

第一步——安装 Hermes：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装程序会自动执行上述依赖扫描。全部通过后，Hermes 就装好了。

第二步——安装 Cognee 插件：

pip install cognee-integration-hermes-agent

就这一行，装完后 Hermes 会自动发现插件。升级也是同一条命令加上 -U 参数。如果不加 -U，你跑的还是旧版本。hermes cognee status 会告诉你已安装副本和已安装包之间是否出现了版本漂移。

想从源码安装？整合代码在 Cognee 的 integrations monorepo 中：

git clone https://github.com/topoteretes/cognee-integrations.git
mkdir -p ~/.hermes/plugins/cognee
cp -R cognee-integrations/integrations/hermes-agent/. ~/.hermes/plugins/cognee/

提醒一下：这会拉入一长串依赖——向量存储、图引擎、LLM 管道等等。看到大量包名滚动而过不必惊慌。

经验法则：当两个工具在共享库版本上产生冲突时，隔离环境比强行统一版本更好。可复现性优先于便利性。

给 Hermes 配置模型

Hermes 把配置和密钥存在 ~/.hermes/.env。首次尝试时 PowerShell 因为目录不存在而报路径错误——一行修复，然后写入文件、填入 GOOGLE_API_KEY 即可。

如果遇到同样的路径错误：

mkdir -p ~/.hermes

运行 hermes model 会打开一个包含大量支持提供商的菜单——OpenAI、Anthropic、Google 等等。本文作者选择了 Google AI Studio，粘贴 API 密钥并选择默认 Gemini 模型。重启后 Hermes 就以 Gemini（gemini-2.5-flash-lite）运行。

值得一提的是：切换模型与记忆层完全解耦。今天用 Gemini、明天用 Opus，Cognee 都不关心——它在底层对两者一视同仁。

记忆提供者插件的工作原理

Hermes 通过扫描 $HERMES_HOME/plugins/ 下包含 plugin.yaml 和 Python 实现的文件夹来发现内存提供者。YAML 声明元数据以及——关键的是——该提供者实现了哪些生命周期钩子。Cognee 插件落在 ~/.hermes/plugins/cognee/，这个文件夹名就是提供者的身份标识。

每个关键节点上 Cognee 的行为：

时刻	Cognee 做什么
会话开始	确保本地 Cognee 服务器运行——或连接到兄弟插件已启动的服务器——并以瘦客户端连接
每轮完成后	把该轮写入 Cognee 会话记忆。快速，不构建图谱。
cognee_recall	先搜索会话记忆，回退到知识图谱
cognee_remember	把持久事实直接写入图谱
cognee_forget	处理删除请求
显式 Hermes 记忆写入	通过 on_memory_write 镜像
会话结束	运行 `cognee.improve()` 把该会话的轮次桥接进永久图谱

最后一行是整个设计中最关键的决定。Cognee 最昂贵的操作——文本分块、用 LLM 提取实体和关系、嵌入、提交边——不会在每一轮内联执行。如果那样做，每一轮都会在图谱构建时冻结。相反，轮次先进入廉价的会话记忆，图谱构建在最后一次性完成，而且是在独立进程中运行——会话结束时插件把关闭操作交给一个 detached worker，它运行 improve() 到完成才从服务器注销。退出 Hermes 会立即返回，你永远不会坐在终端里看着图谱构建结束。

这种顺序是必须的：本地服务器以 agent 模式运行，在最后一个 agent 注销后 60 秒内自动退役。如果先注销再构建，会把晋升过程拦腰截断。

三种连接模式：

模式	何时使用	通信方式
local-server（默认）	未设置 COGNEE_BASE_URL，COGNEE_EMBEDDED 未设置	确保本地服务器运行，以瘦客户端连接
remote	设置了 COGNEE_BASE_URL	瘦客户端连接 Cognee Cloud 或自管理实例
embedded	COGNEE_EMBEDDED=true	在进程内运行 Cognee

作者原本以为 embedded 会是合理的默认值，但事实并非如此——原因很充分。Cognee 的本地存储（SQLite、Kuzu/Ladybug、LanceDB）是单写入者的。从 Agent 的后台线程或在共享同一数据根目录的第二个 Hermes 进程中驱动它们，会导致"数据库已锁定"错误，最终损坏数据。本地 Cognee 服务器是序列化所有访问的单一所有者，Agent 只需发 HTTP 调用。这和 Claude Code、Codex 插件采用的是同一设计。Embedded 是可选加入的，只适合单进程或离线使用。

另一个值得欣赏的设计是：没有静默回退。如果设置了 COGNEE_BASE_URL 但无法连接，或本地服务器启动失败，初始化会直接抛错，而不是悄悄切换到另一种模式。如果初始化失败，记忆保持关闭：Hermes 记录错误后照常启动，提供者拒绝所有调用，而不是运行一个半连接的后端。你得到的是响亮的失败，而不是三周后才发现记忆神秘消失。

跨 Agent 的共享大脑：

这是作者最喜欢的一点。默认情况下，Hermes 插件加入与 Claude Code、Codex 和 OpenClaw^广告 Cognee 插件相同的记忆：相同数据集（agent_sessions）、相同本地存储（~/.cognee/{data,system}）、相同服务器端口（8011）和相同签发的 API 密钥。哪个插件先启动服务器，其余的就连接到它。你在 Claude Code 里记住的事实，在 Hermes 里也能回忆起来——反之亦然。

想让 Hermes 或某个 Hermes 配置文件独立？给它自己的 COGNEE_PLUGIN_DATASET。完全隔离则需要自己的 COGNEE_DATA_ROOT / COGNEE_SYSTEM_ROOT 和 COGNEE_LOCAL_PORT。服务器属于先到达其端口的那个，所以私有存储需要私有端口。

单写入者（single-writer） 指的是某存储在同一时刻只允许一个进程持有写权限。SQLite、Kuzu、LanceDB 这类嵌入式数据库为简化部署，通常默认单进程独占文件或目录，并在检测到并发写入时直接抛出“数据库已锁定”或损坏数据。当 Agent 的主循环、后台线程以及另一个 Hermes 进程都想直接打开同一个数据根目录时，冲突几乎必然发生。解决办法不是加锁重试，而是引入一个长期运行的本地服务器作为唯一所有者，所有访问改走 HTTP，由其序列化。这也是 local-server 模式成为默认、embedded 模式仅作可选的根本原因。

将 Cognee 设为记忆提供者

运行：

hermes memory setup

Hermes 会列出可用的内存提供者——自带记忆加上 Cognee。选择 Cognee 后，它询问你如何连接，也就是前面三种模式决策以提示形式出现。Local 让一切留在本机——这也是需要 LLM API 密钥的模式，因为 Cognee 需要模型在构建图谱时从文本中提取实体和关系。Cloud 指向托管租户：一个基础 URL 和一个 Cognee Cloud API 密钥，不需要自己的 LLM 密钥。

这个选择会写入 ~/.hermes/cognee.json，且该文件优先于环境变量。本地设置会在其中写入空的 service_url，这就是为什么后来导出 COGNEE_BASE_URL 不会把你切到云端。改变主意需要重新运行 hermes memory setup，而不是编辑变量。

确认配置已生效：

hermes memory status

显示 Installed、Available、Active——整个握手就完成了，Hermes 现在把记忆和学习路由到 Cognee。

生命周期钩子（lifecycle hooks） 是宿主程序在特定时刻回调插件代码的约定点，例如会话开始、每轮结束、会话关闭等。Hermes 通过 plugin.yaml 声明某个记忆提供者实现了哪些钩子，再据此在对应时刻调用它。正因如此，Cognee 才能把“每轮写入廉价会话记忆”与“会话结束运行昂贵的图谱晋升”分别挂在不同的钩子上，而不必侵入 Hermes 核心循环。理解钩子机制也有助于排查问题：如果某个时刻的记忆行为异常，往往意味着对应的钩子未被触发或初始化已失败。

实际测试：它真的记得吗？

一个声称能工作的配置说明不了什么。作者实际测试了记忆召回——大多数"记忆"演示都在这里悄悄作弊。

给它的内容是："Use cognee_remember that my favorite editor is Helix."

它调用了 cognee_remember，19 秒后确认。没有要求的是接下来发生的事——它反过来对自己调用 cognee_recall 来确认写入已落地。返回了"Your favorite editor is Helix"，更有用的是带了一个来源标签：graph，dataset agent_sessions。然后它把同一事实写入了 Hermes 自己的记忆存储，这次耗时 0.0 秒，因为事实已经在那里了。

这个来源标签值得多琢磨一下。cognee_recall 先检查会话记忆，只在找不到时才回退到图谱。所以当它告诉你的答案来自图谱时，它并不是在把你三十秒前输入的句子原封不动还给你。这个事实确实在知识图谱里。

有两条写入路径，行为不同。cognee_remember 是持久的那条——直接进入知识图谱，立即生效。普通对话轮次不会这样做；它们落入会话记忆，只在会话结束时被 improve() 晋升到图谱中。

这意味着你随口说的和显式要求记住的内容，至少在一开始并不在同一个地方。种测试方式可以证明走的是图谱路径而不是不小心测了回滚缓冲区：一是直接使用 cognee_remember 并读取来源标签；二是走慢路线——完全关闭 Hermes，给 detached worker 一点时间完成会话晋升，重新打开，冷启动后提问。第二种更有说服力，第一种只需二十秒。

跨模型验证： 为了展示记忆层与模型无关，作者把 Hermes 切换到 gemini-3.5-flash，告诉它："our next product launch is September 12th." 这触发了 Cognee 的完整摄取管道。后来提问时，Hermes 正确回忆出了发布日期：September 12th。不同的模型，相同的记忆，正确的答案——这就是全部意义所在。

踩过的坑与实用反馈

#	问题	修复方法
1	`packaging` 24.2 与 `packaging==26.0` 冲突	用 `uv` 虚拟环境隔离 Cognee，避免共享依赖
2	PowerShell 因目录不存在无法创建 `~/.hermes/.env`	先运行 `mkdir -p ~/.hermes`
3	配置后首次 hermes 会话挂起几分钟	这是本地服务器首次启动的一次性数据库迁移。用 `curl -s http://127.0.0.1:8011/health` 判断何时真正就绪
4	导出 `COGNEE_BASE_URL` 想切到云端，却固执地留在本地	`~/.hermes/cognee.json` 优先于环境变量，本地设置写了空的 service_url。重新运行 `hermes memory setup`

这些都不是致命问题，但每一个都会让你多花二十分钟挠头——现在它们被记录下来了。

后续方向：

共享大脑：同时为 Claude Code、Codex 或 OpenClaw 安装 Cognee 插件，它们默认共享数据集、存储和端口
扩展后端：图谱超出本地存储时，切换到 Postgres/pgvector、Neo4j 或 Qdrant
喂入文档：Cognee 可以摄取文件、JSON 等——指向你的项目文档，让图谱自行构建
探索搜索模式：Cognee 提供十几种检索策略，从经典 RAG 到图遍历补全
调整会话结束行为：COGNEE_IMPROVE_BACKGROUND 控制图谱构建在哪里运行，默认 auto 交给 detached worker

常见问题

需要 GPU 或付费云服务吗？ 不需要。一切本地运行，基于本地 Cognee 服务器——SQLite、嵌入式向量存储、嵌入式图引擎。没有 GPU、没有托管数据库、没有云账户。"本地"不意味着"进程内"——默认是 127.0.0.1:8011 上的小型本地服务器，因为 Cognee 本地存储是单写入者的，服务器是维持单一所有者的方式。

Cognee 启动失败会怎样？ 记忆保持关闭，而且是响亮的失败。提供者从不悄悄降级——远程 URL 不可达或本地服务器无法启动时，初始化会抛错。Hermes 记录错误后照常启动，提供者拒绝所有调用。如果确实想要进程内模式的取舍，需要显式设置 COGNEE_EMBEDDED=true。

能换模型而不丢失记忆吗？ 可以，这正是插件设计的核心。记忆层完全与模型解耦。

能同时运行多个外部记忆提供者吗？ 不能。Hermes 强制同时只允许一个外部记忆提供者，第二个注册会被拒绝并发出警告。这防止两个后端争夺工具 schema 并互相破坏。

记忆数据存在哪里？ 不在 Hermes 配置文件里。在 ~/.cognee/data 和 ~/.cognee/system，数据集为 agent_sessions——与其他 Cognee Agent 插件相同的根目录，这正是跨 Claude Code、Codex、OpenClaw 和 Hermes 共享大脑机制的基础。因为这些根目录在 HERMES_HOME 之外，插件会将其报告给 hermes backup。

从旧版插件升级后记忆不见了？ 不是丢了，只是位置变了。1.0 版本有三个默认值变动：本地端口从 8000 变为 8011，默认数据集从 hermes 变为共享的 agent_sessions，本地存储默认到 ~/.cognee/{data,system}。将 COGNEE_PLUGIN_DATASET=hermes 指向旧数据即可恢复。