Persistent, SQLite-backed memory for Hermes Agent.
No server. No daemon. No vector DB. One-line install. Pure SQLite + Python stdlib.
Keywords: hermes-memory-enhancer, sqlite-memory, agent-memory, hermes-plugin, persistent-memory, hermes-agent, semantic-search, self-hosted-memory

bash install.sh → Hermes remembers everything. Done.

About this project: 450 lines of Python. One dependency (PyYAML — for the installer only). No server. No daemon. No Docker. No cloud. No API keys. No vector DB. Just a single SQLite file and the Hermes plugin interface. We believe agent memory should be a plugin, not an infrastructure project. Thirty seconds from git clone to your first remembered fact.

Hermes Agent has no long-term memory. Every session starts from scratch. You tell it the same project context, the same research findings, the same infrastructure details — over and over.

Existing solutions are overkill:

• Vector DBs (Chroma, Qdrant) → server, pip install, embeddings API, Docker
• LangChain memory → framework lock-in, heavyweight
• Flat markdown files → no search, no structure, manual curation

This is different. It's not a vector DB. It's not a wiki. It's a persistent knowledge base that Hermes queries automatically — session to session, agent to agent, project to project.

We intentionally don't try to do everything. We specialize in the simplest possible memory for the two agents that power your daily workflow: your conversation agent (Hermes) and your coding agent (Codex). If you use both, you get a unified memory philosophy across both tools — without the complexity of MCP, vector DBs, or cloud APIs.

Memories survive across sessions. When you tell Hermes something important, it stays — no more repeating the same context.

Data is organized as memory:// URIs:

memory://
├── user/hermes/
│ ├── memories/ ← Extracted and explicitly remembered facts
│ └── skills/ ← Procedural knowledge
└── resources/ ← Imported local files

Browse it like a filesystem: memory_enhancer_browse(action="tree")

SQLite FTS5 ranks results by relevance. Search across memories, resources, and skills in one query.

memory_enhancer_search(query="deployment config")

Three detail levels — start with a summary, drill down only when needed:

• Abstract (L0) — ~100 tokens, skim the gist
• Overview (L1) — ~2k tokens, key points
• Full (L2) — complete content

Memories carry an importance score. Future support for priority-based context injection.

memory_enhancer_stats()

Returns: total memories, category distribution, importance distribution, session count, message count, DB size.

Connect memories with typed relations (semantic + temporal) and visualize the graph — no external database needed.

# Point L3 to the same DB as the plugin
export L3_DB_PATH=~/.hermes/memory_enhancer/memory.sqlite3
# Tag a memory URI
python3 scripts/l3.py tag add "memory://user/hermes/memories/1" "gwas"
# Relate two nodes (semantic relations)
python3 scripts/l3.py relate \
 "memory://user/hermes/memories/1" \
 "memory://user/hermes/memories/2" informs
# Relate two nodes with temporal ordering
python3 scripts/l3.py relate \
 "memory://user/hermes/memories/1" \
 "memory://user/hermes/memories/2" precedes
# Trace connections (optionally filter by relation type)
python3 scripts/l3.py trace "memory://user/hermes/memories/1" --depth 3
python3 scripts/l3.py trace "memory://user/hermes/memories/1" precedes
# Temporal timeline — follow precedes/follows chains
python3 scripts/l3.py timeline "memory://user/hermes/memories/1"
# Generate interactive HTML graph
python3 scripts/l3_graph.py graph.html --db ~/.hermes/memory_enhancer/memory.sqlite3

L3 creates three tables (l3_tags, l3_node_tags, l3_relations) alongside your existing memory schema — zero schema changes to your data.

Relation types:

• Semantic: informs, supports, contradicts, extends, built-from, related_to
• Temporal: precedes (source before target), follows (source after target), contemporaneous (same time period)

Use temporal types to build a chronological knowledge graph — the timeline command traces precedes/follows chains automatically, surfacing "what happened before/after this" relationships across stored memories.

API keys, tokens, and passwords are automatically redacted from sync payloads and search results. Opt-out via MEMORY_ENHANCER_REDACT_SECRETS=false.

# What you DON'T need:
# ❌ pip install chromadb
# ❌ pip install qdrant-client
# ❌ docker pull qdrant/qdrant
# ❌ OPENAI_API_KEY for embeddings
# ❌ A server process
# ❌ A REST API
# What you DO need:
# ✅ Python 3.10+ (stdlib + PyYAML for install script)

Your memory is a single SQLite file. Copy it, back it up, move it anywhere.

# Back up
cp ~/.hermes/memory_enhancer/memory.sqlite3 backup.sqlite3
# Move to new machine
scp user@old-server:.hermes/memory_enhancer/memory.sqlite3 .

git clone <repo-url>
cd hermes-memory-enhancer
bash plugins/memory/hermes_memory_enhancer/install.sh

What the installer does:

1. Registers hermes_memory_enhancer as Hermes' memory provider
2. Creates the SQLite database at ~/.hermes/memory_enhancer/memory.sqlite3
3. Adds MEMORY_ENHANCER_* environment variables to your Hermes profile .env

Then restart your gateway. Done.

Once installed, Hermes exposes these tools to the agent:

Full-text search across the knowledge base. Returns ranked results with memory:// URIs.

Read content at a memory:// URI. Level: abstract (L0), overview (L1), or full (L2).

Filesystem-style navigation. Actions: list, tree, stat.

Store a durable fact. Automatically categorized and indexed immediately.

Returns memory statistics: totals, categories, importance distribution, DB size.

Import a local file into the knowledge base. Disabled by default — requires MEMORY_ENHANCER_ENABLE_ADD_RESOURCE=true and MEMORY_ENHANCER_ALLOWED_UPLOAD_ROOTS.

# Session start — check what's stored
memory_enhancer_stats
# Remember a finding
memory_enhancer_remember(content="GWAS summary stats at ~/data/B003/sumstats.txt", category="entity")
# Later — search before asking
memory_enhancer_search(query="GWAS B003")
# Browse the knowledge tree
memory_enhancer_browse(action="tree")
# Import a reference document
memory_enhancer_add_resource(url="/home/user/papers/review.pdf", reason="Literature review for B003 project")

Hermes session
 ↓
Hermes memory-provider interface
 ↓
Hermes Memory Enhancer plugin (this repo — ~450 lines of Python)
 ↓ (direct SQLite — no network)
Local SQLite database (~/.hermes/memory_enhancer/memory.sqlite3)

The plugin connects Hermes directly to a local SQLite database. There is no external server, no REST API, no Docker container — everything stays on your filesystem.

When a session ends, user messages starting with [Remember] are automatically extracted into the memories table. You can also use memory_enhancer_remember directly.

* PyYAML required only for install/remove scripts

Environment variables in your Hermes profile .env:

Memory Enhancer works alongside Hermes' built-in per-agent memory files (MEMORY.md / USER.md).

Why this matters: Per-agent memory files are automatically injected every turn — ideal for identity, rules, and preferences. The Memory Enhancer DB stores shared knowledge that is queried when needed. Use both together.

• Hermes Agent installed
• Python 3.10+ with built-in sqlite3 module
• PyYAML only for install.sh / remove.sh (install via pip install PyYAML)
• OS: Linux, macOS, Windows WSL

After installing this plugin, add the following instruction to your agent's SOUL.md, AGENTS.md, or equivalent configuration file:

Primary memory system: Use memory_enhancer_* tools (search, remember, browse, read, stats) over the basic memory tool. The basic memory tool is for identity and critical rules only — it is injected every turn. Use memory_enhancer_* for everything else: it is searchable, shared across agents, and does not bloat context.

Session start: Call memory_enhancer_stats or memory_enhancer_search to restore context before asking the user to catch up.

During session: Call memory_enhancer_remember for every important fact, decision, or finding.

Session end: Ensure critical new facts are saved. The plugin auto-extracts [Remember] messages, but explicit memory_enhancer_remember calls are more reliable.

See AGENTS.md in this repository for the complete agent guidelines.

hermes-memory-enhancer/
├── AGENTS.md ← Agent guidelines (read this if you're an AI)
├── README.md ← This file
├── SECURITY.md ← Security policy
├── LICENSE ← MIT
├── scripts/
│ ├── l3.py ← L3 CLI
│ └── l3_graph.py ← HTML graph generator
├── plugins/memory/hermes_memory_enhancer/
│ ├── __init__.py ← MemoryProvider plugin (~450 lines)
│ ├── plugin.yaml ← Plugin metadata
│ ├── install.sh ← One-shot install script
│ └── remove.sh ← Clean removal
└── tests/
 ├── plugins/memory/
 │ ├── test_hermes_memory_enhancer_provider.py
 │ └── test_security_defaults.py
 └── hermes_memory_enhancer_plugin/
 └── test_hermes_memory_enhancer.py

v2.0 is fully backward-compatible. Existing v1 databases are automatically migrated on first access:

• importance column added to memories (default: 3)
• expires_at column added (reserved for future TTL support)
• New memory_enhancer_stats tool available

No manual migration needed.

See SECURITY.md for the full security policy.

Key defaults:

• File import requires explicit MEMORY_ENHANCER_ALLOWED_UPLOAD_ROOTS
• Secret redaction is on by default
• Do not store passwords, API keys, raw PHI/PII, or regulated data

• TTL-based auto-expiry for memories
• Memory consolidation (merge duplicates)
• L3 graph web app (auto-refresh)
• Per-project namespace isolation
• Optional sentence-transformers semantic search

PRs welcome. Ideas welcome.

memory-enhancer is part of a zero-dependency Hermes tool suite:

All three are zero-dependency Python tools that use SQLite under the hood.

• Codex CLI Memory Enhancer — the same memory system, adapted for OpenAI Codex CLI, with L3 graph layer included
• Hermes Agent — the multi-provider agent framework this plugin extends
• SQLite FTS5 — the search engine behind it all. No vector DB needed.