MCP Memento

Intelligent memory management for MCP clients with confidence tracking, relationship mapping, and knowledge quality maintenance.

Memento is an MCP server that provides persistent memory capabilities across multiple platforms:

• IDEs: Zed, Cursor, Windsurf, VSCode, Claude Desktop
• CLI Agents: Gemini CLI, Claude CLI, custom agents
• Programmatic Usage: MCP client (Python), Docker deployment, CLI export/import
• Applications: Any MCP-compatible application

Build a personal or team knowledge base that grows smarter over time, accessible from all your development tools.

Table of Contents

• 🌱 A Gentle Introduction
• ✨ Key Features
• 🚀 Quick Start
• ⚙️ Configuration
• 📖 Core Concepts
• 🔗 Integrations
• 🛠️ Basic Usage Examples
• 📚 Documentation Structure
• 🏗️ Architecture Overview
• 📜 Background
• 🙏 Acknowledgments
• 🤝 Contributing
• 📄 License
• 🔗 Links

🌱 A Gentle Introduction

What is Memento? Imagine you're solving a complex bug, figuring out a tricky configuration, or establishing a new coding pattern. Usually, you'd forget the details in a few weeks. Memento is a "long-term memory drive" for your AI assistant. It allows your AI to save these solutions, decisions, and facts so it can recall them instantly across different projects, even months later.

💡 The Agentic Mindset: A Guide for Traditional Developers If you are used to deterministic software (where things happen automatically because a script says so), interacting with AI agents requires a slight mental shift.

Memento is not an autonomous agent that watches your screen and magically decides what to remember. Instead, Memento is a toolbelt provided to your AI assistant (like Claude, Cursor, or Gemini).

• The AI is the worker: It needs to be told when to use the toolbelt. Nothing is saved without explicit instruction or a pre-defined rule.
• You are the manager: You control what gets stored. You can either tell the AI during a chat ("Save this database connection string"), or you can give the AI standard operating procedures (via system prompts or .cursorrules/CLAUDE.md files) so it knows to automatically save certain things, like bug fixes or architecture decisions.

How to build the habit:

1. Start of session: Ask your AI, "What do we know about the authentication system?" to pull context.
2. During work: When you fix a tricky issue, say, "We fixed the Redis timeout. Store this solution."
3. End of session: Tell your AI, "Store a summary of what we accomplished today."

Alternatively, you can add custom instructions to your AI (see our Agent Configuration Guide) to make it automatically execute these steps without you having to ask every time.

✨ Key Features

🧠 Intelligent Confidence System

• Automatic decay: Unused knowledge loses confidence over time (5% monthly)
• Critical protection: Security/auth/API key memories never decay
• Boost on validation: Confidence increases when knowledge is successfully used
• Smart ordering: Search results ranked by confidence × importance

🔗 Relationship Mapping

• 35 relationship types: SOLVES, CAUSES, IMPROVES, USED_IN, etc. across 7 semantic categories (see Relationship Types Reference)
• Graph navigation: Find connections between concepts
• Pattern detection: Identify recurring solution patterns

📊 Three Profile System

🗃️ Cross-Platform Storage

• SQLite backend: Zero dependencies, local storage
• Full-text search: Fast, fuzzy matching across all memories
• Automatic maintenance: Confidence decay, relationship integrity
• Shared database: Same database works across all integrations

🚀 Quick Start

1. Installation

# Install with pipx (recommended for MCP servers)
pipx install mcp-memento

# Or with pip
pip install mcp-memento

2. Basic Configuration

Memento supports multiple configuration methods. For clarity, we recommend using one method consistently:

Method 1: CLI Arguments (recommended - most explicit)

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": ["--profile", "extended", "--db", "~/.mcp-memento/context.db"]
    }
  }
}

Method 2: Environment Variables

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": [],
      "env": {
        "MEMENTO_PROFILE": "extended",
        "MEMENTO_DB_PATH": "~/.mcp-memento/context.db"
      }
    }
  }
}

Method 3: YAML Configuration File Create ~/.mcp-memento/config.yaml:

profile: extended
db_path: ~/.mcp-memento/context.db

Then use minimal JSON config:

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": []
    }
  }
}

CLI Agents (Gemini CLI):

gemini --mcp-servers memento

Note: The exact flag syntax depends on your Gemini CLI version. Refer to AGENT_CONFIGURATION.md for version-specific setup instructions.

3. First Steps

Once configured, your AI assistant can now:

# Store solutions and knowledge
store_memento(
    type="solution",
    title="Fixed Redis timeout with connection pooling",
    content="Increased connection timeout to 30s and added connection pooling...",
    tags=["redis", "timeout", "production_fix"],
    importance=0.8
)

# Find knowledge later
recall_mementos(query="Redis timeout solutions")

📌 Note: The code above represents MCP tool calls — instructions you give your AI assistant (Claude, Cursor, Gemini, etc.) to invoke Memento's tools. This is not a Python library you can import. For programmatic Python access see the Python Integration Guide.

💬 Natural Language: You can also interact with Memento through natural conversation. Just tell your AI assistant things like "Remember that..." or "Store this..." or "Memento..."- no code required.

📖 Core Concepts

For a deep dive into Memento's concepts (Confidence System, Tagging, Relationships), please read the comprehensive RULES.md and RELATIONSHIPS.md documentation.

🔗 Integrations

Memento works with all major development tools:

See also: Integration Overview for guidance on choosing the right integration.

🛠️ Basic Usage Examples

The examples below show the MCP tool calls that an AI assistant (Zed, Cursor, Claude, Gemini CLI, …) executes on your behalf when you ask it to remember or retrieve something. They are written in a Python-like pseudocode that mirrors the MCP tool interface — they are not a Python library you import directly.

To call these tools programmatically from Python, use the mcp client library. See Python Integration for a working example.

Store and Retrieve Knowledge

# Store a solution — the AI calls this tool when you say "remember this fix"
solution_id = store_memento(
    type="solution",
    title="Fixed memory leak in WebSocket handler",
    content="Added proper cleanup in on_close()...",
    tags=["websocket", "memory", "python"],
    importance=0.9
)

# Natural language search — called when you ask "what do you know about X"
results = recall_mementos(query="WebSocket memory leak", limit=5)

# Tag-based search — for precise filtering
redis_solutions = search_mementos(tags=["redis"], memory_types=["solution"])

Manage Confidence

# Find potentially obsolete knowledge
low_confidence = get_low_confidence_mementos(threshold=0.3)