Memento

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.

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:

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

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.