lorefs

lorefs is a lightweight, high-performance Rust-native SDK designed to provide a "File-First" persistent memory system for AI Agents.

It abstracts the successful experiences of mature systems like Claude Code, Letta MemFS, and OpenClaw into a unified paradigm. It allows developers to build structured, self-editable, and Git-versioned long-term memory for Agents using a simple API.

Core Features

• Everything is a File: Memories are stored in structured Markdown files and folders, making them human-readable.
• Git Version Control: All memory changes are versioned via Git by default, allowing for full auditability and rollback.
• Pinned Context: Core memories (e.g., Persona, Preferences) can be easily injected into System Prompts.
• Agent Self-Editing: The API allows Agents to directly read and update their own memory files.
• Periodic Reflection: Built-in hooks for background summarization and memory optimization.
• Type-Safe: Built with Rust's rigorous type system for safety and performance.

Installation

Add the following to your Cargo.toml:

[dependencies]
lorefs = "0.1.0"

Quick Start

use lorefs::{LoreFS, LoreConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Configure LoreFS
    let config = LoreConfig::builder()
        .base_dir(".lore")
        .git_enabled(true)
        .build()?;

    // 2. Initialize
    let mut lore = LoreFS::new(config)?;

    // 3. Add memory
    lore.add(
        "User prefers Rust for system development.",
        "MEMORY.md",
        &["preference", "rust"],
    )?;

    // 4. Get Pinned Context for System Prompt
    let context = lore.get_pinned_context()?;
    println!("{}", context);

    Ok(())
}

Default Directory Structure

Upon initialization, lorefs automatically creates the following structure:

.lore/
├── system/
│   ├── persona.md       # Agent persona/identity
│   ├── preferences.md   # User preferences
│   └── workflow.md      # Standard operating procedures
├── MEMORY.md            # Core long-term memory
├── USER.md              # User profile/persona
└── .git/                # Automatic version control

Design Philosophy: Lore-First Paradigm

lorefs follows the Lore-First paradigm:

1. Transparency: Memory should not be a black box (like vector databases). It should be composed of files that humans can directly inspect and correct.
2. Durability: Git ensures every change to the memory is tracked, preventing accidental loss or corruption.
3. Layered Loading: Not all memories need to be in the context. Pinned files go into the Context, while others are retrieved via Search or File Tree navigation.

License

MIT License