heptagent-memory-tool-backend

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

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

Or with cargo add:

cargo add heptagent-memory-tool-backend

Quick Start

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:

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 multi-agent LLM orchestration project. Published independently to fill the Rust LLM ecosystem gap for the memory_20250818 protocol.

License

MIT — see LICENSE

heptagent-memory-tool-backend 0.1.0