Project Structure

Overview

The repository is structured as a multi-language monorepo that organizes core memory engines, cross-platform SDKs, dual command-line interfaces, server tooling, and integrated agent plugins into discrete, cohesive subdirectories. At the root level, build automation via Makefiles and Python Hatchling configurations (pyproject.toml) coordinate packaging, formatting, linting, and multi-version test environments for python artifacts.

Sources: Makefile:1-52, pyproject.toml:1-174

TypeScript modules are separated into standalone packages such as the main client library (mem0-ts), open-source memory store implementations (mem0-ts/src/oss), and community extensions (mem0-ts/src/community), while dashboard services reside within dedicated web application directories (server/dashboard). Parallel Python and Node.js command-line tool packages (cli/python, cli/node) implement the standard command interface defined by shared command-line specifications (cli/cli-spec.json). Furthermore, specialized agent plugins (integrations/openclaw, integrations/pi-agent-plugin, integrations/vercel-ai-sdk, integrations/mem0-strands) tie into shared agent cores (integrations/agent-plugin-core) to provide background capture, auto-recall, and lifecycle hooks across diverse AI frameworks.

Sources: mem0-ts/package.json:1-150, server/dashboard/package.json:1-84, cli/cli-spec.json:1-562, integrations/openclaw/index.ts:1-58

Monorepo Build and Packaging Layout

Root Build Configuration and Packaging

The repository root uses Hatchling as its build backend to package the core Python library under project name mem0ai version 2.2.1. The root pyproject.toml defines required core runtime dependencies including vector store clients, Pydantic, OpenAI, httpx, posthog, pytz, SQLAlchemy, and protobuf, alongside extensive optional feature groups.

Sources: pyproject.toml:1-87

Sources: pyproject.toml:92-106

Tooling Automation and Makefiles

The root Makefile exposes automation commands for formatting, sorting imports, building, publishing, and running multi-version test matrices via Hatch environments.

.PHONY: format sort lint

# Variables
ISORT_OPTIONS = --profile black
PROJECT_NAME := mem0ai

# Default target
all: format sort lint

install:
	hatch env create

install_all:
	pip install ruff==0.16.0 groq together boto3 'litellm>=1.83.7,<1.98.0' ollama chromadb weaviate weaviate-client sentence_transformers vertexai \
	            google-generativeai elasticsearch opensearch-py vecs "pinecone<7.0.0" pinecone-text faiss-cpu langchain-community \
							upstash-vector azure-search-documents langchain-memgraph langchain-neo4j langchain-aws rank-bm25 pymochow pymongo psycopg kuzu databricks-sdk valkey

# Format code with ruff
format:
	hatch run format

# Sort imports with isort
sort:
	hatch run isort mem0/

# Lint code with ruff
lint:
	hatch run lint

docs:
	cd docs && mintlify dev

build:
	hatch build

publish:
	hatch publish

clean:
	rm -rf dist

test:
	hatch run test

test-py-3.10:
	hatch run dev_py_3_10:test

test-py-3.11:
	hatch run dev_py_3_11:test

test-py-3.12:
	hatch run dev_py_3_12:test

Sources: Makefile:1-52

Sources: Makefile:13-17

Subpackage Layouts and Tool Configurations

Subpackages within the monorepo maintain independent pyproject.toml manifests with dedicated linting and testing parameters. The Strands integration package (integrations/mem0-strands/python/pyproject.toml) configures mem0-strands with required dependencies on strands-agents>=1.45.0 and mem0ai>=2.0.11, while defining MyPy type-checking rules.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "mem0-strands"
version = "0.1.1"
description = "Persistent long-term memory for Strands agents, backed by Mem0."
readme = "README.md"
requires-python = ">=3.10"
license = "Apache-2.0"
authors = [
    {name = "Mem0", email = "founders@mem0.ai"}
]
keywords = ["strands", "strands-agents", "agents", "ai", "memory", "mem0", "vector-search", "personalization"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]

# strands-agents>=1.45.0: first release shipping the `strands.memory` module
# (MemoryStore / MemoryManager) that Mem0MemoryStore implements.
dependencies = [
    "strands-agents>=1.45.0",
    "mem0ai>=2.0.11",
]

[project.urls]
Homepage = "https://mem0.ai"
Documentation = "https://github.com/mem0ai/mem0/tree/main/integrations/mem0-strands#readme"
Repository = "https://github.com/mem0ai/mem0"
Issues = "https://github.com/mem0ai/mem0/issues"

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0,<9.0.0",
    "pytest-asyncio>=0.25.0,<1.0.0",
    "ruff>=0.11.0,<1.0.0",
    "mypy>=1.15.0,<2.0.0",
    "hatch",
]

Sources: integrations/mem0-strands/python/pyproject.toml:1-48

Similarly, the Python CLI package (cli/python/pyproject.toml) declares mem0-cli using Typer and Rich for console interaction, defining mem0 = "mem0_cli.app:main" as its primary executable script entry point.

dependencies = [
    "typer>=0.9.0",
    "rich>=13.0.0",
    "httpx>=0.24.0",
]

[project.optional-dependencies]
oss = ["mem0ai>=0.1.0"]
dev = [
    "pytest>=7.0",
    "pytest-asyncio>=0.21",
    "ruff>=0.1.0",
]

[project.scripts]
mem0 = "mem0_cli.app:main"

Sources: cli/python/pyproject.toml:27-43

Python Core Engine Architecture

Entry Modules and Version Resolution

The core Python library is initialized via the package entry module mem0/__init__.py. This module dynamically resolves the package version string using importlib.metadata.version("mem0ai") to query the installed distribution metadata.

Copyimport importlib.metadata
 
__version__ = importlib.metadata.version("mem0ai")
 
from mem0.client.main import AsyncMemoryClient, MemoryClient  # noqa
from mem0.memory.main import AsyncMemory, Memory  # noqa

Sources: mem0/init.py:1-6

Sources: mem0/init.py:1-3

Core Component Exports

The package init module exposes primary memory engine interfaces and remote client classes for both synchronous and asynchronous execution workflows. These symbols are imported directly from their respective internal implementation modules with # noqa directives silencing unused import linters.

Sources: mem0/init.py:5-6

Sources: mem0/client/init.py:1-1, mem0/configs/init.py:1-1

TypeScript SDK and OSS Packages

Package Manifest and Root Export Structure

The TypeScript monorepo workspace under mem0-ts splits its architecture into two primary packages: the core mem0ai package and the community-contributed @mem0/community package. The root mem0-ts/package.json configures bundling automation using tsup, emitting CommonJS (.js) and ESM (.mjs) builds alongside bundled declaration maps while defining conditional export paths for . and ./oss.

Sources: mem0-ts/package.json:1-70

The core OSS entry point mem0-ts/src/oss/src/index.ts re-exports the entire memory subsystem, covering core memory definitions, vector stores, embedding providers, LLM backends, and rerankers.

Sources: mem0-ts/src/oss/src/index.ts:1-60

Sources: mem0-ts/package.json:64-69

Community Package and Framework Integrations

The @mem0/community package (mem0-ts/src/community/package.json) manages peripheral ecosystem integrations such as LangChain. It specifies dual export targets for the root package and the LangChain integration module, pinning required peer and runtime dependencies on @langchain/core, @langchain/community, and mem0ai.

Sources: mem0-ts/src/community/package.json:1-38

The community entry module mem0-ts/src/community/src/index.ts exposes framework bindings, delegating to submodule declarations like the LangChain integration entry point.

Copyexport * from "./integrations/langchain";

Sources: mem0-ts/src/community/src/index.ts:1-1

Sources: mem0-ts/src/community/package.json:85-90

Dual CLI Implementations and Specifications

Package Structure and Node.js Dependencies

The Node.js CLI package residing at cli/node/package.json defines the official command-line interface under the package name @mem0/cli at version 0.2.14. It targets Node.js version 18.0.0 or higher and configures its executable binary mapping under the bin field to point ./dist/index.js to the mem0 command.

Sources: cli/node/package.json:1-20

Sources: cli/node/package.json:32-38

Sources: cli/node/package.json:9-17, cli/node/package.json:39-47

Python CLI Layout and Specifications

The Python CLI package structures its commands and backend abstractions within cli/python/src/mem0_cli/, exposing version metadata and backend factory bindings through initializers.

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

Sources: cli/python/src/mem0_cli/init.py:1-2

The backend package initialization module cli/python/src/mem0_cli/backend/__init__.py imports and re-exports the Backend abstract base class and get_backend factory function from the backend subsystem.

Copy"""Backend abstraction layer for mem0 CLI."""
 
from mem0_cli.backend.base import Backend, get_backend
 
__all__ = ["Backend", "get_backend"]

Sources: cli/python/src/mem0_cli/backend/init.py:1-5

Command modules are organized as a submodule package namespace under cli/python/src/mem0_cli/commands/__init__.py.

Copy"""CLI command modules."""

Sources: cli/python/src/mem0_cli/commands/init.py:1-1

Unified behavior across both CLI implementations is governed by the master specification file cli/cli-spec.json, which defines configuration defaults, API endpoint mappings, error messages, and command options.

Sources: cli/cli-spec.json:35-40, cli/cli-spec.json:98-102

Sources: cli/cli-spec.json:109-126

Server Dashboard Application Layout

Web Dashboard Workspace and Metadata

The server web dashboard resides inside server/dashboard/ and is managed as a private Next.js application using pnpm version 10.34.2. Its project configuration specifies execution scripts for development, production builds, local serving, linting, formatting, and typechecking.

Sources: server/dashboard/package.json:6-13

Sources: server/dashboard/package.json:4-4, server/dashboard/package.json:48-50

UI Primitives and State Management Dependencies

The dashboard application integrates component primitives from Radix UI alongside Redux Toolkit for state management, Tailwind CSS for styling utility, and React Hook Form with Zod validation.

Sources: server/dashboard/package.json:14-38, server/dashboard/package.json:44-66, server/dashboard/package.json:80-82

Sources: server/dashboard/package.json:67-69, server/dashboard/package.json:77-79, server/dashboard/package.json:81-83

Agent Integration Plugins and Frameworks

Ecosystem Organization and Package Structure

The repository houses several ecosystem integrations and shared agent harnesses under the integrations/ directory, spanning both Python and TypeScript runtimes. These plugins embed Mem0 functionality directly into popular coding agents, framework runtimes, and LLM orchestration layers such as OpenClaw, Pi Agent, Strands, and the Vercel AI SDK. Shared packages such as @mem0/agent-plugin-core provide common utility implementations across TypeScript agent harnesses.

Sources: integrations/pi-agent-plugin/package.json:1-6, integrations/agent-plugin-core/typescript/package.json:1-6, integrations/mem0-strands/python/pyproject.toml:5-15, integrations/mem0-agent-plugin/core/memory_core.py:2-88, integrations/openclaw/index.ts:1-17, integrations/vercel-ai-sdk/src/index.ts:1-5

Sources: integrations/mem0-agent-plugin/core/memory_core.py:74-88, integrations/mem0-agent-plugin/core/memory_core.py:128-161

Plugin Runtime Exports and Capabilities

Individual ecosystem integrations expose entry points, tool registrations, scoping handlers, and configuration schemas to hook into their respective agent runtimes. Pi Agent and OpenClaw packages bundle extension modules, skill loaders, and telemetry collectors, while the Vercel AI SDK wrapper exposes helper functions like addMemories, retrieveMemories, searchMemories, and getMemories.

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

Sources: integrations/pi-agent-plugin/package.json:70-83

Related

• Overview
• Quick Start