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.

🌱 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:

Start of session: Ask your AI, "What do we know about the authentication system?" to pull context.
During work: When you fix a tricky issue, say, "We fixed the Redis timeout. Store this solution."
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

Profile	Tools	Best For
Core	13 tools	All users - Essential operations
Extended	17 tools	Power users - Statistics, contextual search, decay control
Advanced	25 tools	Administrators - Graph analysis

🗃️ 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:

Platform	Configuration Guide	Notes
Zed Editor	IDE Integration	Native MCP support
Cursor	IDE Integration	AI-powered editor
Windsurf	IDE Integration	Modern code editor
VSCode	IDE Integration	Via MCP extension
Claude Desktop	IDE Integration	Desktop application
Gemini CLI	Agent Integration	Google's CLI agent
Claude CLI	Agent Integration	Anthropic's CLI agent
Python / MCP Client	Python Integration	Embed server or call via MCP client
Docker / CLI	API & Programmatic	MCP client, Docker, export/import

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):

Command-Line Arguments (highest priority)

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

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

YAML Configuration Files
- Project config: ./memento.yaml in current directory (overrides global)
- Global config: ~/.mcp-memento/config.yaml

Priority Order: CLI Arguments > Environment Variables > Project YAML > Global YAML > Defaults

Default Values (lowest priority)

Supported YAML Keys

The following keys are read and applied by the configuration loader. Any other keys present in the YAML file are silently ignored.

Key	Type	Default	Description
`db_path`	string	`~/.mcp-memento/context.db`	SQLite database file path
`profile`	string	`core`	Tool profile (`core`, `extended`, `advanced`)
`logging.level`	string	`INFO`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`features.allow_relationship_cycles`	bool	`false`	Allow cyclic relationships in the graph

Note: The memento.yaml template shipped with the project contains additional commented sections (confidence, search, performance, memory, fts, project). These are not yet implemented — they are aspirational placeholders for future releases and have no effect on the current server behaviour.

Example Configuration Files

Project configuration (./memento.yaml):

db_path: ~/.mcp-memento/context.db
profile: extended
logging:
  level: INFO
features:
  allow_relationship_cycles: false

Global configuration (~/.mcp-memento/config.yaml):

db_path: ~/.mcp-memento/global.db
profile: extended
logging:
  level: INFO

📚 Documentation Structure

Essential Guides

Tools Reference - Complete guide to all MCP tools
Confidence System - How confidence tracking works
Relationship Types - All 35 relationship types with examples
Usage Rules - Best practices and conventions
Agent Configuration - Templates for AI agents

Integration Guides

Integration Overview - Choosing the right integration
IDE Integration - Zed, Cursor, Windsurf, VSCode, Claude Desktop
Python Integration - MCP client usage, server embedding, CLI export/import
Agent Integration - CLI agents and custom applications
API & Programmatic Integration - MCP client (Python), Docker deployment, CLI export/import

Development & Advanced Topics

Database Schema - Technical database structure
Contributing Guidelines - Development setup and workflow

🏗️ Architecture Overview

Database Schema

Memento uses a unified SQLite schema accessible from all integrations:

Core tables: nodes (memory storage), relationships (directed graph)
Full-text search: nodes_fts — FTS5 virtual table for fast searching (falls back to LIKE-based search if FTS5 is unavailable)
Confidence tracking: Automatic decay with protection for critical memories

Consistent Behavior

The system works identically across all platforms:

Same database: All tools access the same SQLite file
Same confidence tracking: Updates from one tool reflected everywhere
Same search ranking: Results ordered by confidence × importance
Same relationship types: 35 semantic relationship types available everywhere

📜 Background

Memento is a simplified, lightweight fork of MemoryGraph by Gregory Dickson, optimized for MCP integration across IDEs and CLI agents.

The fork focuses on portability and token efficiency: it removes heavy dependencies (NetworkX, multi-backend storage, bi-temporal tracking, multi-tenant architecture) in favor of a SQLite-only backend with confidence-based decay and guideline-driven storage.

Team Collaboration & Remote Deployment

Multiple users can share a SQLite database (e.g., on network storage) using tagging conventions (team:[name], author:[name]). Memento can also run as a remote MCP server, though all clients share the same database without tenant isolation. See Team Collaboration guidelines for details.

For true multi-tenancy, use the original MemoryGraph project.

When to Choose MemoryGraph vs Memento?

Use Memento: For lightweight, cross-platform memory management in IDEs and CLI tools
Use MemoryGraph: For enterprise use cases requiring multi-tenancy, bi-temporal tracking, or custom backends

🙏 Acknowledgments

Memento is built upon the solid foundation of Gregory Dickson's MemoryGraph project. We're grateful for his pioneering work in memory management systems.

This fork maintains compatibility with MemoryGraph's core concepts while adapting them for the specific needs of MCP integration and modern development tooling. For users requiring the full power of MemoryGraph's advanced features, we recommend exploring the original project.

🧪 Beta Status

mcp-webgate is in beta. Core functionality is stable and the server is used in production, but the configuration API may still change before 1.0.

Feedback is very welcome. If something doesn't work as expected, behaves oddly, or you have a use case that isn't covered:

→ Open an issue on GitHub

Bug reports, configuration questions, and feature requests all help shape the roadmap.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

Development setup and workflow
Code style and conventions
Testing requirements
Documentation standards
Pull request process

📄 License

MIT License - see LICENSE for details.

🔗 Links

GitHub Repository - Source code and issues
MCP Protocol - Model Context Protocol specification
PyPI Package - Python Package Index
MCP Registry - Model Context Protocol Registry

Need help? Check the documentation or open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 320 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
integrations/zed		integrations/zed
scripts		scripts
src/memento		src/memento
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Desktop.ini		Desktop.ini
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
docker-compose.yml		docker-compose.yml
memento.yaml		memento.yaml
pyproject.toml		pyproject.toml
server.json		server.json

Folders and files

Latest commit

History

Repository files navigation

MCP Memento

Table of Contents

🌱 A Gentle Introduction

✨ Key Features

🧠 Intelligent Confidence System

🔗 Relationship Mapping

📊 Three Profile System

🗃️ Cross-Platform Storage

🚀 Quick Start

1. Installation

2. Basic Configuration

3. First Steps

📖 Core Concepts

🔗 Integrations

🛠️ Basic Usage Examples

Store and Retrieve Knowledge

Manage Confidence

Create Relationships

Natural Language Interaction (Chat-Based)

⚙️ Configuration

Supported YAML Keys

Example Configuration Files

📚 Documentation Structure

Essential Guides

Integration Guides

Development & Advanced Topics

🏗️ Architecture Overview

Database Schema

Consistent Behavior

📜 Background

Team Collaboration & Remote Deployment

When to Choose MemoryGraph vs Memento?

🙏 Acknowledgments

🧪 Beta Status

🤝 Contributing

📄 License

🔗 Links

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages