feat(plugin): hermes-memory-store with holographic retrieval by dusterbloom · Pull Request #2351 · NousResearch/hermes-agent

dusterbloom · 2026-03-21T18:15:07Z

Summary

Addresses #2184 — adds a memory store plugin with structured retrieval, entity resolution, trust scoring, and algebraic fact reasoning. Runs fully locally, zero external dependencies beyond optional numpy.

The novel part: Holographic Reduced Representations (HRR) — phase vectors that enable compositional queries using hashlib + numpy. No models, no APIs, no GPU.

Actions (simple → powerful)

Action	What it does
`search`	3-signal scoring (FTS5 + Jaccard + HRR)
`probe`	Single-entity recall — "what about coding?"
`related`	Structural adjacency — "what connects to Rust?"
`reason`	Multi-entity composition — vector-space JOIN, no keywords needed
`contradict`	Memory hygiene — finds facts sharing entities but making conflicting claims

How HRR works

Vectors are phase angles in [0, 2π). bind = phase addition (associate), unbind = phase subtraction (extract), bundle = circular mean (superpose). Key property: unbind(bind(a, b), b) == a exactly.

The reason action chains these to answer compositional queries in a single vector operation. contradict uses entity overlap + content divergence to self-clean memory. These are algebraic operations no embedding DB supports.

Tested with nemotron-3-nano (4B) on Ollama

The agent navigated to Wikipedia, extracted P vs NP facts into the store, then called reason to find cross-domain connections (complexity theory → cryptography → Millennium Prize). A 4B model doing compositional reasoning over stored knowledge — the HRR algebra does the heavy lifting so the model just passes entity names.

Architecture

plugins/hermes-memory-store/
├── plugin.yaml       # manifest
├── __init__.py       # registration, config, tool handlers
├── store.py          # SQLite + entities + trust + vector lifecycle
├── retrieval.py      # hybrid search + probe + related + reason + contradict
├── holographic.py    # pure HRR math — zero I/O

Also: thread-safe SQLite, auto-extraction hook (opt-in), memory banks with SNR monitoring, graceful numpy-absent fallback.

Complements the built-in memory tool — memory for always-on context, fact_store for deep recall and compositional queries.

Tests

84 tests (22 pure math + 62 integration), all passing.

Closes #2184

Test plan

pytest tests/plugins/test_holographic.py -v
pytest tests/plugins/test_memory_store_plugin.py -v
Manual: add facts, probe entity, reason across entities, contradict to find conflicts
Verify numpy-absent fallback

Tests for Phase 2 holographic memory layer: 22 pure math tests (encode/bind/unbind/bundle/similarity/serialization/SNR) and 59 integration tests covering HRR vector storage, 3-signal search scoring, probe/related/reason actions, memory bank lifecycle, auto-extraction, and numpy-absent fallbacks.

Adds a memory store plugin with Holographic Reduced Representations (HRR) for algebraic fact retrieval. Unlike embedding-based approaches, HRR uses phase vectors (hashlib + numpy) with zero models, zero APIs, zero GPU. Key capabilities: - search: keyword matching via FTS5 + Jaccard + HRR 3-signal scoring - probe: single-entity recall ("what about peppi?") - related: structural adjacency ("what connects to Rust?") - reason: multi-entity composition ("what connects peppi AND backend?") This is a vector-space JOIN — no embedding DB does this. Also includes: trust scoring, entity resolution, temporal decay, thread-safe SQLite, auto-extraction hook, memory bank monitoring. 81 tests (22 pure math + 59 integration).

Detects potentially contradictory facts by finding pairs with high entity overlap but low content-vector similarity. Uses HRR phase cosine to measure content divergence — no keyword heuristics. Completes the algebraic action progression: search → probe → related → reason → contradict 84 tests passing.

Test files now try ~/.hermes/plugins/ first (local dev), then fall back to plugins/ in the repo root (CI). Fixes ImportError on fresh runners where ~/.hermes doesn't exist.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (#1811 Hindsight, #2732 RetainDB, #2933 Mem0, #3499 Byterover, #3369 OpenViking, #2351 Holographic, #727 Cognitive) to implement as plugins rather than one-off integrations.

…rface Adapts PR #2351 by dusterbloom to use the new MemoryProvider ABC. Core files (store.py, retrieval.py, holographic.py) unchanged from the original PR. The __init__.py register() function now calls ctx.register_memory_provider() instead of ctx.register_tool(). HolographicMemoryProvider implements: - initialize() — creates SQLite DB + FactRetriever - system_prompt_block() — shows fact count when active - prefetch(query) — FTS5 search for turn context - get_tool_schemas() — fact_store (9 actions) + fact_feedback - handle_tool_call() — routes to store/retriever - on_session_end() — auto-extract preferences (opt-in) - on_memory_write() — mirrors builtin memory writes as facts 39 tests (22 HRR math + 17 provider adapter), all passing.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

…rface Adapts PR NousResearch#2351 by dusterbloom to use the new MemoryProvider ABC. Core files (store.py, retrieval.py, holographic.py) unchanged from the original PR. The __init__.py register() function now calls ctx.register_memory_provider() instead of ctx.register_tool(). HolographicMemoryProvider implements: - initialize() — creates SQLite DB + FactRetriever - system_prompt_block() — shows fact count when active - prefetch(query) — FTS5 search for turn context - get_tool_schemas() — fact_store (9 actions) + fact_feedback - handle_tool_call() — routes to store/retriever - on_session_end() — auto-extract preferences (opt-in) - on_memory_write() — mirrors builtin memory writes as facts 39 tests (22 HRR math + 17 provider adapter), all passing.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

…rface Adapts PR NousResearch#2351 by dusterbloom to use the new MemoryProvider ABC. Core files (store.py, retrieval.py, holographic.py) unchanged from the original PR. The __init__.py register() function now calls ctx.register_memory_provider() instead of ctx.register_tool(). HolographicMemoryProvider implements: - initialize() — creates SQLite DB + FactRetriever - system_prompt_block() — shows fact count when active - prefetch(query) — FTS5 search for turn context - get_tool_schemas() — fact_store (9 actions) + fact_feedback - handle_tool_call() — routes to store/retriever - on_session_end() — auto-extract preferences (opt-in) - on_memory_write() — mirrors builtin memory writes as facts 39 tests (22 HRR math + 17 provider adapter), all passing.

dusterbloom force-pushed the feat/holographic-memory-store branch from 5cd517d to a8df309 Compare March 21, 2026 20:57

mraxai added 4 commits March 23, 2026 15:17

fix(tests): resolve plugin import path for CI runners

f711a69

Test files now try ~/.hermes/plugins/ first (local dev), then fall back to plugins/ in the repo root (CI). Fixes ImportError on fresh runners where ~/.hermes doesn't exist.

dusterbloom force-pushed the feat/holographic-memory-store branch from a8df309 to f711a69 Compare March 23, 2026 14:18

teknium1 mentioned this pull request Mar 29, 2026

feat(memory): add pluggable memory provider interface #3825

Closed

This was referenced Mar 31, 2026

feat(memory): pluggable memory provider interface with profile isolation #4154

Closed

feat(memory): pluggable memory provider interface with profile isolation, review fixes, and honcho CLI restoration #4623

Merged

teknium1 closed this Apr 3, 2026

NuelMabele92 mentioned this pull request May 20, 2026

[Bug] Holographic probe/reason algebraically broken: circular-mean bundle incompatible with phase-subtract unbind #29406

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(plugin): hermes-memory-store with holographic retrieval#2351

feat(plugin): hermes-memory-store with holographic retrieval#2351
dusterbloom wants to merge 4 commits into
NousResearch:mainfrom
dusterbloom:feat/holographic-memory-store

dusterbloom commented Mar 21, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dusterbloom commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Actions (simple → powerful)

How HRR works

Tested with nemotron-3-nano (4B) on Ollama

Architecture

Tests

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dusterbloom commented Mar 21, 2026 •

edited

Loading