MCP Memento

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)

Boost confidence after verification

boost_memento_confidence( memory_id=verified_solution_id, boost_amount=0.15, reason="Verified in production deployment" )

Create Relationships

# Link solution to problem

create_memento_relationship( from_memory_id=solution_id, to_memory_id=problem_id, relationship_type="SOLVES", # See all 35 types in docs/RELATIONSHIPS.md strength=0.9, context="Connection pooling resolved the timeout issue" )

Explore connected knowledge

related = get_related_mementos( memory_id=solution_id, relationship_types=["RELATED_TO", "USED_IN"], max_depth=2 )

Natural Language Interaction (Chat-Based)

Memento works through natural language conversations. The AI assistant interprets intent and calls the appropriate tools automatically.

Store information:

User: Remember that we solved Redis timeout with connection pooling

AI: ✅ Memento stored - "Redis timeout solution: connection pooling"

Retrieve knowledge:

User: What do you remember about Redis timeout?

AI: Found 2 solutions: 1) Connection pooling... 2) Query optimization...

Using the "Memento" keyword:

User: Memento the deployment script is in /scripts/deploy.sh

AI: ✅ Memento stored - "Deployment script location: /scripts/deploy.sh"

The AI can also store important information automatically when configured with the guidelines in AGENT_CONFIGURATION.md.

⚙️ Configuration

Memento supports multiple configuration sources (in order of precedence):

1. Command-Line Arguments (highest priority)

   memento --profile advanced --db ~/custom/path/memento.db --log-level DEBUG

1. Environment Variables

   export MEMENTO_PROFILE="advanced"

export MEMENTO_DB_PATH="~/custom/path/memento.db" export MEMENTO_LOG_LEVEL="DEBUG" export MEMENTO_ALLOW_CYCLES="false" # Allow cycles in relationship graph

1. YAML Configuration Files -