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]

pip install memorium

uvx memorium

# 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]

memorium init

memorium serve

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

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

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

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

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

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
└──────────────┘

# Start all services
docker compose up -d

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

# 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

python tests/benchmark.py