# Memorium

**Persistent Memory Infrastructure for AI Agents**

Memorium is an open-source, self-hostable [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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.

```mermaid
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

```bash
pip install memorium
```

Or with `uvx` (no install needed):

```bash
uvx memorium
```

### Optional Dependencies

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

```bash
memorium init
```

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

### 2. Start the MCP server

```bash
memorium serve
```

### 3. Connect to your AI assistant

#### Claude Desktop

Add to your `claude_desktop_config.json`:

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

#### Cursor

Add to Cursor MCP configuration:

```json
{
  "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`:

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

```bash
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

```bash
# Start all services
docker compose up -d

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

## Development

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

```bash
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)