SimpleMem Documentation

SimpleMem is composed of four functional layers:

1. API Layer (OpenRouter): Acts as a unified gateway for all LLM and embedding calls, providing multi-provider access and cost tracking.
2. Storage Layer (LanceDB): A vector database that stores dialogue entries and their semantic embeddings.
3. Retrieval Layer (Hybrid Retriever): Combines semantic (vector) search and keyword (BM25) search. The number of retrieved entries is controlled via a configurable top-k parameter.
4. Generation Layer (Answer Generator): Uses retrieved context to generate natural language answers. It supports an optional Reflection Mode for multi-step reasoning on complex queries.

The following tools run fully offline and do not require an API key:

• omni_add_text
• omni_add_document
• omni_stats
• omni_list_events
• omni_list_namespaces
• omni_consolidate
• omni_delete_namespace

Tools requiring an LLM (and thus an OPENAI_API_KEY) include image/audio/video captioning, omni_query, and omni_answer.

SimpleMem's text backend converts raw dialogue into compact, retrievable memory units using three core mechanisms:

1. Semantic Structured Compression: Filters redundant content and reformulates dialogue into atomic, self-contained facts with absolute timestamps and resolved coreferences.
2. Online Semantic Synthesis: Performs on-the-fly synthesis during the write phase. It consolidates related memory fragments into higher-level abstract representations immediately to prevent redundancy.
3. Intent-Aware Retrieval Planning: Uses an LLM to generate a retrieval plan based on latent search intent, executing parallel multi-view retrieval across semantic, lexical, and symbolic indexes.

The fastest way to use SimpleMem is via the hosted service. This provides a managed memory service for your LLM agents without local setup.

1. Visit https://mcp.simplemem.cloud.
2. Enter your OpenRouter API Key.
3. Obtain your authentication token.
4. Configure your MCP client using the token (see 'Configure an MCP Client' below).

You can expose the memory system via a FastAPI REST server. Ensure you have the [server] dependency installed and your OPENAI_API_KEY set.

pip install -e ".[server]"
export OPENAI_API_KEY=your_key_here
python examples/api_server.py

Once running, the interactive documentation is available at http://localhost:8000/docs.

SimpleMem requires an OpenRouter API key to handle all LLM and embedding requests.

1. Obtain a key from openrouter.ai/keys.
2. Ensure the key follows the format starting with sk-or-.
3. Configure your specific LLM and embedding models within the config.py file of the project.

You can run the memory system as a standalone HTTP service using uvicorn or mount it onto an existing FastAPI application.

# Option 1: Create a standalone app
from cross.api_http import create_app
app = create_app(project="my-project")

# Run via CLI:
# uvicorn cross.api_http:app --host 0.0.0.0 --port 8000

# Option 2: Mount on an existing FastAPI app
from fastapi import FastAPI
from cross.api_http import create_cross_router
from cross.orchestrator import create_orchestrator

app = FastAPI()
orch = create_orchestrator(project="my-project")
router = create_cross_router(orch)
app.include_router(router, prefix="/cross")

To use the simplemem-skill, install the required dependencies and configure your OpenRouter API key.

1. Install dependencies: Navigate to the skill directory and install requirements via pip.
2. Configure OpenRouter: Copy the example configuration file to src/config.py and set your OPENROUTER_API_KEY.
3. Data Storage: Memories are automatically stored in the data/lancedb/ directory.

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

# Configure OpenRouter API
cp src/config.py.example src/config.py
# Edit src/config.py and set your OPENROUTER_API_KEY

To use OpenRouter as the unified API gateway for LLM and embedding operations in simplemem-skill, follow these steps:

1. Get an API Key: Create an account at openrouter.ai/keys. Your key will start with sk-or-.
2. Initialize Configuration: Navigate to the skill directory and copy the example configuration file to the active config file:

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

3. Configure Credentials: Open src/config.py and set your OPENROUTER_API_KEY.

To use SimpleMem with MCP-compatible clients (like Claude or Cursor), add the server configuration to your MCP JSON settings file. Replace YOUR_TOKEN with the authentication token obtained from the cloud service or your self-hosted instance.

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

To install EvolveMem, clone the main SimpleMem repository, navigate to the EvolveMem directory, and install the required dependencies using pip.

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