API Reference

r3 v1.3.2 exposes 14 tools through the Model Context Protocol (MCP) over stdio.

MCP tool schemas (JSON) · Published source

The machine-readable schema contains every tool name, description, annotation, and input schema from the published release. Connect an MCP client and call tools/list to read the definitions from your running server.

This release does not expose an HTTP REST API, so it has no OpenAPI document. The JSON schemas above describe MCP tool arguments. They are not an OpenAI API endpoint.

Use tools/call with a tool name and arguments. Your MCP client handles the JSON-RPC transport:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_memory",
    "arguments": {
      "query": "programming preferences",
      "limit": 5
    }
  }
}

user_id selects a memory namespace. Its default comes from the server’s MEM0_USER_ID environment variable. The downloadable schema records the release default.

Store a new memory with automatic deduplication and indexing. Use for persisting facts, preferences, or conversation context. Checks for duplicates by default (85% similarity threshold). Returns immediately; background processing handles indexing. Prefer over update_memory for new content. Returns: confirmation text. Side effects: creates memory record, updates search index, may skip if duplicate detected.

Retrieve a single memory by its unique ID. Use when you have a specific memory_id from prior search/list results. Returns null if not found. Prefer search_memory for content-based lookup. Read-only operation. Returns: Memory object {id, content, user_id, metadata} or null.

Modify an existing memory's content or metadata. Use for corrections or adding context to existing memories. Fails if memory_id not found. Prefer add_memory for new content. Invalidates search cache. Returns: updated Memory object. Side effects: modifies memory record, invalidates cached search results.

Find memories matching a natural language query using hybrid semantic + keyword search. Primary retrieval tool for content-based lookup. Uses vector similarity (enhanced mode) or keyword matching (basic mode). Cache-first by default for speed. Returns ranked results with relevance scores. Read-only. Returns: array of Memory objects or 'No memories found' text.

List all memories for a user with pagination. Use for browsing or bulk operations. For content search, use search_memory instead. Cache-first by default. Large result sets are automatically truncated. Read-only. Returns: {total, limit, offset, returned, hasMore, source, memories[]}.

Permanently remove a memory by ID. Irreversible operation. Removes from storage, cache, and search index. Use deduplicate_memories with dry_run first to preview bulk deletions. Returns: confirmation text. Side effects: deletes memory record, removes from all indexes, invalidates cache.

Detect and optionally remove duplicate memories using content similarity. Run with dry_run=true first to preview. Compares all memories pairwise using Jaccard similarity. Groups duplicates with a primary (oldest) and candidates for removal. Returns: summary with duplicate groups. Side effects (when dry_run=false): deletes duplicate memories, invalidates cache.

Reorganize cache for optimal hit rates. Promotes frequently accessed memories to L1 (24h TTL), demotes cold data to L2 (7d TTL). Use periodically for large memory stores. May temporarily increase latency during optimization. Returns: summary of cached memories. Side effects: modifies cache TTLs, may evict old entries.

View cache performance metrics and health status. Use for monitoring and debugging. Shows memory count, access patterns, and hit rates. Read-only. Returns: summary text with cached memory count. No side effects.

No arguments required.

Check background job queue and sync status. Shows pending async operations from add_memory calls. Use to verify all writes completed. Read-only. Returns: count of pending operations or 'All operations complete'. No side effects.

No arguments required.

Extract named entities and relationships from text using NLP. Identifies people, organizations, technologies, and projects. Also extracts relationships (WORKS_FOR, USES, etc.) and keywords. Requires enhanced intelligence mode. Read-only, stateless. Returns: {people[], organizations[], technologies[], projects[], relationships[], keywords[]}.

Build a knowledge graph from stored memories. Returns entities as nodes and relationships as edges. Use for visualizing connections between concepts. Requires enhanced intelligence mode with prior entity extraction. Read-only. Returns: {nodes[], edges[]} where nodes have {id, type, name, memories[]} and edges have {from, to, type, confidence}.

Discover relationship paths between entities in the knowledge graph. Uses BFS traversal to find how entities connect. Useful for answering 'how is X related to Y?' questions. Requires enhanced mode. Read-only. Returns: {from, to, max_depth, paths_found, paths[]} where each path is array of {from, to, type} edges.

Bulk import memories from external sources. Supports Mem0 API export or local JSON files. Processes in batches with duplicate detection. Use for migration or backup restoration. Returns: summary with imported/skipped/failed counts. Side effects: creates multiple memory records, updates search index.