# API Reference r3 v1.3.2 exposes 14 tools through the Model Context Protocol (MCP) over stdio. [MCP tool schemas (JSON)](/mcp-tools.json) · [Published source](https://github.com/n3wth/r3/blob/v1.3.2/src/index.ts) ## Schema and transport 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: ```json { "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. ## Tools overview | Tool | Purpose | | ----------------------------------------------- | --------------------------------------------------------------------------------------- | | [`add_memory`](#add_memory) | Store a new memory with automatic deduplication and indexing. | | [`get_memory`](#get_memory) | Retrieve a single memory by its unique ID. | | [`update_memory`](#update_memory) | Modify an existing memory's content or metadata. | | [`search_memory`](#search_memory) | Find memories matching a natural language query using hybrid semantic + keyword search. | | [`get_all_memories`](#get_all_memories) | List all memories for a user with pagination. | | [`delete_memory`](#delete_memory) | Permanently remove a memory by ID. | | [`deduplicate_memories`](#deduplicate_memories) | Detect and optionally remove duplicate memories using content similarity. | | [`optimize_cache`](#optimize_cache) | Reorganize cache for optimal hit rates. | | [`cache_stats`](#cache_stats) | View cache performance metrics and health status. | | [`sync_status`](#sync_status) | Check background job queue and sync status. | | [`extract_entities`](#extract_entities) | Extract named entities and relationships from text using NLP. | | [`get_knowledge_graph`](#get_knowledge_graph) | Build a knowledge graph from stored memories. | | [`find_connections`](#find_connections) | Discover relationship paths between entities in the knowledge graph. | | [`import_memories`](#import_memories) | Bulk import memories from external sources. | ## add\_memory 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. | Argument | Type | Required | Description | | ---------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | array | No | Conversation messages to store. Use instead of content for multi-turn context. Each message needs role and content fields. | | `content` | string | No | Plain text content to store. Use instead of messages for simple facts. Either content or messages required, not both. | | `user_id` | string | No | User namespace for memory isolation. Default: "oliver". Use consistent IDs to retrieve related memories. | | `metadata` | object | No | Key-value pairs for categorization (e.g., {category: 'preferences', source: 'onboarding'}). Searchable via search\_memory. | | `priority` | string | No | Cache priority. high: immediate L1 cache (24h TTL). medium: standard processing. low: L2 cache (7d TTL). Default: medium. Values: `high`, `medium`, `low`. | | `async` | boolean | No | Enable background processing. true: returns immediately, indexes async. false: blocks until complete. Default: true. | | `skip_duplicate_check` | boolean | No | Bypass duplicate detection. Use only when intentionally storing similar content. Default: false. | ## get\_memory 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. | Argument | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `memory_id` | string | Yes | Unique identifier of the memory to retrieve. Obtained from add\_memory response, search\_memory results, or get\_all\_memories. | | `user_id` | string | No | User namespace. Must match the user\_id used when memory was created. Default: "oliver". | ## update\_memory 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. | Argument | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- | | `memory_id` | string | Yes | Unique identifier of the memory to update. Must exist or operation fails with error. | | `content` | string | No | New content to replace existing. Omit to keep current content unchanged. | | `metadata` | object | No | Metadata fields to merge. Existing fields not specified are preserved. Pass null value to remove a field. | | `user_id` | string | No | User namespace. Must match original. Default: "oliver". | ## search\_memory 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. | Argument | Type | Required | Description | | -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | Yes | Natural language search query. Supports keywords, phrases, or questions. More specific queries yield better relevance ranking. | | `user_id` | string | No | User namespace to search within. Default: "oliver". | | `limit` | number | No | Maximum results to return. Range: 1-100. Higher values increase latency. Default: 10. | | `prefer_cache` | boolean | No | true: check cache first, fall back to storage. false: query storage directly, then cache results. Default: true. | ## get\_all\_memories 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\[]}. | Argument | Type | Required | Description | | --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | | `user_id` | string | No | User namespace to list. Default: "oliver". | | `limit` | number | No | Maximum memories per page. Range: 1-500. Default: 100. Use with offset for pagination. | | `offset` | number | No | Number of memories to skip. Use for pagination: page N = offset (N-1)\*limit. Default: 0. | | `include_cache_stats` | boolean | No | Append cache statistics to response. Useful for monitoring. Default: true. | | `prefer_cache` | boolean | No | true: return cached memories (faster). false: fetch from storage (fresher). Default: true. | ## delete\_memory 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. | Argument | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `memory_id` | string | Yes | Unique identifier of memory to delete. Obtain from search\_memory or get\_all\_memories. Operation succeeds even if ID not found. | ## deduplicate\_memories 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. | Argument | Type | Required | Description | | ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | No | User namespace to deduplicate. Default: "oliver". | | `similarity_threshold` | number | No | Minimum similarity (0-1) to consider as duplicate. 0.85 = 85% similar. Higher = stricter. Range: 0.5-1.0. Default: 0.85. | | `dry_run` | boolean | No | true: preview duplicates without deletion (safe). false: actually delete duplicates (destructive). Default: true. | ## optimize\_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. | Argument | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | | `force_refresh` | boolean | No | true: clear cache and reload all from storage. false: optimize existing cache. Default: false. | | `max_memories` | number | No | Maximum memories to keep in cache. Range: 100-10000. Older/colder items evicted first. Default: 1000. | ## cache\_stats 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. ## sync\_status 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\_entities 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\[]}. | Argument | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `text` | string | Yes | Input text to analyze. Longer text yields more entities. Supports natural language, code comments, or structured text. | ## get\_knowledge\_graph 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}. | Argument | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `entity_type` | string | No | Filter nodes by type: 'people', 'organizations', 'technologies', or 'projects'. Omit for all types. | | `entity_name` | string | No | Filter nodes containing this name (case-insensitive substring match). Omit for all entities. | | `relationship_type` | string | No | Filter edges by relationship: 'WORKS\_FOR', 'USES', 'BUILT\_WITH', 'KNOWS', etc. Omit for all relationships. | | `limit` | number | No | Maximum nodes to return. Range: 1-100. Default: 20. Edges limited proportionally. | ## find\_connections 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. | Argument | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `from_entity` | string | Yes | Starting entity name for path search. Must match an entity in the knowledge graph exactly. | | `to_entity` | string | No | Target entity name. If omitted, returns all reachable entities up to max\_depth. | | `max_depth` | number | No | Maximum relationship hops to traverse. Range: 1-5. Higher values exponentially increase results. Default: 2. | ## import\_memories 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. | Argument | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `source` | string | Yes | Import source. 'mem0\_api': fetch from Mem0 cloud (requires api\_key). 'json\_file': read local file (requires file\_path). Values: `mem0_api`, `json_file`. | | `api_key` | string | No | Mem0 API token for authentication. Required when source='mem0\_api'. Get from dashboard. | | `user_id` | string | No | User namespace for imported memories. Default: "oliver". | | `file_path` | string | No | Absolute path to JSON file. Required when source='json\_file'. Must be array of memory objects or {memories: \[...]}. | | `batch_size` | number | No | Memories per batch. Lower values are safer but slower. Range: 10-200. Default: 50. | | `priority` | string | No | Cache priority for all imported memories. Default: high (L1 cache). Values: `high`, `medium`, `low`. | | `skip_duplicates` | boolean | No | Check each memory for duplicates before import. Slower but prevents bloat. Default: true. | Source: https://r3.n3wth.com/docs/api-reference