Skip to main content
Glama

PyPI version License: AGPL v3 Python 3.10+ MCP Protocol


Memento is a local-first, open-source MCP middleware that gives your AI agents (Cursor, Claude Desktop, Trae, etc.) persistent memory, proactive goal enforcement, and autonomous intelligence — all running on a zero-cost SQLite temporal graph with Reciprocal Rank Fusion (RRF) retrieval.

No cloud databases. No API calls for storage. Everything stays on your machine.


Architecture

Temporal Graph Memory (RRF)

Built on SQLite FTS5 (full-text search) and cosine similarity (vector embeddings). Fuses keyword matches and semantic meaning via Reciprocal Rank Fusion. WAL-mode enabled for concurrency.

Tri-State Goal Enforcer

Keep your AI aligned with project objectives at three escalation levels:

  • Level 1 — Context Injection: Automatically injects active goals into every search result. Active by default.

  • Level 2 — Strict Mentor: Forces the AI to submit code/plans for goal alignment evaluation via LLM.

  • Level 3 — Daemon Push: File-watcher monitors your workspace and proactively flags goal drift.

Active Coercion (Code Immune System)

Deterministic regex/tree-sitter rules that block anti-patterns at commit time and in the IDE. 100% deterministic — zero LLM hallucination risk during enforcement.

Autonomous Agent

Background cognitive loop with four levels:

  • off: No background behavior (default).

  • passive: Observe health and patterns every 5 min. No modifications.

  • active: Consolidate memories, extract KG, warm caches, detect anomalies every 2 min.

  • autonomous: All of the above plus dream synthesis, goal drift detection, task generation, health reports every 1 min.

Workspace Isolation

Each project gets its own .memento/ directory with an isolated SQLite database. No context bleeding between projects. Configure via MEMENTO_DIR or per-project .cursor/mcp.json.

Session Continuity

  • Auto-checkpoints every 25 tool calls with full L1 working memory snapshot.

  • Auto-resume restores goals and context from the previous session.

  • LLM-agnostic handoff prompts for session transfer between agents.

Project Memory Graph

Semantic entity-relationship graph on top of the Knowledge Graph. Track files, components, decisions, and their dependencies. Impact analysis shows what breaks when you change something.


Related MCP server: Memento

Unified Tool API (v0.3.x)

Memento exposes 14 action-based tools via MCP. Each tool uses an action parameter instead of separate tools per operation:

Tool

Actions

Purpose

memento

(main router)

Primary proactive memory interface

memento_project

set_state, get_state, delete_state, set_goals, list_goals, summary

Vision, milestones, blockers, goals

memento_session

begin, resume, handoff, status, list

Session lifecycle and handoff

memento_graph

add_entity, add_relation, query, impact, summary

Project Memory Graph

memento_search

basic, advanced, explain

FTS, vNext pipeline, routing trace

memento_remember

add, consolidate, share, evaluate, hit

Memory write operations

memento_configure

enforcement, coercion, daemon, autonomy, consolidation_scheduler, kg_scheduler, dependency_tracker, superpowers, access

All configuration

memento_cognitive

dream, align, warnings, tasks

Cognitive engine operations

memento_health

status, health, memory, kg, quality, relevance, cache, explain

Diagnostics

memento_coercion

list_presets, apply_preset, list_rules, add_rule, remove_rule, install_hooks

Active Coercion management

memento_kg

extract, health, cross_workspace_stats

Knowledge Graph operations

memento_notifications

configure, list, dismiss

Proactive notifications

memento_audit_dependencies

(standalone)

Dependency audit

memento_migrate_workspace_memories

(standalone)

Workspace memory migration


Quick Start

Install

pip install memento-mcp

Or run without installing:

uvx memento-mcp

Configure (Cursor / Claude Desktop / Trae)

Add to your global mcp.json (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "memento": {
      "command": "memento-mcp",
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "MEM0_MODEL": "openai/gpt-4o-mini"
      }
    }
  }
}

For per-project workspace isolation, add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "memento": {
      "command": "memento-mcp",
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "MEM0_MODEL": "openai/gpt-4o-mini",
        "MEMENTO_DIR": "${workspaceFolder}"
      }
    }
  }
}

Add .cursor/ to your .gitignore to avoid committing API keys.

Verify

memento-mcp --help
memento --help

Set MEMENTO_EMBEDDING_BACKEND=none to disable embeddings. Memento falls back to FTS5-only search — no API key needed.

MEMENTO_EMBEDDING_BACKEND=none memento-mcp

Environment Variables

Variable

Default

Description

OPENAI_API_KEY

Required for OpenAI embeddings and cognitive features

OPENAI_BASE_URL

https://api.openai.com/v1

OpenAI-compatible endpoint (e.g. OpenRouter)

MEM0_MODEL

openai/gpt-4o-mini

LLM model for cognitive features

MEM0_EMBEDDING_MODEL

text-embedding-3-small

Embeddings model

MEMENTO_EMBEDDING_BACKEND

auto-detect

local (fastembed), openai, or none

MEMENTO_DIR

cwd

Workspace root for .memento/ state

MEMENTO_UI

0

Enable local web UI (1/true)

MEMENTO_UI_PORT

8089

Local UI port

MEMENTO_UI_AUTH_TOKEN

Auth token for local web UI

MEMENTO_RULE_CONFIRMATION

true

Require confirmation before applying coercion rules

MEMENTO_PROACTIVE_INJECT

1

Inject relevant memories on every tool call (0 to disable)

MEMENTO_PROACTIVE_TOP_K

3

Number of memories to inject proactively

MEMENTO_DECAY_SEMANTIC

0.005

Decay λ for semantic memories (~200d half-life)

MEMENTO_DECAY_EPISODIC

0.02

Decay λ for episodic memories (~50d half-life)

MEMENTO_DECAY_WORKING

0.05

Decay λ for working memories (~14d half-life)

MEMENTO_WRITE_SEARCH_TRACE

0

Write last_search.json trace on every search (1 to enable)

MEMENTO_HANDOFF_AUTO_CHECKPOINT_EVERY_N_EVENTS

25

Auto-checkpoint frequency

MEMENTO_SHARED_KG_PATH

Path to a shared KG SQLite file (federation — multiple workspaces share one graph)

MEMENTO_FEDERATION_SOCKET

Unix socket path for push notifications between agents (replaces 30s WAL polling)


CLI Usage

Memento works from the terminal too:

# Auto-capture git context as a memory
memento capture --auto

# Save a free-form note
memento capture --text "Resolved auth timeout by increasing JWT expiry"

# Search memories
memento search "how did I fix the promise bug"

# Show workspace status
memento status

How Proactivity Works

Memento operates at two levels:

Always-on (zero configuration)

  • Goal awareness: Every tool call is checked against active goals. If work drifts, a warning is appended.

  • Auto-resume: L1 working memory (goals, context) restores from the previous session's checkpoint.

  • Auto-checkpoint: Every 25 events, a full session snapshot is saved with project state and handoff prompt.

  • Session diff: Each checkpoint computes the delta from the previous session (goals changed, files touched).

Activatable (via memento_configure)

  • L2 enforcement: Goal alignment checks via LLM on explicit request.

  • L3 daemon: File-watcher with proactive goal drift notifications.

  • Autonomous agent: Background consolidation, KG extraction, dream synthesis, task generation.

  • Active coercion: Deterministic code pattern enforcement.

  • Consolidation/KG schedulers: Background deduplication and knowledge extraction.

Example activation sequence:

memento_project(action="set_goals", goals=["Implement auth flow", "Refactor DB layer"])
memento_configure(action="enforcement", level="level2", enabled=true)
memento_configure(action="consolidation_scheduler", enabled=true, interval_minutes=30)
memento_configure(action="autonomy", level="active")

License

Memento is released under the GNU Affero General Public License v3.0 (AGPL-3.0). If you modify Memento and offer it as a network service, you must release your modified source code under the same license.

See LICENSE for details.

Available Tools

6 tools
memento_audit_dependenciesC

Audit the workspace dependencies to find orphans (declared but unused) and ghosts (used but not declared).

ParametersJSON Schema
NameRequiredDescriptionDefault
workspace_rootNoMANDATORY: The absolute path of the current project/workspace root.

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not state whether the tool is read-only, modifies dependencies, or requires network access. The word 'audit' implies inspection, but this is implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-front-loaded sentence that defines the tool's purpose and key terminology. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and no annotations, so the description should compensate with more context (e.g., return format, side effects, permissions). It falls short given the complexity of dependency auditing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. However, the description calls workspace_root 'MANDATORY' while the schema lists it as optional (no 'required' array), creating confusion. This inconsistency reduces clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool audits workspace dependencies and defines the two categories (orphans and ghosts). It distinguishes itself from siblings by focusing on dependency auditing, but does not explicitly differentiate from similar tools like memento_project or memento_graph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., memento_health, memento_search). No mention of prerequisites or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memento_coercionD

Active Coercion management. Actions: list_presets, apply_preset, list_rules, add_rule, remove_rule, install_hooks.

ParametersJSON Schema
NameRequiredDescriptionDefault
ruleNo
actionYes
presetNo
rule_idNo
workspace_rootNo

TDQS

D1.5/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses no behavioral traits such as side effects (e.g., destructive nature of remove_rule), authorization requirements, or state modifications beyond action names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short but fails to provide necessary details. It is under-specification rather than conciseness, lacking any meaningful structure or prioritization.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, nested objects, no output schema), the description is completely inadequate. It provides no information about return values, input constraints, or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not add any meaning to parameters like preset, rule_id, rule, workspace_root. The agent is left with no clue about their purpose or format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'Active Coercion management' which is vague and unclear in context. It lists actions but does not specify what coercion means or how it differs from sibling tools like memento_configure or memento_cognitive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description only lists action names without any context on preferred use cases or when to avoid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memento_cognitiveC

Cognitive engine. Actions: dream (creative insight), align (goal check), warnings (spider-sense), tasks (auto-generate).

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes
contentNoCode/plan to evaluate (for align).
contextNoTopic/context (for dream, warnings).
active_contextNo
workspace_rootNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral transparency. It states actions and their intents (e.g., 'align (goal check)') but fails to explain side effects, state changes, or limitations. For example, 'warnings (spider-sense)' is ambiguous—does it check something? Does it modify state? The description lacks details on error conditions, idempotency, or required setup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise—two lines, front-loaded with the core concept ('Cognitive engine') followed by a colon and a bullet-like list of actions. Each action gets a one-word hint. There is no extraneous text. While it could be slightly more structured (e.g., separate lines), it efficiently conveys the gist.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, 5 parameters with low schema coverage, and four distinct actions, the description is incomplete. It does not explain return values, error handling, or use cases. For example, 'tasks (auto-generate)' is vague—what tasks? Based on what? The lack of any output description or further context makes the tool under-specified for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 40% (2 of 5 parameters have descriptions). The description adds meaning to the 'action' enum by associating each value with a one-word explanation (e.g., 'dream (creative insight)'), supplementing the schema's pure enum list. However, the parameters 'active_context' and 'workspace_root' are completely undocumented in both schema and description. The description does not compensate for the missing schema descriptions elsewhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it's a 'cognitive engine' and lists four actions with brief explanations (dream, align, warnings, tasks). Each action has a one-word hint (e.g., 'creative insight'). This clearly communicates the tool's purpose and distinguishes it from sibling tools that have different names like memento_search or memento_remember. However, it doesn't explain how these actions relate to each other or what the tool outputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus its siblings (e.g., memento_search, memento_remember). There is no indication of prerequisites, context, or examples. The description only lists available actions without explaining the decision criteria for choosing one action over another or when this tool is preferred over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memento_configureD

Configure Memento. Actions: enforcement, coercion, daemon, autonomy, consolidation_scheduler, kg_scheduler, dependency_tracker, superpowers, access.

ParametersJSON Schema
NameRequiredDescriptionDefault
levelNo
stateNo
tasksNo
actionYes
enabledNo
warningsNo
workspace_rootNo
interval_minutesNo
install_git_hooksNo

TDQS

D1.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description provides no behavioral details such as side effects, permissions required, or destructive potential. For a configuration tool, this is a critical omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief but at the cost of clarity. It front-loads the verb 'Configure' but the rest is a bare list of actions. This is under-specification, not conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, many enums, no output schema, no annotations), the description is severely incomplete. It fails to explain what the tool does for each action or how parameters interact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage and 9 parameters, the description only lists action enum values without explaining their meaning or the purpose of other parameters like 'level', 'state', or 'warnings'. It adds virtually no value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Configure Memento' and lists actions, giving a general sense of purpose. However, it lacks specifics on what each action configures, making it vague and not fully clear for distinguishing among sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like memento_coercion or memento_cognitive. The absence of usage context or when-not-to-use conditions hurts decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memento_migrate_workspace_memoriesC

Copy-only migration: redistribute memories from a source DB into per-workspace DBs using deterministic text heuristics. Produces a JSON report.

ParametersJSON Schema
NameRequiredDescriptionDefault
report_pathNo
source_db_pathYes
workspace_rootNoMANDATORY: The absolute path of the current project/workspace root.
workspace_rootsYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It states 'copy-only migration' indicating non-destructive behavior, but fails to explain side effects, idempotency, error handling, or safety considerations like whether the source DB is modified or if the tool can be re-run safely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a single sentence and a result note. It front-loads the key action and output, avoiding unnecessary verbosity. However, it could benefit from structured sections for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a migration tool with no output schema and limited schema descriptions, the description omits important context such as the format of the JSON report, expected behavior under failure, required permissions, and the exact nature of the 'deterministic text heuristics'. This leaves significant gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 25% of schema parameters have descriptions (workspace_root has a description but contradictory 'MANDATORY' vs not required in schema). The tool description does not compensate for the missing parameter explanations for source_db_path, workspace_roots, and report_path, leaving agents uncertain about input requirements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a 'copy-only migration' tool that redistributes memories from a source DB into per-workspace DBs using deterministic text heuristics, which distinguishes it from other memento tools that handle queries or configurations. However, it could explicitly contrast with sibling tools like memento_remember or memento_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies usage when migration is needed, but lacks conditions, prerequisites, or when not to use it. No mention of alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.2.1
    • Removedmemento
    • Removedmemento_graph
    • Removedmemento_health
    • Removedmemento_kg
    • Removedmemento_notifications
    • Removedmemento_project
    • Removedmemento_remember
    • Removedmemento_session
  2. 14 tool updatesv0.3.1
    • First observedmemento
    • First observedmemento_audit_dependencies
    • First observedmemento_coercion
    • First observedmemento_cognitive
    • First observedmemento_configure
    • First observedmemento_graph
    • First observedmemento_health
    • First observedmemento_kg
    • First observedmemento_migrate_workspace_memories
    • First observedmemento_notifications
    • First observedmemento_project
    • First observedmemento_remember
    • First observedmemento_search
    • First observedmemento_session

TDQS

C2.6/5.0

Scored across 6 tools

Disambiguation4/5

Most tools expose distinct functional areas—search, migration, dependency audit, configuration, cognitive actions, and coercion—so an agent can typically tell them apart. However, memento_configure includes 'coercion' and 'dependency_tracker' actions that overlap with memento_coercion and memento_audit_dependencies.

Naming Consistency3/5

All tools share the consistent memento_ prefix and snake_case style, but the suffixes mix verb phrases like audit_dependencies and migrate_workspace_memories with noun/module names like cognitive and coercion. This is readable but lacks a uniform verb_noun pattern.

Tool Count5/5

Six tools is a well-scoped count for a server with this breadth of operational areas. Each tool represents a distinct functional domain, and the number is comfortably within the ideal range.

Completeness3/5

The server covers search, migration, audit, configuration, cognitive actions, and coercion management, but it lacks direct memory lifecycle operations such as create, update, or delete memories. For a memory-focused server, this is a notable gap even though the maintenance and control surface is fairly complete.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Memento is a local-first MCP server that gives AI coding agents durable project memory — facts, decisions, patterns, and architecture notes — so they stop re-learning the same context every session. Runs locally on Node.js 18+ with SQLite storage and optional cloud embeddings; works with Claude Code, Cursor, Windsurf, and any MCP client.
    19
    6 npm
    2
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Memento is a local-first, LLM-agnostic memory layer. It runs an MCP server over a single SQLite file on your machine, so any MCP-capable AI assistant — Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, a custom agent — can read and write durable, structured memory about you, your work, and your decisions.
    75 npm
    23
    Apache 2.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    Local-first persistent memory for AI agents via MCP, enabling semantic search and memory sharing across agents with zero cloud cost and full privacy.
    7 npm
    1
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    MCP server providing persistent AI memory with four-tier retrieval (SQLite FTS5, graph, vector, LLM agent) to give AI assistants structured, long-term memory without RAG.
    1
    Apache 2.0