Agent Memory RS

<p align="center"> <img src="logo.png" alt="Agent Memory RS Logo" width="300"/> </p>

Episodic memory system for AI agents with vector search, exposed via MCP server.

Verified Performance: 65.9% R@10 on LoCoMo benchmark • Up to 74% on long conversations

Note: This project was developed using Kiro CLI - an AI-powered development assistant.

Overview

Agent Memory RS stores interaction episodes with vector embeddings and retrieves them using cosine similarity search. Exposed as an MCP server with learn and search tools.

Features

• Episode Storage — Events stored with vector embeddings (BGE-Small, 384 dims)
• Vector Search — Cosine distance retrieval on episode embeddings
• BM25 Search — Keyword search with proper IDF calculation
• MCP Server — Learn and search tools via Model Context Protocol (stdio + HTTP)
• Workspace Isolation — Separate SQLite databases per workspace (~/.memory-rs/workspaces/)
• Multiple Models — BGE-Small (default), Nomic (long context), MiniLM (fastest)

┌─────────────────────────┐
│       MCP Client        │
└───────────┬─────────────┘
            │ stdio (JSON-RPC)
┌───────────▼─────────────┐
│      MCP Server         │
│  ┌─────────┐ ┌────────┐ │
│  │  learn  │ │ search │ │
│  └────┬────┘ └───┬────┘ │
└───────┼──────────┼──────┘
┌───────▼──────────▼──────┐
│   EpisodicMemoryStore   │
│  ┌──────────────────┐   │
│  │ SQLite + vec0     │   │
│  │ (episodes table)  │   │
│  │ (vector index)    │   │
│  └──────────────────┘   │
└─────────────────────────┘

🚀 Quick Start

Installation

git clone https://github.com/yourusername/agent-memory-rs
cd agent-memory-rs
cargo build --release

MCP Server (Recommended)

# Start the server
./target/release/agent-memory-mcp my-workspace

Configure your AI assistant:

{
  "mcpServers": {
    "agent-memory": {
      "command": "/path/to/agent-memory-mcp",
      "args": ["my-workspace"],
      "env": {
        "MEMORY_MODEL": "bge"
      }
    }
  }
}

Configuration Options:

| Environment Variable | Values | Default | Description | |---------------------|--------|---------|-------------| | MEMORY_MODEL | bge, nomic, minilm | bge | Embedding model to use |

Model Selection:

• bge (BGE-Small) - Best quality/speed balance, 384 dims, ~33MB ⭐ Recommended
• nomic (Nomic Embed) - Best for long context (8K tokens), 768 dims, ~138MB
• minilm (MiniLM) - Fastest, 384 dims, ~23MB

Available MCP Tools:

• @memory/learn - Store new memories
• @memory/search - Search across all memory types

Remote Access (HTTP)

Run the MCP server as a standalone HTTP service to share memory across devices on your network:

# Start HTTP server
./target/release/agent-memory-mcp --http 0.0.0.0:8230 my-workspace

Any MCP client that supports HTTP transport can connect directly:

{
  "mcpServers": {
    "agent-memory": {
      "url": "http://server-ip:8230/mcp"
    }
  }
}

This is useful when you want a single memory database shared across multiple machines — run the server on one device (e.g. a Raspberry Pi or home server) and connect from anywhere on your network.

For environments without native HTTP MCP support, a agent-memory-proxy binary is included that bridges stdio ↔ HTTP:

{
  "mcpServers": {
    "agent-memory": {
      "command": "/path/to/agent-memory-proxy",
      "args": ["--remote", "http://server-ip:8230/mcp"]
    }
  }
}

Data Storage

Workspace Isolation: Each workspace has its own isolated database. Memories are NOT shared between workspaces.

Database Location:

~/.memory-rs/workspaces/
├── prime-sde-workspace/
│   └── memory.db          # All memories for this workspace
├── my-project/
│   └── memory.db          # Separate isolated memories
└── default/
    └── memory.db          # Default workspace

Workspace Naming:

• Specified in MCP server args: ["workspace-name"]
• If no arg provided, auto-generates from current directory: <hash>-<dirname>
  • Example: /path/to/workspace/myproject → a1b2c3d4-myproject
  • Hash ensures uniqueness across different paths with same directory name
• Falls back to "default" if directory name unavailable

Data Persistence:

• ✅ Survives Kiro restarts (stored in home directory)
• ✅ Survives repo deletion (not stored in repo)
• ❌ Deleting ~/.memory-rs/ loses all memories
• ❌ No cross-workspace knowledge sharing (by design)

Model Cache: Models are downloaded once and cached in the standard HuggingFace cache:

~/.cache/huggingface/hub/
├── models--BAAI--bge-small-en-v1.5/
├── models--nomic-ai--nomic-embed-text-v1/
└── models--sentence-transformers--all-MiniLM-L6-v2/

CLI Usage

# Create workspace
cargo run --bin agent-memory-cli workspace create --name my-project --path /path/to/project

# List workspaces
cargo run --bin agent-memory-cli workspace list

# Store episode
cargo run --bin agent-memory-cli store --workspace 1 --type user_query --context "How do I use Rust?" --outcome "Provided tutorial" --valence 0.8

# Query memories
cargo run --bin agent-memory-cli query --workspace 1 "rust programming" --limit 10

# Check system health
cargo run --bin agent-memory-cli stats --workspace 1

Programmatic Usage

use agent_memory_rs::services::MemoryManager;
use agent_memory_rs::storage::Database;

// Initialize
let db = Database::new("memory.db")?;
let manager = MemoryManager::new(db.clone());

// Store episode
manager.store_episode(
    1, // workspace_id
    "user_query",
    serde_json::json!({"query": "How do I use Rust?"}),
    Some("Provided Rust tutorial"),
    Some(0.8), // positive valence
)?;

// Search memories
let results = manager.retrieve("rust programming", 1, 10)?;

📚 Documentation

• Getting Started Guide - Complete API reference and examples
• Design Rationale - Design decisions, formulas, algorithms, and research

🎓 Agent Skill

The repository includes a skill for AI agents using Kiro CLI:

Location: skill/agent-memory/SKILL.md

Add to your agent configuration:

{
  "resources": [
    "skill:///path/to/agent-memory-rs/skill/agent-memory/SKILL.md"
  ]
}

What the skill provides:

• When to use @memory/learn vs @memory/search
• Best practices for memory management
• Importance scoring and tagging strategies
• Workflow patterns for common scenarios
• Configuration options and troubleshooting

The skill is loaded on-demand, providing guidance only when needed without consuming context at startup.

🏗️ Architecture

MemoryManager (Facade)
    ├── EpisodicMemoryStore      - Raw interaction events
    └── HybridRetrievalEngine    - BM25 + Vector search

Built with SOLID principles:

• Core traits (MemoryStore, MemoryRetriever, EmbeddingService)
• Dependency injection throughout
• Thread-safe Database pattern: Arc<Mutex<Connection>>

🧪 Testing

# Run all tests
cargo test

# Run integration tests only
cargo test --test '*'

# Run with output
cargo test -- --nocapture

Test Coverage: 29 tests covering full lifecycle

📊 Performance

• Episode Storage: ~5ms
• Hybrid Search: ~20ms (10k memories)

🔬 Research Foundation

Based on modern AI agent memory research:

1. Memory Management for Long-Running Agents (2025, arXiv:2509.25250v1)
2. Episodic Memory for RAG (2024, arXiv:2511.07587v1)
3. MIRIX Multi-Agent Memory (2024)
4. Episodic Memory Properties (2025, arXiv:2502.06975v1)
5. Procedural Memory Is Not All You Need (2025, arXiv:2505.03434v1)

See Design Rationale for complete references.

🛠️ Technology Stack

• Language: Rust 1.70+
• Database: SQLite with sqlite-vec extension
• Embeddings: BERT MiniLM (384 dimensions) via Candle
• Vector Search: Cosine distance with HNSW-like indexing
• Interface: MCP (Model Context Protocol)

📝 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

🙏 Acknowledgments

Inspired by cognitive science research on human memory systems and modern AI agent architectures.

Prune old memories

memory-cli prune --workspace 1 --dry-run

## 🧪 Testing

```bash
# Run all tests
cargo test

# Run integration tests only
cargo test --test '*'

# Run with output
cargo test -- --nocapture

Test Coverage: 29 tests covering full lifecycle

🔧 Development

Project Structure

src/
├── services/          # 6 core services
├── storage/           # Database and memory store
├── traits/            # 5 SOLID traits
├── models/            # DTOs and types
├── cli/               # CLI commands
└── mcp/               # MCP server

tests/                 # 16 integration test files
docs/                  # 5 documentation files

Building

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Build MCP server only
cargo build --bin memory-rs-mcp --release

📊 Performance

• Episode storage: ~5ms
• Hybrid search: ~20ms (1000 memories)
• All operations: Non-blocking

🤝 Contributing

1. Follow SOLID principles
2. Write minimal, focused code
3. Add tests for new features
4. Update documentation
5. Run cargo test before committing

📝 License

MIT OR Apache-2.0

🙏 Acknowledgments

Built with:

• Rust 🦀
• SQLite + sqlite-vec
• Candle (ML framework)
• MCP Protocol

---

Status: Production-ready ✅ Tests: 44 passing ✅ Documentation: Complete ✅ }

#### Search (Query Memories)

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "programming languages",
      "workspace_id": 1,
      "limit": 5
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "results": [
      {
        "memory_id": 42,
        "text": "Rust is a systems programming language...",
        "similarity_score": 0.92,
        "combined_score": 0.88,
        "importance_score": 0.8,
        "tags": "rust,programming",
        "created_at": "2026-01-30T22:00:00Z"
      }
    ],
    "count": 1
  }
}

📚 Architecture

┌─────────────────────────────────────────────────────────────┐
│                         CLI Tool                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ stdio (JSON-RPC 2.0)
┌──────────────────────────▼──────────────────────────────────┐
│                      MCP Server                              │
│  ┌────────────────┐  ┌────────────────┐                     │
│  │  Learn Tool    │  │  Search Tool   │                     │
│  └────────┬───────┘  └────────┬───────┘                     │
└───────────┼──────────────────┼─────────────────────────────┘
            │                  │
┌───────────▼──────────────────▼─────────────────────────────┐
│                    Memory System                             │
│  ┌──────────────────┐  ┌──────────────────┐                │
│  │  FastEmbedder    │  │  Memory Store    │                │
│  │  (MiniLM/Nomic)  │  │  (SQLite+vec)    │                │
│  └──────────────────┘  └──────────────────┘                │
└─────────────────────────────────────────────────────────────┘
            │                  │
┌───────────▼──────────────────▼─────────────────────────────┐
│              Workspace Manager                               │
│  ~/.memo