RememberMe
Integrates with OpenAI-compatible embedding APIs to automatically vectorize memory content for semantic search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RememberMe remember that I prefer dark mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RememberMe - CLI + MCP Server
A dual-mode tool providing long-term memory management for Claude Code and other MCP clients. Features both a CLI interface for direct commands and an MCP server for programmatic access.
Built on Qdrant vector database with semantic search and user/session isolation.
Table of Contents
Related MCP server: mem0-mcp-selfhosted
Features
Dual-Mode: CLI commands + MCP server integration
Semantic Search - Natural language queries using vector similarity
Multi-User Support - User memory isolation via
userIdSession Tracking - Associate memories with specific agent sessions via
runIdContent Deduplication - MD5 hash to detect duplicate memories
Auto-Vectorization - OpenAI-compatible embedding service integration
Quick Start
# Install
pip install -e .
# CLI usage
rememberme add "User prefers dark mode"
rememberme search "preferences" --limit 5
rememberme status
# MCP mode (for Claude Code)
python -m remembermeInstallation
This guide walks you through setting up RememberMe from downloading the repository to your first command.
Prerequisites
Python 3.10+
Qdrant (vector database) - Install via Docker
Embedding API (OpenAI-compatible) - e.g., Doubao, OpenAI, LocalAI
Step 1: Clone the Repository
git clone https://github.com/JoeXie/remember-me.git
cd remember-meOr download and extract the archive from GitHub.
Step 2: Install Dependencies
pip install -e .This installs RememberMe in development mode and creates the rememberme command.
Step 3: Configure Environment
Create the config directory and copy the example env file:
mkdir -p ~/.config/rememberme/
cp .env.example ~/.config/rememberme/.envEdit ~/.config/rememberme/.env with your settings:
# Required: Your embedding API credentials
EMBEDDING_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/coding/v3
# Required: Embedding model configuration
EMBEDDING_MODEL=doubao-embedding-vision
EMBEDDING_DIMENSIONS=2048
# Optional: Qdrant connection (defaults shown)
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=memories
# Optional: Default user ID
DEFAULT_USER_ID=user_defaultStep 4: Start Qdrant
Make sure Qdrant is running:
# Using Docker
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
# Or using Podman
podman run -p 6333:6333 -p 6334:6334 qdrant/qdrantStep 5: Verify Installation
Check that everything is connected:
rememberme statusExpected output:
## RememberMe Status
- **Qdrant**: `Connected`
- Host: `localhost:6333`
- Collection: `memories`
- **Memories**: `0` storedStep 6: Try Your First Command
# Add a memory
rememberme add "User prefers dark mode theme"
# Search memories
rememberme search "preferences"
# Get help
rememberme --helpTroubleshooting
Issue | Solution |
| Ensure Qdrant is running ( |
| Check |
Command not found | Re-run |
Collection error | RememberMe auto-creates the collection on first run |
Config not found | Ensure |
CLI Commands
# Add a new memory
rememberme add "User prefers dark mode"
# Search memories
rememberme search "user preferences"
rememberme search "project decisions" --limit 10
# Check status
rememberme status
# Delete a memory
rememberme delete <memory_id>
# Delete all memories
rememberme delete-all --force
# JSON output (for programmatic use)
rememberme add "text" --json
rememberme search "query" --jsonCLI Options
Option | Description |
| User ID scope (defaults to DEFAULT_USER_ID env var) |
| Enable debug logging |
Architecture
Dual-Mode Entry
┌─────────────────┐
│ __main__.py │
│ auto-detects │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │
▼ ▼
┌───────────┐ ┌─────────────┐
│ CLI Mode │ │ MCP Mode │
│ (Click) │ │ (stdio) │
└─────┬─────┘ └──────┬──────┘
│ │
▼ │
MemoryManager │
(core/memory_manager.py) │
│ │
└────────────────┼────────────────┘
│
▼
┌─────────────────────────┐
│ MemoryStore │
│ (Qdrant operations) │
└─────────────────────────┘MCP Server Integration
Method 1: Using claude code command
# Add MCP server
claude mcp add rememberme -- python -m rememberme
# Or specify working directory
claude mcp add rememberme -- bash -c "cd /path/to/RememberMe && python -m rememberme"Method 2: Manual configuration (persistent)
Add to ~/.claude/settings.json:
{
"mcpServers": {
"rememberme": {
"command": "python",
"args": ["-m", "rememberme"],
"env": {
"QDRANT_HOST": "<HOST>",
"QDRANT_PORT": "<PORT>",
"EMBEDDING_API_KEY": "<YOUR_API_KEY>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
"EMBEDDING_DIMENSIONS": "<EMBEDDING_DIMENSIONS>",
"OPENAI_BASE_URL": "<OPENAI_BASE_URL>",
"DEFAULT_USER_ID": "<DEFAULT_USER_ID>"
}
}
}
}Available MCP Tools
add_memory- Add a memorysearch_memories- Semantic searchget_memory- Get a single memoryupdate_memory- Update a memorydelete_memory- Delete a memorydelete_all_memories- Clear all memories
OpenClaw Skill Integration
For OpenClaw agents, install the RememberMe skill to enable auto-recall and auto-storage:
# Install skill from local repository
/skill install path/to/RememberMe/skills/using-rememberme-cli --always trueImportant: When installing, set always: true to enable automatic pre-execution recall and post-response storage on every conversation.
The skill provides:
Auto-Recall: Automatically searches memory before responding based on context
Auto-Storage: Evaluates and stores new facts after responding
Configuration
Configuration is loaded from ~/.config/rememberme/.env by default.
If this file doesn't exist, it will be created automatically (the directory will be created if needed).
To set up:
mkdir -p ~/.config/rememberme/
cp .env.example ~/.config/rememberme/.envThen edit ~/.config/rememberme/.env with your settings.
Note: Environment variables (e.g., when running via MCP with env in ~/.claude/settings.json) take precedence over the .env file.
Environment Variables
Variable | Description | Default |
| Qdrant server address |
|
| Qdrant port |
|
| Collection name |
|
| Qdrant API key | - |
| Embedding API key | Required |
| Embedding model (OpenAI compatible) |
|
| Vector dimensions |
|
| Embedding API endpoint | Required |
| Default user ID |
|
| Log level |
|
Data Format
Payload structure stored in Qdrant:
{
"userId": "<USER_ID>",
"data": "Memory content",
"hash": "<MD5_HASH>",
"createdAt": "<TIMESTAMP>",
"runId": "agent:main:<UUID>"
}Project Structure
src/rememberme/
├── __main__.py # Dual-mode entry (CLI + MCP auto-detect)
├── config.py # Configuration management
├── models.py # Data models
├── embeddings.py # Embedding service
├── memory_store.py # Qdrant operations
│
├── core/ # Core business logic
│ ├── __init__.py
│ ├── exceptions.py # Custom exceptions
│ └── memory_manager.py
│
├── cli/ # CLI interface
│ ├── __init__.py
│ ├── commands.py # Click commands
│ ├── formatter.py # Output formatters
│ └── lazy.py # Lazy imports
│
├── mcp/ # MCP adapter
│ ├── __init__.py
│ └── adapter.py # MCP server
│
└── skill/ # OpenClaw skill
└── manage_personal_memory.py
skills/ # OpenClaw skills (distributed separately)
└── using-rememberme-cli/
└── SKILL.md
tests/
├── test_models.py
├── test_config.py
└── test_embeddings.pyRun Tests
pytest tests/License
MIT
Available Tools
6 toolsadd_memoryA
Save important information to long-term memory.
When to Use
User stated preferences ('User prefers dark mode')
Personal context ('User is learning Rust', 'User works on payments team')
Project patterns ('API endpoint at /api/v2', 'Uses PostgreSQL for this project')
Agreed decisions ('Team decided to use Docker for deployment')
Constraints ('Budget is tight', 'Deadline is end of month')
Lessons learned ('Don't use library X, it caused issues')
Post-Response Storage Pattern (IMPORTANT)
After responding to user, EVALUATE whether new facts should be stored:
Did user share personal context? → Store it
Did we make a technical decision? → Store it
Did user express a preference? → Store it
Did user correct previous information? → Update existing memory
Deduplication
Search before adding if the info seems routine. Prefer UPDATING existing memories when finding conflicting info. Store each distinct piece as a separate memory with clear, searchable text.
Inputs: text (required), user_id, agent_id, metadata.
delete_all_memoriesA
Bulk delete all memories for a user, optionally filtered to a specific session.
Use Cases
User starts fresh on a project ('Clear all my memories')
Complete privacy wipe requested
Abandoned/debug session cleanup
User explicitly requests full memory reset
Caution
Destructive and irreversible. Confirm with user if request seems broad.
Without agent_id: deletes ALL user memories With agent_id: deletes only that session's memories
Pre-Deletion Recommendation
Before bulk delete, consider:
Informing user how many memories will be deleted
Confirming they want to proceed
Suggesting targeted delete if they only want to remove specific memories
Inputs: user_id, agent_id.
delete_memoryA
Remove a specific memory when it is no longer relevant, was stored in error, or user requests deletion.
When to Use
User requests deletion ('Forget what I said about X')
Old version redundant after update
Something stored by mistake
User explicitly asks to 'forget' or 'delete' specific information
Privacy
Honor all deletion requests promptly. User privacy is paramount.
Cleanup Pattern
After post-response storage evaluation, if a memory is found to be:
Redundant with newly updated version
Incorrectly stored
No longer relevant
→ Delete the old/incorrect memory to maintain clean memory store.
Inputs: id (required).
get_memoryA
Retrieve a specific memory by its ID.
When to Use
You have a memory ID from a previous search result
After adding a memory and need to verify or get full details
User asks for details about a specific memory they referenced
After update/delete operations to confirm results
Pre-Execution Recall
Usually you'll use search_memories first to find relevant memories. Use get_memory when you already have an ID and need full details.
Returns full memory details including metadata, timestamps, and the stored content.
Inputs: id (required).
search_memoriesA
Query stored memories to retrieve relevant context.
Pre-Execution Recall Pattern (IMPORTANT)
BEFORE responding to user, search for relevant memories based on context:
User asks about skills/capabilities? → Search 'user programming language', 'user technical skills'
User mentions location/environment? → Search 'user city', 'user location', 'user timezone'
User asks about preferences? → Search 'user preference', 'user coding preference'
User references past decisions? → Search 'user decision', 'user project choice'
User asks about project context? → Search 'user project framework', 'user project database'
Triggers
When starting new tasks (check 'has user worked on this before?')
Before giving advice on topics from past sessions
When user references something you don't recall
After any significant decision or preference is stated
Proactive Early Search
At session start, consider searching 'user preferences', 'project architecture', 'agreed approach' to build context.
Use lower limits (1-3) for specific lookups, higher limits (5-10) for broad context.
Inputs: query (required), user_id, agent_id, limit.
update_memoryA
Update an existing memory when information changes or needs correction.
When to Use
Same fact changes ('User now prefers light mode instead of dark')
More precise info becomes available ('Project uses PostgreSQL 16, not 15')
User corrects previous information
Correcting errors in stored facts
Post-Response Correction Pattern
After responding, if user provides CORRECTIONS or UPDATED information:
Search for existing memory on the topic
If found → UPDATE the existing memory
If not found → ADD new memory (don't force update on genuinely new topics)
Storage Decision
ADD NEW for genuinely new topics
UPDATE existing when same fact changes
If unsure, prefer ADD - storing multiple perspectives is safer than losing context
The text field replaces content entirely; metadata (runId) preserves linkage.
Inputs: id (required), text, metadata.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: add, delete individual, bulk delete, get by ID, search, and update. There is no overlap or confusion between them.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., add_memory, delete_all_memories, delete_memory, get_memory, search_memories, update_memory. The pattern is predictable and clear.
With 6 tools, the server is well-scoped for memory management. Each tool earns its place, covering essential operations without unnecessary bloat or sparseness.
The tool surface covers all fundamental memory operations: create, read, update, delete (individual and bulk), and search. There are no obvious gaps for typical memory management tasks.
Maintenance
Related MCP Connectors
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides persistent semantic memory for Claude Code via local embeddings and six MCP tools, enabling context storage and retrieval across sessions without cloud dependencies.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to maintain cross-session memory using self-hosted Qdrant vector storage, optional Neo4j knowledge graphs, and Ollama embeddings, with Anthropic or Ollama as the main LLM. It exposes MCP tools for adding, searching, updating, deleting, and graphing memories, plus hooks for automatic context injection and session summarization.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to store, search, update, and delete persistent memories across sessions, backed by self-hosted Qdrant vector storage, an optional Neo4j knowledge graph, and Ollama embeddings, with Anthropic or Ollama as the main LLM. Exposes 11 MCP tools plus session hooks and a CLAUDE.md guide so context is injected at startup and saved automatically at session end.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to maintain persistent cross-session memory backed by self-hosted Qdrant, Neo4j, and Ollama, including semantic search, memory CRUD, and knowledge-graph entity exploration. It supports both Anthropic/Claude and fully local Ollama LLM configurations through MCP tools and session hooks.-