EdgeHDF5 Memory

HDF5-backed persistent cognitive memory for AI agents. Use when: (1) saving conversation exchanges to long-term memory, (2) searching/recalling past conversations by semantic similarity, (3) managing agent memory files — stats, export, snapshot, WAL flush, (4) generating AGENTS.md summaries from memory. Requires the `edgehdf5` CLI binary (install via `cargo install edgehdf5-cli`).

Persistent HDF5-backed memory with vector search, BM25 hybrid retrieval, Hebbian learning, and temporal decay.

Setup

# Install the CLI (one-time)
cargo install edgehdf5-cli
# Or from source:
cargo install --path crates/edgehdf5-cli

Set EDGEHDF5_PATH env var or pass --path <file.h5> to every command.

Commands

All output is JSON for easy parsing.

Create a memory file

edgehdf5 --path agent.h5 create --agent-id myagent --dim 384 --wal

Save an entry

Pass JSON via --json or stdin:

edgehdf5 --path agent.h5 save --json '{"chunk":"User asked about weather","embedding":[0.1,0.2,...],"source_channel":"discord","timestamp":1700000000.0,"session_id":"s1","tags":"weather"}'

Embedding must match the dimension specified at creation.

Search memory

edgehdf5 --path agent.h5 search --embedding '[0.1,0.2,...]' --query 'weather forecast' -k 5

Optional: --vector-weight 0.7 --keyword-weight 0.3 (defaults).

Recall a specific entry

edgehdf5 --path agent.h5 recall 42

Stats

edgehdf5 --path agent.h5 stats

Returns: count, active entries, WAL pending, config details.

Flush WAL

edgehdf5 --path agent.h5 flush-wal

Generate AGENTS.md

edgehdf5 --path agent.h5 agents-md
# Or write to file:
edgehdf5 --path agent.h5 agents-md --output AGENTS.md

Export all entries

edgehdf5 --path agent.h5 export

Outputs one JSON object per line (JSONL).

Snapshot

edgehdf5 --path agent.h5 snapshot backup.h5

Workflow: Saving Conversations

1. After each exchange, construct a MemoryEntry JSON with the conversation chunk and its embedding vector
2. Pipe to edgehdf5 save
3. The WAL (if enabled) ensures low-latency writes — flush periodically with flush-wal

Workflow: Recalling Context

1. Embed the current query using your embedding model
2. Run edgehdf5 search --embedding '[...]' --query 'user text' -k 10
3. Use returned chunks as context for the response

Notes

• Embeddings must be generated externally (e.g., via an embedding API or local model)
• The .h5 file is a standard HDF5 file readable by any HDF5 library
• WAL files are stored alongside the .h5 file as <name>.h5.wal