### Quick Start

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

A minimal example demonstrating how to initialize SimpleMem, add dialogues, and query the memory.

```APIDOC
## Quick Start

### Minimal Example

```python
from simplemem import SimpleMemSystem

# Initialize the system with your API key
system = SimpleMemSystem(
    api_key="your-openai-api-key",
    clear_db=True  # Start fresh
)

# Add dialogues with timestamps
system.add_dialogue("Alice", "Let's meet at Starbucks tomorrow at 2pm", "2025-01-15T14:30:00")
system.add_dialogue("Bob", "Sure, I'll bring the report", "2025-01-15T14:31:00")

# Finalize memory encoding
system.finalize()

# Query the memory
answer = system.ask("When and where will Alice and Bob meet?")
print(answer)
# Output: "Alice and Bob will meet at Starbucks on January 16, 2025 at 2:00 PM"
```

### Using Environment Variables

```python
import os
from simplemem import SimpleMemSystem

# Set API key via environment variable
os.environ["OPENAI_API_KEY"] = "your-api-key"

# Initialize without explicit api_key parameter
system = SimpleMemSystem(clear_db=True)
```
```

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

### SimpleMem Installation and Setup

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Provides bash commands for cloning the SimpleMem repository, installing dependencies, and configuring API settings.

```bash
# 📥 Clone repository
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 Install dependencies
pip install -r requirements.txt

# ⚙️ Configure API settings
cp config.py.example config.py
# Edit config.py with your API key and preferences
```

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

### SimpleMem Setup and Benchmark Execution

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Shell commands for setting up SimpleMem by cloning the repository, installing dependencies, configuring API keys, and running benchmark tests.

```bash
# Setup
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem
pip install -r requirements.txt
cp config.py.example config.py
# Edit config.py with your API key

# Run benchmark tests
python test_locomo10.py
python test_locomo10.py --num-samples 5  # Quick test with 5 samples

# Docker deployment
docker compose up -d
# Web UI: http://localhost:8000/
# REST API: http://localhost:8000/api/
# MCP: http://localhost:8000/mcp
```

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

### Python Orchestrator Quick Start

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Demonstrates how to use the SimpleMem orchestrator to start, record events, and stop a session. Ensure the 'cross' library is installed.

```python
from cross.orchestrator import create_orchestrator

async def main():
    orch = create_orchestrator(project="my-project")

    # Start session — previous context is injected automatically
    result = await orch.start_session(
        content_session_id="session-001",
        user_prompt="Continue building the REST API",
    )
    print(result["context"])  # Relevant context from previous sessions

    # Record events during the session
    await orch.record_message(result["memory_session_id"], "User asked about JWT")
    await orch.record_tool_use(
        result["memory_session_id"],
        tool_name="read_file",
        tool_input="auth/jwt.py",
        tool_output="class JWTHandler: ...",
    )

    # Finalize — extracts observations, generates summary, stores memories
    report = await orch.stop_session(result["memory_session_id"])
    print(f"Stored {report.entries_stored} memory entries")

    await orch.end_session(result["memory_session_id"])
    orch.close()
```

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

### Configure OpenRouter API Key

Source: https://github.com/aiming-lab/simplemem/blob/main/SKILL/simplemem-skill/references/openrouter-guide.md

Copy the example configuration file and edit it to include your OpenRouter API key. Ensure the key starts with 'sk-or-'.

```bash
cd SKILL/simplemem-skill
cp src/config.py.example src/config.py
```

```python
OPENROUTER_API_KEY = "sk-or-your-actual-key-here"
```

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

### SimpleMem Configuration Example

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

A placeholder for a Python configuration file example.

```python
 
```

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

### Install Omni-SimpleMem

Source: https://github.com/aiming-lab/simplemem/blob/main/OmniSimpleMem/README.md

Clone the repository and install Omni-SimpleMem in editable mode. This is the primary installation command.

```bash
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem/OmniSimpleMem
pip install -e .
```

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

### Multimodal Memory: Auto Selection

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

This example shows the setup for multimodal memory. The `create()` function with `mode='auto'` will select the Omni-SimpleMem backend if multimodal methods are called first.

```python
import simplemem_router as simplemem

mem = simplemem.create()  # auto mode

```

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

### SimpleMem Configuration Example

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Example configuration file for SimpleMem, setting API keys, model parameters, and processing settings.

```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # or "https://api.qwen.ai/v1" for Qwen

# Model settings
LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"

# Processing settings
WINDOW_SIZE = 20           # Dialogues per processing batch
SEMANTIC_TOP_K = 25        # Semantic search result count
KEYWORD_TOP_K = 5          # Keyword search result count
ENABLE_PLANNING = True     # Query planning
ENABLE_REFLECTION = True   # Reflection iteration
MAX_REFLECTION_ROUNDS = 2  # Maximum reflection rounds

# Parallel processing
ENABLE_PARALLEL_PROCESSING = True
MAX_PARALLEL_WORKERS = 8
ENABLE_PARALLEL_RETRIEVAL = True
MAX_RETRIEVAL_WORKERS = 4
```

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

### Installation

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Instructions for installing the SimpleMem package with various dependency options.

```APIDOC
## Installation

### Basic Installation

```bash
pip install simplemem
```

### With GPU Support (CUDA)

```bash
pip install simplemem[gpu]
```

### With Development Tools

```bash
pip install simplemem[dev]
```

### With Benchmark Tools

```bash
pip install simplemem[benchmark]
```

### Full Installation (All Dependencies)

```bash
pip install simplemem[all]
```

### Requirements

- Python 3.10 or higher
- OpenAI-compatible API key (OpenAI, Qwen, Azure OpenAI, etc.)
```

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

### Install SimpleMem Skill

Source: https://github.com/aiming-lab/simplemem/blob/main/SKILL/README.md

Steps to install the SimpleMem skill by copying it to the Claude skills directory, installing dependencies, and configuring the API key.

```bash
# Copy skill to Claude's skills directory
cp -r simplemem-skill ~/.claude/skills/

# Install dependencies
cd ~/.claude/skills/simplemem-skill
pip install -r requirements.txt

# Configure API key
cp src/config.py.example src/config.py
# Edit src/config.py and add your OPENROUTER_API_KEY
```

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

### Install SimpleMem Dependencies

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/reference/README.md

Clone the repository and install the necessary Python dependencies using pip.

```bash
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem
pip install -r requirements.txt
```

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

### Run Omni-SimpleMem REST API Server

Source: https://github.com/aiming-lab/simplemem/blob/main/OmniSimpleMem/README.md

Starts the Omni-SimpleMem REST API server using FastAPI. Ensure you have installed the server dependencies and set your OpenAI API key.

```bash
pip install -e ".[server]"
export OPENAI_API_KEY=your_key_here
python examples/api_server.py
# Visit http://localhost:8000/docs
```

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

### Configure API Settings

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/reference/README.md

Copy the example configuration file and edit it with your API key and preferred model settings.

```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # or custom endpoint for Qwen/Azure

LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # State-of-the-art retrieval
```

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

### MCP client configuration example

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Example JSON configuration for an MCP client, such as Claude Desktop. This defines the server URL and any necessary authentication headers.

```json
// MCP client configuration (claude_desktop_config.json)
{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

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

### Install Dependencies

Source: https://github.com/aiming-lab/simplemem/blob/main/SKILL/simplemem-skill/SKILL.md

Install the necessary Python dependencies for the SimpleMem Skill from the requirements file.

```bash
cd ~/.claude/skills/simplemem-skill
pip install -r requirements.txt
```

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

### Install SimpleMem

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Install the SimpleMem package using pip. Use the `[gpu]` extra for CUDA support.

```bash
pip install simplemem
```

```bash
pip install simplemem[gpu]
```

```bash
pip install simplemem[dev]
```

```bash
pip install simplemem[benchmark]
```

```bash
pip install simplemem[all]
```

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

### Minimal SimpleMem Quick Start

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Initialize SimpleMem, add dialogues with timestamps, finalize memory encoding, and query the system. Ensure your API key is provided.

```python
from simplemem import SimpleMemSystem

# Initialize the system with your API key
system = SimpleMemSystem(
    api_key="your-openai-api-key",
    clear_db=True  # Start fresh
)

# Add dialogues with timestamps
system.add_dialogue("Alice", "Let's meet at Starbucks tomorrow at 2pm", "2025-01-15T14:30:00")
system.add_dialogue("Bob", "Sure, I'll bring the report", "2025-01-15T14:31:00")

# Finalize memory encoding
system.finalize()

# Query the memory
answer = system.ask("When and where will Alice and Bob meet?")
print(answer)
# Output: "Alice and Bob will meet at Starbucks on January 16, 2025 at 2:00 PM"
```

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

### Install Optional Omni-SimpleMem Dependencies

Source: https://github.com/aiming-lab/simplemem/blob/main/OmniSimpleMem/README.md

Install specific optional dependency groups for Omni-SimpleMem, such as visual, audio, vector search, or server functionalities. Use '[all]' to install everything.

```bash
pip install -e ".[all]"      # Everything
pip install -e ".[visual]"   # Image/video (torch, transformers, CLIP)
pip install -e ".[audio]"    # Audio (soundfile, librosa)
pip install -e ".[vector]"   # FAISS vector search
pip install -e ".[server]"   # FastAPI REST server
pip install -e ".[dev]"      # Development (pytest)
```

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

### Configure OpenRouter API

Source: https://github.com/aiming-lab/simplemem/blob/main/SKILL/simplemem-skill/SKILL.md

Set up the OpenRouter API configuration by copying the example file and editing it with your API key.

```bash
cp src/config.py.example src/config.py
# Edit src/config.py and set your OPENROUTER_API_KEY
```

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

### Start a New Session via HTTP API

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Demonstrates how to initiate a new session using a cURL command, specifying tenant ID, project, and an initial user prompt.

```bash
# Start a new session
curl -X POST http://localhost:8000/cross/sessions/start \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "default",
    "content_session_id": "session-001",
    "project": "my-project",
    "user_prompt": "Help me debug the auth module"
  }'
```

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

### Start MCP Server locally

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Instructions to start the MCP Server locally using pip and Python. The server will be accessible at http://localhost:8000.

```bash
cd MCP
pip install -r requirements.txt
python run.py
```

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

### Install SimpleMem-Cross Dependencies

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

This command installs the necessary dependencies for SimpleMem-Cross. It relies on the same dependencies as SimpleMem and includes standard library 'sqlite3'. No additional packages beyond 'requirements.txt' are needed.

```bash
pip install -r requirements.txt
```

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

### Create and Run HTTP Server with CrossMemOrchestrator

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

Instantiate the FastAPI application for the CrossMemOrchestrator. This example shows how to create the app and provides instructions for running it with uvicorn.

```python
from cross.api_http import create_app

app = create_app(project="my-project")

# Run with uvicorn
# uvicorn cross.api_http:app --host 0.0.0.0 --port 8000
```

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

### Start SimpleMem MCP Server

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/README.md

Launches the SimpleMem MCP Server. This command starts the FastAPI application, making the Web UI, REST API, and MCP endpoints available.

```bash
python run.py
```

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

### Run SimpleMem with Docker Compose

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Execute this command from the repository root to start the MCP Server in Docker. Data is persisted in the ./data directory.

```bash
docker compose up -d
```

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

### Example JSONL Data for Batch Import

Source: https://github.com/aiming-lab/simplemem/blob/main/SKILL/simplemem-skill/references/import-guide.md

This is an example of a JSONL file used for batch importing data. Each line is a JSON object with 'speaker', 'content', and an optional 'timestamp'. If 'timestamp' is omitted, the current system time is used.

```jsonl
{"speaker": "Alice", "content": "Let's meet tomorrow at 2pm", "timestamp": "2026-01-16T14:00:00Z"}
{"speaker": "Bob", "content": "Sounds good, I'll be there"}
{"speaker": "Alice", "content": "Don't forget to bring the documents"}
```

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

### Create SimpleMem System with create_system()

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Factory function to create a SimpleMem system with simplified parameters. Useful for quick setup with common configurations.

```python
from simplemem import create_system

system = create_system(
    clear_db=True,
    enable_parallel_processing=True,
    max_parallel_workers=8
)
```

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

### Install Dependencies for SimpleMem

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/README.md

Installs the necessary Python dependencies for the SimpleMem MCP Server. Ensure you are in the 'MCP' directory and have activated your virtual environment.

```bash
cd MCP
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

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

### Install Development Dependencies and Run Tests

Source: https://github.com/aiming-lab/simplemem/blob/main/OmniSimpleMem/README.md

Bash commands to install the project in development mode and run tests using pytest.

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

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

### Create Orchestrator and Manage Session

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

This snippet demonstrates how to create an orchestrator, start a new session, record events, and stop the session. Context from previous sessions is automatically injected upon session start. Ensure the orchestrator is closed after use.

```python
import asyncio
from cross.orchestrator import create_orchestrator

async def main():
    # 🔧 Create the orchestrator for your project
    orch = create_orchestrator(project="my-project")

    # 🚀 Start a new session — context from previous sessions is injected automatically
    result = await orch.start_session(
        content_session_id="session-001",
        user_prompt="Continue building the REST API authentication",
    )
    memory_session_id = result["memory_session_id"]
    print(result["context"])  # 📚 Relevant context from previous sessions

    # 📝 Record events during the session
    await orch.record_message(memory_session_id, "User asked about JWT auth")
    await orch.record_tool_use(
        memory_session_id,
        tool_name="read_file",
        tool_input="auth/jwt.py",
        tool_output="class JWTHandler: ...",
    )
    await orch.record_message(memory_session_id, "Implemented token refresh logic", role="assistant")

    # ✅ Finalize — extracts observations, generates summary, stores memory entries
    report = await orch.stop_session(memory_session_id)
    print(f"Stored {report.entries_stored} memory entries, {report.observations_count} observations")

    # 🧹 Cleanup
    await orch.end_session(memory_session_id)
    orch.close()

asyncio.run(main())
```

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

### Add Text, Image, and Audio to Memory

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Demonstrates adding different data types (text, image, audio) to memory and querying for information. Ensure the 'simplemem' library is installed and initialized.

```python
mem.add_text(
    "User loves hiking in the Rocky Mountains.",
    tags=["session_id:D1"],
)
mem.add_image("photo.jpg", tags=["session_id:D1"])
mem.add_audio("voice_note.wav", tags=["session_id:D1"])

result = mem.query("What does the user enjoy?", top_k=5)
for item in result.items:
    print(item["summary"])

mem.close()
```

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

### Example Synthesis of Memory Fragments

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Shows how related memory fragments are consolidated into a single, comprehensive memory unit.

```diff
- Fragment 1: "User wants coffee"
- Fragment 2: "User prefers oat milk"
- Fragment 3: "User likes it hot"
+ Consolidated: "User prefers hot coffee with oat milk"
```

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

### Personal Assistant Memory Example

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Create a persistent memory for a personal assistant, add user preferences via dialogues, and query for specific information. Set `OPENAI_API_KEY` and `db_path` for persistence.

```python
from simplemem import SimpleMemSystem
import os

os.environ["OPENAI_API_KEY"] = "your-key"

# Create a persistent memory for personal assistant
system = SimpleMemSystem(
    db_path="./assistant_memory",
    clear_db=False  # Persist across sessions
)

# Add user preferences
system.add_dialogue("User", "I prefer to wake up at 6am", "2025-01-15T08:00:00")
system.add_dialogue("User", "I'm allergic to peanuts", "2025-01-15T08:05:00")
system.add_dialogue("User", "My favorite restaurant is The Green Kitchen", "2025-01-15T08:10:00")
system.finalize()

# Later, query preferences
answer = system.ask("What are the user's dietary restrictions?")
print(answer)  # "The user is allergic to peanuts"
```

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

### Meeting Notes Processing Example

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Initialize a SimpleMem system for processing meeting notes. This snippet sets up the system with an API key and clears the database.

```python
from simplemem import SimpleMemSystem, Dialogue

system = SimpleMemSystem(api_key="your-key", clear_db=True)
```

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

### Basic SimpleMem Usage

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/reference/README.md

Initialize the SimpleMem system, add dialogues, finalize encoding, and query the system. Ensure 'clear_db=True' for a fresh start.

```python
from main import SimpleMemSystem

# 🚀 Initialize system
system = SimpleMemSystem(clear_db=True)

# 💬 Add dialogues (Stage 1: Semantic Structured Compression)
system.add_dialogue("Alice", "Bob, let's meet at Starbucks tomorrow at 2pm", "2025-11-15T14:30:00")
system.add_dialogue("Bob", "Sure, I'll bring the market analysis report", "2025-11-15T14:31:00")

# ✅ Finalize atomic encoding
system.finalize()

# 🔎 Query with adaptive retrieval (Stage 3: Adaptive Query-Aware Retrieval)
answer = system.ask("When and where will Alice and Bob meet?")
print(answer)
# Output: "16 November 2025 at 2:00 PM at Starbucks"
```

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

### Run in Development Mode

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/README.md

Use the --reload flag to enable auto-reloading during development. This command starts the application with live-reloading capabilities.

```bash
python run.py --reload
```

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

### Custom Docker Compose Configuration

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Copy the example environment file and edit it to customize settings like JWT secret key and LLM provider. Then, run Docker Compose with the custom environment file.

```bash
cp .env.example .env
# Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc.
docker compose --env-file .env up -d
```

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

### Configure Environment Variables for SimpleMem

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Set environment variables for API keys, model names, and database paths. Example `.env` file content provided for reference.

```bash
OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
SIMPLEMEM_MODEL=gpt-4.1-mini
SIMPLEMEM_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
SIMPLEMEM_DB_PATH=./my_memory_db
```

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

### Memory Consolidation Worker Setup and Execution

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Python code to set up and run a memory consolidation worker. It defines a consolidation policy and initializes the worker with storage backends.

```python
from cross.consolidation import ConsolidationWorker, ConsolidationPolicy

# Define consolidation policy
policy = ConsolidationPolicy(
    max_age_days=90,                   # Decay entries older than 90 days
    decay_factor=0.9,                  # Multiply importance by 0.9 per period
    merge_similarity_threshold=0.95,   # Merge near-duplicates (95% similar)
    min_importance=0.05                # Prune entries below this threshold
)

# Create worker with storage backends
worker = ConsolidationWorker(sqlite_storage, vector_store, policy)

# Run consolidation for a tenant
result = worker.run(tenant_id="default")

print(f"Decayed: {result.decayed_count}")   # Entries with reduced importance
print(f"Merged: {result.merged_count}")     # Near-duplicate entries combined
print(f"Pruned: {result.pruned_count}")     # Low-importance entries removed
```

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

### Create Cross-Session HTTP API with FastAPI

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Provides examples for setting up a FastAPI application to manage cross-session memory. It shows how to create a standalone app or mount the cross-router onto an existing FastAPI instance.

```python
from cross.api_http import create_app, create_cross_router
from cross.orchestrator import create_orchestrator

# Option 1: Create standalone app
app = create_app(project="my-project")
# Run with: uvicorn cross.api_http:app --host 0.0.0.0 --port 8000

# Option 2: Mount router on existing FastAPI app
from fastapi import FastAPI
app = FastAPI()
orch = create_orchestrator(project="my-project")
router = create_cross_router(orch)
app.include_router(router, prefix="/cross")
```

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

### View Help

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/README.md

Use the --help flag to display all available command-line options and their descriptions. This is useful for understanding the full range of configurations.

```bash
python run.py --help
```

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

### Create and Use SimpleMem System

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Demonstrates initializing a SimpleMem system with specific configurations and adding/querying dialogues.

```python
system = create_system(
    clear_db=True,
    enable_parallel_processing=True,
    max_parallel_workers=8
)

# Add dialogues and query
system.add_dialogue("User", "I prefer hot coffee with oat milk", "2025-01-15T09:00:00")
system.finalize()
answer = system.ask("What kind of coffee does the user like?")
```

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

### Initialize MCP Tools and Dispatch Tool Call

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

Set up the MCP tools for the CrossMemOrchestrator and demonstrate how to dispatch a tool call. This includes creating the orchestrator, generating tool definitions, and calling a specific tool like 'cross_session_start'.

```python
from cross.api_mcp import create_mcp_tools
from cross.orchestrator import create_orchestrator

orch = create_orchestrator(project="my-project")
tools = create_mcp_tools(orch)

# Get tool definitions for MCP server registration
definitions = tools.get_tool_definitions()

# Dispatch a tool call
result = await tools.call_tool("cross_session_start", {
    "tenant_id": "default",
    "content_session_id": "ses-1",
    "project": "my-project",
    "user_prompt": "Help me debug the auth module",
})
```

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

### Create SimpleMem Router Instance

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Use `simplemem.create()` to initialize a memory system. It auto-detects the backend mode (text or omni) or allows explicit mode selection. Dependencies for modes can be checked with `is_available()`.

```python
import simplemem_router as simplemem

# Auto mode (recommended) - backend chosen by first call
mem = simplemem.create()  # mode="auto" is default

# Explicit text mode
mem = simplemem.create(mode="text", clear_db=True)

# Explicit omni mode with custom data directory
mem = simplemem.create(mode="omni", data_dir="./my_memory")

# Check available modes
print(simplemem.list_modes())
# {'text': 'Single-modal text memory with semantic lossless compression',
#  'omni': 'Multimodal memory — text, image, audio, video (Omni-SimpleMem)'}

# Check if a mode's dependencies are satisfied
print(simplemem.is_available("omni"))  # True / False

# Check which mode was auto-selected
print(mem.mode)  # "auto" (pending), "text", or "omni"
```

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

### Configuration

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Details on configuring SimpleMem using constructor parameters, environment variables, or a global configuration object.

```APIDOC
## Configuration

SimpleMem offers flexible configuration through three priority levels:

1. **Constructor Parameters** (highest priority)
2. **Environment Variables**
3. **Default Values** (lowest priority)

### Using SimpleMemConfig

```python
from simplemem import SimpleMemConfig, set_config, SimpleMemSystem

# Create custom configuration
config = SimpleMemConfig(
    openai_api_key="your-api-key",
    llm_model="gpt-4.1-mini",
    embedding_model="Qwen/Qwen3-Embedding-0.6B",
    lancedb_path="./my_memory_db",
    enable_parallel_processing=True,
    max_parallel_workers=8,
)

# Set as global config
set_config(config)

# Create system (will use global config)
system = SimpleMemSystem(clear_db=True)
```

### Configuration Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `openai_api_key` | str | `$OPENAI_API_KEY` | OpenAI API key |
| `openai_base_url` | str | None | Custom API endpoint |
| `llm_model` | str | `"gpt-4.1-mini"` | LLM model name |
| `embedding_model` | str | `"Qwen/Qwen3-Embedding-0.6B"` | Embedding model |
| `lancedb_path` | str | `"./lancedb_data"` | Database storage path |
| `enable_parallel_processing` | bool | True | Parallel memory building |
| `max_parallel_workers` | int | 16 | Max workers for building |
| `enable_parallel_retrieval` | bool | True | Parallel query execution |
| `max_retrieval_workers` | int | 8 | Max workers for retrieval |
| `enable_planning` | bool | True | Multi-query planning |
| `enable_reflection` | bool | True | Reflection-based retrieval |
| `max_reflection_rounds` | int | 2 | Max reflection iterations |
```

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

### Get SimpleMem statistics

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Retrieve statistics about the SimpleMem service, including counts of sessions, events, observations, and summaries.

```bash
curl http://localhost:8000/cross/stats
```

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

### Get MCP Server info

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Retrieve information about the MCP Server, including its name, version, and supported protocol version.

```bash
curl https://mcp.simplemem.cloud/api/server/info
```

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

### MCP tool: memory_stats

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Get statistics about the memory system using the memory_stats tool. This provides insights into the memory usage and state.

```json
# MCP tool: memory_stats - Get memory statistics
{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
        "name": "memory_stats",
        "arguments": {}
    }
}
```

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

### Unified Router API - create()

Source: https://context7.com/aiming-lab/simplemem/llms.txt

The `simplemem_router` module provides a unified entry point for creating memory instances. The `create()` function returns a memory system that auto-detects the appropriate backend (text or omni) based on your first API call, or you can specify the mode explicitly.

```APIDOC
## Unified Router API - create()

### Description
Provides a unified entry point for creating memory instances. The `create()` function returns a memory system that auto-detects the appropriate backend (text or omni) based on your first API call, or you can specify the mode explicitly.

### Method
`simplemem.create()`

### Parameters
#### Query Parameters
- **mode** (string) - Optional - Specifies the memory mode ('auto', 'text', 'omni'). Defaults to 'auto'.
- **clear_db** (boolean) - Optional - If true, clears the existing database. Defaults to false.
- **data_dir** (string) - Optional - Specifies the directory for storing memory data.

### Request Example
```python
import simplemem_router as simplemem

# Auto mode (recommended) - backend chosen by first call
mem = simplemem.create()

# Explicit text mode
mem = simplemem.create(mode="text", clear_db=True)

# Explicit omni mode with custom data directory
mem = simplemem.create(mode="omni", data_dir="./my_memory")
```

### Response
#### Success Response (200)
- **mem** (object) - A SimpleMem memory system instance.

### Additional Functions
#### list_modes()
Returns a dictionary of available memory modes and their descriptions.

#### is_available(mode)
Checks if a specified mode's dependencies are satisfied.

#### mem.mode
Attribute to check the auto-selected mode of the memory instance.
```

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

### Configure and Run Consolidation Worker

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

Sets up a consolidation policy with parameters for age, decay, similarity, and minimum importance, then runs the worker using specified storage and vector store. Prints the counts of decayed, merged, and pruned entries.

```python
from cross.consolidation import ConsolidationWorker, ConsolidationPolicy

policy = ConsolidationPolicy(
    max_age_days=90,                    # ⏰ Decay entries older than 90 days
    decay_factor=0.9,                   # 📉 Multiply importance by 0.9 per period
    merge_similarity_threshold=0.95,   # 🔗 Merge near-duplicates
    min_importance=0.05,               # 🗑️ Prune below this threshold
)

worker = ConsolidationWorker(sqlite_storage, vector_store, policy)
result = worker.run(tenant_id="default")

print(f"📉 Decayed: {result.decayed_count}")
print(f"🔗 Merged: {result.merged_count}")
print(f"🗑️ Pruned: {result.pruned_count}")
```

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

### Register and get MCP authentication token

Source: https://context7.com/aiming-lab/simplemem/llms.txt

Register with the SimpleMem cloud service to obtain an authentication token. This requires providing an OpenRouter API key.

```bash
curl -X POST https://mcp.simplemem.cloud/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"openrouter_api_key": "your-openrouter-api-key"}'
```

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

### Initialize SimpleMemSystem Constructor

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

The `SimpleMemSystem` constructor accepts various parameters for API keys, models, database paths, and enabling/disabling features like planning and parallel processing.

```python
SimpleMemSystem(
    api_key: Optional[str] = None,
    model: Optional[str] = None,
    base_url: Optional[str] = None,
    db_path: Optional[str] = None,
    table_name: Optional[str] = None,
    clear_db: bool = False,
    enable_thinking: Optional[bool] = None,
    use_streaming: Optional[bool] = None,
    enable_planning: Optional[bool] = None,
    enable_reflection: Optional[bool] = None,
    max_reflection_rounds: Optional[int] = None,
    enable_parallel_processing: Optional[bool] = None,
    max_parallel_workers: Optional[int] = None,
    enable_parallel_retrieval: Optional[bool] = None,
    max_retrieval_workers: Optional[int] = None,
)
```

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

### Configure Multi-tenant Memory Tables

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Use separate tables for different users or contexts by specifying a unique `table_name` for each `SimpleMemSystem` instance.

```python
# User A's memory
system_a = SimpleMemSystem(
    api_key="your-key",
    table_name="user_alice_memories",
    clear_db=False
)

# User B's memory
system_b = SimpleMemSystem(
    api_key="your-key",
    table_name="user_bob_memories",
    clear_db=False
)
```

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

### Create SimpleMem Instance

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Instantiate SimpleMem with automatic backend detection. The backend is determined by the first method called on the instance.

```python
import simplemem_router as simplemem

mem = simplemem.create()  # mode="auto" — backend chosen by first call
```

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

### Reproduce LoCoMo Results

Source: https://github.com/aiming-lab/simplemem/blob/main/OmniSimpleMem/README.md

Bash commands to download the LoCoMo dataset, set the OpenAI API key, and run the benchmark. Includes options for a quick test.

```bash
# 1. Download dataset
git clone https://github.com/snap-research/locomo.git

# 2. Set API key
export OPENAI_API_KEY="your-openai-api-key"

# 3. Run benchmark
python benchmarks/locomo/run_locomo.py \
    --data-path /path/to/locomo/data/locomo10.json \
    --model gpt-4o -o ./locomo_results

# Quick test (1 conversation, 20 QA pairs)
python benchmarks/locomo/run_locomo.py \
    --data-path /path/to/locomo/data/locomo10.json \
    --max-conversations 1 --max-qa 20
```

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

### Initialize SimpleMem with Parallel Processing

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Configures SimpleMem for parallel processing to enhance performance in large-scale dialogue handling. This setup enables faster memory building and retrieval operations.

```python
import simplemem_router as simplemem

mem = simplemem.create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ Parallel memory building
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 Parallel query execution
    max_retrieval_workers=4
)
```

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

### Configure SimpleMemSystem with Full Options

Source: https://context7.com/aiming-lab/simplemem/llms.txt

The `SimpleMemSystem` class allows detailed configuration of the memory system, including API keys, model names, database paths, and various processing and retrieval options like parallelization and reflection.

```python
from main import SimpleMemSystem, create_system

# Full configuration with all options
system = SimpleMemSystem(
    api_key="your-api-key",              # OpenAI-compatible API key
    model="gpt-4.1-mini",                # LLM model name
    base_url=None,                       # Custom API endpoint (for Qwen/Azure)
    db_path="./memory.db",               # Database path
    table_name="memories",               # Memory table name
    clear_db=True,                       # Clear existing database
    enable_thinking=False,               # Deep thinking mode (Qwen compatible)
    use_streaming=False,                 # Enable streaming responses
    enable_planning=True,                # Multi-query planning for retrieval
    enable_reflection=True,              # Reflection-based additional retrieval
    max_reflection_rounds=2,             # Maximum reflection iterations
    enable_parallel_processing=True,     # Parallel memory building
    max_parallel_workers=8,              # Workers for memory building
    enable_parallel_retrieval=True,      # Parallel query execution
    max_retrieval_workers=4              # Workers for retrieval
)

```

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

### SimpleMemSystem Constructor

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Reference for the SimpleMemSystem constructor, detailing its parameters and their purposes.

```APIDOC
## Core API Reference

### SimpleMemSystem

The main class for interacting with SimpleMem.

#### Constructor

```python
SimpleMemSystem(
    api_key: Optional[str] = None,
    model: Optional[str] = None,
    base_url: Optional[str] = None,
    db_path: Optional[str] = None,
    table_name: Optional[str] = None,
    clear_db: bool = False,
    enable_thinking: Optional[bool] = None,
    use_streaming: Optional[bool] = None,
    enable_planning: Optional[bool] = None,
    enable_reflection: Optional[bool] = None,
    max_reflection_rounds: Optional[int] = None,
    enable_parallel_processing: Optional[bool] = None,
    max_parallel_workers: Optional[int] = None,
    enable_parallel_retrieval: Optional[bool] = None,
    max_retrieval_workers: Optional[int] = None,
)
```
```

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

### Configuration

Source: https://github.com/aiming-lab/simplemem/blob/main/cross/README.md

Configure the CrossMemOrchestrator, including paths and multi-tenancy.

```APIDOC
### Default Paths

- **SQLite DB**: `~/.simplemem-cross/cross_memory.db` - Session metadata, events, observations.
- **LanceDB**: `~/.simplemem-cross/lancedb_cross` - Vector storage for memory entries.
- **Max context tokens**: `2000` - Token budget for context injection.

### Custom Configuration Example

```python
from cross.orchestrator import create_orchestrator

orch = create_orchestrator(
    project="my-project",
    tenant_id="team-alpha",
    db_path="/custom/path/memory.db",
    lancedb_path="/custom/path/lancedb",
    max_context_tokens=3000,
)
```

### Multi-Tenant Support

Pass `tenant_id` to isolate memory across tenants. Each tenant's memories are stored and retrieved independently.
```

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

### Transforming Relative to Absolute Time

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/reference/README.md

This example demonstrates the transformation of a relative and ambiguous time input into an absolute and atomic output, resolving coreferences and timestamps. This is a key step in SimpleMem's write-time disambiguation process.

```diff
- Input:  "He'll meet Bob tomorrow at 2pm"  [❌ relative, ambiguous]
+ Output: "Alice will meet Bob at Starbucks on 2025-11-16T14:00:00"  [✅ absolute, atomic]
```

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

### SimpleMemSystem Methods

Source: https://github.com/aiming-lab/simplemem/blob/main/docs/PACKAGE_USAGE.md

Documentation for the core methods of the SimpleMemSystem class, including adding dialogues.

```APIDOC
#### Methods

##### `add_dialogue(speaker, content, timestamp=None)`

Add a single dialogue entry to the memory.

```python
system.add_dialogue(
    speaker="Alice",
    content="I finished the quarterly report",
    timestamp="2025-01-15T10:00:00"  # ISO 8601 format
)
```

##### `add_dialogues(dialogues)`

Batch add multiple dialogues.

```python
from simplemem import Dialogue

dialogues = [
    Dialogue(dialogue_id=1, speaker="Alice", content="Hello", timestamp="2025-01-15T10:00:00"),
    Dialogue(dialogue_id=2, speaker="Bob", content="Hi there!", timestamp="2025-01-15T10:01:00"),
]
system.add_dialogues(dialogues)
```
```

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

### SimpleMem Router Utilities

Source: https://github.com/aiming-lab/simplemem/blob/main/README.md

Python code demonstrating how to interact with the SimpleMem router to list available modes, check dependency availability, and create memory instances. Custom backends can also be registered.

```python
import simplemem_router as simplemem

# List all registered modes
simplemem.list_modes()
# {'text': 'Single-modal text memory with semantic lossless compression',
#  'omni': 'Multimodal memory — text, image, audio, video (Omni-SimpleMem)'}

# Check if a mode's dependencies are satisfied
simplemem.is_available("omni")  # True / False

# Check which mode was auto-selected
mem = simplemem.create()
print(mem.mode)  # "auto" (pending), "text", or "omni"

# Register a custom backend
simplemem.register(
    mode="my_backend",
    module_path="my_package.memory",
    class_name="MyMemorySystem",
    description="Custom memory backend",
    required_deps=["my_package"],
)
mem = simplemem.create(mode="my_backend")
```

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

### Run SimpleMem Benchmark Tests

Source: https://github.com/aiming-lab/simplemem/blob/main/MCP/reference/README.md

Execute benchmark tests for SimpleMem. Options include running the full LoCoMo benchmark, a subset, or specifying a custom output file.

```bash
# 🎯 Full LoCoMo benchmark
python test_locomo10.py

# 📉 Subset evaluation (5 samples)
python test_locomo10.py --num-samples 5

# 💾 Custom output file
python test_locomo10.py --result-file my_results.json
```