8 · 记忆系统 ★

这一章讲 Hermes 怎么「跨会话记住事情」。它由三部分组成：一个可插拔的提供者接口、一个内置的全息记忆实现、以及一个 SQLite 状态层。

8.1 记忆提供者接口

「只能有一个」这条限制的两个理由

所以记忆提供者和上下文引擎一样，属于「互斥策略」而非「可叠加能力」。这个区分在第 9 章会展开。

八种可选后端

plugins/memory/
├── holographic/      ★ 内置：HRR 全息记忆（见 8.3）
├── honcho/           外部服务
├── hindsight/        外部服务
├── mem0/             外部服务
├── byterover/        外部服务
├── openviking/       外部服务
├── retaindb/         外部服务
├── supermemory/      外部服务
├── query_rewrite.py  查询改写（通用辅助）
└── config_schema.py

8.2 生命周期与钩子

"""
Lifecycle (called by MemoryManager, wired in run_agent.py):
  initialize()           — connect, create resources, warm up
  system_prompt_block()  — static text for the system prompt
  prefetch(query)        — background recall before each turn
  sync_turn(user, asst)  — async write after each turn
  get_tool_schemas()     — tool schemas to expose to the model
  handle_tool_call()     — dispatch a tool call
  shutdown()             — clean exit

Optional hooks (override to opt in):
  on_turn_start(turn, message, **kwargs)      — 每轮的时钟滴答，带运行时上下文
  on_session_end(messages)                    — 会话结束时的提取
  on_session_switch(new_session_id, **kwargs) — 进程中途的会话 ID 轮转
  on_pre_compress(messages) -> str            — ★ 上下文压缩前的提取
  on_memory_write(action, target, content, metadata=None)
                                              — 镜像内置记忆的写入
  on_delegation(task, result, **kwargs)       — 父侧观察子智能体的工作
  backup_paths() -> list[str]                 — 备份时要包含的额外磁盘路径
"""

hermes-agent/agent/memory_provider.py

三个值得单独说的钩子

on_pre_compress(messages) -> str（压缩前提取）是整套设计里最关键的一个：

on_delegation(task, result)（委派观察）解决的是：子智能体的工作过程不在父的上下文里（这正是子智能体的价值，见第 10 章）。但子智能体可能发现了值得长期记住的事实。这个钩子让父侧的记忆系统能观察到子任务的输入和结果。

backup_paths()（备份路径）是一个很实在的运维考虑：hermes backup 命令需要知道记忆提供者把数据存在哪些额外的磁盘位置，才能完整备份。

8.3 接口的版本化契约

# Version 1 is the historical, implicit contract every provider is already
# on: best-effort on_pre_compress() with the raw message list. Version 2 is
# the opt-in fail-closed checkpoint contract (normalized evidence handoff +
# strict-mode failure propagation).
PRE_COMPRESS_CHECKPOINT_API_VERSION = 2

译：版本 1 是历史上的隐式契约，每个已有的提供者都在用：拿到原始消息列表、尽力而为地做 on_pre_compress。版本 2 是可选加入的「失败即闭合」检查点契约（归一化的证据交接 + 严格模式下的失败传播）。

8.4 琐碎提问过滤器

这是一个很小但很实用的优化：

# Prompts that carry no semantic signal — trivial acknowledgements, greetings,
# slash commands, empty input. Single source of truth shared by the core
# per-turn prefetch gate and provider-side classifiers so the two can never
# drift apart.
TRIVIAL_PROMPT_RE = re.compile(
    r'^(yes|no|ok|okay|sure|thanks|thank you|y|n|yep|nope|yeah|nah|'
    r'hi|hey|hello|yo|sup|'
    r'continue|go ahead|do it|proceed|got it|cool|nice|great|done|next|lgtm|k)'
    r'[\s!?.:;,"\'~…—–()\[\]{}<>*&^%$#@!+=` ]*$',
    re.IGNORECASE,
)

def is_trivial_prompt(text: Optional[str]) -> bool:
    """Callers use this to skip memory-provider prefetch/injection on turns
    that carry no semantic signal — saving a blocking network round-trip
    and preventing stale user-model context from derailing one-word replies."""
    if not text: return True
    stripped = text.strip()
    if not stripped: return True
    if stripped.startswith("/"): return True         # 斜杠命令
    return bool(TRIVIAL_PROMPT_RE.match(stripped))

它省掉的是什么

用户说「好的」「谢谢」「继续」这类话时：

• 省一次阻塞的网络往返 —— 外部记忆服务的检索是要联网的，通常几百毫秒
• 防止过期的用户模型把一个词的回复带偏 —— 用户只说了「好」，你却往上下文里注入了三段关于他的历史记忆，模型可能会莫名其妙地开始谈论那些内容

正则的锚定设计

注意注释里提到的「单一真相来源」：这个正则被核心的每轮预取闸门和提供者侧的分类器共享，「so the two can never drift apart」（这样两者永远不会漂移）。如果各自实现一份，迟早会出现「核心认为琐碎、提供者认为不琐碎」的不一致。

8.5 记忆使用指示器

INDICATOR_GLYPH = "🧠"     # 默认字形；各提供者可以用自己的品牌标记覆盖
                            # （比如 Hindsight 用 "👁️"）

@dataclass(frozen=True)
class RecallStatus:
    """Summary of what a provider's most recent prefetch injected this turn.

    …so the agent can emit a deterministic, model-independent
    "memory was used" indicator. ``count`` is the number of discrete
    memories injected; ``0`` means content was injected but has no discrete
    count (e.g. a synthesized reflect answer), which the indicator renders
    generically rather than as "0 memories".
    """
    provider_label: str
    count: int
    glyph: str = INDICATOR_GLYPH

8.6 内置的全息记忆

plugins/memory/holographic/，四个文件：holographic.py（HRR 数学运算）、store.py（SQLite 存储）、retrieval.py（检索）、__init__.py（提供者实现）。

HRR 是什么

三个核心运算

def bind(a, b):        # 绑定 = 循环卷积 = 逐元素相位相加
    return (a + b) % _TWO_PI
    # 把两个概念绑定成一个复合向量。
    # 结果与两个输入都不相似（数学上叫"准正交"）

def unbind(memory, key):   # 解绑 = 循环相关 = 相位相减
    return (memory - key) % _TWO_PI
    # unbind(bind(a, b), a) ≈ b   （差一个叠加噪声）

def bundle(*vectors):  # 打包 = 叠加 = 复指数的圆均值
    complex_sum = np.sum([np.exp(1j * v) for v in vectors], axis=0)
    return np.angle(complex_sum) % _TWO_PI
    # 结果与每个输入都相似；
    # 能容纳 O(√dim) 项，超过就开始退化

def similarity(a, b):  # 相似度 = 相位余弦，范围 [-1, 1]
    return float(np.mean(np.cos(a - b)))

hermes-agent/plugins/memory/holographic/holographic.py

不需要懂数学也能理解用途：

• 绑定把「键」和「值」粘成一个向量，比如把「用户的编辑器」和「Vim」绑起来
• 解绑是逆运算，给一个键能取回对应的值
• 打包把很多条记忆压成一个向量，用一个向量代表整个类别

源码还说明了选相位编码的理由：「Phase encoding is numerically stable, avoids the magnitude collapse of traditional complex-number HRRs, and maps cleanly to cosine similarity.」（相位编码数值稳定，避免了传统复数 HRR 的幅值塌缩，而且能干净地映射到余弦相似度。）

最值得注意的工程决策：用 SHA-256 而不是随机数

def encode_atom(word: str, dim: int = 1024) -> "np.ndarray":
    """Deterministic phase vector via SHA-256 counter blocks.

    Uses hashlib (not numpy RNG) for cross-platform reproducibility.

    Algorithm:
    - Generate enough SHA-256 blocks by hashing f"{word}:{i}" for i=0,1,2,...
    - Concatenate digests, interpret as uint16 values via struct.unpack
    - Scale to [0, 2π): phases = values * (2π / 65536)
    - Truncate to dim elements
    """
    values_per_block = 16                    # 每个 SHA-256 摘要 32 字节 = 16 个 uint16
    blocks_needed = math.ceil(dim / values_per_block)
    uint16_values = []
    for i in range(blocks_needed):
        digest = hashlib.sha256(f"{word}:{i}".encode()).digest()
        uint16_values.extend(struct.unpack("<16H", digest))
    phases = np.array(uint16_values[:dim], dtype=np.float64) * (_TWO_PI / 65536.0)
    return phases

诚实的容量上限

def snr_estimate(dim: int, n_items: int) -> float: ...

因为 bundle() 打包运算只能容纳约 √维度 项 —— 1024 维大约在 32 项之后就开始退化。这个函数估算「在给定维度下塞进 N 条记忆后的信噪比」。

把自己方案的容量上限写成一个可调用的函数暴露出来，是很成熟的做法。它承认了「这个方法有边界」，并且让使用者能测出边界在哪。

8.7 存储层与信任分

CREATE TABLE IF NOT EXISTS facts (...)          -- 事实，带 trust_score 和 category
CREATE TABLE IF NOT EXISTS entities (...)       -- 实体（人、项目、技术名词）
CREATE TABLE IF NOT EXISTS fact_entities (...)  -- 事实↔实体 多对多关联
CREATE INDEX IF NOT EXISTS idx_facts_trust    ON facts(trust_score DESC);
CREATE INDEX IF NOT EXISTS idx_facts_category ON facts(category);
CREATE INDEX IF NOT EXISTS idx_entities_name  ON entities(name);
CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts   -- ★ FTS5 全文索引
CREATE TABLE IF NOT EXISTS memory_banks (...)  -- 按 category 聚合的 HRR 打包向量

hermes-agent/plugins/memory/holographic/store.py

class MemoryStore:
    def add_fact(...)
    def search_facts(...)
    def update_fact(...)
    def remove_fact(fact_id: int) -> bool
    def list_facts(...)
    def record_feedback(self, fact_id: int, helpful: bool) -> dict     # ★ 反馈闭环
    def _extract_entities(self, text: str) -> list[str]
    def _resolve_entity(self, name: str) -> int
    def _link_fact_entity(self, fact_id: int, entity_id: int) -> None
    def _compute_hrr_vector(self, fact_id: int, content: str) -> None
    def _rebuild_bank(self, category: str) -> None
    def rebuild_all_vectors(self, dim: int | None = None) -> int
    @classmethod
    def release_all_under(cls, directory) -> int
    def close(self) -> None
    def __enter__ / __exit__       # 支持 with 语句

rebuild_all_vectors(dim) 的存在也值得注意：如果要调整向量维度（比如从 1024 提到 4096），需要重算全库。虽然 SHA-256 编码是确定性的、不受模型版本影响，但维度是一个参数 —— 改了还是要重算。这个函数把这件事变成一次显式的、可控的操作。

8.8 SQLite 状态层

除了记忆，还有一套更大的状态存储：

hermes_state_portability.py 的存在是「不绑定笔记本」这个主张的落地：你在本机试用，觉得不错，要迁到云服务器上 —— 会话历史、记忆、配置都得能整体搬过去。

而 session_search 这个工具（在核心工具清单里）让模型可以搜索自己过往的对话 —— 对应 README 里那句「searches its own past conversations」。它靠的就是 hermes_state_search.py 的 FTS5 索引。

8.9 三种记忆的分工总结