Overview

Overview

Mem0 provides an extensible memory infrastructure and agent runtime integration suite designed to equip AI agents and applications with persistent context across dual deployment tiers: open-source (OSS) local backends and the hosted Mem0 Platform. At its core, the architecture coordinates cross-runtime command-line interfaces in both Python and Node.js Python CLI Architecture, Node.js CLI Architecture, alongside a unified family of agent harness plugins such as Claude Code Plugin that synchronize conversation history, background session flows, and diagnostic telemetry.

Platform Architecture and Core Concepts

Core Components and Client Entrypoints

Mem0 defines its foundational memory layers and client entrypoints across dedicated package modules. The core package exposes synchronous and asynchronous interfaces for both local engine management via Memory and AsyncMemory, alongside hosted cloud interactions through MemoryClient and AsyncMemoryClient.

Sources: mem0/init.py:5-6

Deployment Tiers and Versioning

The architecture operates across dual deployment tiers: open-source self-hosted backends and remote platform synchronization. Package versioning is dynamically retrieved via metadata for the underlying distribution (mem0ai), while command-line operations are governed by the dedicated CLI distribution version.

Copy"""mem0 CLI — the command-line interface for the mem0 memory layer."""
 
__version__ = "0.2.13"

Sources: cli/python/src/mem0_cli/init.py:1-3, mem0/init.py:1-3

Unified CLI Specification and Dual-Runtime Interfaces

CLI Schema and Branding Specifications

Mem0 unifies its command-line interfaces through a cross-runtime JSON specification file (cli/cli-spec.json) that establishes metadata, brand assets, configuration directories, and remote API endpoints for both Python and Node client entrypoints. The specification defines global branding identifiers, color palettes, and operational icons used to render terminal output consistently across runtime boundaries.

Sources: cli/cli-spec.json:1-34

Configuration Schema and Environment Bindings

Client configuration is structured around local directory storage combined with environment variable overrides. The configuration subsystem maps platform settings and default identifiers to specific environment variables, allowing seamless authentication and scoping for autonomous agents and developer workstations.

Sources: cli/cli-spec.json:35-86

REST Endpoint Mappings

The CLI specification maps remote control actions to standardized REST API endpoints, defining HTTP methods, path patterns, authentication headers, and entity type mappings for remote synchronization Python Client SDK.

Sources: cli/cli-spec.json:87-98

Agent Harness Architecture and Plugins Family

Shared Core and Harness Configuration

The Mem0 agent plugin family relies on a shared core implementation (memory_core.py) that handles session event recording, background flushing, redacting sensitive secrets, and local storage operations across diverse IDE harnesses and coding assistants. Plugins configure their runtime environment using configure_harness(), which sets up harness-specific naming prefixes, data directories, and source tags for telemetry tracking.

Sources: integrations/mem0-agent-plugin/core/memory_core.py:34-38, integrations/antigravity-plugin/core/memory_core.py:34-38, integrations/kimi-plugin/core/memory_core.py:34-38, integrations/cursor-plugin/core/memory_core.py:34-38, integrations/codex-plugin/core/memory_core.py:34-38

Diagnostic CLI and Control Operations

Each IDE plugin embeds a command-line interface (memory_cli.py) that exposes diagnostic checks, user controls, and lifecycle actions for managing local and remote memories. The CLI uses Python's argparse module to dispatch subcommands such as status inspection, health diagnostics, pausing, resuming, and repository purging.

Sources: integrations/mem0-agent-plugin/core/memory_cli.py:61-80, integrations/antigravity-plugin/core/memory_cli.py:61-80, integrations/kimi-plugin/core/memory_cli.py:61-80, integrations/cursor-plugin/core/memory_cli.py:61-80, integrations/codex-plugin/core/memory_cli.py:61-80

MCP Server Integration and Manifests

Model Context Protocol (MCP) manifests (mcp.json) bind the memory core into host IDE environments using standard input/output transport streams. The manifest defines server registration parameters that execute the Python MCP server script within the plugin root directory.

Copy{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "mem0": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "${PLUGIN_ROOT}/core/mcp_server.py"
      ]
    }
  }
}

Sources: integrations/mem0-agent-plugin/mcp.json:1-12

External Agent and Workflow Ecosystem

OpenClaw and Pi Agent Integrations

Mem0 extends beyond core LLM memory engines by providing specialized integrations for agent frameworks, runtime environments, and workflow automation tools. These packages bridge external architectures into the Mem0 memory fabric without requiring custom storage layers.

The OpenClaw Integration plugin (openclaw-mem0) exposes six core memory tools (memory_search, memory_add, memory_get, memory_list, memory_update, and memory_delete) while handling automatic recall and capture across agent turns. It isolates multi-agent setups by routing per-agent namespaces through session key resolution and supports both platform and self-hosted backends. Similarly, the Pi Agent Plugin package structures memory management through exported configuration loaders, scoping handlers, formatting utilities, and command extensions.

Copy/**
 * OpenClaw Memory (Mem0) Plugin
 *
 * Long-term memory via Mem0 — supports both the Mem0 platform
 * and the open-source self-hosted SDK. Uses the official `mem0ai` package.
 *
 * Features:
 * - 6 core tools: memory_search, memory_add, memory_get, memory_list,
 *   memory_update, memory_delete
 * - Short-term (session-scoped) and long-term (user-scoped) memory
 * - Auto-recall: injects relevant memories (both scopes) before each agent turn
 * - Auto-capture: stores key facts scoped to the current session after each agent turn
 * - Per-agent isolation: multi-agent setups write/read from separate userId namespaces
 *   automatically via sessionKey routing (zero breaking changes for single-agent setups)
 * - CLI: openclaw mem0 search, openclaw mem0 status
 * - Dual mode: platform or open-source (self-hosted)
 */

Sources: integrations/openclaw/index.ts:1-17

Copyexport type {
  Scope,
  Mem0Config,
  ScopeContext,
  CustomCategory,
} from "./types.ts";
export { DEFAULT_CUSTOM_CATEGORIES } from "./types.ts";
 
export { loadConfig, CONFIG_DIR } from "./config/index.ts";
 
export { registerMemoryTool, buildToolExecute } from "./memory/tools.ts";
export { detectAppId, detectRunId, resolveSearchFilters, resolveAddParams } from "./memory/scoping.ts";
export { formatAge, formatMemoryCompact, formatMemoryList, groupByCategory } from "./memory/formatting.ts";
 
export { setupAutoCapture, extractConversation } from "./capture/index.ts";
 
export { MEMORY_POLICY } from "./prompt.ts";
 
export { registerCommands } from "./commands.ts";
 
export { captureEvent, captureToolEvent, captureCommandEvent, _getEventQueue, _resetForTesting } from "./telemetry.ts";
 

Sources: integrations/pi-agent-plugin/src/index.ts:1-22

Strands Agent Framework Integration

The Mem0 Strands package (mem0-strands) provides persistent long-term memory for Strands agents via Mem0MemoryStore. It plugs into agent execution loops through a MemoryManager to deliver automatic memory injection and extraction.

Copy"""Strands Mem0 -- persistent long-term memory for Strands agents, backed by Mem0.
 
:class:`Mem0MemoryStore` is a Strands ``MemoryStore`` that plugs into the agent
loop via a :class:`~strands.memory.MemoryManager`, with automatic memory injection
and extraction. It implements both write sinks, so ``extraction`` uses Mem0's
server-side extraction (no extra model call).
 
For the explicit, model-called tool (``store`` / ``retrieve`` / ``get`` / ``delete``),
use the ``mem0_memory`` tool from ``strands-agents-tools``; a store and the tool can
share one Mem0 backend and namespace.
"""

Sources: integrations/mem0-strands/python/src/mem0_strands/init.py:1-11

Cross-Subsystem Data and Telemetry Flow

Background Telemetry and Execution Coordination

End-to-end data coordination across host harnesses, background sync workers, and anonymized diagnostic telemetry relies on decoupled logging and asynchronous flushing. In agent CLI implementations, commands execute within an instantiated EvidenceStore context that records control actions, telemetry payloads, and local sqlite state updates before finalizing execution through deferred background worker threads.

Copyif args.plugin_data_dir:
    os.environ["MEM0_CODE_DATA_DIR"] = args.plugin_data_dir
store = EvidenceStore()
try:
    repo = resolve_repo(os.getcwd())
    telemetry.record("control", repo=repo, action=args.command)

Sources: integrations/mem0-agent-plugin/core/memory_cli.py:86-91

Copyfinally:
    store.close()
    telemetry.spawn_flush()
return 0

Sources: integrations/mem0-agent-plugin/core/memory_cli.py:147-150

Harness Configuration and Data Routing

Runtime contexts receive environment parameters, configuration prefixes, and source identifiers through modular configuration routines. The harness configuration initializes specific global variables governing environment lookup paths, local plugin data directories, and source telemetry tagging.

Copydef configure_harness(
    name: str,
    env_prefix: str = "",
    data_dir_name: str = "",
    source_tag: str = "",
) -> None:
    global _harness_name, _harness_env_prefix, _harness_data_dir_name, _harness_source_tag
    _harness_name = name
    _harness_env_prefix = env_prefix or f"MEM0_{name.upper().replace('-', '_')}"
    _harness_data_dir_name = data_dir_name or f"{name}-plugin"
    _harness_source_tag = source_tag or f"{name.replace('-', '_')}_plugin"
 

Sources: integrations/mem0-agent-plugin/core/memory_core.py:40-51

Sources: integrations/mem0-agent-plugin/core/memory_core.py:34-51

Where to go next

Related

• Quick Start
• Project Structure
• Memory Lifecycle