edgehdf5-memory

HDF5 支持的 AI 代理持久认知记忆。在以下情况下使用：(1) 将对话交换保存到长期记忆中，(2) 通过语义相似性搜索/回忆过去的对话，(3) 管理代理内存文件 — 统计、导出、快照、WAL 刷新，(4) 从内存生成 AGENTS.md 摘要。需要 `edgehdf5` CLI 二进制文件（通过 `cargo install edgehdf5-cli` 安装）。

## 概述（中文）

HDF5 支持的 AI 代理持久认知记忆。在以下情况下使用：(1) 将对话交换保存到长期记忆中，(2) 通过语义相似性搜索/回忆过去的对话，(3) 管理代理内存文件 — 统计、导出、快照、WAL 刷新，(4) 从内存生成 AGENTS.md 摘要。需要 `edgehdf5` CLI 二进制文件（通过 `cargo install edgehdf5-cli` 安装）。

## 原文

# EdgeHDF5 Memory

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

## Setup

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

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

### Save an entry

Pass JSON via `--json` or stdin:

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

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

```bash
edgehdf5 --path agent.h5 recall 42
```

### Stats

```bash
edgehdf5 --path agent.h5 stats
```

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

### Flush WAL

```bash
edgehdf5 --path agent.h5 flush-wal
```

### Generate AGENTS.md

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

### Export all entries

```bash
edgehdf5 --path agent.h5 export
```

Outputs one JSON object per line (JSONL).

### Snapshot

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