heptagent-memory-tool-backend 0.1.0

Rust backend for the Anthropic memory_20250818 tool-call protocol — 6-command dispatcher with redb persistence + per-quest rate limiter. Not affiliated with Anthropic, PBC.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# heptagent-memory-tool-backend

[![Crates.io](https://img.shields.io/crates/v/heptagent-memory-tool-backend.svg)](https://crates.io/crates/heptagent-memory-tool-backend)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Rust backend for the Anthropic `memory_20250818` tool-call protocol.**

> **Not affiliated with or endorsed by Anthropic, PBC.** This is a community implementation
> of the open `memory_20250818` tool-call protocol for use in Rust LLM agent frameworks.

Fills a gap in the Rust LLM ecosystem: as of 2026-05-24, the `memory_20250818`
tool-call protocol has 51 type definitions but no published Rust backends. This crate
provides a production-ready implementation with redb persistence + per-quest rate limiting.

## What is `memory_20250818`?

`memory_20250818` is a memory tool protocol for LLM agents (Workers). Workers
emit structured tool-calls to read and write persistent memory files across reasoning steps
and sessions. The protocol defines 6 file operations via JSON tool-call messages.

## Installation

```toml
[dependencies]
heptagent-memory-tool-backend = "0.1"
```

Or with `cargo add`:

```bash
cargo add heptagent-memory-tool-backend
```

## Quick Start

```rust
use heptagent_memory_tool_backend::{
    MemoryCommand, MemoryDispatcher, QuestRateLimiter, RedbMemoryBackend,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open (or create) redb database
    let backend = RedbMemoryBackend::new(std::path::Path::new("memory.redb"))?;
    let rate_limiter = QuestRateLimiter::new(20); // 20 calls per quest

    let dispatcher = MemoryDispatcher::new(backend, rate_limiter);

    // Worker emits a Create tool-call
    let result = dispatcher.dispatch(MemoryCommand::Create {
        path: "project/decisions.md".to_string(),
        file_text: "Always use kebab-case for file names.".to_string(),
    }).await;

    assert!(!result.is_error, "Create failed: {}", result.content);

    // Worker emits a View tool-call
    let view = dispatcher.dispatch(MemoryCommand::View {
        path: "project/decisions.md".to_string(),
        view_range: None,
    }).await;

    println!("Memory content: {}", view.content);
    Ok(())
}
```

## 6-Command Reference

| Command | Fields | Description |
|---|---|---|
| `view` | `path`, `view_range?` | Read file content, optionally line-ranged (1-indexed) |
| `create` | `path`, `file_text` | Create new file (fails if path exists — T-FP-02 spec compliance) |
| `str_replace` | `path`, `old_str`, `new_str` | Replace first occurrence of `old_str` |
| `insert` | `path`, `insert_line`, `insert_text` | Insert text after line N (0 = prepend) |
| `delete` | `path` | Delete file |
| `rename` | `old_path`, `new_path` | Rename file |

## Rate Limiter (D-C-03)

`QuestRateLimiter` enforces a hard cap of N calls per quest (default 20) using
an `AtomicU32` — lock-free and race-safe under concurrent Workers:

```rust
let rate_limiter = QuestRateLimiter::new(20);
// After 20 calls, dispatch() returns MemoryResult { is_error: true, content: "rate limit exceeded" }

// Reset at quest boundary:
dispatcher.reset_for_new_quest();
```

## Architecture

```
Worker tool-call JSON
        ↓
MemoryCommand (serde strict — unknown commands → error)
        ↓
MemoryDispatcher<B: MemoryBackend>
        ├── QuestRateLimiter (AtomicU32, 20 calls/quest)
        └── MemoryBackend (async trait)
            ├── RedbMemoryBackend (v0.1 — embedded ACID KV)
            └── (planned: MegrezVaultBackend — age-encrypted cold storage)
```

## Security

- **Path traversal**: rejects `..`, `/`-prefix, `\`-prefix, empty paths
- **Strict deserialization**: unknown `command` variants → serde error (no fallthrough)
- **Spec compliance**: `create()` fails on existing paths (PathExists error) — no silent overwrite
- **Rate limiting**: `AtomicU32` fetch_add — race-safe under 100 concurrent Workers
- **Zero-knowledge tracing**: `#[instrument(skip(...))]` on all plaintext fields

## Feature Flags

None in v0.1. Planned:

- `megrez-backend` — age-encrypted Megrez vault backend (K-02+)
- `lancedb-backend` — Tier 3 semantic search backend (K-03+)

## Part of heptagent

This crate is part of the [heptagent](https://github.com/easyinplay/heptagent-cli)
multi-agent LLM orchestration project. Published independently to fill the Rust LLM
ecosystem gap for the `memory_20250818` protocol.

## License

MIT — see [LICENSE](LICENSE)