Recallium Installation Guide

Quick Overview

Recallium is an AI memory and project intelligence server that gives your IDE agents persistent memory. It uses the Model Context Protocol (MCP) to store, search, and reason about your code, decisions, and project knowledge—creating a digital twin that grows smarter over time.

Free Local Option (No API Keys!)

Want to run completely free and private? Use Ollama + built-in embeddings:

LLM: Ollama (Llama 3, Mistral, Qwen - runs locally)
Embeddings: GTE-Large (built-in, no API needed)
Cost: $0

Just install Ollama, pull a model, and select it in the Setup Wizard. Your data never leaves your machine.

IDE Support At-a-Glance

Prerequisites

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download from https://ollama.ai/download

ollama serve

# Required for insights (or use OpenAI/Anthropic)
ollama pull qwen2.5-coder:7b

npm install -g recallium

Quick Start

cd install
chmod +x start-recallium.sh
./start-recallium.sh

cd install
chmod +x start-recallium.sh
./start-recallium.sh

# Edit /etc/docker/daemon.json
{ "ipv6": true }
# Then: sudo systemctl restart docker

# Change: -p "[::]:${PORT}:9000"
# To:     -p "${PORT}:9000"

netsh advfirewall firewall add rule name="Ollama" dir=in action=allow program="C:\Users\<YOUR_USERNAME>\AppData\Local\Programs\Ollama\ollama.exe" enable=yes profile=private

cd install
start-recallium.bat

cd install
docker compose --env-file recallium.env pull    # Download latest image
docker compose --env-file recallium.env up -d   # Start container

OLLAMA_HOST=http://YOUR_IP:11434
OLLAMA_BASE_URL=http://YOUR_IP:11434

HOST_UI_PORT=9001        # Web UI: http://localhost:9001
HOST_API_PORT=8001       # MCP API: http://localhost:8001
HOST_POSTGRES_PORT=5433  # PostgreSQL: localhost:5433
VOLUME_NAME=recallium-v1 # Data volume name

# 1. Check container is running
docker ps -f name=recallium

# 2. Verify health endpoint
curl http://localhost:8001/health
# Expected: {"status":"healthy",...}

# 3. Check MCP tools are available
curl http://localhost:8001/mcp/status
# Expected: List of 16 available tools

# 4. Open the Web UI
open http://localhost:9001   # macOS
# or visit http://localhost:9001 in your browser

Setup Wizard (First-Time Configuration)

On first launch, visit http://localhost:9001 to complete the setup wizard:

The Setup Wizard guides you through initial configuration

1. Choose Your LLM Provider

Select from 5 supported LLM providers

Recallium works with any LLM provider—use what you already have:

2. Test Your Configuration

The setup wizard lets you:

• Test API keys before saving
• Verify connectivity to your chosen provider
• Switch providers anytime without losing data

Configure provider priority and automatic failover

3. Complete Setup

Once configured, the MCP tools become available to all connected IDEs.

After setup: Your dashboard shows system stats, recent activity, and quick access to all features

Free Local Setup (No API Keys Required)

Want to run completely free and private?

LLM: Ollama (local models like Llama 3, Mistral)
Embeddings: GTE-Large (built-in, runs locally)

Just select Ollama in the setup wizard and ensure Ollama is running locally.

Configuration

The recallium.env file contains all configuration options. Key settings:

POSTGRES_PASSWORD=recallium_password  # Change in production!

HOST_UI_PORT=9001        # Access UI on your machine
HOST_API_PORT=8001       # Access MCP API on your machine
HOST_POSTGRES_PORT=5433  # Access PostgreSQL on your machine

See recallium.env for all available options with detailed inline documentation.

Advanced Configuration

All configuration is managed through recallium.env (single source of truth). Common customizations:

# Edit install/recallium.env
LLM_MODEL=llama3.2:3b           # Smaller, faster
# or
LLM_MODEL=gpt-oss:20b           # Larger, more accurate

# Edit install/recallium.env
CHUNK_SIZE_TOKENS=400           # Safe with 22% margin (recommended)
CHUNK_SIZE_TOKENS=450           # Moderate margin

# Edit install/recallium.env
BATCH_SIZE=20                   # Process more memories at once
MAX_CONCURRENT=10               # More parallel operations
QUEUE_WORKERS=3                 # More background workers

# Edit install/recallium.env
ENABLE_PATTERN_MATCHING=false   # Skip pattern detection
ENABLE_UNIFIED_INSIGHTS=false   # Disable insights processing
REAL_TIME_PROCESSING=false      # Queue for batch processing

After editing recallium.env, restart the container:

cd install
docker compose down
docker compose --env-file recallium.env up -d

IDE Integration

Recallium supports two connection methods:

HTTP-Capable IDEs (Recommended - No npm Client)

These IDEs connect directly to http://localhost:8001/mcp:

Command-Only IDEs (Requires npm Client)

These IDEs only support command-based connections and need the npm client as a stdio→HTTP bridge:

First, install the npm client:

npm install -g @recallium/mcp-client

Note: If you changed HOST_API_PORT in recallium.env from the default 8001, update the URL in your IDE config accordingly.

Management Commands

# View logs
docker compose --env-file recallium.env logs -f

# Stop
docker compose down

# Restart
docker compose --env-file recallium.env restart

# Update to latest version
docker compose --env-file recallium.env pull
docker compose --env-file recallium.env up -d

# Reset everything (deletes all data!)
docker compose down -v

Tips

Always use recallium MCP tools when working with this codebase. Specifically:
- Use store_memory to capture implementation decisions, learnings, and code context
- Use search_memories to find past decisions and context before making changes
- Use get_rules at the start of each session to load project behavioral guidelines
- Link memories to files using related_files parameter for better code searchability

# Test HTTP connection
npx @modelcontextprotocol/inspector http://localhost:8001/mcp

# Test npm client (stdio→HTTP bridge)
npx @modelcontextprotocol/inspector npx -y recallium-mcp

Troubleshooting

Next Steps

1. Complete Setup Wizard: Visit http://localhost:9001 to configure your LLM provider
2. Configure IDE: Follow the IDE Integration guides above
3. Start Using: Your AI now has persistent memory across sessions!

Your First Commands (Try These in Your IDE!)

Once your IDE is connected, try these commands with your AI assistant:

"recallium"
→ Magic summon: loads all your project context in one call

"Store a memory: We decided to use PostgreSQL because..."
→ Saves your decision with auto-tagging

"Search my memories about authentication"
→ Finds past decisions, patterns, learnings

"What was I working on last week?"
→ Session recap with recent activity

"Get insights about my database patterns"
→ Cross-project pattern analysis

What You Can Do Now