8 · The Memory System ★

This chapter covers how Hermes “remembers things across sessions.” It has three parts: a pluggable provider interface, a built-in holographic memory implementation, and a SQLite state layer.

8.1 The Memory Provider Interface

Two reasons behind the “only one” limit

So memory providers, like context engines, are a “mutually exclusive strategy” rather than a “stackable capability.” Chapter 9 develops this distinction.

Eight optional backends

plugins/memory/
├── holographic/      ★ built-in: HRR holographic memory (see 8.6)
├── honcho/           external service
├── hindsight/        external service
├── mem0/             external service
├── byterover/        external service
├── openviking/       external service
├── retaindb/         external service
├── supermemory/      external service
├── query_rewrite.py  query rewriting (shared helper)
└── config_schema.py

8.2 Lifecycle and Hooks

"""
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)      — per-turn clock tick, with runtime context
  on_session_end(messages)                    — extraction at session end
  on_session_switch(new_session_id, **kwargs) — mid-process session ID rotation
  on_pre_compress(messages) -> str            — ★ extraction before context compaction
  on_memory_write(action, target, content, metadata=None)
                                              — mirror writes to the built-in memory
  on_delegation(task, result, **kwargs)       — parent-side observation of subagent work
  backup_paths() -> list[str]                 — extra on-disk paths to include in backups
"""

hermes-agent/agent/memory_provider.py

Three hooks worth calling out

on_pre_compress(messages) -> str (pre-compaction extraction) is the single most important piece of the whole design:

on_delegation(task, result) (delegation observation) solves this problem: a subagent's work happens outside the parent's context (that is precisely the point of subagents; see chapter 10). But the subagent may have discovered facts worth remembering long-term. This hook lets the parent-side memory system observe the subtask's input and result.

backup_paths() (backup paths) is a very practical operational concern: the hermes backup command needs to know which extra on-disk locations a memory provider stores its data in before it can make a complete backup.

8.3 The Interface's Versioned Contract

# 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

In plain terms: version 1 is the historical, implicit contract that every existing provider is already on: get the raw message list, do on_pre_compress on a best-effort basis. Version 2 is the opt-in “fail-closed” checkpoint contract (a normalized evidence handoff plus failure propagation in strict mode).

8.4 The Trivial-Prompt Filter

This is a small but very practical optimization:

# 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         # slash command
    return bool(TRIVIAL_PROMPT_RE.match(stripped))

What it saves

When the user says something like “ok,” “thanks,” or “continue”:

• It saves one blocking network round-trip — retrieval from an external memory service goes over the network, typically a few hundred milliseconds
• It keeps a stale user model from derailing a one-word reply — the user just said “ok,” but you injected three paragraphs of their history into the context, and the model may inexplicably start talking about that material

The regex's anchoring design

Note the “single source of truth” mentioned in the comment: this regex is shared by the core per-turn prefetch gate and the provider-side classifiers, “so the two can never drift apart.” If each kept its own copy, sooner or later you would get the inconsistency where “the core thinks it's trivial, the provider thinks it isn't.”

8.5 The Memory-Usage Indicator

INDICATOR_GLYPH = "🧠"     # default glyph; providers can override with their own brand mark
                            # (Hindsight uses "👁️", for example)

@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 The Built-in Holographic Memory

plugins/memory/holographic/, four files: holographic.py (the HRR math), store.py (SQLite storage), retrieval.py (retrieval), and __init__.py (the provider implementation).

What HRR is

The three core operations

def bind(a, b):        # bind = circular convolution = element-wise phase addition
    return (a + b) % _TWO_PI
    # Binds two concepts into one composite vector.
    # The result resembles neither input (mathematically, "quasi-orthogonal")

def unbind(memory, key):   # unbind = circular correlation = phase subtraction
    return (memory - key) % _TWO_PI
    # unbind(bind(a, b), a) ≈ b   (up to superposition noise)

def bundle(*vectors):  # bundle = superposition = circular mean of complex exponentials
    complex_sum = np.sum([np.exp(1j * v) for v in vectors], axis=0)
    return np.angle(complex_sum) % _TWO_PI
    # The result resembles every input;
    # holds O(√dim) items, degrades beyond that

def similarity(a, b):  # similarity = phase cosine, range [-1, 1]
    return float(np.mean(np.cos(a - b)))

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

You don't need the math to understand what these are for:

• Bind glues a “key” and a “value” into one vector — say, binding “the user's editor” to “Vim”
• Unbind is the inverse: given a key, it recovers the corresponding value
• Bundle squeezes many memories into one vector, so a single vector can stand for a whole category

The source also explains why phase encoding was chosen: “Phase encoding is numerically stable, avoids the magnitude collapse of traditional complex-number HRRs, and maps cleanly to cosine similarity.” (That is, it holds up numerically, sidesteps the magnitude collapse of traditional complex-number HRRs, and maps neatly onto cosine similarity.)

The most notable engineering decision: SHA-256 instead of random numbers

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                    # each SHA-256 digest is 32 bytes = 16 uint16 values
    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

An honest capacity ceiling

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

Because the bundle() operation can only hold about √dim items — at 1024 dimensions, it starts degrading after roughly 32 items. This function estimates “the signal-to-noise ratio after packing N memories into a given number of dimensions.”

Exposing your own scheme's capacity ceiling as a callable function is a mature move. It admits that “this method has limits,” and lets users measure where those limits are.

8.7 The Storage Layer and Trust Scores

CREATE TABLE IF NOT EXISTS facts (...)          -- facts, with trust_score and category
CREATE TABLE IF NOT EXISTS entities (...)       -- entities (people, projects, technical terms)
CREATE TABLE IF NOT EXISTS fact_entities (...)  -- fact↔entity many-to-many links
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 full-text index
CREATE TABLE IF NOT EXISTS memory_banks (...)  -- HRR bundle vectors aggregated per category

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     # ★ feedback loop
    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__       # supports the with statement

The existence of rebuild_all_vectors(dim) is also worth noting: if you want to change the vector dimension (say, from 1024 up to 4096), the whole database has to be recomputed. SHA-256 encoding is deterministic and immune to model versions, but the dimension is a parameter — change it and you still recompute. This function turns that into a single explicit, controlled operation.

8.8 The SQLite State Layer

Beyond memory, there is a larger state store:

The existence of hermes_state_portability.py is where the “not tied to your laptop” claim becomes real: you try it on your local machine, like it, and want to move it to a cloud server — session history, memory, and configuration all have to move over as a whole.

And the session_search tool (on the core tool list) lets the model search its own past conversations — matching the README's line, “searches its own past conversations.” It relies on the FTS5 index in hermes_state_search.py.

8.9 Summing Up the Division of Labor Among Three Kinds of Memory