hermes-semantic-memory 0.1.0

Semantic memory provider for Hermes Agent — float16 embeddings with Q4 quantization

hermes-semantic-memory

Semantic memory provider for Hermes Agent. Stores conversation turns as float16 embedding vectors and retrieves by semantic similarity — not keyword matching.

Why

Hermes built-in FTS5 memory searches for exact words. "What database do we use?" cannot match "we migrated to Postgres" because the word "database" isn't in the stored text.

hermes-semantic-memory encodes each turn into a 384-dim vector that captures semantic meaning. Float16 storage gives 2x compression vs FP32 with zero retrieval quality loss (Kendall tau 0.99).

Provider	Recall@5	MRR	Semantic Gap@5
FTS5 (built-in)	0.422	0.265	0.000
hermes-semantic-memory	0.967	0.599	0.933

2.3x recall. 93% prompt bloat reduction at 100 stored turns.

Install

pip install hermes-semantic-memory[embeddings]

This installs sentence-transformers (~80MB, CPU-only). For API-based embeddings:

pip install hermes-semantic-memory

Configure

Add to ~/.hermes/config.yaml:

memory:
  provider: kv_memory

plugins:
  hermes_semantic_memory:
    embedding_backend: auto
    top_k: 5
    storage_mode: fp16

Usage

No explicit memory commands needed. Every turn is captured automatically via a post_llm_call hook. Semantically relevant past turns are prefetched and injected into context before each API call.

hermes -z "My DB password is xyz123, remember it" --yolo
hermes -z "What is my database password?" --yolo
# Agent recalls "xyz123" via hermes_semantic_memory prefetch

Backends

Backend	Config	Notes
sentence-transformers	embedding_backend: auto	Default. all-MiniLM-L6-v2, ~80MB, CPU, ~5ms/turn
api	embedding_backend: api	OpenAI-compatible embedding API

Run Tests

pip install hermes-semantic-memory[dev]
python -m pytest hermes_semantic_memory/tests/ -v
# 60 passed

Benchmarks

python benchmarks/unified_benchmark.py

Measures semantic search recall, prompt bloat, and storage efficiency vs built-in FTS5.

License

MIT