Memora-rs

Memora-rs is a Rust implementation of the Memora memory system described in the paper Memora: A Harmonic Memory Representation Balancing Abstraction and Specificity.

Key Features

• Interchangeable AI Backends:
  • Cloud provider: OpenAI & Azure OpenAI
  • Local provider: Ollama (fully local completions and embeddings)
• Flexible Vector Storage:
  • ChromaDB integration
  • Redis integration
• Document Extractors: Built-in support for extracting text from files (PDF, TXT, and Markdown)
• Advanced Retrieval: Supports standard semantic search, BM25 hybrid search, and multi-step prompt-guided query planning (traversing the implicit memory graph via semantic cue anchors)

Deferred Paper Features

While Memora-rs implements the core memory representation and guided retrieval loop detailed in the paper, the following research-specific component has been intentionally deferred:

• Policy Model RL Training (GRPO): The paper details optimizing the sequential retrieval policy ($\pi_\theta$) via Group-Relative Policy Updates (GRPO) using preference learning, scoring judges, and trajectory advantage normalization. Memora-rs implements the prompt-guided zero-shot policy retriever (PromptedRetriever) using standard LLM completion prompts. The reinforcement learning training, trajectory collection, and policy model fine-tuning components are deferred.

---

Installation & Setup

Ensure you have Rust and Cargo installed. Clone the repository and build:

cargo build --release --workspace

The CLI binary package is located in crates/memora-cli. You can run commands using:

cargo run --bin memora -- [commands]

---

Usage

1. Running with OpenAI (Default)

Configure your API credentials:

export OPENAI_API_KEY="your-api-key"

Add factual memory:

cargo run --bin memora -- add "Memora-rs implements memory modules for AI agents."

Query memory:

cargo run --bin memora -- query "What does Memora do?"

---

2. Running with Ollama (Fully Local)

Ensure Ollama is running and has the required models downloaded:

ollama pull nomic-embed-text-v2-moe:latest
ollama pull qwen3.6:35b-a3b-coding-nvfp4

Add factual memory:

cargo run --bin memora -- --provider ollama add "Memora is running fully local now."

Query memory:

cargo run --bin memora -- --provider ollama query "Is Memora local?"

Global configuration arguments available:

• --provider: choose "openai" or "ollama" (default: "openai")
• --llm-model: select LLM model name
• --embedding-model: select Embedding model name
• --ollama-base: local Ollama endpoint (default: http://localhost:11434)

---

3. Using as a Library

To use Memora-rs as a dependency in your own Rust application, add it to your Cargo.toml:

[dependencies]
memora = { git = "https://github.com/mcxross/memora-rs", package = "memora", features = ["chroma", "llm"] }

You can toggle backend support using Cargo feature flags:

• chroma (default): Enables ChromaDB vector client.
• redis: Enables Redis Search client.
• llm (default): Enables OpenAI, Azure OpenAI, and local Ollama clients.

Memora API

use memora::Memora;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Minimal setup — Ollama with all defaults
    let m = Memora::builder()
        .ollama()
        .collection("my_agent_collection")
        .user("agent_user_1")
        .build()
        .await?;

    m.add("AI agents need robust memory architectures.").await?;

    // Simple query — uses default top_k and semantic retrieval
    let results = m.query("What do AI agents need?").await?;

    // Customized query — explicit top_k and prompted multi-step retrieval
    let results = m.query("What do AI agents need?")
        .top_k(5)
        .prompted()
        .await?;

    for memory in results {
        println!("- {}", memory.value);
    }

    Ok(())
}

---

Running the Web UI Demo

Memora-rs includes a browser UI built with Axum. Ensure you have ChromaDB running on port 8000:

docker run -d -p 8000:8000 chromadb/chroma

Start the Axum Web Server:

# Using OpenAI backend
cargo run --bin memora -- ui --port 3000

# Using Ollama backend
cargo run --bin memora -- --provider ollama ui --port 3000

Open your browser and navigate to http://localhost:3000 to interact with the database, ingest files, and query memories visually.

---

Running Integration Tests

To run the suite of integration tests verifying Ollama and ChromaDB compatibility:

cargo test -p memora --test integration_tests -- --nocapture

---

License

Licensed under the Apache License, Version 2.0. See LICENSE.