Skip to main content
Glama

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 userId

  • Session Tracking - Associate memories with specific agent sessions via runId

  • Content 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 rememberme

Installation

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

Or 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/.env

Edit ~/.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_default

Step 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/qdrant

Step 5: Verify Installation

Check that everything is connected:

rememberme status

Expected output:

## RememberMe Status

- **Qdrant**: `Connected`
  - Host: `localhost:6333`
  - Collection: `memories`
- **Memories**: `0` stored

Step 6: Try Your First Command

# Add a memory
rememberme add "User prefers dark mode theme"

# Search memories
rememberme search "preferences"

# Get help
rememberme --help

Troubleshooting

Issue

Solution

QdrantOfflineError

Ensure Qdrant is running (docker run -p 6333:6333 qdrant/qdrant)

ValidationError

Check EMBEDDING_API_KEY and OPENAI_BASE_URL in ~/.config/rememberme/.env

Command not found

Re-run pip install -e . to create the rememberme command

Collection error

RememberMe auto-creates the collection on first run

Config not found

Ensure ~/.config/rememberme/.env exists (or will be auto-created)

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" --json

CLI Options

Option

Description

--user-id

User ID scope (defaults to DEFAULT_USER_ID env var)

--debug

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 memory

  • search_memories - Semantic search

  • get_memory - Get a single memory

  • update_memory - Update a memory

  • delete_memory - Delete a memory

  • delete_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 true

Important: 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/.env

Then 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_HOST

Qdrant server address

localhost

QDRANT_PORT

Qdrant port

6333

QDRANT_COLLECTION_NAME

Collection name

memories

QDRANT_API_KEY

Qdrant API key

-

EMBEDDING_API_KEY

Embedding API key

Required

EMBEDDING_MODEL

Embedding model (OpenAI compatible)

doubao-embedding-vision

EMBEDDING_DIMENSIONS

Vector dimensions

2048

OPENAI_BASE_URL

Embedding API endpoint

Required

DEFAULT_USER_ID

Default user ID

user_default

LOG_LEVEL

Log level

INFO

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.py

Run Tests

pytest tests/

License

MIT

Available Tools

6 tools
add_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:

  1. Did user share personal context? → Store it

  2. Did we make a technical decision? → Store it

  3. Did user express a preference? → Store it

  4. 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:

  1. Informing user how many memories will be deleted

  2. Confirming they want to proceed

  3. 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:

  1. User asks about skills/capabilities? → Search 'user programming language', 'user technical skills'

  2. User mentions location/environment? → Search 'user city', 'user location', 'user timezone'

  3. User asks about preferences? → Search 'user preference', 'user coding preference'

  4. User references past decisions? → Search 'user decision', 'user project choice'

  5. 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

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:

  1. Search for existing memory on the topic

  2. If found → UPDATE the existing memory

  3. 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

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    With 6 tools, the server is well-scoped for memory management. Each tool earns its place, covering essential operations without unnecessary bloat or sparseness.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent semantic memory for Claude Code via local embeddings and six MCP tools, enabling context storage and retrieval across sessions without cloud dependencies.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -