### Recallium Docker Quick Start

Source: https://context7.com/recallium-ai/recallium/llms.txt

Quick start commands for installing and running Recallium using Docker on macOS/Linux and Windows. Includes commands for pulling images, starting, stopping, and updating.

```bash
# Quick Start - macOS/Linux
cd install
chmod +x start-recallium.sh
./start-recallium.sh

# Quick Start - Windows
cd install
start-recallium.bat
```

--------------------------------

### Start Recallium on macOS/Linux

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Execute the start script to launch Recallium on macOS or Linux. This script handles Docker setup, image pulling, and container startup.

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

--------------------------------

### Pull and Start Docker Compose

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use these commands to download the latest Recallium image and start the containers using Docker Compose. Ensure you are in the 'install' directory and have your environment file configured.

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

--------------------------------

### Start Recallium on Windows

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Run the start script to launch Recallium on Windows. This script configures Ollama connection details and starts the Docker container.

```cmd
cd install
start-recallium.bat
```

--------------------------------

### Install Ollama on Linux

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Download and execute the official installation script to install Ollama on Linux systems. This is required for running AI models locally.

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

--------------------------------

### Initialize Recallium via Shell

Source: https://github.com/recallium-ai/recallium/blob/main/README.md

Execute the startup script based on the host operating system to begin the installation process.

```bash
# macOS / Linux
cd install
chmod +x start-recallium.sh
./start-recallium.sh

# Windows
cd install
start-recallium.bat
```

--------------------------------

### Install Recallium Skill

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/README.md

Commands to install the skill on different operating systems.

```bash
cd claude-code-skills
chmod +x install.sh
./install.sh
```

```cmd
cd claude-code-skills
install.bat
```

--------------------------------

### Start Ollama Server

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Run the Ollama server command to make AI models available for use. This command starts the background service.

```bash
ollama serve
```

--------------------------------

### GET /get_rules

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Retrieves project-specific or global rules to guide agent behavior. Rules must be loaded at the start of every session.

```APIDOC
## GET /get_rules

### Description
Retrieves rules associated with a specific project or global rules. These rules are non-negotiable and must be followed.

### Method
GET

### Parameters
#### Query Parameters
- **project_name** (string) - Required - The name of the project to fetch rules for. Use "__global__" for global rules.

### Request Example
get_rules(project_name="my-project")
```

--------------------------------

### Install Ollama on macOS

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use Homebrew to install Ollama on macOS. Ensure Ollama is installed for local AI model execution.

```bash
# macOS
brew install ollama
```

--------------------------------

### Example Recallium MCP Tool Rule

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

This is an example rule for IDEs like Cursor to automatically invoke Recallium MCP tools for specific tasks such as capturing memories or searching context.

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

--------------------------------

### Other HTTP-Capable IDEs Configuration Examples

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configuration snippets for integrating Recallium with various other IDEs and CLIs that support HTTP-based MCP servers.

```json
Gemini CLI - Use `httpUrl: "http://localhost:8001/mcp"`
```

```json
Qodo Gen - Use `type: "remote", url: "http://localhost:8001/mcp"`
```

```json
Opencode - Use `type: "remote", url: "http://localhost:8001/mcp"`
```

```json
Trae - Use `url: "http://localhost:8001/mcp"`
```

```json
Copilot Coding Agent - Use `type: "http", url: "http://localhost:8001/mcp"`
```

--------------------------------

### Invoke Recallium MCP Tool

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

The mandatory command to initialize the project context at the start of every session.

```text
Invoke the MCP tool: recallium(project_name="current-project")
```

--------------------------------

### List Installed MCP Servers in Claude Code

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Verify that Recallium has been successfully added as an MCP server by listing all installed servers using the Claude CLI.

```bash
claude mcp list
```

--------------------------------

### Recallium AI Assistant Commands

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Example commands to interact with the Recallium AI assistant once your IDE is connected. These demonstrate core functionalities like context loading, memory storage, and information retrieval.

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

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

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

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

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

--------------------------------

### Initiate Structured Reasoning

Source: https://context7.com/recallium-ai/recallium/llms.txt

Begin a structured thinking sequence for complex decisions using 'start_thinking'. Provide a goal and project name to get a sequence ID for subsequent 'add_thought' calls.

```python
# Start a thinking sequence for a complex decision
result = start_thinking(
    goal="Design authentication system for mobile app",
    project_name="mobile-api"
)
sequence_id = result.sequence_id
```

--------------------------------

### Load Session Context with recallium

Source: https://context7.com/recallium-ai/recallium/llms.txt

Invoke this tool at the start of every session to load project-specific rules, recent activity, and pending tasks.

```python
# MANDATORY: Call at the start of every session
recallium(project_name="ecommerce-api")

# Response includes:
# - Global rules (MUST follow these)
# - Project-specific rules
# - Recent activity and context
# - Pending tasks
# - Project briefs/PRDs

# Example response:
# "Welcome back! Loading your context...
#  Project: ecommerce-api
#  Recent: 12 memories in last 7 days
#  Last session (2 days ago):
#    → Implemented JWT refresh token rotation
#    → Fixed race condition in payment webhook
#    → Decision: Using Redis for session storage
#  Pending Tasks:
#    → Add rate limiting to checkout endpoint
#    → Write tests for payment flow
#  Active Rules:
#    → Always confirm destructive operations
#    → Search memories before implementing
#  Ready to continue."
```

--------------------------------

### Verify Recallium Installation

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Perform these checks to ensure Recallium is running correctly. Verify the container status, check the health endpoint, confirm MCP tools are available via the API, and access the Web UI.

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

--------------------------------

### Get Project Documents

Source: https://context7.com/recallium-ai/recallium/llms.txt

Retrieve all documents associated with a specific project using the 'projects' function with the 'get' action.

```python
projects(action="get", project_name="ecommerce-api")
```

--------------------------------

### Configure Recallium Environment Variables

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Modify the 'recallium.env' file to customize port mappings for the Web UI, MCP API, and PostgreSQL, as well as the data volume name. These settings should be adjusted before starting the containers if default ports cause conflicts.

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

--------------------------------

### List and Complete Project Tasks

Source: https://context7.com/recallium-ai/recallium/llms.txt

Retrieve pending tasks for a project using 'tasks(action="get", ...)' and mark tasks as complete using 'tasks(action="complete", ...)' with a list of task IDs.

```python
# List pending tasks for a project
tasks(action="get", project_name="ecommerce-api")
```

```python
# Complete tasks
tasks(action="complete", project_name="ecommerce-api", task_ids=["123", "456"])
```

--------------------------------

### Remove Old Docker Image and Restart

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Completely remove the existing Recallium Docker image and then start fresh to resolve issues related to outdated or corrupted images.

```bash
# Remove old image completely and start fresh
docker compose down
docker rmi recalliumai/recallium:latest
docker compose --env-file recallium.env up -d
```

--------------------------------

### Recallium Docker Compose Management

Source: https://context7.com/recallium-ai/recallium/llms.txt

Commands for managing Recallium using Docker Compose. Includes pulling images, starting, stopping, viewing logs, updating, resetting data, and forcing image pulls.

```bash
# Using Docker Compose directly
cd install
docker compose --env-file recallium.env pull    # Download latest image
docker compose --env-file recallium.env up -d   # Start container

# Verify installation
docker ps -f name=recallium
curl http://localhost:8001/health
curl http://localhost:8001/mcp/status

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

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

# Stop Recallium
docker compose down

# Reset everything (DELETES ALL DATA)
docker compose down -v

# Force pull latest ignoring cache
docker compose --env-file recallium.env up --pull always
```

--------------------------------

### Get Session Summary

Source: https://context7.com/recallium-ai/recallium/llms.txt

Retrieves a summary of recent session activity, including stored memories, decisions, and tasks in progress. Useful for resuming work after a break.

```python
# Get session recap
session_recap()
```

--------------------------------

### GET /get_insights

Source: https://context7.com/recallium-ai/recallium/llms.txt

Analyzes memories across projects to discover patterns, quality issues, and recommendations.

```APIDOC
## GET /get_insights

### Description
Provides cross-project analysis based on specific analysis types.

### Parameters
#### Query Parameters
- **analysis_type** (string) - Required - Type of analysis: 'comprehensive', 'patterns', 'quality', 'technical_debt', 'learning', 'productivity', or 'progress'.
- **topic** (string) - Optional - Filter analysis by topic.
- **project_name** (string) - Optional - Filter analysis by project name.
```

--------------------------------

### GET /search_memories

Source: https://context7.com/recallium-ai/recallium/llms.txt

Searches across stored memories and documents using semantic or keyword matching.

```APIDOC
## GET /search_memories

### Description
Performs a search across memories and documents. Supports semantic (default) and keyword search modes.

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term or question.
- **search_mode** (string) - Optional - 'semantic' or 'keyword'.
- **target** (string) - Optional - 'memories', 'documents', or 'all'.
- **file_path** (string) - Optional - Filter by file path pattern.
- **recent_only** (boolean) - Optional - If true, searches only recent memories.
```

--------------------------------

### Get Insights

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Generates analytical reports based on stored memories. Useful for identifying patterns, quality issues, or project progress.

```python
# Find clusters related to a topic
get_insights(analysis_type="comprehensive", topic="authentication")

# Quality issues in a specific project
get_insights(analysis_type="quality", project_name="my-api")
```

--------------------------------

### Get Insights - Cross-Project Analysis

Source: https://context7.com/recallium-ai/recallium/llms.txt

Analyzes memories across projects for patterns, quality issues, and recommendations. Supports various analysis types like comprehensive, patterns, quality, technical debt, learning, productivity, and progress.

```python
# Comprehensive analysis of a topic
get_insights(analysis_type="comprehensive", topic="authentication")
# Returns patterns, decisions, issues related to authentication
```

```python
# Find recurring patterns across projects
get_insights(analysis_type="patterns")
# Example response:
# "Analyzed 89 memories across 5 projects. Pattern detected:
#  You ALWAYS follow this progression:
#  1. Start with PostgreSQL (5/5 projects)
#  2. Hit connection pool limits around 10K users (3/5)
#  3. Add PgBouncer to solve it (3/3 that hit the issue)
#  Recommendation: Include PgBouncer from day 1."
```

```python
# Quality analysis for a specific project
get_insights(analysis_type="quality", project_name="my-api")
# Returns bug patterns, root causes, recurring issues
```

```python
# Technical debt identification
get_insights(analysis_type="technical_debt", project_name="ecommerce-api")
# Returns cleanup candidates, refactoring opportunities
```

```python
# Track learning and growth
get_insights(analysis_type="learning", topic="database optimization")
# Shows knowledge evolution over time
```

```python
# Productivity trends
get_insights(analysis_type="productivity", project_name="my-api")
# Returns activity trends, focus areas
```

```python
# Project progress overview
get_insights(analysis_type="progress", project_name="user-service-v3")
# Returns milestones, momentum indicators
```

--------------------------------

### Manage Projects - List and Create

Source: https://context7.com/recallium-ai/recallium/llms.txt

Manages formal project documentation including briefs, PRDs, and implementation plans. Use store_memory for day-to-day decisions and learnings.

```python
# List all projects
projects(action="list_all")
# Returns list of all projects with their documents
```

```python
# Create a project brief
projects(
    action="create",
    project_name="ecommerce-api",
    content="""
    # E-Commerce API Project Brief

    **Goal:** Build a scalable REST API for e-commerce platform
    **Scope:** Product catalog, cart, checkout, order management
    **Stakeholders:** Frontend team, Mobile team, Operations
    **Timeline:** Q2 2024
    **Key Constraints:** Must handle 10K concurrent users
    """)
```

--------------------------------

### Create Project Documentation

Source: https://context7.com/recallium-ai/recallium/llms.txt

Use the 'projects' function to create different types of project documentation like PRDs and implementation plans. Specify the action, project name, document type, and content.

```python
projects(
    action="create",
    project_name="ecommerce-api",
    doc_type="prd",
    content="""
    # E-Commerce API PRD

    ## User Stories
    - As a customer, I can browse products by category
    - As a customer, I can add items to cart
    - As a customer, I can complete checkout with Stripe

    ## Requirements
    - RESTful API with OpenAPI spec
    - JWT authentication with refresh tokens
    - Rate limiting: 100 req/min per user
    """)
```

```python
projects(
    action="create",
    project_name="ecommerce-api",
    doc_type="plan",
    content="""
    # Implementation Plan

    ## Phase 1: Foundation (Week 1-2)
    - Set up PostgreSQL + PgBouncer
    - Implement JWT auth with refresh tokens
    - Create product catalog endpoints

    ## Phase 2: Cart & Checkout (Week 3-4)
    - Shopping cart with Redis storage
    - Stripe payment integration
    - Order management system
    """)
```

--------------------------------

### Start/Restart Recallium with Helper Script

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use the start-recallium script to initiate or restart the Recallium service. This command also pulls the latest Docker image.

```bash
./start-recallium.sh
```

```bat
start-recallium.bat
```

--------------------------------

### Verify Downloaded Ollama Models

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

List all the models that have been downloaded and are available for use with Ollama.

```bash
ollama list
```

--------------------------------

### Configure Host Port Mappings

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Define the host ports for the UI, API, and database services.

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

--------------------------------

### Configure Deployment Environment Variables

Source: https://github.com/recallium-ai/recallium/blob/main/README.md

Adjust environment settings for corporate proxy SSL bypass or air-gapped offline operation.

```bash
DISABLE_SSL_VERIFY=1
```

```bash
HF_HUB_OFFLINE=1
TRANSFORMERS_OFFLINE=1
```

--------------------------------

### Retrieve Project and Global Rules

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Use these functions to fetch rules for a specific project or the global rule set. Always check existing rules before attempting to store new ones.

```python
# Get project + global rules
get_rules(project_name="my-project")

# Global rules only
get_rules(project_name="__global__")
```

--------------------------------

### Connect to PostgreSQL Database

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Establish a direct connection to the Recallium PostgreSQL database for manual inspection or troubleshooting.

```bash
docker exec -it recallium psql -U recallium -d recallium_memories
```

--------------------------------

### Configure Ollama Host in recallium.env

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

If Ollama is running on a different host or port, update the OLLAMA_HOST variable in your recallium.env file to point to the correct address.

```bash
OLLAMA_HOST=http://your-ollama-host:11434
```

--------------------------------

### Retrieve Project Rules

Source: https://context7.com/recallium-ai/recallium/llms.txt

Fetch project-specific and global rules governing agent behavior using the 'get_rules' function. Use '__global__' as the project name to retrieve only global rules.

```python
# Get project + global rules
get_rules(project_name="ecommerce-api")
```

```python
# Get global rules only
get_rules(project_name="__global__")
```

--------------------------------

### Export Recallium Memories

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Create a timestamped zip file containing all your Recallium memories for backup purposes.

```bash
./download-memories.sh
```

--------------------------------

### Change Host Port Mappings in recallium.env

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

If you encounter port conflicts, edit the `recallium.env` file to change the `HOST_*` port mappings to unused ports. Remember to restart Recallium after making changes.

```bash
# Edit recallium.env and change HOST_* port mappings
# Example:
# HOST_API_PORT=8001
# HOST_WEB_PORT=3000
```

--------------------------------

### Create Project Tasks

Source: https://context7.com/recallium-ai/recallium/llms.txt

Manage project tasks using the 'tasks' function. Create new tasks by specifying the action, project name, and task description. Multiple related tasks can be created sequentially.

```python
# Create a task
tasks(
    action="create",
    project_name="ecommerce-api",
    task_description="Implement rate limiting on checkout endpoint"
)
```

```python
# Create multiple related tasks
tasks(action="create", project_name="ecommerce-api",
      task_description="Add rate limiting to checkout endpoint")
tasks(action="create", project_name="ecommerce-api",
      task_description="Write tests for payment flow")
tasks(action="create", project_name="ecommerce-api",
      task_description="Update API documentation")
```

--------------------------------

### Zed Settings Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Add this configuration to your Zed `settings.json` file to enable Recallium integration. See Zed Context Server docs for more info.

```json
{
  "context_servers": {
    "recallium": {
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Restart Recallium with Docker Compose

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Restart the Recallium services using Docker Compose, applying configurations from recallium.env.

```bash
docker compose --env-file recallium.env restart
```

--------------------------------

### Configure Ollama to Bind to All Interfaces on Windows

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

On Windows, set the OLLAMA_HOST environment variable to '0.0.0.0:11434' to allow Docker containers to connect to Ollama. Restart Ollama after changing the variable.

```bash
OLLAMA_HOST=0.0.0.0:11434
```

--------------------------------

### Connect IDE via MCP

Source: https://github.com/recallium-ai/recallium/blob/main/README.md

Use the MCP endpoint to integrate Recallium with supported IDEs and tools.

```text
http://localhost:8001/mcp
```

```bash
claude mcp add --scope user --transport http recallium http://localhost:8001/mcp
```

--------------------------------

### Pull Qwen2.5 Coder Model

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Download the Qwen2.5 Coder model using Ollama. This model is recommended for insights and can be used as an alternative to OpenAI or Anthropic models.

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

--------------------------------

### Restart Container

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Apply configuration changes by restarting the Docker container.

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

--------------------------------

### Manage Tasks

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Handles the task lifecycle including creation, retrieval, completion, and linking to relevant memories.

```python
# Create task
tasks(action="create", project_name="x", task_description="Implement user auth")

# List pending tasks
tasks(action="get", project_name="x")

# Complete task(s)
tasks(action="complete", project_name="x", task_ids=["123", "456"])

# Link memories to task
tasks(action="link_memories", project_name="x", task_ids="123", memory_ids=[100, 101])
```

--------------------------------

### View Recallium Logs with Docker Compose

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Stream the logs from the Recallium Docker containers in real-time. Ensure your recallium.env file is in the current directory.

```bash
docker compose --env-file recallium.env logs -f
```

--------------------------------

### Update recallium.env with Ollama IP Address on Windows

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Manually set the OLLAMA_HOST and OLLAMA_BASE_URL in recallium.env to your machine's IP address if Ollama is not accessible via localhost. Replace `192.168.1.46` with your actual IP.

```bash
OLLAMA_HOST=http://192.168.1.46:11434
OLLAMA_BASE_URL=http://192.168.1.46:11434
```

--------------------------------

### POST /projects

Source: https://context7.com/recallium-ai/recallium/llms.txt

Manages project documentation including briefs, PRDs, and implementation plans.

```APIDOC
## POST /projects

### Description
Manages formal project documentation. Actions include listing projects or creating new project briefs.

### Parameters
#### Request Body
- **action** (string) - Required - 'list_all' or 'create'.
- **project_name** (string) - Optional - Required for 'create' action.
- **content** (string) - Optional - The content of the project brief or PRD.
```

--------------------------------

### View All Docker Logs

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Monitor all logs from the Recallium container in real-time to identify and debug issues.

```bash
docker logs -f recallium
```

--------------------------------

### Store Memories with store_memory

Source: https://context7.com/recallium-ai/recallium/llms.txt

Capture substantive interactions, decisions, and debug sessions by providing content, project metadata, and relevant tags.

```python
# Store a debug session with full context
store_memory(
    content="""
    ## Fixed: Authentication Token Refresh Race Condition

    **Problem:** Multiple concurrent API calls triggered simultaneous token refreshes,
    causing 401 errors when the first refresh invalidated tokens used by in-flight requests.

    **Solution:** Implemented token refresh mutex with request queuing. Pending requests
    wait for refresh completion rather than triggering their own refresh.

    **Files changed:**
    - src/auth/token-manager.ts: Added refreshMutex and pendingRefresh promise
    - src/api/client.ts: Modified interceptor to await pending refresh

    **Testing:** Added concurrent request test, verified single refresh per cycle.
    """,
    project_name="my-api",
    memory_type="debug",
    related_files=["src/auth/token-manager.ts", "src/api/client.ts"],
    tags=["authentication", "race-condition", "token-refresh"],
    importance_score=0.8
)

# Store an architecture decision
store_memory(
    content="""
    ## Decision: Using PostgreSQL with PgBouncer from Day 1

    **Context:** Building user-service-v3, expected scale 50K users.

    **Options considered:**
    1. PostgreSQL only - simpler, but hit connection limits at 10K users in past projects
    2. PostgreSQL + PgBouncer - proven pattern, handled 100K users in admin-api

    **Decision:** Include PgBouncer from start.
    **Rationale:** Adding PgBouncer later caused 2 hours downtime in admin-api.
    """,
    project_name="user-service-v3",
    memory_type="decision",
    related_files=["docker-compose.yml", "config/database.ts"],
    tags=["postgresql", "pgbouncer", "architecture", "scaling"],
    importance_score=0.9
)
```

--------------------------------

### Configure Ollama Host Environment Variable (Windows)

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Set the OLLAMA_HOST system environment variable to '0.0.0.0:11434' for Windows. This ensures Docker can connect to Ollama.

```cmd
set OLLAMA_HOST=0.0.0.0:11434
```

--------------------------------

### Configure MCP Endpoint and Health Checks

Source: https://context7.com/recallium-ai/recallium/llms.txt

Use these commands to verify the Recallium MCP server status and health via HTTP.

```bash
# MCP Endpoint URL (default configuration)
http://localhost:8001/mcp

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

# MCP status check
curl http://localhost:8001/mcp/status
# Expected: List of 16 available tools
```

--------------------------------

### Force Pull Latest Docker Image and Restart

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Update to the latest Recallium Docker image and restart the services. Use the `--pull always` flag to ensure the newest image is fetched, bypassing local caches.

```bash
cd install
docker compose down
docker compose --env-file recallium.env up --pull always
```

--------------------------------

### Cursor IDE MCP Configuration

Source: https://context7.com/recallium-ai/recallium/llms.txt

Configuration for Cursor IDE to connect to Recallium MCP. Place this in ~/.cursor/mcp.json or within Cursor's settings.

```json
{
  "mcpServers": {
    "recallium": {
      "url": "http://localhost:8001/mcp",
      "transport": "http"
    }
  }
}
```

--------------------------------

### Add Windows Firewall Rule for Ollama

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Create a Windows Firewall rule to allow Ollama executable through the firewall. This is necessary for network connectivity, especially when running Recallium.

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

--------------------------------

### Change Processing Settings

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Tune performance parameters for memory processing and background tasks.

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

--------------------------------

### Configure Offline Mode for HuggingFace Models

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Set up Recallium AI to work in an air-gapped environment by enabling offline mode for HuggingFace model downloads. This involves pre-downloading models and setting environment variables.

```bash
# Download Nomic model cache
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('nomic-ai/nomic-embed-text-v1.5', trust_remote_code=True)"
```

```bash
HF_HUB_OFFLINE=1
TRANSFORMERS_OFFLINE=1
```

```yaml
volumes:
  - /path/to/hf-cache:/app/.cache/huggingface
```

--------------------------------

### Restart Docker Compose with Environment File

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use this command to restart Recallium AI services after modifying environment variables in the recallium.env file. Ensure you update IDE configurations if ports are changed.

```bash
docker compose down
docker compose --env-file recallium.env up -d
```

--------------------------------

### Set PostgreSQL Password

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configure the PostgreSQL database password by editing the 'recallium.env' file. Remember to change this password for production environments.

```bash
POSTGRES_PASSWORD=recallium_password  # Change in production!
```

--------------------------------

### JetBrains IDEs MCP Configuration

Source: https://context7.com/recallium-ai/recallium/llms.txt

Configuration for JetBrains IDEs to connect to Recallium MCP. Access this through the IDE's settings menu.

```json
// JetBrains IDEs - Settings > Tools > AI Assistant > MCP
{
  "mcpServers": {
    "recallium": {
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Enable IPv6 in Docker Daemon

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configure the Docker daemon to enable IPv6. This is a troubleshooting step for port binding issues on Linux, particularly for Safari compatibility.

```json
# Edit /etc/docker/daemon.json
{
  "ipv6": true
}
```

--------------------------------

### JetBrains AI Assistant JSON Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configure Recallium in JetBrains IDEs via JSON. Ensure you select 'Streamable HTTP' as the transport and enter the provided URL and name.

```json
{
  "mcpServers": {
    "recallium": {
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### View PostgreSQL Database Logs

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Access the PostgreSQL database logs directly from the container to troubleshoot connection or data-related problems.

```bash
docker exec recallium tail -f /data/postgres.log
```

--------------------------------

### Configure Recallium in VS Code

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Add Recallium as an HTTP MCP server in VS Code's global configuration. This allows VS Code to communicate with the Recallium AI service. Restart VS Code after applying changes.

```json
{
  "mcp": {
    "servers": {
      "recallium": {
        "type": "http",
        "url": "http://localhost:8001/mcp"
      }
    }
  }
}
```

--------------------------------

### Augment Code Server Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Add this server configuration to your `settings.json` in Augment Code and restart your editor. See Augment MCP docs for more info.

```json
"augment.advanced": {
  "mcpServers": [
    {
      "name": "recallium",
      "transport": "http",
      "url": "http://localhost:8001/mcp"
    }
  ]
}
```

--------------------------------

### Visual Studio 2022 MCP Server Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configure your Visual Studio MCP settings to connect to Recallium. Refer to Visual Studio MCP docs for details.

```json
{
  "inputs": [],
  "servers": {
    "recallium": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Recallium Environment Variables

Source: https://context7.com/recallium-ai/recallium/llms.txt

Key environment variables in recallium.env for customizing Recallium's behavior, including port configuration, embedding models, Ollama settings, processing limits, and database credentials.

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

# Embedding Model Options
# Option 1: Nomic (768D) - Default, ARM64 compatible
EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.5
EMBEDDING_DIM=768

# Option 2: Snowflake Arctic (1024D)
#EMBEDDING_MODEL=Snowflake/snowflake-arctic-embed-l-v2.0
#EMBEDDING_DIM=1024

# Ollama Configuration (for LLM)
OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_BASE_URL=http://host.docker.internal:11434

# Processing Configuration
WORKERS=2                          # API server workers
MEMORY_PROCESSOR_MIN_WORKERS=5     # Concurrent memory processing
MEMORY_PROCESSOR_MAX_WORKERS=30

# Corporate/Air-gapped Environment
DISABLE_SSL_VERIFY=1               # For corporate proxy SSL issues
HF_HUB_OFFLINE=1                   # For air-gapped environments
TRANSFORMERS_OFFLINE=1

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=recallium
DB_PASSWORD=recallium_password
DB_NAME=recallium_memories

# Volume naming (bump suffix for schema changes)
VOLUME_NAME=recallium-v1
```

--------------------------------

### Link Memories to Tasks

Source: https://context7.com/recallium-ai/recallium/llms.txt

Enhance task context by linking related memories using the 'tasks' function with the 'link_memories' action. Provide the project name, task IDs, and a list of memory IDs.

```python
# Link memories to a task (adds context)
tasks(
    action="link_memories",
    project_name="ecommerce-api",
    task_ids="123",
    memory_ids=[100, 101, 102]
)
```

--------------------------------

### Adjust Document Chunk Size

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Set the token limit for document chunks to manage context window usage.

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

--------------------------------

### Update Recallium Git Repository

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Update the Recallium project files from the Git repository while preserving your existing recallium.env configuration.

```bash
./update-recallium.sh
```

```bat
update-recallium.bat
```

--------------------------------

### Update Windows IP Address in .env File

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

For Windows users employing Docker Compose, manually update the 'recallium.env' file with your machine's IP address for OLLAMA_HOST and OLLAMA_BASE_URL if not using the provided batch script. Find your IP using 'ipconfig'.

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

--------------------------------

### Switch Embedding Model

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Configure the embedding model and dimensions. Ensure EMBEDDING_DIM matches the model's output dimensions.

```bash
# Edit install/recallium.env

# Option 1: Nomic (768D) - Default, ARM64 compatible
EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.5
EMBEDDING_DIM=768

# Option 2: Snowflake Arctic (1024D) - No trust_remote_code
EMBEDDING_MODEL=Snowflake/snowflake-arctic-embed-l-v2.0
EMBEDDING_DIM=1024

# Option 3: OpenAI (requires API key in vault)
# Configure via Web UI → Providers → Embedding
```

--------------------------------

### Verify Ollama Accessibility with IP Address

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Test the connection to Ollama using your machine's IP address. This is useful for verifying network connectivity after configuration changes.

```cmd
curl http://YOUR_IP:11434/api/version
```

--------------------------------

### Verify Docker Container Status

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use this command to check if the Recallium Docker container is running. Ensure the container name matches 'recallium'.

```bash
docker ps -f name=recallium
```

--------------------------------

### Add Recallium MCP Server in Claude Code

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use the Claude CLI to add Recallium as an MCP server with HTTP transport for the user scope. This command registers the server for use within Claude Code.

```bash
claude mcp add --scope user --transport http recallium http://localhost:8001/mcp
```

--------------------------------

### Windsurf MCP Configuration

Source: https://context7.com/recallium-ai/recallium/llms.txt

Configuration for Windsurf to connect to Recallium MCP. This JSON snippet defines the server details.

```json
{
  "mcpServers": {
    "recallium": {
      "serverUrl": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Disable SSL Verification for Downloads

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Temporarily disable SSL verification by setting `DISABLE_SSL_VERIFY=1` in your `.env` file. This is a quick fix for SSL certificate errors, often seen in corporate networks. Use with caution.

```bash
DISABLE_SSL_VERIFY=1
```

```bash
docker compose down
docker compose --env-file recallium.env up -d
```

--------------------------------

### VS Code MCP Configuration

Source: https://context7.com/recallium-ai/recallium/llms.txt

Configuration for VS Code to connect to Recallium MCP. This file path is specific to macOS.

```json
// VS Code - ~/Library/Application Support/Code/User/mcp.json (macOS)
{
  "mcp": {
    "servers": {
      "recallium": {
        "type": "http",
        "url": "http://localhost:8001/mcp"
      }
    }
  }
}
```

--------------------------------

### Update Recallium to Latest Version with Docker Compose

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Pull the latest Docker image and redeploy Recallium services. This ensures you are running the most recent version.

```bash
docker compose --env-file recallium.env pull
docker compose --env-file recallium.env up -d
```

--------------------------------

### Stop Recallium with Docker Compose

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Gracefully stop all running Recallium Docker containers.

```bash
docker compose down
```

--------------------------------

### Store Memory

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Saves a memory entry to the system. Provide detailed content, project context, and metadata to ensure effective retrieval.

```python
store_memory(
    content="""
    ## Fixed: Authentication Token Refresh Race Condition

    **Problem:** Multiple concurrent API calls triggered simultaneous token refreshes,
    causing 401 errors when the first refresh invalidated tokens used by in-flight requests.

    **Solution:** Implemented token refresh mutex with request queuing. Pending requests
    wait for refresh completion rather than triggering their own refresh.

    **Files changed:**
    - src/auth/token-manager.ts: Added refreshMutex and pendingRefresh promise
    - src/api/client.ts: Modified interceptor to await pending refresh

    **Testing:** Added concurrent request test, verified single refresh per cycle.
    """,
    project_name="my-api",
    memory_type="debug",
    related_files=["src/auth/token-manager.ts", "src/api/client.ts"],
    tags=["authentication", "race-condition", "token-refresh"],
    importance_score=0.8
)
```

```python
# ❌ TOO VAGUE
store_memory(content="Fixed auth bug", project_name="my-api")

# ❌ NO RELATED FILES
store_memory(content="Updated token refresh logic", project_name="my-api")

# ❌ WRONG TYPE - this is a decision, not working-notes
store_memory(content="Decided to use Redis for session storage because...",
             memory_type="working-notes")
```

--------------------------------

### Store a New Rule

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Only execute this function when a user explicitly requests a new rule. Ensure the memory_type is set to 'rule'.

```python
# ONLY do this when user explicitly requests a new rule
store_memory(
    content="Always use uv instead of pip for Python dependency management",
    project_name="__global__",  # or specific project
    memory_type="rule",
    importance_score=0.9
)
```

--------------------------------

### Test Ollama Connection with cURL

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Verify that you can connect to the Ollama API endpoint. This command checks the API version.

```bash
curl http://localhost:11434/api/version
```

--------------------------------

### Reset Recallium (Deletes Data)

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Completely reset the Recallium environment, including deleting all stored data. This action requires confirmation.

```bash
./reset-recallium.sh
```

```bat
reset-recallium.bat
```

--------------------------------

### Claude Code MCP CLI Commands

Source: https://context7.com/recallium-ai/recallium/llms.txt

Commands for managing Recallium MCP connections using the Claude Code CLI. Use 'claude mcp add' to add a server and 'claude mcp list' or 'claude mcp test' to verify.

```bash
# Claude Code - Terminal command
claude mcp add --scope user --transport http recallium http://localhost:8001/mcp

# Verify installation
claude mcp list
claude mcp test recallium
```

--------------------------------

### Store a Rule

Source: https://context7.com/recallium-ai/recallium/llms.txt

Use this function to store a rule for Recallium. Specify the content of the rule, the project it applies to (or '__global__'), and its importance.

```python
store_memory(
    content="Always use uv instead of pip for Python dependency management",
    project_name="__global__",  # or specific project name
    memory_type="rule",
    importance_score=0.9
)
```

--------------------------------

### Cline MCP Server Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Add this configuration to your Cline MCP servers configuration to connect with Recallium.

```json
{
  "mcpServers": {
    "recallium": {
      "type": "streamableHttp",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Roo Code MCP Server Configuration

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Add this to your Roo Code MCP configuration file for Recallium integration.

```json
{
  "mcpServers": {
    "recallium": {
      "type": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

--------------------------------

### Search Memories - Semantic and Keyword

Source: https://context7.com/recallium-ai/recallium/llms.txt

Searches memories using semantic (conceptual) or keyword (exact term) matching. Can filter by file path or search only recent memories. Use expand_memories to retrieve full content.

```python
# Semantic search for concepts (default)
search_memories(query="how do we handle authentication errors")
# Returns memories about auth error handling patterns
```

```python
# Keyword search for exact terms
search_memories(query="handleAuthCallback", search_mode="keyword")
# Returns memories mentioning exact function name
```

```python
# File-based search (find all context about a file)
search_memories(query="authentication", file_path="%auth.ts%")
# Returns memories related to any file matching *auth.ts*
```

```python
# Search recent memories only
search_memories(query="token refresh", recent_only=True)
# Returns only recent memories about token refresh
```

```python
# Search uploaded documents
search_memories(query="OAuth implementation requirements", target="documents")
# Searches through uploaded PDFs and specs
```

```python
# Search everything
search_memories(query="rate limiting", target="all")
# Searches both memories and documents
```

```python
# After searching, expand relevant results
expand_memories(memory_ids=[123, 456, 789])
# Returns full content of specified memories
```

--------------------------------

### Reset Recallium with Docker Compose (Deletes Volumes)

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Completely reset Recallium by stopping containers and removing associated volumes, which deletes all data. This action does not prompt for confirmation.

```bash
docker compose down -v
```

--------------------------------

### Uninstall Recallium Skill

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/README.md

Commands to remove the skill directory and clean up configuration files.

```bash
rm -rf ~/.claude/skills/recallium-guidance
# Remove the @~/.claude/skills/recallium-guidance/SKILL.md line from ~/.claude/CLAUDE.md
```

```cmd
rmdir /s /q "%USERPROFILE%\.claude\skills\recallium-guidance"
REM Manually edit %USERPROFILE%\.claude\CLAUDE.md to remove the skill line
```

--------------------------------

### Check MCP Server Health and Status

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Diagnose issues by checking the health and status of the MCP server. This is useful when tools are not appearing in your IDE.

```bash
curl http://localhost:8001/health
curl http://localhost:8001/mcp/status
```

--------------------------------

### POST /store_memory

Source: https://context7.com/recallium-ai/recallium/llms.txt

Stores a code snippet or project memory for future retrieval and context.

```APIDOC
## POST /store_memory

### Description
Stores a code snippet or project memory, allowing for tagging and association with specific files.

### Parameters
#### Request Body
- **content** (string) - Required - The text content of the memory or code snippet.
- **project_name** (string) - Required - The name of the project the memory belongs to.
- **memory_type** (string) - Required - The category of the memory (e.g., 'code-snippet').
- **related_files** (array) - Optional - List of file paths associated with the memory.
- **tags** (array) - Optional - List of tags for categorization.
- **importance_score** (float) - Optional - A score representing the importance of the memory.
```

--------------------------------

### Test Recallium MCP Connection with Inspector

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Use the MCP Inspector to test and debug your Recallium MCP connection. This command opens a web interface for tool testing and debugging.

```bash
npx @modelcontextprotocol/inspector http://localhost:8001/mcp
```

--------------------------------

### Check PostgreSQL Database Status

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Verify if the PostgreSQL database is running within its container. This command is essential for diagnosing database connection issues.

```bash
docker exec recallium pg_isready -U recallium
```

--------------------------------

### POST /store_memory

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Stores a new memory or rule. Note that rules should only be stored when explicitly requested by the user.

```APIDOC
## POST /store_memory

### Description
Stores a memory, decision, or rule. Proactive storage of rules is prohibited; only store rules when the user explicitly requests it.

### Method
POST

### Parameters
#### Request Body
- **content** (string) - Required - The text content of the memory or rule.
- **project_name** (string) - Required - The project context for the memory.
- **memory_type** (string) - Required - The category of memory (e.g., "rule").
- **importance_score** (float) - Optional - A score from 0.0 to 1.0 indicating the significance of the memory.

### Request Example
store_memory(
	content="Always use uv instead of pip for Python dependency management",
	project_name="__global__",
	memory_type="rule",
	importance_score=0.9
)
```

--------------------------------

### Recallium Golden Rules

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Core operational principles for maintaining memory and rule compliance.

```text
1. ALWAYS INVOKE THE RECALLIUM MCP TOOL AT SESSION START (not the Skill)
2. ALWAYS FOLLOW LOADED RULES
3. STORE MEMORIES, NOT DOCUMENTS
4. STORE CONSTANTLY - DON'T WAIT TO BE ASKED
```

--------------------------------

### Disable Features

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Toggle specific features off to reduce resource usage or change processing behavior.

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

--------------------------------

### Search Memories

Source: https://github.com/recallium-ai/recallium/blob/main/claude-code-skills/SKILL.md

Retrieves memories using semantic or keyword-based queries. Supports filtering by file path and recency.

```python
# Conceptual search
search_memories(query="how do we handle authentication errors")

# Exact term search
search_memories(query="handleAuthCallback", search_mode="keyword")

# File-based search (find all context about a file)
search_memories(query="authentication", file_path="%auth.ts%")

# Recent only
search_memories(query="token refresh", recent_only=True)
```

--------------------------------

### Change LLM Model

Source: https://github.com/recallium-ai/recallium/blob/main/install/README.md

Update the LLM_MODEL variable in recallium.env to switch between different model sizes.

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