lorefs 0.1.0

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

```toml
[dependencies]
lorefs = "0.1.0"
```

## Quick Start

```rust
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:

```text
.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