simplemem
/simplemem
Build persistent LLM agent memory with SimpleMem - semantic lossless compression with 30x token reduction. MCP server (cloud/self-hosted), Python API, cross-session memory. Use when: adding long-term memory to agents, cross-session context recall, semantic dialogue search, memory consolidation.
- Author
- evolv3-ai ↗
- Repository
- vibe-skills ↗
- Licence
- MIT
- Last repository change
- 22.07.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 7
No signals detected. Repository changed on 22.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Build persistent LLM agent memory with SimpleMem - semantic lossless compression with 30x token reduction. MCP server (cloud/self-hosted), Python API, cross-session memory. Use when: adding long-term memory to agents, cross-session context recall, semantic dialogue search, memory consolidation.
Original author description
Build persistent LLM agent memory with SimpleMem - semantic lossless compression with 30x token reduction. MCP server (cloud/self-hosted), Python API, cross-session memory. Use when: adding long-term memory to agents, cross-session context recall, semantic dialogue search, memory consolidation.
How it works
- Integration Paths
- MCP Server Setup (Recommended)
- Python API
- Configuration
- Cross-Session Memory (SimpleMem-Cross)
- Three-Stage Pipeline
- Data Model
- Troubleshooting
SKILL.md preview
---
name: simplemem
description: >
Build persistent LLM agent memory with SimpleMem - semantic lossless compression
with 30x token reduction. MCP server (cloud/self-hosted), Python API, cross-session
memory. Use when: adding long-term memory to agents, cross-session context recall,
semantic dialogue search, memory consolidation.
---
# SimpleMem
Efficient lifelong memory for LLM agents via semantic lossless compression.
SimpleMem converts unstructured dialogue into compact, atomic memory units with coreference resolution and temporal anchoring. It achieves 43.24% F1 on the LoCoMo benchmark with 30x fewer tokens than full-context methods.
## Integration Paths
Choose the path that fits your use case:
| Path | Best For | Setup |
|------|----------|-------|
| **MCP Server (cloud)** | Quickest start, multi-platform | Config only |
| **MCP Server (self-hosted)** | Privacy, custom deployment | Docker or Python |
| **Python API (`pip install simplemem`)** | Programmatic integration | pip/uv |
| **SimpleMem-Cross** | Cross-session agent memory | Python + orchestrator |
## MCP Server Setup (Recommended)
### Cloud Service
The fastest path. Uses the hosted service at `mcp.simplemem.cloud`.
1. Visit `https://mcp.simplemem.cloud`
2. Enter your OpenRouter API key to get an auth token
3. Add to your MCP client config:
**Claude Desktop / Claude Code (`~/.claude.json`):**
```json
{
"mcpServers": {
"simplemem": {
"url": "https://mcp.simplemem.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
**Cursor (`.cursor/mcp.json`):**
```json
{
"mcpServers": {
"simplemem": {
"url": "https://mcp.simplemem.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
### Self-Hosted (Docker)
For privacy-sensitive deployments or custom infrastructure:
```bash
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem/MCP
# Configure environment
export JWT_SECRET_KEY="your-secure-random-secret"
export ENCRYPTION_KEY="your-32-byte-encryption-key!!"
# Run with Docker
docker compose up -d
```
The server exposes:
- Web UI: `http://localhost:8000/`
- REST API: `http://localhost:8000/api/`
- MCP endpoint: `http://localhost:8000/mcp`
See [references/mcp-setup.md](references/mcp-setup.md) for full self-hosting guide.
### MCP Tools Available
| Tool | Purpose |
|------|---------|
| `memory_add` | Store a dialogue (auto-compresses to atomic facts) |
| `memory_add_batch` | Batch store multiple dialogues |
| `memory_query` | Semantic Q&A over stored memories |
| `memory_retrieve` | Raw memory entry retrieval |
| `memory_delete` | Delete entries by entry_id or ref_id |
| `memory_stats` | Storage statistics |
| `memory_clear` | Delete all memories (irreversible) |
## Python API
Install via pip or uv:
```bash
pip install simplemem
# or
uv add simplemem
```
### Basic Usage
```python
from simplemem import SimpleMemSystem
# Initialize (uses config.py for API settings)
system = SimpleMemSystem(clear_db=True)
# Stage 1: Add dialogues (semantic structured compression)
system.add_dialogue("Alice", "Let's meet at Starbucks tomorrow at 2pm", "2025-11-15T14:30:00")
system.add_dialogue("Bob", "I'll bring the market analysis report", "2025-11-15T14:31:00")
# Finalize atomic encoding
system.finalize()
# Stage 3: Query with intent-aware retrieval
answer = system.ask("When and where will Alice and Bob meet?")
# "16 November 2025 at 2:00 PM at Starbucks"
```
### Parallel Processing
For large dialogue datasets:
```python
system = SimpleMemSystem(
clear_db=True,
enable_parallel_processing=True,
max_parallel_workers=8,
enable_parallel_retrieval=True,
max_retrieval_workers=4
)
```
### Memory Deletion
Delete entries by ID:
```python
# Delete by entry_id
system.vector_store.delete_by_id(entry_id="uuid-here")
# Delete by ref_id (application-level reference)
system.vector_store.delete_by_ref_id(ref_id="my-ref")
```
## Configuration
SimpleMem supports any OpenAI-compatible API provider:
```python
# config.py
OPENAI_API_KEY = "your-api-key" # OpenAI, OpenRouter, or compatible
OPENAI_BASE_URL = None # Set for non-OpenAI providers
# Models
LLM_MODEL = "gpt-4.1-mini" # Or any OpenAI-compatible model
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # State-of-the-art retrieval
# Via OpenRouter (multi-provider gateway)
OPENROUTER_API_KEY = "sk-or-..."
LLM_MODEL = "openai/gpt-4.1-mini" # OpenRouter model path
EMBEDDING_MODEL = "qwen/qwen3-embedding-8b"
EMBEDDING_DIMENSION = 4096
```
**Provider options:**
- **OpenAI direct** - Set `OPENAI_API_KEY`
- **OpenRouter** - Set `OPENROUTER_API_KEY`, prefix model names with provider
- **LiteLLM** - Multi-provider abstraction, configure via `LITELLM_*` settings
- **Azure OpenAI** - Set `OPENAI_BASE_URL` to your Azure endpoint
- **Qwen / local models** - Set `OPENAI_BASE_URL` to your endpoint
See [references/api-reference.md](references/api-reference.md) for full configuration.
## Cross-Session Memory (SimpleMem-Cross)
SimpleMem-Cross enables persistent memory across conversations. Agents recall context, decisions, and learnings from previous sessions automatically.
**Performance:** 64% improvement over Claude-Mem on LoCoMo benchmark (score 48 vs 29.3).
### Quick Example
```python
from cross.orchestrator import create_orchestrator
async def main():
orch = create_orchestrator(project="my-project")
# Start session - previous context 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 past 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()
```
### Key Features
| Feature | Description |
|---------|-------------|
| Session lifecycle | start -> record -> stop -> end with full event tracking |
| Automatic context injection | Token-budgeted context from previous sessions at start |
| Event collection | Messages, tool uses, file changes with 3-tier redaction |
| Observation extraction | Heuristic extraction of decisions, discoveries, learnings |
| Provenance tracking | Every memory links back to source evidence |
| Consolidation | Automatic decay, merge, and prune of old memories |
See [references/cross-session.md](references/cross-session.md) for full API and architecture.
## Three-Stage Pipeline
SimpleMem's architecture is based on semantic lossless compression:
### Stage 1: Semantic Structured Compression
Raw dialogue is converted to atomic, self-contained memory units:
- **Coreference resolution**: "He" becomes "Bob"
- **Temporal anchoring**: "tomorrow" becomes "2025-11-16T14:00:00"
- **Density gating**: Filters low-information content
```
Input: "He'll meet Bob tomorrow at 2pm"
Output: "Alice will meet Bob at Starbucks on 2025-11-16T14:00:00"
```
### Stage 2: Online Semantic Synthesis
Related fragments are consolidated during writes:
- Eliminates redundant information
- Merges related facts into unified representations
- Maintains compact memory topology
### Stage 3: Intent-Aware Retrieval Planning
Queries trigger parallel multi-view retrieval:
- **Semantic layer**: Dense vector similarity (1024-d embeddings)
- **Lexical layer**: BM25 keyword matching
- **Symbolic layer**: Metadata filtering (persons, locations, timestamps, entities)
- Dynamic retrieval depth based on query complexity
See [references/architecture.md](references/architecture.md) for detailed architecture.
## Data Model
Each memory entry contains:
| Field | Type | Description |
|-------|------|-------------|
| `entry_id` | UUID | Unique identifier |
| `ref_id` | String | Application-level reference (for deletion) |
| `lossless_restatement` | String | Self-contained atomic fact |
| `keywords` | List[str] | Core keywords for BM25 search |
| `timestamp` | ISO 8601 | When the event occurred |
| `location` | String | Where (natural language) |
| `persons` | List[str] | People mentioned |
| `entities` | List[str] | Companies, products, organizations |
| `topic` | String | Topic phrase |
| `agents` | List[str] | Agent sources |
| `source` | String | Origin identifier |
## Troubleshooting
**Embedding dimension mismatch:**
```
RuntimeError: lance error: Invalid: ListType can only be casted to FixedSizeListType
```
The `EMBEDDING_DIMENSION` in config doesn't match the model's output. Update the value and clear the database: `rm -rf data/lancedb/*`
**API key not detected:**
- Verify key is set in `config.py` (not `config.py.example`)
- For OpenRouter keys, ensure they start with `sk-or-`
- Restart Python after updating the key
**Model not found:**
- Use full provider path for OpenRouter: `openai/gpt-4.1-mini` not `gpt-4.1-mini`
- Check available models at `openrouter.ai/models`
Files in this package (7)
- SKILL.md 9 KB
- assets/config.py.example 3 KB
- references/api-reference.md 6 KB
- references/architecture.md 4 KB
- references/cli-reference.md 3 KB
- references/cross-session.md 5 KB
- references/mcp-setup.md 7 KB
Versions
The database has no other skills named simplemem.
Database snapshot: 13.11.2026 · package version 45d20a14e444 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100agent-memory
Give an agent persistent semantic memory with @three-ws/agent-memory. Use when code needs to remember facts across sessions, recall them by meaning, read the entity graph, or curate an agent's working context. - 100agent-memory
Add persistent memory to AI coding agents — file-based, vector, and semantic search memory systems that survive between sessions. Use when a user asks to "remember this", "add memory to my agent", "persist context between sessions", "build a knowledge base for my agent", "set up… - 90agent-memory
Use when implementing or managing persistent, hierarchical memory systems for AI agents. Covers cross-session state, fact supersession, and self-managed memory tools to enable long-term recall and adaptive agent behavior. - 90project-memory
Use when working in a repository that keeps durable project context, cross-session memory, incident history, decisions, or agent state across Claude, Codex, and later sessions. - 95cpersona-memory
Give Claude persistent, searchable memory across sessions using the CPersona MCP server. Use this skill whenever the user wants Claude to remember things between conversations, asks to install or set up CPersona / a memory server, or when CPersona tools are available and the… - 100shodh-memory
Persistent memory system for AI agents. Use this skill to remember context across conversations, recall relevant information, and build long-term knowledge. Activate when you need to store decisions, learnings, errors, or context that should persist beyond the current session.