hermes-memory-pgvector Skill 技能

技能简介

hermes-memory-pgvector 是 Nous Research 官方生态的 hermes-agent 多智能体内存插件，基于 PostgreSQL + pgvector 为 AI Agent 舰队提供持久化语义记忆层。在 hot path（记忆读写路径）完全不调用 LLM，只依赖向量数据库完成语义检索，性能和稳定性都有保障。

hermes-agent 是 Nous Research 开源的自改进 AI Agent，支持多会话学习、跨会话记忆检索、并行子智能体调度等功能。hermes-memory-pgvector 填补了 hermes-agent 在多智能体（multi-minion）部署场景下的共享记忆空白——默认的 MEMORY.md / USER.md 方案仅支持单机单智能体，多个智能体同时运行时会相互覆盖记忆；hermes-memory-pgvector 通过 Postgres 的行级隔离实现每个智能体（minion）拥有独立主题（theme）的记忆空间，同时支持跨主题的显式检索。

核心能力

• 多智能体主题隔离：每个智能体拥有独立的 memory_entries 和 conversations 表空间，通过 X-Hermes-Session-Key 头部的 agent_identity 字段实现身份治理，营销智能体的记忆不会污染交易智能体的检索结果
• 零 LLM 热路径：记忆写入时仅做向量嵌入（调用外部 embedding 端点），检索时仅做向量相似度计算，全程不经过 LLM，延迟低、失败模式简单
• 异步写入队列：记忆写入钩子（on_memory_write）在微秒级返回，实际嵌入和数据库写入在后台线程异步完成，不阻塞 Agent 对话循环
• 混合检索（RRF）：recall_memory 和 recall_conversation 将向量相似度排名与 PostgreSQL 全文搜索排名通过 Reciprocal Rank Fusion（k=60）融合，解决纯向量检索的召回盲区
• 身份治理与归属链：支持智能体身份规范化（匿名化手机号等 PII）、 delegation 归属链记录（哪个智能体在何时委托了什么），通过 memory_agents 和 memory_agent_edges 表维护
• 连接池自动管理：使用 psycopg_pool.ConnectionPool（min=0, max=4），空闲时零连接、智能体退出时不产生连接泄漏

安装配置

环境要求

• Python 3.11+
• PostgreSQL 15+（需启用 pgvector 扩展）
• 一个向量嵌入端点（支持任何兼容 API 的 embedding 服务，如 OpenAI、Cohere、本地 embedding 模型）
• hermes-agent 主程序（需先完成 hermes-agent 安装）

安装步骤

第一步：准备 PostgreSQL 数据库

创建专用数据库和用户：

CREATE USER hermes_mem WITH PASSWORD ''; CREATE DATABASE hermes_memory OWNER hermes_mem; c hermes_memory CREATE EXTENSION vector; GRANT ALL PRIVILEGES ON DATABASE hermes_memory TO hermes_mem;

第二步：安装 hermes-memory-pgvector

pip install hermes-memory-pgvector

第三步：配置 .env 环境变量

在 hermes-agent 的 .env 文件中添加：

MEMORY_PROVIDER=hermes_pgvector HERMES_PGVECTOR__DSN=postgresql://hermes_mem:@localhost:5432/hermes_memory HERMES_PGVECTOREMBED_ENDPOINT=https://api.openai.com/v1/embeddings # 替换为你的 embedding 端点 HERMES_PGVECTOREMBED_MODEL=text-embedding-3-small HERMES_PGVECTOR__EMBED_API_KEY=sk-... # 你的 embedding API Key

第四步：运行数据库迁移

hermes-pgvector migrate

该命令执行 001_schema.sql（HNSW 索引创建）和 002_attribution.sql（归属链表）， idempotent 设计可安全重复执行。

使用步骤

步骤一：启动 hermes-agent

hermes

智能体启动时 initialize() 钩子自动验证 schema、初始化连接池，并将现有的 MEMORY.md / USER.md 内容批量导入 pgvector 表。

步骤二：验证记忆写入

向 Agent 说：

"记住我最喜欢的编程语言是 Rust，我目前在做一个分布式缓存项目。"

Agent 调用 memory(action='add') 写入，hermes-memory-pgvector 在后台异步完成：

1. 向量嵌入 → 2. 写入 memory_entries 表（theme=当前智能体 identity）

步骤三：验证语义检索

在新会话中问 Agent：

"我之前说过我最喜欢什么编程语言？"

Agent 调用 recall_memory(query=...)，pgvector 在当前 theme 下做余弦相似度检索，返回之前写入的记忆条目。

步骤四：跨主题检索（管理员场景）

如果需要跨所有智能体检索（需谨慎使用）：

Agent 调用 recall_memory(query=..., scope='all')，在所有主题的 memory_entries 中执行混合 RRF 检索。

适用场景

• 多智能体舰队记忆共享：每个垂直领域（客服/风控/运营）部署独立智能体，共享 Postgres 作为统一记忆后端，打破单机文件系统隔离
• 长周期项目连续性：跨多日、多会话的复杂项目，Agent 每次对话自动补充上下文，不需要手动传递背景信息
• 多租户用户画像：在 SaaS 场景中，每个租户对应独立 theme，Agent 对该租户的交互历史全部可检索，天然支持多租户隔离
• Agent 归属审计：通过 memory_agent_edges 表追溯某个决策是由哪个智能体、在哪个会话中做出的，适合合规和调试场景

适用人群

• Nous Research hermes-agent 高级用户：已使用 hermes-agent 构建多智能体系统，需要将记忆从单机文件迁移到共享数据库
• AI 应用开发者：基于 hermes-agent 开发企业级 AI 应用，需要多租户记忆隔离和长期上下文管理
• AI 研究人员：研究多智能体协作、记忆共享机制，需要可控的实验环境（hermes-memory-pgvector 纯 Python，开源可审计）

工作原理

hermes-memory-pgvector 实现 hermes-agent 的 memory provider 接口（initialize / on_memory_write / sync_turn / prefetch / recall_memory / recall_conversation）。

写入路径：Agent 调用 memory(action='add') → on_memory_write 钩子捕获内容 → 提交到 AsyncWriter 队列 → 后台线程调用 embedding 端点 → 写入 Postgres memory_entries 表。

检索路径：Agent 调用 recall_memory(query=...) → prefetch 注入 top-K 相关记忆条目 → Agent 自行决定如何使用注入的上下文。

所有表按 theme（agent_identity）做行级隔离，HNSW 索引加速向量检索。连接池默认 min=0，idle 30 秒后自动释放，避免连接泄漏。

官方链接

• PyPI：https://pypi.org/project/hermes-memory-pgvector/
• GitHub：https://github.com/andreab67/hermes-memory-pgvector
• hermes-agent 主仓库：https://github.com/NousResearch/hermes-agent
• hermes-agent 官方文档：https://hermes-agent.nousresearch.com/docs/