Metadata-Version: 2.4
Name: hermes-semantic-memory
Version: 0.1.0
Summary: Semantic memory provider for Hermes Agent — float16 embeddings with Q4 quantization
Project-URL: Homepage, https://github.com/RUFFY-369/hermes-semantic-memory
Project-URL: Repository, https://github.com/RUFFY-369/hermes-semantic-memory
Project-URL: Issues, https://github.com/RUFFY-369/hermes-semantic-memory/issues
Author-email: Prakarsh Kaushik <ruffy-369@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: embeddings,hermes,memory,semantic-search,sentence-transformers
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.0; extra == 'embeddings'
Description-Content-Type: text/markdown

# hermes-semantic-memory

Semantic memory provider for [Hermes Agent](https://github.com/NousResearch/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

```bash
pip install hermes-semantic-memory[embeddings]
```

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

```bash
pip install hermes-semantic-memory
```

## Configure

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

```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.

```bash
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

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

## Benchmarks

```bash
python benchmarks/unified_benchmark.py
```

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

## License

MIT
