@slorenzot/memento-mcp-server

Model Context Protocol (MCP) server providing 24 memory tools for AI agent integration with Claude Desktop, VS Code, OpenCode, and other MCP clients.

Installation

# Using Bun (recommended)
bun add @slorenzot/memento-mcp-server

# Using npm
npm install @slorenzot/memento-mcp-server

Basic Usage

Shell

# Run MCP server (recommended)
bunx @slorenzot/memento-mcp-server

# Use with custom database path
MEMENTO_DB_PATH=/custom/path/database.db bunx @slorenzot/memento-mcp-server

TypeScript

import { MCPServer } from '@slorenzot/memento-mcp-server';

const server = new MCPServer('./data/memento.db');
// Server uses stdio for MCP communication
// Designed to be executed by MCP clients

Available MCP Tools

The server provides 24 MCP tools organized by category:

Core — Observations

mem_save

Save an observation to persistent memory. Call this PROACTIVELY after making decisions, fixing bugs, or discovering something non-obvious.

Parameters:

{
  title: string;                    // Short, searchable title
  content: string;                  // Structured: What/Why/Where/Learned
  type?: 'decision' | 'bug' | 'discovery' | 'note' | 'summary' |
         'learning' | 'pattern' | 'architecture' | 'config' | 'preference';
  topic_key?: string;               // Stable key for grouping (e.g. "architecture/auth")
  project_id?: string;              // Project identifier
  metadata?: Record<string, unknown>;
  scope?: 'project' | 'personal';   // Scope (default: project)
  pinned?: boolean;                  // Pin for system prompt injection
  read_only?: boolean;               // Mark as read-only
}

mem_search

Search observations using full-text search (FTS5). Results are TRUNCATED — use mem_get_observation for full content.

Parameters:

{
  query?: string;
  type?: /* 10 observation types */;
  project_id?: string;
  topic_key?: string;
  limit?: number;                    // Default: 10
  offset?: number;
  include_deleted?: boolean;
  scope?: 'project' | 'personal';
  sort?: 'relevance' | 'chronological';  // Default: relevance
  mode?: 'keyword' | 'semantic' | 'hybrid';  // Default: keyword
}

mem_get_observation

Get full untruncated content of a specific observation by ID.

Parameters:

{
  id: number;
  include_deleted?: boolean;
}

mem_update

Update an existing observation. Only provided fields will be updated.

Parameters:

{
  id: number;
  title?: string;
  content?: string;
  type?: /* 10 observation types */;
  topic_key?: string;
  pinned?: boolean;
}

mem_replace

Replace a substring within an observation. More token-efficient than mem_update for small changes. Respects read-only protection.

Parameters:

{
  id: number;
  old_text: string;    // Must be unique in content
  new_text: string;
}

Lifecycle

mem_delete

Consolidated observation lifecycle management.

Parameters:

{
  id?: number;                                           // Required for soft/restore
  action?: 'soft' | 'permanent' | 'restore' | 'list';   // Default: soft
  reason?: string;                                        // For soft action
  confirm?: boolean;                                      // Required for permanent
  project_id?: string;                                    // For list/permanent
  observation_ids?: number[];                              // Specific IDs to purge
  limit?: number;                                         // For list action
}

mem_merge

Merge related observations into a single record. ALWAYS dry_run: true first.

Parameters:

{
  project_id: string;
  topic_key?: string;
  observation_ids?: number[];
  strategy?: 'by_topic' | 'by_similarity' | 'by_ids';
  dry_run?: boolean;
}

mem_export

Export observations to JSON, XML, or TXT.

Parameters:

{
  format?: 'json' | 'xml' | 'txt';
  project_id?: string;
  type?: /* 10 observation types */;
  topic_key?: string;
  date_from?: string;
  date_to?: string;
  include_deleted?: boolean;
}

Pin & Lock

mem_pin

Pin an observation for always-injection in system prompt.

Parameters: { id: number }

mem_unpin

Remove observation from system prompt injection.

Parameters: { id: number }

mem_lock

Mark observation as read-only (prevents agent modifications).

Parameters: { id: number }

mem_unlock

Allow modifications on a locked observation.

Parameters: { id: number }

Session Management

mem_session_start

Start a new memory session. Auto-closes stale sessions for the project.

Parameters:

{
  project_id?: string;
  metadata?: Record<string, unknown>;
}

mem_session_end

End the current active session. Call BEFORE closing a conversation.

Parameters: {}

mem_session_summary

Save a structured session summary (Goal/Discoveries/Accomplished/Files). Use this NATIVE tool instead of mem_save with type "summary".

Parameters:

{
  content: string;          // Structured: Goal/Discoveries/Accomplished/Files
  project_id?: string;
  session_id?: number;
}

mem_context

Quick context recovery. Returns recent observations ordered by created_at DESC. Does NOT use FTS5.

Parameters:

{
  project_id?: string;
  limit?: number;           // Default: 20
  scope?: 'project' | 'personal';
}

Capture

mem_capture_passive

Parse text to extract learnings from "## Key Learnings:" or "## Aprendizajes Clave:" sections. Deduplicates by Jaccard similarity.

Parameters:

{
  content: string;
  project_id?: string;
  session_id?: number;
  source?: string;
}

Diagnostics

mem_status

Compound diagnostic tool. Replaces mem_stats, mem_health, mem_config, mem_list_sessions, mem_get_session.

Parameters:

{
  section?: 'all' | 'health' | 'stats' | 'config' | 'sessions';
  session_id?: number;       // Get specific session details
  project_id?: string;       // Filter sessions by project
  limit?: number;            // Max sessions (default: 20)
}

Journal — Audit Trail

mem_journal_write

Create an immutable journal entry. Entries cannot be edited or deleted. Use supersedes to correct a previous entry.

Parameters:

{
  title: string;
  body: string;
  tags?: string[];
  project_id?: string;
  supersedes?: number;
  metadata?: Record<string, unknown>;
}

mem_journal_read

Read a journal entry by ID.

Parameters: { id: number }

mem_journal_search

Search journal entries with FTS5, tags, and date filters.

Parameters:

{
  query?: string;
  tags?: string[];
  project_id?: string;
  active_only?: boolean;     // Exclude superseded entries
  date_from?: string;
  date_to?: string;
  limit?: number;
  offset?: number;
}

Sync — Cloud

mem_sync_status

Check sync authentication status and last sync metadata.

Parameters: {}

mem_sync_project

Bidirectional sync with memento-hub. First-time: returns verification URL and user code.

Parameters:

{
  project_id: string;
  device_code?: string;      // Resume auth after user authorizes
}

mem_logout

Clear stored sync token. Agent will need to re-authenticate.

Parameters: {}

MCP Client Integration

Claude Desktop

{
  "mcpServers": {
    "memento": {
      "command": "bunx",
      "args": ["@slorenzot/memento-mcp-server"],
      "env": {
        "MEMENTO_DB_PATH": "${userHome}/.memento/data/memento.db"
      }
    }
  }
}

VS Code (with MCP extension)

{
  "mcp.servers": {
    "memento": {
      "command": "bunx",
      "args": ["@slorenzot/memento-mcp-server"]
    }
  }
}

OpenCode

{
  "mcpServers": {
    "memento": {
      "command": "bunx",
      "args": ["@slorenzot/memento-mcp-server"]
    }
  }
}

Complete Session Workflow

// 1. Start session
await mem_session_start({ project_id: 'my-app' })

// 2. Save observations during work
await mem_save({
  title: 'Use PostgreSQL for auth',
  content: 'What: Switch to PostgreSQL\nWhy: Better JSON support\nWhere: src/db/config.ts',
  type: 'decision',
  topic_key: 'architecture/database',
  project_id: 'my-app'
})

// 3. Quick context recovery
await mem_context({ project_id: 'my-app', limit: 10 })

// 4. Search with semantic mode
await mem_search({
  query: 'database configuration',
  mode: 'semantic',
  project_id: 'my-app'
})

// 5. Save session summary (NATIVE tool)
await mem_session_summary({
  content: '## Goal\nSetup database\n## Discoveries\nPostgreSQL has better JSON support\n## Accomplished\nConfigured PostgreSQL connection',
  project_id: 'my-app'
})

// 6. End session
await mem_session_end()

Dependencies

Main Dependencies

• @slorenzot/memento-core — Memory engine
• @modelcontextprotocol/sdk — Model Context Protocol SDK
• zod — Schema validation

Runtime

• bun v1.0+ (recommended)
• node v20+ (compatible)

Development

# Clone the project
git clone https://github.com/slorenzot/memento.git
cd memento/packages/mcp-server

# Install dependencies
bun install

# Build
bun run build

# Tests
bun test

Changelog

[2.0.9] — 2026-05

• Added: Sync tools (mem_sync_status, mem_sync_project, mem_logout)
• Added: Journal tools (mem_journal_write, mem_journal_read, mem_journal_search)
• Added: Pin/Lock tools (mem_pin, mem_unpin, mem_lock, mem_unlock)
• Added: mem_replace for surgical substring edits
• Added: mem_merge for observation deduplication
• Added: mem_session_summary native tool
• Added: mem_context for quick context recovery
• Added: mem_capture_passive for learning extraction
• Added: Semantic and hybrid search modes
• Added: 6 new observation types (summary, learning, pattern, architecture, config, preference)
• Changed: mem_delete consolidated (soft/restore/permanent/list)
• Changed: mem_status compound tool (all/health/stats/config/sessions)

[1.0.0] — 2025

• Changed: Tool consolidation (26 → 16 active tools)
• Changed: mem_delete with action parameter
• Changed: mem_search with sort parameter
• Changed: mem_status compound diagnostic tool
• Changed: mem_save auto-suggests topic_key

[0.1.1] — 2024-04-04

• Fixed: Core dependency updates
• Fixed: deleteObservation method correction

[0.1.0] — 2024-04-04

• Added: Initial MCP server version
• Added: 15 memory management tools
• Added: Full Model Context Protocol integration

Author

Soulberto Lorenzo

• GitHub: @slorenzot
• Email: [email protected]

License

This package is licensed under Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International.

View Full License

Spanish version (Version en espanol)