SimpleMem

<div align="center"> <img alt="simplemem_logo" src="https://github.com/user-attachments/assets/6ea54ad1-e007-442c-99d7-1174b10d1fec" width="450"> <div align="center"> ## Efficient Lifelong Memory for LLM Agents — Text & Multimodal <small>Store, compress, and retrieve long-term memories with semantic lossless compression. Now with multimodal support for text, image, audio & video. Works across Claude, Cursor, LM Studio, and more.</small> </div> <p><b>Works with any AI platform that supports MCP or Python integration</b></p> <table> <tr> <td align="center" width="100"> <a href="https://www.anthropic.com/claude"> <img src="https://cdn.simpleicons.org/claude/D97757" width="48" height="48" alt="Claude Desktop" /> </a><br/> _{<a href="https://www.anthropic.com/claude"><b>Claude Desktop</b></a>} </td> <td align="center" width="100"> <a href="https://cursor.com"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/cursor/FFFFFF"> <img src="https://cdn.simpleicons.org/cursor/000000" width="48" height="48" alt="Cursor" /> </picture> </a><br/> _{<a href="https://cursor.com"><b>Cursor</b></a>} </td> <td align="center" width="100"> <a href="https://lmstudio.ai"> <img src="https://github.com/lmstudio-ai.png?size=200" width="48" height="48" alt="LM Studio" /> </a><br/> _{<a href="https://lmstudio.ai"><b>LM Studio</b></a>} </td> <td align="center" width="100"> <a href="https://cherry-ai.com"> <img src="https://github.com/CherryHQ.png?size=200" width="48" height="48" alt="Cherry Studio" /> </a><br/> _{<a href="https://cherry-ai.com"><b>Cherry Studio</b></a>} </td> <td align="center" width="100"> <a href="https://pypi.org/project/simplemem/"> <img src="https://cdn.simpleicons.org/pypi/3775A9" width="48" height="48" alt="PyPI" /> </a><br/> _{<a href="https://pypi.org/project/simplemem/"><b>PyPI Package</b></a>} </td> <td align="center" width="100"> _{<b>+ Any MCP<br/>Client</b>} </td> </tr> </table> <div align="center"> <br/> [🇨🇳 中文](./docs/i18n/README.zh-CN.md) • [🇯🇵 日本語](./docs/i18n/README.ja.md) • [🇰🇷 한국어](./docs/i18n/README.ko.md) • [🇪🇸 Español](./docs/i18n/README.es.md) • [🇫🇷 Français](./docs/i18n/README.fr.md) • [🇩🇪 Deutsch](./docs/i18n/README.de.md) • [🇧🇷 Português](./docs/i18n/README.pt-br.md)<br/> [🇷🇺 Русский](./docs/i18n/README.ru.md) • [🇸🇦 العربية](./docs/i18n/README.ar.md) • [🇮🇹 Italiano](./docs/i18n/README.it.md) • [🇻🇳 Tiếng Việt](./docs/i18n/README.vi.md) • [🇹🇷 Türkçe](./docs/i18n/README.tr.md) <br/> [](https://aiming-lab.github.io/SimpleMem-Page) <p align="center"> <a href="https://arxiv.org/abs/2601.02553"><img src="https://img.shields.io/badge/arXiv-2601.02553-b31b1b?style=flat&labelColor=555" alt="arXiv"></a> <a href="https://github.com/aiming-lab/SimpleMem"><img src="https://img.shields.io/badge/github-SimpleMem-181717?style=flat&labelColor=555&logo=github&logoColor=white" alt="GitHub"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/aiming-lab/SimpleMem?style=flat&label=license&labelColor=555&color=2EA44F" alt="License"></a> <a href="https://github.com/aiming-lab/SimpleMem/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&labelColor=555" alt="PRs Welcome"></a> <br/> <a href="https://pypi.org/project/simplemem/"><img src="https://img.shields.io/pypi/v/simplemem?style=flat&label=pypi&labelColor=555&color=3775A9&logo=pypi&logoColor=white" alt="PyPI"></a> <a href="https://pypi.org/project/simplemem/"><img src="https://img.shields.io/pypi/pyversions/simplemem?style=flat&label=python&labelColor=555&color=3775A9&logo=python&logoColor=white" alt="Python"></a> <a href="https://mcp.simplemem.cloud"><img src="https://img.shields.io/badge/MCP-mcp.simplemem.cloud-14B8A6?style=flat&labelColor=555" alt="MCP Server"></a> <a href="https://github.com/aiming-lab/SimpleMem"><img src="https://img.shields.io/badge/Claude_Skills-supported-FFB000?style=flat&labelColor=555" alt="Claude Skills"></a> <br/> <a href="https://discord.gg/KA2zC32M"><img src="https://img.shields.io/badge/Discord-Join_Chat-5865F2?style=flat&labelColor=555&logo=discord&logoColor=white" alt="Discord"></a> <a href="fig/wechat_logo3.JPG"><img src="https://img.shields.io/badge/WeChat-Group-07C160?style=flat&labelColor=555&logo=wechat&logoColor=white" alt="WeChat"></a> </p> <br/> [🚀 Quick Start](#-quick-start) • [🌟 Overview](#-overview) • [📈 Results](#-results) • [🧠 Omni-SimpleMem](#-omni-simplemem-multimodal-memory) • [📦 Installation](#-installation) • [🔄 Cross-Session Memory](#-cross-session-memory-text-memory) • [🔌 MCP Server](#-mcp-server-text-memory) • [📝 Citation](#-citation) </div> </div> <br/> ## 🔥 News - **[04/02/2026]** 🧠 **Omni-SimpleMem — Multimodal Memory is Here!** SimpleMem now supports **text, image, audio & video** memory. Achieving **new SOTA on LoCoMo (F1=0.613, +47%)** and **Mem-Gallery (F1=0.810, +51%)** over previous best, Omni-SimpleMem brings state-of-the-art multimodal lifelong memory to your agents. [View Omni-SimpleMem →](OmniSimpleMem/) - **[02/09/2026]** 🚀 **Cross-Session Memory is Here — Outperforming Claude-Mem by 64%!** SimpleMem now supports **persistent memory across conversations**. On the LoCoMo benchmark, SimpleMem achieves a **64% performance boost** over Claude-Mem. Your agents can now recall context, decisions, and learnings from previous sessions automatically. [View Cross-Session Documentation →](cross/README.md) - **[01/20/2026]** **SimpleMem is now available on PyPI!** 📦 Install directly via `pip install simplemem`. [View Package Usage Guide →](docs/PACKAGE_USAGE.md) - **[01/19/2026]** **Added Local Memory Storage for SimpleMem Skill!** 💾 SimpleMem Skill now supports local memory storage within Claude Skills. - **[01/18/2026]** **SimpleMem now supports Claude Skills!** 🚀 Use SimpleMem in claude.ai for long-term memory across conversations. Register at [mcp.simplemem.cloud](https://mcp.simplemem.cloud), configure your token, and import the skill! - **[01/14/2026]** **SimpleMem MCP Server is now LIVE and Open Source!** 🎉 Cloud-hosted memory service at [mcp.simplemem.cloud](https://mcp.simplemem.cloud). Integrates with LM Studio, Cherry Studio, Cursor, Claude Desktop via **Streamable HTTP** MCP protocol. [View MCP Documentation →](MCP/README.md) - **[01/08/2026]** 🔥 Join our [Discord](https://discord.gg/KA2zC32M) and [WeChat Group](fig/wechat_logo3.JPG) to collaborate and exchange ideas! - **[01/05/2026]** SimpleMem paper was released on [arXiv](https://arxiv.org/abs/2601.02553)! --- ## 📑 Table of Contents - [🚀 Quick Start](#-quick-start) - [🌟 Overview](#-overview) - [📈 Results](#-results) - [📝 SimpleMem: Text Memory](#-simplemem-text-memory) - [🧠 Omni-SimpleMem: Multimodal Memory](#-omni-simplemem-multimodal-memory) - [📦 Installation](#-installation) - [🐳 Docker](#-run-with-docker) - [🔌 Router Utilities](#-router-utilities) - [🔄 Cross-Session Memory](#-cross-session-memory-text-memory) - [🔌 MCP Server](#-mcp-server-text-memory) - [🗺️ Roadmap](#️-roadmap) - [📊 Evaluation](#-evaluation) - [📝 Citation](#-citation) --- ## 🚀 Quick Start ### 🧠 Understanding the Basic Workflow At a high level, SimpleMem works as a long-term memory system for LLM-based agents. The workflow consists of three simple steps: 1. **Store information** – Dialogues or facts are processed and converted into structured, atomic memories. 2. **Index memory** – Stored memories are organized using semantic embeddings and structured metadata. 3. **Retrieve relevant memory** – When a query is made, SimpleMem retrieves the most relevant stored information based on meaning rather than keywords. This design allows LLM agents to maintain context, recall past information efficiently, and avoid repeatedly processing redundant history. ### 🎓 Basic Usage SimpleMem provides a **unified entry point** via `simplemem_router`. The default `mode="auto"` **automatically detects** which backend to use based on what you call — no manual configuration needed: ```python import simplemem_router as simplemem mem = simplemem.create() # mode="auto" — backend chosen by first call ``` The first method you call determines the backend: | First call | Backend selected | Why | |:--|:--|:--| | `add_dialogue()` | **Text** (SimpleMem) | Dialogue-based API → text mode | | `add_text()` / `add_image()` / `add_audio()` / `add_video()` | **Omni** (Omni-SimpleMem) | Multimodal API → omni mode | <table> <tr> <td width="50%"> **📝 Auto → Text** (pure text input) ```python import simplemem_router as simplemem mem = simplemem.create() # 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" ``` </td> <td width="50%"> **🧠 Auto → Omni** (multimodal input) ```python import simplemem_router as simplemem mem = simplemem.create() # 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() ``` </td> </tr> </table> > **💡 Tip**: Auto mode picks the lightest backend that fits your data. You can still use `mode="text"` or `mode="omni"` explicitly if you prefer. --- ### 🚄 Advanced: Parallel Processing For large-scale dialogue processing, enable parallel mode: ```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 ) ``` > **💡 Pro Tip**: Parallel processing significantly reduces latency for batch operations! --- ## 🌟 Overview **SimpleMem** is a family of efficient memory frameworks — **SimpleMem** for text and **Omni-SimpleMem** for multimodal (text, image, audio, video) — based on **semantic lossless compression** that addresses the fundamental challenge of **efficient long-term memory for LLM agents**. Unlike existing systems that either passively accumulate redundant context or rely on expensive iterative reasoning loops, SimpleMem maximizes **information density** and **token utilization** through a three-stage pipeline: <table> <tr> <td width="33%" align="center"> ### 🔍 Stage 1 **Semantic Structured Compression** Distills unstructured interactions into compact, multi-view indexed memory units </td> <td width="33%" align="center"> ### 🗂️ Stage 2 **Online Semantic Synthesis** Intra-session process that instantly integrates related context into unified abstract representations to eliminate redundancy </td> <td width="33%" align="center"> ### 🎯 Stage 3 **Intent-Aware Retrieval Planning** Infers search intent to dynamically determine retrieval scope and construct precise context efficiently </td> </tr> </table> > For multimodal memory, see [Omni-SimpleMem](#-omni-simplemem-multimodal-memory) below. <div align="center"> <img src="fig/Fig_framework.png" alt="SimpleMem Framework" width="900"/> *The SimpleMem Architecture: (1) Semantic Structured Compression filters low-utility dialogue and converts informative windows into compact, context-independent memory units. (2) Online Semantic Synthesis consolidates related fragments during writing, maintaining a compact and coherent memory topology. (3) Intent-Aware Retrieval Planning infers search intent to adapt retrieval scope and query forms, enabling parallel multi-view retrieval and token-efficient context construction.* </div> --- ### 🏆 Performance Comparison <div align="center"> <img src="fig/Fig_tradeoff.png" alt="Performance vs Efficiency Trade-off" width="900"/> *SimpleMem achieves superior F1 score (43.24%) with minimal token cost (~550), occupying the ideal top-left position.* **Speed Comparison Demo** <video src="https://github.com/aiming-lab/SimpleMem/raw/main/fig/simplemem-new.mp4" controls width="900"></video> *SimpleMem vs. Baseline: Real-time speed comparison demonstration* </div> <div align="center"> **LoCoMo-10 Benchmark Results (GPT-4.1-mini)** | Model | ⏱️ Construction Time | 🔎 Retrieval Time | ⚡ Total Time | 🎯 Average F1 | |:------|:--------------------:|:-----------------:|:-------------:|:-------------:| | A-Mem | 5140.5s | 796.7s | 5937.2s | 32.58% | | LightMem | 97.8s | 577.1s | 675.9s | 24.63% | | Mem0 | 1350.9s | 583.4s | 1934.3s | 34.20% | | **SimpleMem** ⭐ | **92.6s** | **388.3s** | **480.9s** | **43.24%** | </div> --- ## 📈 Results ### 📊 Benchmark Results (LoCoMo) <details open> <summary><b>🏆 Cross-Session Memory Comparison</b></summary> | System | LoCoMo Score | vs SimpleMem | |:-------|:------------:|:------------:| | **SimpleMem** | **48** | — | | Claude-Mem | 29.3 | **+64%** | </details> <details> <summary><b>🔬 High-Capability Models (GPT-4.1-mini)</b></summary> | Task Type | SimpleMem F1 | Mem0 F1 | Improvement | |:----------|:------------:|:-------:|:-----------:| | **MultiHop** | 43.46% | 30.14% | **+43.8%** | | **Temporal** | 58.62% | 48.91% | **+19.9%** | | **SingleHop** | 51.12% | 41.3% | **+23.8%** | </details> <details> <summary><b>⚙️ Efficient Models (Qwen2.5-1.5B)</b></summary> | Metric | SimpleMem | Mem0 | Notes | |:-------|:---------:|:----:|:------| | **Average F1** | 25.23% | 23.77% | Competitive with 99× smaller model | </details> ### 🧠 Omni-SimpleMem Results <table> <tr> <td align="center" width="170">🏆 <b>0.613 F1</b><br>_{LoCoMo (+47% over prev. SOTA)}</td> <td align="center" width="170">🏆 <b>0.810 F1</b><br>_{Mem-Gallery (+51% over prev. SOTA)}</td> <td align="center" width="140">⚡ <b>3.5x faster</b><br>_{retrieval throughput}</td> <td align="center" width="140">🧠 <b>4 modalities</b><br>_{Text · Image · Audio · Video}</td> </tr> </table> --- ## 📝 SimpleMem: Text Memory ### 1️⃣ Semantic Structured Compression SimpleMem applies an **implicit semantic density gating** mechanism integrated into the LLM generation process to filter redundant interaction content. The system reformulates raw dialogue streams into **compact memory units** — self-contained facts with resolved coreferences and absolute timestamps. Each unit is indexed through three complementary representations for flexible retrieval: <div align="center"> | 🔍 Layer | 📊 Type | 🎯 Purpose | 🛠️ Implementation | |---------|---------|------------|-------------------| | **Semantic** | Dense | Conceptual similarity | Vector embeddings (1024-d) | | **Lexical** | Sparse | Exact term matching | BM25-style keyword index | | **Symbolic** | Metadata | Structured filtering | Timestamps, entities, persons | </div> **✨ Example Transformation:** ```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] ``` --- ### 2️⃣ Online Semantic Synthesis Unlike traditional systems that rely on asynchronous background maintenance, SimpleMem performs synthesis **on-the-fly during the write phase**. Related memory units are synthesized into higher-level abstract representations within the current session scope, allowing repetitive or structurally similar experiences to be **denoised and compressed immediately**. **✨ Example Synthesis:** ```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" ``` This proactive synthesis ensures the memory topology remains compact and free of redundant fragmentation. --- ### 3️⃣ Intent-Aware Retrieval Planning Instead of fixed-depth retrieval, SimpleMem leverages the reasoning capabilities of the LLM to generate a **comprehensive retrieval plan**. Given a query, the planning module infers **latent search intent** to dynamically determine retrieval scope and depth: $$\{ q_{\text{sem}}, q_{\text{lex}}, q_{\text{sym}}, d \} \sim \mathcal{P}(q, H)$$ The system then executes **parallel multi-view retrieval** across semantic, lexical, and symbolic indexes, and merges results through ID-based deduplication: <table> <tr> <td width="50%"> **🔹 Simple Queries** - Direct fact lookup via single memory unit - Minimal retrieval depth - Fast response time </td> <td width="50%"> **🔸 Complex Queries** - Aggregation across multiple events - Expanded retrieval depth - Comprehensive coverage </td> </tr> </table> **📈 Result**: 43.24% F1 score with **30× fewer tokens** than full-context methods. --- <div align="center"> # 🧠 Omni-SimpleMem: Multimodal Memory **NEW** — SimpleMem now handles text, image, audio & video. </div> **Omni-SimpleMem** extends SimpleMem to **unified multimodal memory** — supporting text, image, audio, and video experiences with state-of-the-art accuracy across all five LLM backbones tested. Built on three principles: **Selective Ingestion** (entropy-driven filtering for each modality), **Progressive Retrieval** (hybrid FAISS + BM25 search with pyramid token-budget expansion), and **Knowledge Graph Augmentation** (multi-hop cross-modal reasoning). > 📖 Full documentation, benchmarks, and architecture details: [**Omni-SimpleMem →**](OmniSimpleMem/) --- ## 📦 Installation ### 📝 Notes for First-Time Users - Ensure you are using **Python 3.10 in your active environment**, not just installed globally. - An OpenAI-compatible API key must be configured **before running any memory construction or retrieval**, otherwise initialization may fail. - When using non-OpenAI providers (e.g., Qwen or Azure OpenAI), verify both the model name and `OPENAI_BASE_URL` in `config.py`. - For large dialogue datasets, enabling parallel processing can significantly reduce memory construction time. ### 📋 Requirements - 🐍 Python 3.10 - 🔑 OpenAI-compatible API (OpenAI, Qwen, Azure OpenAI, etc.) ### 🛠️ Setup ```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 ``` ### ⚙️ Configuration Example ```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 ``` --- ## 🐳 Run with Docker The **MCP Server** can be run in Docker for a consistent, isolated environment. Data (LanceDB and user DB) is persisted in a host volume. ### Prerequisites - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) ### Quick run ```bash # From the repository root docker compose up -d ``` - **Web UI:** http://localhost:8000/ - **REST API:** http://localhost:8000/api/ - **MCP (SSE):** http://localhost:8000/mcp/sse?token=&lt;TOKEN&gt; Data is stored in `./data` on the host (created automatically). ### Custom configuration 1. Copy the environment template and edit it: ```bash cp .env.example .env # Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc. ``` 2. Run with the env file: ```bash docker compose --env-file .env up -d ``` ### Using Ollama on the host When `LLM_PROVIDER=ollama` and Ollama runs on your machine (not in Docker), set in `.env`: ```bash LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 ``` On Linux, `host.docker.internal` is enabled automatically via the Compose file. ### Useful commands ```bash docker compose logs -f simplemem # Follow logs docker compose down # Stop and remove containers ``` > 📖 For self-hosting the MCP server (Docker or bare metal), see [MCP Documentation](MCP/README.md). --- ## 🔌 Router Utilities The router uses a **registry-based factory** pattern — backends are lazily loaded only when requested, and dependencies are checked before instantiation. ```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") ``` --- ## ❓ Common Setup Issues & Troubleshooting If you encounter issues while setting up or running SimpleMem for the first time, check the following common cases: ### 1️⃣ API Key Not Detected - Ensure your API key is correctly set in `config.py` - For OpenAI-compatible providers (Qwen, Azure, etc.), verify that `OPENAI_BASE_URL` is configured correctly - Restart your Python environment after updating the key ### 2️⃣ Python Version Mismatch - SimpleMem requires **Python 3.10** - Check your version using: ```bash python --version ``` --- ## 🔄 Cross-Session Memory *(text memory)* **SimpleMem-Cross** extends SimpleMem with persistent cross-conversation memory capabilities. Agents can recall context, decisions, and observations from previous sessions — enabling continuity across conversations without manual context re-injection. ### Key Features | Feature | Description | |---------|-------------| | **Session Lifecycle** | Full session management with start/record/stop/end lifecycle | | **Automatic Context Injection** | Token-budgeted context from previous sessions injected at session start | | **Event Collection** | Record messages, tool uses, file changes with automatic redaction | | **Observation Extraction** | Heuristic extraction of decisions, discoveries, and learnings | | **Provenance Tracking** | Every memory entry links back to source evidence | | **Consolidation** | Decay, merge, and prune old memories to maintain quality | ### Quick Example ```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() ``` ### Architecture ``` Agent Frameworks (Claude Code / Cursor / custom) | +--------------+--------------+ | | Hook/Lifecycle Adapter HTTP/MCP API (FastAPI) | | +--------------+--------------+ | CrossMemOrchestrator | +-----------------+------------------+ | | | Session Manager Context Injector Consolidation (SQLite) (budgeted bundle) (decay/merge/prune) | | | +---------+-------+ | | | Cross-Session Vector Store (LanceDB) <--+ ``` ### Module Reference | Module | Description | |--------|-------------| | `cross/types.py` | Pydantic models, enums, records | | `cross/storage_sqlite.py` | SQLite backend for sessions, events, observations | | `cross/storage_lancedb.py` | LanceDB vector store with provenance | | `cross/hooks.py` | Lifecycle hooks (SessionStart/ToolUse/End) | | `cross/collectors.py` | Event collection with 3-tier redaction | | `cross/session_manager.py` | Full session lifecycle orchestration | | `cross/context_injector.py` | Token-budgeted context builder | | `cross/orchestrator.py` | Top-level facade and factory | | `cross/api_http.py` | FastAPI REST endpoints | | `cross/api_mcp.py` | MCP tool definitions | | `cross/consolidation.py` | Memory maintenance worker | > 📖 For detailed API documentation, see [Cross-Session README](cross/README.md) --- ## 🔌 MCP Server *(text memory)* SimpleMem is available as a **cloud-hosted memory service** via the Model Context Protocol (MCP), enabling seamless integration with AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients. **🌐 Cloud Service**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — or self-host the MCP server locally using [Docker](#-run-with-docker). ### Key Features | Feature | Description | |---------|-------------| | **Streamable HTTP** | MCP 2025-03-26 protocol with JSON-RPC 2.0 | | **Multi-tenant Isolation** | Per-user data tables with token authentication | | **Hybrid Retrieval** | Semantic search + keyword matching + metadata filtering | | **Production Optimized** | Faster response times with OpenRouter integration | ### Quick Configuration ```json { "mcpServers": { "simplemem": { "url": "https://mcp.simplemem.cloud/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` > 📖 For detailed setup instructions and self-hosting guide, see [MCP Documentation](MCP/README.md) --- ## 🗺️ Roadmap **Omni-SimpleMem infrastructure** — bringing multimodal memory to all shared components: - [ ] Omni cross-session memory (text + image + audio + video persistence) - [ ] Omni MCP server (multimodal memory via MCP protocol) - [ ] Omni Docker support - [ ] Omni PyPI package (`pip install omni-simplemem`) - [ ] Omni Claude Skills integration **Core improvements:** - [ ] Streaming ingestion for real-time memory updates - [ ] Memory sharing across multiple agents - [ ] Benchmark expansion (more multimodal benchmarks) Contributions welcome! Open an [issue](https://github.com/aiming-lab/SimpleMem/issues) to discuss. --- ## 📊 Evaluation ### 🧪 Run Benchmark Tests ```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 ``` --- ### 🔬 Reproduce Paper Results Use the exact configurations in `config.py`: - **🚀 High-capability**: GPT-4.1-mini, Qwen3-Plus - **⚙️ Efficient**: Qwen2.5-1.5B, Qwen2.5-3B - **🔍 Embedding**: Qwen3-Embedding-0.6B (1024-d) --- ## 📝 Citation If you use SimpleMem in your research, please cite: ```bibtex @article{simplemem2025, title={SimpleMem: Efficient Lifelong Memory for LLM Agents}, author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu}, journal={arXiv preprint arXiv:2601.02553}, year={2025}, url={https://github.com/aiming-lab/SimpleMem} } ``` ```bibtex @article{omnisimplemem2026, title = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory}, author = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu}, journal = {arXiv preprint arXiv:2604.01007}, year = {2026}, } ``` --- ## 📄 License This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. --- ## 🙏 Acknowledgments We would like to thank the following projects and teams: - 🔍 **Embedding Model**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - State-of-the-art retrieval performance - 🗄️ **Vector Database**: [LanceDB](https://lancedb.com/) - High-performance columnar storage - 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Long-context memory evaluation framework