Hermes Hybrid Memory - Setup Guide

Repo: sheldon904/hermes-hybrid-memory Author: sheldon904 License: MIT Requires: Python 3.11+, Hermes Agent, sqlite-vec

Overview

Hybrid Memory replaces flat system-prompt memory with a unified store combining:

1. Structured facts (FTS5 full-text search)
2. Semantic vector recall (sqlite-vec, 384-dim embeddings)
3. Knowledge graph (nodes + edges, incrementally maintained)

Plus Hofstadter-inspired mechanisms: analogy slot, emergent chunking, and usage-driven forgetting. All in one SQLite file.

Architecture

documents in ──▶ memory_ingest.py ──▶ entity_resolve.py
                       │
                       ▼
              memory_store.db (SQLite)
              ┌──────────────────────────┐
              │ facts + FTS5 + trust     │
              │ sqlite-vec vectors       │
              │ graph (nodes/edges)      │
              └──────────────────────────┘
                       │
                       ▼
              memory_retrieve.py
              (keyword / vector / graph / analogy)

Step 1: Prerequisites

# Verify Python version
python3 --version  # must be 3.11+

# Install sqlite-vec extension
pip install sqlite-vec

# Verify Hermes Agent is installed
hermes --version

Step 2: Clone and Install

# Clone into your Hermes plugins directory
mkdir -p ~/.hermes/plugins/
cd ~/.hermes/plugins/
git clone https://github.com/sheldon904/hermes-hybrid-memory.git
cd hermes-hybrid-memory

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
python3 -c "import hybrid_memory; print('OK')"

Step 3: Configure Hermes Agent

Add to your ~/.hermes/config.yaml:

# Memory provider configuration
memory:
  provider: hybrid_memory
  store_path: ~/.hermes/memory/memory_store.db

  # Optional: custom embedding model
  embedding:
    model: all-MiniLM-L6-v2  # default, 384-dim
    # Or use any sentence-transformers compatible model

  # Optional: tuning
  hybrid:
    graph_weight: 0.3        # graph traversal weight in retrieval
    vector_weight: 0.4       # semantic similarity weight
    keyword_weight: 0.3      # FTS5 keyword weight
    analogy_threshold: 0.7   # minimum similarity for analogy match
    chunking_interval: 50    # facts before emergent chunking triggers
    forgetting_decay: 0.95   # per-day decay factor (1.0 = no decay)

Step 4: Initialize the Memory Store

# Create the memory directory
mkdir -p ~/.hermes/memory/

# Initialize the database
python3 ~/.hermes/plugins/hermes-hybrid-memory/scripts/init_store.py \
  --db-path ~/.hermes/memory/memory_store.db

# Expected output:
# ✓ Created facts table with FTS5 index
# ✓ Created vector store (384-dim)
# ✓ Created graph tables (nodes, edges)
# ✓ Memory store ready at ~/.hermes/memory/memory_store.db

Step 5: Memory Ingestion Pipeline

Hybrid Memory uses an ingestion pipeline that runs as a side effect of normal memory writes:

# Manual ingestion (for testing / backfill)
python3 ~/.hermes/plugins/hermes-hybrid-memory/memory_ingest.py \
  --db-path ~/.hermes/memory/memory_store.db \
  --input-dir ~/.hermes/memory/inbox/ \
  --llm-model sonnet

# The ingest pipeline:
# 1. LLM distills facts + graph nodes/edges from documents
# 2. entity_resolve.py canonicalizes entity names
# 3. Facts written to FTS5 + vector store
# 4. Graph nodes/edges updated incrementally

Documents can be placed in ~/.hermes/memory/inbox/ as: - .txt files (plain text) - .md files (markdown notes) - .json files (structured facts) - .jsonl files (pre-distilled facts from upstream agents)

The ingestion runs automatically during Hermes sessions when memory_provider: hybrid_memory is configured.

Step 6: Verify Memory Is Working

# Start Hermes with hybrid memory
hermes --profile <your-profile>

# In a Hermes session, test memory operations:
# "Remember: the API key for Stripe is sk_live_xxx"
# "What's our Stripe API key?"
# "What else do you know about our payment infrastructure?"

# Check the memory store directly
python3 ~/.hermes/plugins/hermes-hybrid-memory/scripts/query_store.py \
  --db-path ~/.hermes/memory/memory_store.db \
  --query "Stripe payment" \
  --mode hybrid  # uses keyword + vector + graph

Step 7: Brain Visualization

Hybrid Memory ships with a visualization tool:

# Generate interactive brain graph
python3 ~/.hermes/plugins/hermes-hybrid-memory/brain_viz.py \
  --db-path ~/.hermes/memory/memory_store.db \
  --output ~/.hermes/memory/brain_snapshot.html

# Open in browser
open ~/.hermes/memory/brain_snapshot.html

The brain visualization is a self-contained HTML file showing: - All entity nodes (color-coded by type) - Edge connections (weight = relationship strength) - Search and filter by entity type - Click any entity to see its facts and connections - Prospect leaves can be hidden

Key Mechanisms

Analogy Slot

The Hofstadter-inspired analogy mechanism finds memories that are structurally similar but superficially different. Example: "Which of our leads looks most like our best client?" - the system matches on relationship patterns (lead→discovery→trial→purchase) rather than surface text similarity.

Emergent Chunking

After every ~50 facts, the system looks for patterns that can be compressed into reusable categories. A chunk is a named concept that replaces the raw facts it subsumes, saving retrieval cost and improving recall quality.

Usage-Driven Forgetting

Memory decay is driven by usage frequency, not age. A fact accessed daily never decays. A fact never accessed decays slowly (configurable forgetting_decay rate). Facts that drop below a threshold are pruned. This is a deliberate departure from the common "recency-weighted" approach.

Production Tuning

# For agents with high memory volume (>10K facts)
hybrid:
  graph_weight: 0.4        # more graph, less keyword
  vector_weight: 0.35
  keyword_weight: 0.25
  chunking_interval: 100   # chunk less frequently
  forgetting_decay: 0.98   # slower decay

# For agents with sparse memory (<1K facts)  
hybrid:
  graph_weight: 0.2
  vector_weight: 0.5       # rely more on semantic similarity
  keyword_weight: 0.3
  chunking_interval: 30    # chunk more aggressively
  forgetting_decay: 0.90   # faster decay to keep store lean

Troubleshooting

"sqlite-vec extension not found"

pip install sqlite-vec
# If that fails, install from source:
pip install git+https://github.com/asg017/sqlite-vec.git

"Memory store locked"

The store uses WAL mode for concurrent reads. If you get a lock error:

# Check for stale locks
sqlite3 ~/.hermes/memory/memory_store.db "PRAGMA wal_checkpoint(TRUNCATE);"

"Empty retrieval results"

1. Verify facts are being ingested: python3 scripts/query_store.py --mode stats
2. Check embedding dimension matches (384-dim default)
3. Ensure the Hermes session has write access to memory_store.db

"Slow retrieval with large stores"

1. Run VACUUM: sqlite3 memory_store.db "VACUUM;"
2. Increase chunking_interval to reduce fact count
3. Consider archiving old, never-accessed facts

Integration with Other Memory Systems

Hybrid Memory can coexist with Honcho or other memory systems. Configure Hermes to use Hybrid Memory as the primary memory_provider while Honcho handles session-level context:

memory:
  provider: hybrid_memory
  store_path: ~/.hermes/memory/memory_store.db

# Honcho still handles session context
honcho:
  enabled: true
  session_db: ~/.hermes/honcho/sessions.db

---

Setup guide created by CorpusIQ. Repo maintained by sheldon904. Contributions welcome.

Integration with CorpusIQ

CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.

This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.

See what CorpusIQ connects