RBMEM

Structured, temporal, graph-aware memory for AI agents.

RBMEM is a file format and Rust library for managing agent memory with stable section paths, protected timestamps, hierarchical organization, graph relationships, and IDF-weighted context retrieval optimized for LLM consumption.

Why RBMEM?

Markdown is human-readable but lacks structure. Agents need:

Stable identifiers — Section paths like agents.reader.capabilities don't change when content is rewritten
Temporal awareness — Tool-protected timestamps prevent models from inventing history
Graph relationships — Explicit edges between concepts, not just prose links
Hierarchical inheritance — Parent sections provide context to children
Compact output — Minified views for context windows without losing metadata on disk
Provenance tracking — Know where each section came from and when it was updated
Precision retrieval — IDF-weighted scoring finds the right sections in 38µs, not the whole file

Features

IDF-weighted query precision — Rare terms score higher, common terms score lower; 3.8× more precise than Markdown
Section-level operations — Query, update, delete, encrypt individual sections
Graph-aware retrieval — Follow relationships to find related context (100% neighbor recall)
SAT planning — Built-in planner with Kissat/CaDiCaL support and DPLL fallback with VSIDS
AES-256-GCM encryption — Per-section encryption for sensitive data
Hermes integration — Native support for Hermes agent workflows
Markdown conversion — Import from Markdown with automatic graph inference
Context packs — Reusable context configurations via .rbmempacks
HTTP server — Axum-based REST API for agent runtimes
Multiple output modes — Canonical, compact, minified, JSON, YAML
Three-way merge — Section-level conflict resolution
MCP server (RBForge) — Runtime tool creation for agents via Model Context Protocol

Benchmark Results

RBMEM outperforms plain Markdown for agent memory tasks:

Metric	RBMEM	Markdown	Improvement
Precision	24.3%	6.4%	3.8× better
Recall	81.7%	100% (full dump)	Targeted retrieval
Graph-aware recall	100%	N/A	Unique capability
F1 Score	0.375	0.312 (keyword)	1.2× better
Token efficiency	70.3% savings	baseline	Smarter context
Query latency	38 µs	23 µs (grep)	1.7× slower, richer results

Benchmark: 46 sections, 15 queries, 100 iterations. See benchmark methodology.

Quick Start

Installation

git clone https://github.com/DJLougen/Rust-Brain.git
cd Rust-Brain
cargo build --release

The binary is at target/release/rbmem.

Basic Usage

Create a memory file:

rbmem create memory.rbmem

Add a section:

rbmem update memory.rbmem \
  --section project.rules \
  --type list \
  --content "- Prefer small, tested changes"

Query for relevant context:

rbmem query memory.rbmem "project rules" --resolve --minified

Agent Context

Get the smallest useful context for an LLM:

rbmem context memory.rbmem \
  --task "review this pull request" \
  --resolve --minified --graph-depth 1

Use context packs for repeatable workflows:

# Define in .rbmempacks
[pack: code_review]
include:
  - project.rules
  - memory.user.preferences
query: "pull request testing"
graph_depth: 1
mode: minified

# Load the pack
rbmem pack memory.rbmem code_review --resolve

## MCP Server

RBForge is an MCP (Model Context Protocol) server that exposes RBMEM as a tool to AI agents. It enables runtime tool creation, validation, and persistent storage through the `rbmem` CLI.

**Key capabilities:**

- **Runtime tool creation** — Agents can forge, validate, and save custom tools into RBMEM
- **MCP integration** — Works with Claude, Cursor, and other MCP-compatible agents
- **Tool registry** — Index, metrics, and graph relationships for all forged tools
- **178 passing tests** — Comprehensive test suite for reliability

**Quick start:**

```bash
cd mcp-server
python -m pip install -e .[dev]
export RBMEM_CLI=/path/to/rbmem
rbforge doctor memory.rbmem

See mcp-server/README.md for full documentation and examples.

Architecture

RBMEM is organized as a Rust library with a CLI wrapper:

CLI (main.rs) — Command parsing and user interaction
Library modules — Hermes integration, SAT planner, Markdown sync, context packs, conversion
Core (document.rs) — Document model, sections, graph, temporal metadata
Query engine (commands.rs + index.rs) — IDF-weighted scoring, section index, graph traversal
Infrastructure — Parser (parser.rs), encryption (crypto.rs), diff/merge (diff.rs), HTTP server (server/)
Storage — .rbmem files, section index, AES-256-GCM encrypted sections
MCP server (mcp-server/) — RBForge runtime tool creation for agents

See docs/ARCHITECTURE.md for detailed design.

Usage

SAT Planning

Generate plans from goals, tasks, and constraints:

# Plan from explicit goal
rbmem plan "deploy agent release" --file memory.rbmem

# Derive goal from memory
rbmem plan --from-memory --file memory.rbmem

# Use external solver
rbmem plan "deploy" --solver kissat --proof --verify-proof

The planner writes results to plans.<goal>.<timestamp>.* sections with full provenance.

Graph Relationships

RBMEM infers relationships from content and hierarchy:

# Infer relations during conversion
rbmem convert-from-md notes.md memory.rbmem --infer-relations

# Visualize the graph
rbmem export memory.rbmem --format mermaid
rbmem export memory.rbmem --format dot

Inference strategies: off, explicit, balanced (default), aggressive.

Encryption

Protect sensitive sections with AES-256-GCM:

# Set encryption key
export RBMEM_ENCRYPTION_KEY="<base64-encoded-32-byte-key>"

# Encrypt a section
rbmem encrypt memory.rbmem --section secrets.api

# Query with decryption
rbmem query memory.rbmem "api credentials" --decrypt

Encrypted sections are skipped by default. Use --decrypt to include them.

Markdown Sync

Keep Markdown files in sync with RBMEM:

# One-time conversion
rbmem sync ./notes ./memory --infer-relations

# Watch for changes
rbmem sync ./notes ./memory --watch --infer-relations

Hermes Integration

Native support for Hermes agent workflows:

# Initialize Hermes memory
rbmem hermes init my-agent

# Load context for agent
rbmem hermes load my-agent.rbmem --resolve --minified

# Save agent updates
rbmem hermes save my-agent.rbmem --json '{
  "sections": [{
    "path": "memory.observations",
    "type": "hermes:memory",
    "content": "- User prefers concise responses",
    "mode": "append"
  }]
}'

# Plan with SAT solver
rbmem hermes plan my-agent.rbmem --goal "deploy release"

See HERMES.md for complete agent integration guide.

HTTP Server

Run RBMEM as a REST API:

rbmem serve --bind localhost:3000 --dir ./memories

Endpoints: /health, /memories, /memories/:name/sections, /query, /context, /diff, /merge, /export.

Rust Library API

Use RBMEM as a Rust library:

use rbmem::{create, query, update, ContextOptions, SectionType};

// Create a memory file
create("memory.rbmem", CreateOptions {
    created_by: "agent".to_string(),
    purpose: "personal-agent-memory".to_string(),
    ..Default::default()
})?;

// Add a section
update("memory.rbmem", UpdateOptions {
    section: "agents.reader".to_string(),
    section_type: SectionType::Text,
    content: "Reads memory carefully.".to_string(),
    ..Default::default()
})?;

// Query for context
let context = query("memory.rbmem", "reader", ContextOptions {
    resolve: true,
    minified: true,
    graph_depth: 1,
    ..Default::default()
})?;

See docs/API.md for complete API reference.

Command Reference

Command	Description
`create <file>`	Create a new RBMEM document
`read <file>`	Read and display a document
`update <file> --section <path>`	Add or update a section
`delete-section <file> --section <path>`	Remove a section
`query <file> <text>`	Query for relevant sections
`context <file> --task <text>`	Assemble task-specific context
`pack <file> <name>`	Load a named context pack
`plan <goal>`	Generate a SAT plan
`convert-from-md <in> <out>`	Convert Markdown to RBMEM
`sync <md-dir> <rbmem-dir>`	Sync Markdown folder
`infer <file>`	Infer graph relations
`encrypt <file> --section <path>`	Encrypt a section
`decrypt <file> --section <path>`	Decrypt a section
`diff <before> <after>`	Compare two documents
`merge <base> <local> <remote>`	Three-way merge
`review <file>`	Validate and flag changes
`doctor <file>`	Check document health
`tree <file>`	Show section hierarchy
`timeline <file>`	Show temporal entries
`graph <file>`	Export graph (JSON/DOT)
`export <file> --format <fmt>`	Export to Mermaid/Cytoscape/GEXF
`serve --bind <addr>`	Start HTTP server
`hermes load <file>`	Load Hermes context
`hermes save <file> --json <payload>`	Save Hermes updates
`hermes plan <file> --goal <goal>`	Plan with Hermes
`hermes doctor <file>`	Check Hermes memory health

Add --format json to any command for machine-readable output.
Add --resolve to apply hierarchical inheritance.
Add --minified for compact LLM context.
Add --graph-depth N to include N levels of graph neighbors.

File Format

RBMEM files are plain text with structured sections:

rbmem# RBMEM v1.4.0 - Rust-Brain Memory Format

meta:
  version: 1.4.0
  purpose: "agent-memory"
  generated_at: "2026-05-20T10:00:00Z"
  last_updated: "2026-05-20T10:00:00Z"

[SECTION: project.rules]
type: list
temporal:
  created_at: "2026-05-20T10:00:00Z"
  updated_at: "2026-05-20T10:00:00Z"
content: |
  - Prefer small, tested changes
  - Preserve user intent
[END SECTION]

[SECTION: agents.reader]
type: text
temporal:
  created_at: "2026-05-20T10:00:00Z"
  updated_at: "2026-05-20T10:00:00Z"
content: |
  Reads memory carefully and respects timestamps.
[END SECTION]

Development

# Build
cargo build

# Test
cargo test --all-features

# Lint
cargo clippy --all-targets --all-features -- -D warnings

# Format
cargo fmt --check

# Benchmark
cargo bench --bench rbmem_vs_markdown -- --nocapture

**Test coverage**: 107 Rust tests (14 suites) + 178 Python tests (MCP server) = **285 tests** total.

```bash
# MCP server tests
cd mcp-server && python -m pytest

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Roadmap

Acknowledgments

Built with Rust, Clap, Axum, and Petgraph.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github		.github
benches		benches
docs		docs
examples		examples
mcp-server		mcp-server
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
HERMES.md		HERMES.md
LICENSE		LICENSE
README.md		README.md
architecture_v2.png		architecture_v2.png
banner.png		banner.png
benchmark_results.png		benchmark_results.png

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RBMEM

Why RBMEM?

Features

Benchmark Results

Quick Start

Installation

Basic Usage

Agent Context

Architecture

Usage

SAT Planning

Graph Relationships

Encryption

Markdown Sync

Hermes Integration

HTTP Server

Rust Library API

Command Reference

File Format

Development

Contributing

License

Roadmap

Acknowledgments

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

RBMEM

Why RBMEM?

Features

Benchmark Results

Quick Start

Installation

Basic Usage

Agent Context

Architecture

Usage

SAT Planning

Graph Relationships

Encryption

Markdown Sync

Hermes Integration

HTTP Server

Rust Library API

Command Reference

File Format

Development

Contributing

License

Roadmap

Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages