### Setup and Configuration

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

Commands for installing dependencies and configuring the OpenRouter API key.

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

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

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

### Run REST API Server

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

Install server dependencies and start the FastAPI server.

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

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

### Install and Configure SimpleMem

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

Commands to clone the repository, install dependencies, and prepare the configuration file.

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

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

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

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

### Initialize local configuration

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

Copy the example configuration file to a local version to begin editing settings.

```bash
cp config.py.example config.py
# Edit config.py with your API key, base URL, and model preferences
```

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

### Configure SimpleMem Environment

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

Initialize the configuration file from the provided example template.

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

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

### Install EvolveMem

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

Clone the repository and install the required dependencies.

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

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

### Quick Start CLI Usage

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

Basic commands for adding dialogue and querying stored memories.

```bash
# Add a dialogue
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "Alice" --content "Meet Bob tomorrow at 2pm"

# Query memories
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "When should Alice meet Bob?"
```

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

### Install OmniSimpleMem

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

Clone the repository and install the package in editable mode.

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

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

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

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

### 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 via pip

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

Various installation commands for SimpleMem, including optional dependencies for GPU, development, and benchmarking.

```bash
pip install simplemem
```

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

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

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

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

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

### Configure API settings

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

Configuration examples for setting up the LLM and embedding models in config.py.

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

```python
# config.py — using Atlas Cloud as an OpenAI-compatible backend
OPENAI_API_KEY = "your-atlascloud-api-key"
OPENAI_BASE_URL = "https://api.atlascloud.ai/v1"

LLM_MODEL = "deepseek-ai/deepseek-v4-pro"   # a reasoning model — keep max tokens generous
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"
```

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

### Install SimpleMem Skill

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

Commands to copy the skill to the Claude directory, install dependencies, and configure 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
```

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

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

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

### Configure Environment Variables

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

Example of a .env file configuration for setting API keys, model names, and database paths.

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

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

### Install Omni-SimpleMem Dependencies

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

Install core requirements and optional packages for cloud storage or document processing support.

```bash
cd OmniSimpleMem
pip install -r requirements.txt          # core Omni-Memory dependencies

# Optional, only if you use the matching feature:
pip install boto3                        # s3:// (AWS S3 or MinIO)
pip install google-cloud-storage         # gs:// (Google Cloud Storage)
pip install pypdf                        # .pdf documents
pip install python-docx                  # .docx documents
```

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

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

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

### Install Optional Dependencies

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

Install specific dependency groups for extended functionality like visual, audio, or vector search support.

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

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

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

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

### 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"}
```

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

### Configure API and Model Settings

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

Example configuration for setting the OpenAI API key and selecting LLM and embedding models.

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

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

### JSONL Dialogue Format Example

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

A sample JSONL file structure where each line represents a distinct dialogue entry.

```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"}
```

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

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

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

### 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())
```

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

### 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 Simplemem with Docker Compose

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

Starts the service in detached mode from the repository root.

```bash
# From the repository root
docker compose up -d
```

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

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

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

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

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

### 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",
})
```

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

### Initialize SimpleMem with constructor parameters

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

Configure the text backend instance directly using constructor arguments.

```python
from simplemem import create

mem = create(
    mode="text",
    clear_db=True,
    model="gpt-4.1-mini",
    enable_parallel_processing=True,
    max_parallel_workers=8,
)
```

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

### Create a backend instance

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

Initializes a specific backend instance using the factory method.

```python
from simplemem import create

mem = create(mode="text", clear_db=True)
```

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

### Configure Environment Variables

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

Commands to initialize and run the service with a custom environment file.

```bash
cp .env.example .env
# Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc.
```

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

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

### Reproduce LoCoMo Benchmark Results

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

Use these commands to clone the dataset, set the required environment variable, and execute the evaluation script. The quick test mode limits the scope to a single conversation for faster validation.

```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 and Query SimpleMem

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

Basic workflow for initializing the system, adding dialogues, and querying memory.

```python
from simplemem import SimpleMem

# Initialize the system. mode="auto" (default): the backend is chosen
# by the first method you call — add_dialogue() selects the text backend.
mem = SimpleMem()

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

# Finalize memory encoding
mem.finalize()

# Query the memory
answer = mem.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"
```

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

### Configure Environment Variables

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

Set the necessary API keys and model configuration for the LLM backend.

```bash
export OPENAI_API_KEY="your-key-here"
export OPENAI_API_BASE="https://api.openai.com/v1"   # or Azure endpoint
export LLM_MODEL="gpt-4o"
```

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

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

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

### 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}")
```

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

### Create Personal Assistant Memory

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

Demonstrates initializing a persistent memory instance and adding user preferences for later retrieval.

```python
from simplemem import create
import os

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

# Create a persistent memory for a personal assistant
mem = create(
    mode="text",
    db_path="./assistant_memory",
    clear_db=False,  # Persist across sessions
)

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

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

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

### Run Benchmark Tests

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

Execute the LoCoMo benchmark using various command-line arguments for sample size and output file configuration.

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

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

### Configure S3-compatible storage environment variables

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

Set these environment variables to enable access to MinIO or other S3-compatible storage providers.

```bash
export S3_ENDPOINT_URL=https://minio.internal:9000
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
```

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

### Run Omni-SimpleMem Server

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

Execute the server using the stdio transport with a specified data directory.

```bash
python -m omni_mcp --data-dir ~/.omni_simplemem/mcp
```

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

### View package structure

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

Displays the directory layout of the OmniSimpleMem project.

```text
OmniSimpleMem/
├── omni_memory/               # Core package
│   ├── orchestrator.py        # Central coordinator
│   ├── app.py                 # FastAPI REST server
│   ├── core/                  # MAU, config, events
│   ├── storage/               # FAISS vector store, cold storage, dedup
│   ├── retrieval/             # Pyramid retriever, BM25, query processor
│   ├── processors/            # Text, image, audio, video processors
│   ├── triggers/              # CLIP visual & VAD audio triggers
│   ├── knowledge/             # Knowledge graph & entity extraction
│   ├── graph/                 # Event management
│   ├── parametric/            # Memory consolidation
│   ├── routing/               # Query routing
│   ├── evolution/             # Self-evolution
│   └── utils/                 # Embedding, model utilities, logging
├── configs/                   # Benchmark YAML configs
├── benchmarks/                # LoCoMo & Mem-Gallery adapters
├── tests/                     # 126 unit tests
├── examples/                  # Usage examples
├── setup.py
├── requirements.txt
└── LICENSE                    # Apache 2.0
```

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

### Display memory statistics via CLI

Source: https://github.com/aiming-lab/simplemem/blob/main/simplemem/integrations/simplemem-skill/references/cli-reference.md

Use the stats command to view total entries and database configuration.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py stats
```

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

### Run Omni-SimpleMem Benchmarks

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

Execute the LoCoMo benchmark script from the OmniSimpleMem directory.

```bash
cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o
```

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

### Run EvolveMem Benchmarks

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

Execute evolution and benchmark scripts from the EvolveMem directory.

```bash
cd EvolveMem
python run_evolution.py --data data/locomo10.json --max-rounds 7
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3
python run_benchmark.py membench --agent FirstAgent --max-rounds 3
```

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

### create(mode="auto", **kwargs)

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

Factory function that returns a backend instance based on the specified mode.

```APIDOC
## create(mode="auto", **kwargs)

### Description
Factory that returns a backend instance. kwargs are forwarded to the selected backend's constructor.

### Parameters
- **mode** (str) - Optional - The backend mode ('auto', 'text', or 'omni').
- **kwargs** (dict) - Optional - Additional configuration arguments.
```

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

### Run Benchmark Evaluation

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

Evaluate the agent performance on LoCoMo or MemBench benchmarks.

```bash
# LoCoMo evaluation
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3

# MemBench evaluation
python run_benchmark.py membench --agent FirstAgent \
    --categories simple comparative aggregative conditional \
    --initial weak --max-rounds 3
```

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

### Explicit Backend Selection

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

Using the create function to specify a memory mode and listing available backends.

```python
from simplemem import create, list_modes

# Single-modal text memory
mem = create(mode="text", clear_db=True)

# Multimodal memory (text, image, audio, video)
mem = create(mode="omni", data_dir="./my_memory")

# Inspect the available backends
print(list_modes())
# {'text': 'Single-modal text memory ...', 'omni': 'Multimodal memory ...'}
```

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

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

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

### Configure Ollama Provider

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

Settings for connecting to an Ollama instance running on the host machine.

```bash
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
```

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

### Use Omni Backend via Auto Mode

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

Demonstrates adding multimodal inputs to trigger the omni backend automatically.

```python
from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_image() → omni backend auto-selected
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()
```

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

### Use Text Backend via Auto Mode

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

Demonstrates adding dialogue entries to trigger the text backend automatically.

```python
from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_dialogue() → text backend auto-selected
mem.add_dialogue(
    "Alice",
    "Bob, let's meet at Starbucks tomorrow at 2pm",
    "2025-11-15T14:30:00",
)
mem.add_dialogue(
    "Bob",
    "Sure, I'll bring the market analysis report",
    "2025-11-15T14:31:00",
)
mem.finalize()

answer = mem.ask("When and where will Alice and Bob meet?")
# → "16 November 2025 at 2:00 PM at Starbucks"
```

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

### Query memory system via CLI

Source: https://github.com/aiming-lab/simplemem/blob/main/simplemem/integrations/simplemem-skill/references/cli-reference.md

Use the query command to retrieve answers based on natural language questions.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question QUESTION [--enable-reflection] [--top-k K]
```

```bash
# Simple query
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "What did Alice say about the deadline?"
```

```bash
# With reflection enabled
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "Summarize all project updates" --enable-reflection
```

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

### Use Custom Table Names

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

Organize conversation contexts by specifying a custom table name.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py --table-name my_custom_table add --speaker "User" --content "Message"
```

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

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

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

### Basic Memory Usage

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

Initialize the orchestrator, store text data with tags, and perform a semantic query.

```python
from omni_memory import OmniMemoryOrchestrator, OmniMemoryConfig

config = OmniMemoryConfig()
config.embedding.model_name = "all-MiniLM-L6-v2"
config.embedding.embedding_dim = 384

orchestrator = OmniMemoryOrchestrator(config=config, data_dir="./my_memory")

# Store
orchestrator.add_text(
    "User loves hiking in the Rocky Mountains every summer.",
    tags=["session_id:D1", "timestamp:2024-06-15"],
)

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

orchestrator.close()
```

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

### Initialize Multi-tenant Memory Tables

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

Isolate memory storage by defining unique table names for different users or contexts.

```python
from simplemem import create

# User A's memory
system_a = create(mode="text", table_name="user_alice_memories", clear_db=False)

# User B's memory
system_b = create(mode="text", table_name="user_bob_memories", clear_db=False)
```

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

### SimpleMem Initialization

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

Initializes a SimpleMem instance using the create factory method with specific configuration parameters.

```APIDOC
## SimpleMem Initialization

### Description
Initializes the SimpleMem instance. Parameters passed here override environment variables and config.py settings.

### Method
create(mode, **kwargs)

### Parameters
- **mode** (str) - Required - The backend mode (e.g., "text").
- **api_key** (str) - Optional - OpenAI-compatible API key.
- **model** (str) - Optional - LLM model name.
- **base_url** (str) - Optional - Custom API endpoint.
- **db_path** (str) - Optional - LanceDB storage path.
- **table_name** (str) - Optional - Memory table name.
- **clear_db** (bool) - Optional - Clear existing database on start.
- **enable_thinking** (bool) - Optional - Deep-thinking mode.
- **use_streaming** (bool) - Optional - Stream LLM responses.
- **enable_planning** (bool) - Optional - Multi-query retrieval planning.
- **enable_reflection** (bool) - Optional - Reflection-based retrieval.
- **max_reflection_rounds** (int) - Optional - Max reflection iterations.
- **enable_parallel_processing** (bool) - Optional - Parallel memory building.
- **max_parallel_workers** (int) - Optional - Max workers for building.
- **enable_parallel_retrieval** (bool) - Optional - Parallel query execution.
- **max_retrieval_workers** (int) - Optional - Max workers for retrieval.
```

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

### Initialize and Optimize SimpleMem

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

Basic usage for importing the text core and triggering the self-evolving retrieval optimization process.

```python
from simplemem import SimpleMem
```

```python
simplemem.optimize(...)
```

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

### Initialize SimpleMem

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

Initialize the SimpleMem instance using the default auto mode, which selects the backend based on the first method called.

```python
from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — backend chosen by first call
```

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

### Run LoCoMo Benchmarks

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

Execute LoCoMo benchmark tests from the repository root using the provided Python script.

```bash
python test_locomo10.py                       # full LoCoMo benchmark
python test_locomo10.py --num-samples 5       # quick subset
python test_locomo10.py --result-file my_results.json
```

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

### ask(question)

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

Queries the text memory system with a natural-language question.

```APIDOC
## ask(question)

### Description
Query the memory system with a natural-language question.

### Parameters
- **question** (str) - Required - The question to ask the memory system.
```

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

### Add a dialogue entry via CLI

Source: https://github.com/aiming-lab/simplemem/blob/main/simplemem/integrations/simplemem-skill/references/cli-reference.md

Use the add command to insert a speaker and content into the memory store.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker SPEAKER --content CONTENT [--timestamp TIMESTAMP]
```

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "Alice" --content "Project deadline is Friday"
```

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

### Import MemoryEntry Model

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

Access the atomic memory unit structure used by the compression pipeline.

```python
from simplemem.core.models.memory_entry import MemoryEntry
```

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

### Configure Claude Desktop for Omni-SimpleMem

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

Add the server configuration to the Claude Desktop JSON file to enable integration.

```json
{
  "mcpServers": {
    "omni-simplemem": {
      "command": "python",
      "args": ["-m", "omni_mcp", "--data-dir", "~/.omni_simplemem/mcp"],
      "cwd": "/absolute/path/to/SimpleMem/OmniSimpleMem",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "PYTHONPATH": "/absolute/path/to/SimpleMem/OmniSimpleMem"
      }
    }
  }
}
```

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

### Configure CrossMemOrchestrator with Custom Paths and Token Limit

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

Customize the CrossMemOrchestrator's configuration by specifying custom paths for the SQLite database and LanceDB, as well as setting a custom maximum context token limit.

```python
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,
)
```

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

### Process Meeting Notes

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

Shows how to batch process dialogue entries from a meeting transcript and query for specific insights.

```python
from simplemem import create
from simplemem.core.models.memory_entry import Dialogue

mem = create(mode="text", clear_db=True)

# Process a meeting transcript
meeting_dialogues = [
    Dialogue(dialogue_id=1, speaker="PM", content="Let's review Q1 targets", timestamp="2025-01-15T10:00:00"),
    Dialogue(dialogue_id=2, speaker="Sales", content="We achieved 120% of our target", timestamp="2025-01-15T10:02:00"),
    Dialogue(dialogue_id=3, speaker="PM", content="Great! Q2 target is set to 50M", timestamp="2025-01-15T10:05:00"),
    Dialogue(dialogue_id=4, speaker="Finance", content="Budget approval needed by Friday", timestamp="2025-01-15T10:08:00"),
]

mem.add_dialogues(meeting_dialogues)
mem.finalize()

# Query meeting insights
print(mem.ask("What was the Q1 performance?"))
print(mem.ask("What's the deadline for budget approval?"))
```

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

### Set Database Path

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

Specify a writable path for the database to avoid permission errors.

```python
mem = create(mode="text", db_path="/path/with/write/permission")
```

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

### Configure API Key via Environment Variables

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

Setting the OpenAI API key programmatically using environment variables before initialization.

```python
import os
from simplemem import SimpleMem

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

# Initialize (reads OPENAI_API_KEY from the environment)
mem = SimpleMem()
```

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

### Configure Requesty Provider

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

Settings for using Requesty as an OpenAI-compatible router.

```bash
LLM_PROVIDER=requesty
REQUESTY_BASE_URL=https://router.requesty.ai/v1
```

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

### Manage Multi-Session Memory

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

Illustrates how to persist data across separate application sessions by reusing the same database path.

```python
from simplemem import create

# Session 1: Add information
mem = create(mode="text", db_path="./persistent_memory", clear_db=False)
mem.add_dialogue("User", "My birthday is March 15th", "2025-01-10T10:00:00")
mem.finalize()

# ... application closes ...

# Session 2: Query previously stored information
mem = create(mode="text", db_path="./persistent_memory", clear_db=False)
answer = mem.ask("When is the user's birthday?")
print(answer)  # "The user's birthday is March 15th"
```

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

### Optimize and persist retrieval configuration

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

Generate an optimized configuration object based on development questions and save it for deployment.

```python
import simplemem
from simplemem import SimpleMem, load_config

# mem is a finalized SimpleMem instance with memories already built
dev_questions = [
    ("When is the meeting?", "2pm tomorrow at Starbucks"),
    ("What should Bob prepare?", "the report"),
]
config = simplemem.optimize(mem, dev_questions, max_rounds=3)
config.save("my_config.json")

# Later, deploy with the optimized config
config = load_config("my_config.json")
mem = SimpleMem(config=config)
```

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

### Manage Docker Containers

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

Common commands for monitoring logs and stopping the service.

```bash
docker compose logs -f simplemem   # Follow logs
docker compose down                 # Stop and remove containers
```

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

### Define configuration variables

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

Set environment-specific variables within the config.py file.

```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None            # or a custom OpenAI-compatible endpoint
LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"
```

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

### SimpleMem Directory Structure

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

Overview of the file and directory layout for the simplemem-skill project.

```text
simplemem-skill/
├── SKILL.md              # Main skill documentation (Claude reads this)
├── requirements.txt      # Python dependencies
├── scripts/              # CLI tools for memory management
├── src/                  # Core SimpleMem implementation
├── references/           # Detailed guides (loaded on-demand)
└── data/                 # LanceDB storage (auto-created)
```

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

### Specify Port

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

Use the --port flag to specify a custom port for the application. This allows you to run the application on a port other than the default.

```bash
python run.py --port 3000
```

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

### Configure Custom LLM Endpoints

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

Connect to OpenAI-compatible APIs by specifying the base URL and model name.

```python
from simplemem import create

# Using Qwen (Alibaba DashScope)
mem = create(
    mode="text",
    api_key="your-qwen-api-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    model="qwen-plus",
    clear_db=True,
)

# Using Azure OpenAI
mem = create(
    mode="text",
    api_key="your-azure-key",
    base_url="https://your-resource.openai.azure.com/openai/deployments/your-deployment",
    model="gpt-4.1-mini",
    clear_db=True,
)
```

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

### SimpleMem Write Flow: Dialogue to Memory

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

Illustrates the process of converting user dialogue into structured memory entries, including LLM processing, fact extraction, and storage in a vector database.

```text
Dialogue Input                  Processing                     Memory Storage
───────────────────────────────────────────────────────────────────────────

"I'll meet Bob            ┌─────────────────┐
at Starbucks             │ LLM Processing  │
tomorrow at 3pm"      ──▶│                 │ ──────────────▶  Atomic Fact
                          └─────────────────┘
                                                      │
                                                      ▼
                                              ┌─────────────────────────┐
                                              │ Atomic Fact:            │
                                              │ "User will meet Bob at  │
                                              │  Starbucks on           │
                                              │  2025-01-15 at 15:00"   │
                                              │                         │
                                              │ persons: [User, Bob]    │
                                              │ location: Starbucks     │
                                              │ timestamp: 2025-01-15   │
                                              │ topic: Meeting          │
                                              └───────────┬─────────────┘
                                                          │
                                                          ▼
                                              ┌─────────────────────────┐
                                              │      Embedding          │
                                              │   (qwen3-embed-4b)      │
                                              └───────────┬─────────────┘
                                                          │
                                                          ▼
                                              ┌─────────────────────────┐
                                              │   LanceDB Vector Store  │
                                              └─────────────────────────┘
```

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

### Run Self-Evolution

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

Execute the evolution process with different round counts or by using a pre-extracted cache.

```bash
# Full evolution on LoCoMo (7 rounds)
python run_evolution.py --data data/locomo10.json --max-rounds 7

# Quick 3-round evolution
python run_evolution.py --data data/locomo10.json --max-rounds 3

# Start from pre-extracted memory cache
python run_evolution.py --use-cache cache.json --max-rounds 5
```

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

### Global Options

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

Global options that can be applied to any SimpleMem CLI command.

```APIDOC
## Global Options

### `--table-name TABLE_NAME`

Use a custom table name instead of the default `memory_entries`.
```