Memento

The Autonomous Nervous System for AI Agents

---

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:

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

Running without OpenAI (offline / testing)

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.