Memorium

Persistent Memory Infrastructure for AI Agents

Memorium is an open-source, self-hostable Model Context Protocol (MCP) server that gives AI assistants persistent long-term memory. Install once, connect to any MCP-compatible client (Claude Desktop, Cursor, etc.), and your AI finally remembers you.

flowchart LR
    A[AI Assistant] -- MCP stdio --> B[Memorium]
    B --> C[(SQLite / PostgreSQL)]
    B --> D[(Qdrant Vector DB)]
    B --> E[Memory Engine]
    E --> F[Extraction]
    E --> G[Scoring]
    E --> H[Dedup]
    E --> I[Conflict Resolution]

Features

• Automatic Memory - AI detects and stores important information without manual commands
• 7 MCP Tools - remember, search_memory, retrieve_context, update_memory, forget_memory, list_memories, memory_stats
• MCP Resources - Expose memories as readable resources (memora://default/context, memora://default/memories)
• Context Injection - Auto-inject relevant memories as context before answering
• Intelligent Pipeline - Extraction → Classification → Importance Scoring → Dedup → Conflict Resolution → Storage
• 6 Memory Types - Profile, Preference, Semantic, Episodic, Procedural, Project
• Hybrid Search - Keyword + tag + importance + recency ranking
• Memory Consolidation - Background merging of related memories, cleanup of expired entries
• Duplicate Detection - Automatic detection and skipping of duplicate information
• Conflict Resolution - Detects contradictions, marks outdated information while keeping history
• Sensitive Data Protection - Automatically detects and blocks passwords, API keys, tokens
• Local-First - All data stored locally by default, no external APIs required
• Privacy-First - You own all your data. Encryption option available.

Installation

pip install memorium

Or with uvx (no install needed):

uvx memorium

Optional Dependencies

# PostgreSQL support
pip install memorium[postgres]

# Qdrant vector search
pip install memorium[qdrant]

# Redis caching
pip install memorium[redis]

# Neo4j graph memory
pip install memorium[neo4j]

# LLM providers
pip install memorium[ollama,openai,gemini]

# Everything
pip install memorium[all]

Quick Start

1. Initialize configuration

memorium init

This creates ~/.memorium/config.yaml with default settings.

2. Start the MCP server

memorium serve

3. Connect to your AI assistant

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "memora": {
      "command": "uvx",
      "args": ["memorium"]
    }
  }
}

Cursor

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "memora": {
      "command": "uvx",
      "args": ["memorium"]
    }
  }
}

How It Works

When you chat with your AI:

1. You share information naturally
2. The AI calls remember() to store important details
3. Before answering, the AI calls retrieve_context() to fetch relevant memories
4. Memories are automatically extracted, classified, scored, deduplicated, and stored

User: "My name is Khalid and I prefer Python for AI projects."

AI detects important information → calls remember()

Memory stored:
{
  "type": "preference",
  "content": "User prefers Python for AI projects",
  "importance": 0.9
}

Later:
User: "What programming language do I prefer for AI?"

AI calls retrieve_context("programming language preference")
→ retrieves memory → answers correctly

Configuration

Configuration is stored in ~/.memorium/config.yaml:

storage:
  type: sqlite                    # sqlite | postgres
  sqlite_path: ~/.memorium/memora.db

embedding:
  provider: ollama                # ollama | openai | gemini
  model: nomic-embed-text

llm:
  provider: openai                # ollama | openai | gemini
  model: gpt-4o-mini

vector:
  provider: qdrant                # optional: qdrant
  url: http://localhost:6333

cache:
  provider: redis                 # optional: redis
  url: redis://localhost:6379/0

graph:
  provider: neo4j                 # optional: neo4j
  uri: bolt://localhost:7687

security:
  encryption_enabled: false

All settings can also be set via environment variables:

export MEMORIUM_STORAGE__TYPE=postgres
export MEMORIUM_STORAGE__POSTGRES_DSN=postgresql://user:pass@localhost:5432/memorium
export MEMORIUM_EMBEDDING__PROVIDER=openai
export MEMORIUM_EMBEDDING__API_KEY=sk-...

CLI Reference

Command	Description
memorium init	Create default configuration
memorium serve	Start the MCP server
memorium status	Show database and memory statistics
memorium export	Export all memories (JSON/YAML)
memorium delete	Delete all memories

MCP API

Tools

Tool	Description	Key Inputs
remember	Store a new memory	content (required), memory_type, user_id
search_memory	Search relevant memories	query (required), limit, memory_type
retrieve_context	Get context for answering	query (required)
update_memory	Modify existing memory	memory_id (required), content
forget_memory	Delete a memory	memory_id (required)
list_memories	List stored memories	user_id, memory_type, limit, offset
memory_stats	Show analytics	user_id
consolidate	Merge related memories	user_id, dry_run

Resources

URI	Description
memorium://default/context	Active memory context (markdown)
memorium://default/memories	All stored memories list (markdown)

Architecture

User Message
     │
     ▼
┌──────────────┐
│  Extractor   │  Extract structured memories from conversation
│              │  Classify into type, detect sensitive data
└──────┬───────┘
       ▼
┌──────────────┐
│   Scorer     │  Score importance (0-1) based on:
│              │  - Explicit "remember" cues
│              │  - Personal relevance
│              │  - Future usefulness
└──────┬───────┘
       ▼
┌──────────────┐
│  Classifier  │  Assign memory type:
│              │  profile, preference, semantic,
│              │  episodic, procedural, project
└──────┬───────┘
       ▼
┌──────────────┐
│  Deduplicator│  Check for exact/near-duplicate memories
└──────┬───────┘
       ▼
┌──────────────┐
│  Conflict    │  Detect contradictions with existing memories
│  Resolver    │  Mark outdated memories, keep history
└──────┬───────┘
       ▼
┌──────────────┐
│   Storage    │  SQLite (default) / PostgreSQL / Qdrant
└──────────────┘

Memory Types

Type	Description	Examples
Profile	User identity	Name, location, occupation
Preference	User preferences	Likes Python, prefers dark mode
Semantic	Facts and knowledge	"RAG systems use retrieval"
Episodic	Past events	"Last week we discussed..."
Procedural	User workflows	"I always deploy with Docker"
Project	Current projects	"Building a RAG system"

Docker

# Start all services
docker compose up -d

# Or just the memorium server
docker build -t memorium .
docker run -v ~/.memora:/root/.memora memorium

Development

# Clone the repository
git clone https://github.com/yourusername/memorium
cd memorium

# Install in dev mode
pip install -e ".[all]"

# Run linting
ruff check src/

# Run type checking
mypy src/

# Run tests
pytest

# Run benchmarks
python tests/benchmark.py

Benchmark Results

Run the built-in benchmark suite:

python tests/benchmark.py

Measures:

• Storage throughput (ops/sec)
• Search latency (p50/p95/p99)
• Retrieval recall@k
• Duplicate detection accuracy
• Conflict resolution accuracy
• Extraction throughput
• Consolidation efficiency

Security

• Sensitive data detection - Passwords, API keys, tokens are never stored
• Encryption - Optional encryption at rest
• User isolation - Memories are scoped by user_id
• Local-first - No external API calls required by default

License

MIT

Roadmap

• [ ] Embedding-based vector search (built-in, no external deps)
• [ ] Web UI for browsing memories
• [ ] Memory graph visualization
• [ ] Multi-user server mode
• [ ] Plugin system for custom extractors
• [ ] Cloud sync option (end-to-end encrypted)