Hermes Agent 企业级本地记忆扩展技术方案

调研时间：2026-06-24
定位：企业内网环境，数据不出本地，不依赖任何云服务

一、背景与目标

Hermes Agent 默认的记忆方案基于 MEMORY.md / USER.md 纯文本文件，每次会话加载全文，通过 session_search 做 FTS5 全文检索。这套方案在个人场景够用，但在企业级需求下有明显短板：

无语义搜索 — FTS5 只能做关键词匹配，无法理解语义相似度
无向量检索 — 无法通过 embedding 做近似搜索，召回质量受限
无实体关系 — 无法建立人、项目、工具之间的知识图谱关系
无信任评分 — 旧记忆和新记忆权重一致，冲突记忆无法自动淘汰
无多用户隔离 — 单文件存储，不适合多团队/多 Agent 场景
中文支持弱 — 正则实体抽取只匹配英文大写开头的词

目标：设计一个零云服务依赖的企业级本地记忆插件，基于 Hermes 的 MemoryProvider ABC 接口实现，支持语义检索、实体关系、信任评分、多租户隔离。

二、Hermes 记忆插件架构

Hermes 记忆系统的核心是 agent/memory_provider.py 中定义的 MemoryProvider 抽象基类。启动时由 agent/agent_init.py 调用 plugins/memory/__init__.py 的 load_memory_provider 函数发现并加载插件。

插件生命周期：

is_available() — 检查依赖是否就绪（不发起网络请求）
initialize(session_id, **kwargs) — 建立连接，创建存储资源
system_prompt_block() — 返回注入系统提示的静态文本
prefetch(query) — 每次 turn 前召回相关上下文
sync_turn(user, asst) — 每次 turn 后异步持久化
get_tool_schemas() — 暴露给 LLM 的工具定义
handle_tool_call(name, args) — 处理工具调用
on_session_end(messages) — 会话结束时的提取钩子
shutdown() — 清理资源

可选钩子：on_turn_start、on_session_switch、on_pre_compress、on_memory_write、on_delegation。

插件发现机制扫描两个目录：

内置：~/.hermes/hermes-agent/plugins/memory/<name>/
用户安装：~/.hermes/plugins/<name>/

同名时内置优先。只能通过 memory.provider 配置激活一个外部插件。

三、现有插件能力对比

Hermes 目前内置 9 个记忆插件，按云/本地分类：

插件	模式	部署	向量检索	实体关系	信任评分	中文	多租户
builtin（默认）	文件	本地	无	无	无	差	无
holographic	SQLite+HRR	本地	HRR近似	正则抽取	有	差	无
byterover	CLI知识树	本地为主	无	无	无	依赖LLM	无
hindsight	知识图谱	本地/云	语义搜索	图谱	observation层	依赖LLM	bank_id
openviking	上下文DB	自托管	语义搜索	自动抽取	无	依赖LLM	资源隔离
mem0	向量DB	云端	有	有	无	有	agent_id
honcho	用户建模	云端	无	无	偏好推断	有	session
supermemory	语义记忆	云端	有	无	无	有	无
retaindb	混合搜索	云端	有	无	无	有	无

企业级本地方案的核心差距：

holographic 最接近需求，但 HRR 向量维度固定 1024 且不支持语义嵌入模型，实体抽取不支持中文
hindsight local 能力最强（知识图谱+语义搜索），但依赖 npm 包和本地 LLM daemon，部署复杂度最高
openviking 功能完整，但 VikingDB 自托管文档少，社区生态弱
所有内置插件都缺乏多租户隔离机制

四、技术选型

4.1 存储层

推荐：SQLite（WAL 模式）

企业环境不一定有 DBA 维护 PostgreSQL。SQLite WAL 模式支持并发读写，单文件部署，备份直接 cp。对于 10 万条以内的事实存储，SQLite 性能足够。

如果企业已有 PostgreSQL 基础设施，可以加一个 PG 适配层，接口不变。

数据表设计（参考 holographic 的 store.py 并扩展）：

facts 表：fact_id, content, category, tags, trust_score, embedding_id, tenant_id, created_at, updated_at
entities 表：entity_id, name, alias, entity_type, tenant_id
fact_entities 表：fact_id, entity_id, role（subject/object/context）
memory_banks 表：bank_name, vector（HRR 复合向量，可选）, tenant_id
prefetch_cache 表：query_hash, result_json, expires_at（prefetch 结果缓存）

tenant_id 字段实现多租户隔离，不同团队/Agent 的数据物理隔离在同一库中。

4.2 向量层

推荐：sqlite-vec（首选）或 FAISS（备选）

sqlite-vec 是 SQLite 扩展，直接在 SQL 中做向量距离计算，无需额外服务。pip install sqlite-vec，加载扩展后创建虚拟表：

CREATE VIRTUAL TABLE IF NOT EXISTS fact_embeddings USING vec0(
  fact_id INTEGER PRIMARY KEY,
  embedding FLOAT[384]
);

查询时用 distance_cosine(embedding, ?) 做近似最近邻搜索。

FAISS（Facebook AI Similarity Search）是纯 Python/C++ 库，无服务，支持多种索引类型（FlatIP、IVF、HNSW）。适合百万级向量，但需要自己管理 id 映射和持久化。

不推荐 ChromaDB：虽然本地模式可用，但依赖较多（huggingface、tokenizers），在企业内网离线环境安装麻烦。

不推荐 Qdrant：需要单独跑一个进程或 Docker，增加运维成本。

向量维度选择：384 维（all-MiniLM-L6-v2）是性价比最高的选项，检索质量够用，存储开销小。768 维（all-mpnet-base-v2）质量更高但存储翻倍。

4.3 嵌入层

推荐：ONNX Runtime + 本地模型

企业环境要求离线可用，不能调用任何云 API。

方案优先级：

ONNX Runtime — 将 sentence-transformers 模型转换为 ONNX 格式，用 onnxruntime 推理。CPU 即可运行，无 GPU 依赖。模型文件约 90MB（all-MiniLM-L6-v2）。
Ollama embedding — 如果企业已部署 Ollama，通过 http://localhost:11434/api/embeddings 调用本地 embedding 模型。零代码改动，但依赖 Ollama 服务。
sentence-transformers 原生 — pip install sentence-transformers，首次运行自动下载模型。依赖较重（torch ~2GB），但最省事。

中文支持：paraphrase-multilingual-MiniLM-L12-v2 支持 50+ 语言包括中文，384 维，是本地多语言场景的最佳选择。

4.4 实体抽取层

holographic 用正则匹配英文大写开头的词，中文完全不支持。

推荐：jieba 分词 + 规则抽取

jieba 做中文分词和词性标注，提取 nr（人名）、ns（地名）、nt（机构名）、nz（其他专名）
保留 holographic 的英文正则规则，中英双语并行
实体消歧：同义词表（alias 字段），如"老王"和"王总"映射到同一 entity_id

如果企业有 GPU 资源，可以换 LAC（百度词法分析）或 HanLP，准确率更高。

4.5 检索层

混合检索架构：三路召回 + 加权融合

用户查询
  ├── 路径1：FTS5 全文搜索（关键词精确匹配）
  ├── 路径2：向量余弦相似度（语义近似匹配）
  └── 路径3：实体图遍历（关联实体扩展）
        ↓
  加权融合评分 = w1 * fts_score + w2 * vec_score + w3 * entity_score
        ↓
  信任加权 = 融合评分 * trust_score
        ↓
  时间衰减（可选）= 信任加权 * 0.5^(age_days / half_life)
        ↓
  返回 Top-K

权重默认值：fts=0.3, vec=0.5, entity=0.2。向量权重最高，因为语义搜索是核心升级点。

prefetch 缓存：每次 turn 的查询结果缓存到 prefetch_cache 表，TTL 5 分钟。下次相同/相似查询直接返回，避免重复计算。

五、插件实现方案

5.1 目录结构

~/.hermes/plugins/mnemosyne/
  __init__.py          — 插件入口，register_memory_provider 函数
  plugin.yaml          — 插件元信息
  store.py             — SQLite 存储层（建表、CRUD）
  embedder.py          — 嵌入层封装（ONNX/Ollama/ST 三种后端）
  retriever.py         — 混合检索（FTS5 + 向量 + 实体）
  entities.py          — 实体抽取（jieba + 规则）
  config.py           — 配置加载和 schema

5.2 核心类

class MnemosyneProvider(MemoryProvider):
    name = "mnemosyne"
    
    def is_available(self) — 检查 sqlite-vec / onnxruntime 是否可 import
    def initialize(session_id, **kwargs) — 建库、加载模型、预热
    def system_prompt_block() — 返回记忆状态摘要
    def prefetch(query) — 混合检索，返回格式化的召回结果
    def sync_turn(user, asst) — 异步写入队列（不阻塞主循环）
    def get_tool_schemas() — 返回 fact_store / fact_feedback 工具定义
    def handle_tool_call(name, args) — 路由到 store/retriever
    def on_session_end(messages) — 自动事实抽取（可选）
    def shutdown() — 关闭连接、保存模型缓存

5.3 工具设计

向 LLM 暴露两个工具：

fact_store — 结构化记忆操作

action: add / search / probe / related / reason / contradict / update / remove / list
参数：content, query, entity, entities, category, tags, fact_id, limit, min_trust

fact_feedback — 信任评分反馈

action: helpful / unhelpful
参数：fact_id

工具描述中明确指导 LLM：回答用户问题前必须先 probe 或 reason，这是提升召回率的关键。

5.4 配置项

plugins:
  mnemosyne:
    db_path: ~/.hermes/mnemosyne.db
    model_name: paraphrase-multilingual-MiniLM-L12-v2
    embed_backend: onnx
    vector_dim: 384
    fts_weight: 0.3
    vec_weight: 0.5
    entity_weight: 0.2
    default_trust: 0.5
    min_trust: 0.3
    temporal_decay_half_life: 90
    auto_extract: true
    tenant_id: default
    prefetch_cache_ttl: 300

六、企业部署方案

6.1 单机部署（< 50 人团队）

一台 Linux 服务器
  ├── Hermes Agent（pip install hermes-agent）
  ├── mnemosyne 插件（pip install 或复制到 ~/.hermes/plugins/）
  ├── ONNX 模型文件（提前下载，放到 ~/.hermes/models/）
  └── SQLite 数据文件（~/.hermes/mnemosyne.db）

安装步骤：

pip install hermes-agent sqlite-vec onnxruntime jieba
下载 ONNX 模型到本地目录
复制插件到 ~/.hermes/plugins/mnemosyne/
config.yaml 设置 memory.provider: mnemosyne
启动时自动建表和加载模型

6.2 多团队部署（50-500 人）

共享服务器
  ├── Hermes Agent（多 profile，每团队一个）
  ├── mnemosyne 插件（共享代码）
  ├── SQLite 多库（每团队一个 .db 文件）
  │    或通过 tenant_id 字段单库隔离
  └── Ollama 服务（可选，共享 embedding 计算）

多租户隔离通过 tenant_id 实现。每个 profile 配置不同的 tenant_id，检索时自动过滤。

6.3 大规模部署（500+ 人）

应用服务器集群
  ├── Hermes Agent × N（无状态，可水平扩展）
  ├── PostgreSQL（替代 SQLite，共享存储）
  ├── FAISS 索引服务（独立进程，gRPC 接口）
  ├── Ollama embedding 服务（GPU 节点）
  └── Redis（prefetch 缓存，替代 SQLite 内置缓存）

此时需要重写 store.py 的存储后端，MemoryProvider 接口不变。

七、与现有方案对比

能力	builtin	holographic	hindsight local	mnemosyne（本方案）
数据不出内网	完全	完全	完全	完全
结构化存储	无	SQLite	知识图谱	SQLite + 向量
语义搜索	无	HRR近似	有	有（ONNX本地）
实体关系	无	正则（仅英文）	知识图谱	jieba + 规则
信任评分	无	有	observation	有
时间衰减	无	有	无	有
多租户	无	无	bank_id	tenant_id
中文支持	差	差	依赖LLM	多语言模型
10万+ 事实	文件慢	SQLite 可以	取决于daemon	SQLite 可以
部署复杂度	零	低	高（npm+daemon）	中（pip+模型）
离线可用	完全	完全	需本地LLM	完全

八、实施路线图

Phase 1：最小可用（1-2 周）

实现 MemoryProvider 骨架 + SQLite 存储层
集成 FTS5 全文搜索（复用 holographic 的检索逻辑）
实现 fact_store / fact_feedback 两个工具
支持 add / search / update / remove 基本操作
信任评分 + 时间衰减

Phase 1 完成后，即可获得比 builtin 更好的结构化存储和检索能力，零额外依赖。

Phase 2：语义搜索（1 周）

集成 ONNX Runtime + 多语言嵌入模型
集成 sqlite-vec 向量索引
实现混合检索（FTS5 + 向量加权）
prefetch 缓存

Phase 2 完成后，召回质量大幅提升，接近 mem0 云版本的语义搜索能力。

Phase 3：实体关系（1 周）

集成 jieba 中文实体抽取
实体消歧和同义词表
probe / related / reason 图遍历查询
contradict 矛盾检测

Phase 3 完成后，具备知识图谱能力，接近 hindsight 的核心功能。

Phase 4：企业级加固（1 周）

多租户隔离（tenant_id）
后台异步写入队列
模型预热和缓存
配置热重载
监控指标（召回率、延迟、存储量）

九、风险与缓解

风险	影响	缓解措施
ONNX 模型推理慢	每次嵌入需 50-200ms	批量推理 + prefetch 缓存
SQLite 写入并发	WAL 模式下单写者限制	异步队列串行化写入
模型文件大（~90MB）	首次部署下载慢	提前打包到离线安装包
jieba 实体抽取不准	中文人名/项目名漏抽	支持用户自定义词典
向量索引膨胀	百万级向量占用内存	定期清理低 trust 事实
多租户数据泄露	tenant_id 过滤遗漏	所有查询强制加 tenant_id WHERE

十、总结

本方案基于 Hermes 的 MemoryProvider 插件接口，用 SQLite + sqlite-vec + ONNX Runtime + jieba 构建全本地化的企业记忆系统。四个核心能力：

语义搜索 — 本地 ONNX 嵌入模型 + sqlite-vec，无需云 API
实体关系 — jieba 中文抽取 + 图遍历查询
信任评分 — 用户反馈驱动的自适应权重 + 时间衰减
多租户 — tenant_id 字段隔离，单库多团队

部署上从单机 SQLite 到集群 PostgreSQL + FAISS 可以平滑演进，接口层不变。Phase 1 即可交付可用版本，后续迭代增加语义和图谱能力。

如果你觉得本文有用，请点赞，收藏，转发

你有什么问题，请留言，我来帮你解答。