Related Pages

Related topics: SDK Quickstart & Memory Operations, Self-Hosting, Server Stack & OpenMemory

Overview & V3 Memory Algorithm

1. Project Overview

Mem0 (Memory + Zero) is a self-improving memory layer for AI agents and assistants, distributed as a multi-language monorepo that includes a Python SDK, a TypeScript SDK, framework integrations, an evaluation harness, and several first-party plugins. The project is licensed under Apache 2.0 (with the evaluation subtree under MIT) and is described in the research paper *Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory* (arXiv:2504.19413) Source: [README.md:1-30, evaluation/README.md:1-30].

The repository is organized around the concept of a "memory" object — a discrete, retrievable fact distilled from conversational context — and a uniform API surface (add, search, get_all, update, delete, history) exposed by both client SDKs Source: [mem0-ts/README.md:1-50, mem0-ts/src/client/mem0.ts:1-60]. Two deployment modes are supported: the Mem0 Platform (managed SaaS reached via API key) and the Mem0 OSS stack (self-hosted, library-only, with pluggable vector stores, LLMs, and embedders) Source: [mem0-ts/src/oss/README.md:1-50, skills/mem0/README.md:1-40].

2. The V3 Memory Algorithm

The "V3" algorithm — announced as the *New Memory Algorithm (April 2026)* in the top-level README — is a single-pass, ADD-only extraction pipeline. Rather than performing UPDATE or DELETE operations against previously stored memories, V3 simply accumulates new facts and lets retrieval time-signal scoring decide which ones are most relevant to a query Source: [README.md:25-45].

Key design properties of V3:

• Single-pass ADD-only extraction — exactly one LLM call per add() invocation. No agentic loops, no second-pass conflict resolution. Memories accumulate monotonically; nothing is overwritten Source: [README.md:30-40].
• Agent-generated facts are first-class — when an agent confirms an action, the resulting fact is stored with equal weight to user-generated facts, which is important for multi-agent workflows Source: [README.md:32-36].
• Entity linking — entities (people, places, products, etc.) are extracted, embedded, and linked across memories to support retrieval boosting Source: [README.md:36-40, mem0-ts/src/oss/src/utils/entity_extraction.ts:1-80].
• Multi-signal retrieval — semantic (vector) similarity, BM25 keyword matching, and entity matching are scored in parallel and combined additively Source: [README.md:38-45, mem0-ts/src/oss/src/utils/scoring.ts:1-60].

The V3 algorithm is reported to reach 91.6 on LoCoMo, 94.8 on LongMemEval, 64.1 on BEAM (1M), and 48.6 on BEAM (10M), with median latency under ~1.1 s and ~7K tokens of context per query Source: [README.md:22-32].

Extraction Prompt Contract

The extraction prompt in the TypeScript SDK codifies the V3 contract. It instructs the LLM to extract concrete, specific facts (e.g., "*The tribunal found Reward Homes breached its contract*" — not "*User asked for the introductory paragraph to be shortened*"), to avoid *detail contamination* from unrelated existing memories, and to populate a linked_memory_ids field whenever a new fact relates to a previously stored one Source: [mem0-ts/src/oss/src/prompts/index.ts:1-30].

Hybrid Retrieval Scoring

The scoring module normalizes BM25 with a query-length-adaptive sigmoid, then combines it with the dense vector score and an entity-match boost. The default entity boost weight is 0.5, and BM25 parameters (midpoint, steepness) are tuned per query length bucket (≤3, 4–6, 7–9, 10–15, 16+ terms) Source: [mem0-ts/src/oss/src/utils/scoring.ts:1-60]. Entity extraction rejects vague nouns (e.g., *thing*, *way*, *kind*) and vague adjectives (e.g., *new*, *old*, *great*) before they are indexed, keeping entity matching high-precision Source: [mem0-ts/src/oss/src/utils/entity_extraction.ts:1-80].

flowchart LR
    A[New Messages] --> B[LLM Extract<br/>single-pass]
    B --> C[Facts +<br/>linked_memory_ids]
    C --> D[Embedder<br/>dense vectors]
    C --> E[Entity<br/>Extractor]
    E --> F[Entity Index]
    D --> G[(Vector Store)]
    F --> G
    C --> H[(History Store)]
    Q[Query] --> I[Semantic Search]
    Q --> J[BM25 Search]
    Q --> K[Entity Match]
    I --> L[Additive<br/>Scoring]
    J --> L
    K --> L
    L --> M[Top-K Memories]

3. Repository Topology

The monorepo is composed of several first-party packages, each with a distinct audience:

The Platform client (mem0-ts/src/client/mem0.ts) is a thin axios-based wrapper that validates that entity parameters such as user_id, agent_id, app_id, and run_id are passed only inside the filters object, never at the top level, by inspecting both snake_case and camelCase keys Source: [mem0-ts/src/client/mem0.ts:30-60].

4. Known Limitations and Community-Reported Issues

Several issues reported by the community are direct consequences of the V3 design choices and are worth understanding before adoption:

• Silent memory loss on partial batch failures — When the embedder fails on individual items inside a batch during add(), the failure is logged at WARNING but no exception is raised to the caller, so extracted facts can be silently dropped (#5245) [Source: community issue #5245].
• Time-blindness, semantic conflicts, and missing CRUD — Because V3 is ADD-only and relies on memory linking plus client-side retrieval prioritization, prior issues (#4896, #4904) were closed as "not planned." Self-hosted users must implement their own conflict resolution and time-decay logic (#5352) [Source: community issue #5352].
• Pluggable storage for cloud-native backends — The current OSS storage layer is not fully decoupled; a proposal (#5354) requests that every storage layer (vector, history, graph) be replaceable with mature external systems [Source: community issue #5354].
• Qdrant HTTPS mis-detection — The Qdrant vector store can incorrectly connect over HTTPS when configured with host + port + api_key against a self-hosted HTTP Qdrant instance (#5378) [Source: community issue #5378].
• Platform v3 API entity-scoped add — add() accepts user_id/agent_id but does not always store them, leading get_all() to return empty for those filters (#5224) [Source: community issue #5224].
• OpenAIEmbedder base64 default — In mem0-ts, the SDK defaults to encoding_format="base64", which breaks against OpenAI-compatible proxies that only support float (#5168, mirrors fixed Python bug #4057) [Source: community issue #5168].
• Supply-chain risk — A malicious npm package named mem0-mcp-server has been impersonating the official @mem0/mcp-server; users must install only the scoped, official package (#5274) [Source: community issue #5274].
• Self-hosting build prerequisites — make bootstrap in the self-hosting stack requires make and a Node version that ships node:sqlite; older Node runtimes fail (#5291, #2690) [Source: community issues #5291, #2690].

See Also

• Mem0 Documentation
• Mem0 Research Paper (arXiv:2504.19413)
• Vercel AI SDK Provider (v2.4.6) release notes
• Mem0 Node SDK (v3.0.6) release notes
• Evaluation harness (LOCOMO, LongMemEval, BEAM)

Related Pages

Related topics: Overview & V3 Memory Algorithm, Integrations, Extensibility & Common Failure Modes

SDK Quickstart & Memory Operations

Overview

Mem0 ships a multi-language SDK ecosystem for adding long-term memory to AI agents. The umbrella repository hosts the Python SDK, the TypeScript/Node SDK (mem0-ts), the official CLI, the Vercel AI SDK provider, and the self-hostable OpenMemory UI. All SDKs expose the same conceptual surface: extract facts from messages, embed them, store them in a vector store, and retrieve them later by semantic similarity, BM25, or graph relationships.

The repository is organized so that each subproject is independently publishable:

• mem0-ts/src/client/mem0.ts — the hosted Platform client (REST over axios), exposing add, search, getAll, update, delete, webhooks, projects, feedback, and export endpoints. Source: mem0-ts/src/client/mem0.ts:1-60.
• mem0-ts/src/oss/ — the local OSS memory pipeline (in-memory or pluggable vector store, OpenAI embedder/LLM, optional graph store). Source: mem0-ts/src/oss/README.md:1-50.
• vercel-ai-sdk/ — @mem0/vercel-ai-provider, wrapping the Vercel AI SDK so memory is injected automatically per call. Source: vercel-ai-sdk/README.md:1-40.
• cli/ — terminal clients (@mem0/cli for Node, mem0-cli for Python). Source: cli/README.md:1-15.
• openmemory/ — the self-hostable dashboard, MCP server, and backend service. Source: openmemory/README.md:1-30.

Memory Operations

Platform Client (Hosted API)

The hosted client targets Mem0's managed infrastructure. Requests are authenticated with an API key and dispatched through axios. The TypeScript types live in mem0-ts/src/client/mem0.types.ts, which defines AddMemoryOptions, SearchMemoryOptions, GetAllMemoryOptions, DeleteAllMemoryOptions, MemoryUpdateBody, ProjectOptions, WebhookCreatePayload, FeedbackPayload, and CreateMemoryExportPayload. Source: mem0-ts/src/client/mem0.types.ts:1-60.

Entity scoping (who the memory belongs to) must be supplied through the filters object rather than top-level arguments. The client enforces this with a rejectTopLevelEntityParams guard that rejects user_id, agent_id, app_id, and run_id (and their camelCase variants) at the top level of the request. Source: mem0-ts/src/client/mem0.ts:24-50. This is a frequent gotcha — placing user_id outside filters triggers a validation error rather than silent mis-routing.

OSS Pipeline (Local)

The OSS pipeline performs the full extract → embed → dedup → store workflow on the caller's machine. The TypeScript README documents the entry point:

import { Memory } from "mem0-ts";
const memory = new Memory({
  embedder: { provider: "openai", config: { apiKey: process.env.OPENAI_API_KEY, model: "text-embedding-3-small" } },
  llm:      { provider: "openai", config: { apiKey: process.env.OPENAI_API_KEY } },
  vectorStore: { provider: "memory", config: { collectionName: "custom-memories" } },
});

Source: mem0-ts/src/oss/README.md:36-55.

Hybrid retrieval is the default in v3: dense similarity is combined with BM25 and an entity-recognition boost. The scoring layer adapts sigmoid parameters to query length — short queries (≤3 terms) use a midpoint of 5.0 with steepness 0.7, while longer queries (≥16 terms) shift the midpoint to 12.0. The ENTITY_BOOST_WEIGHT constant of 0.5 controls how much the entity-recognition path contributes to the final score. Source: mem0-ts/src/oss/src/utils/scoring.ts:11-30.

Vercel AI SDK Integration

The Vercel provider wraps a chat model so memory is automatically retrieved and prepended as system context:

import { generateText } from "ai";
import { createMem0 } from "@mem0/vercel-ai-provider";
const mem0 = createMem0({ provider: "openai", mem0ApiKey: process.env.MEM0_API_KEY });
const { text } = await generateText({
  model: mem0("gpt-4-turbo", { user_id: "borat" }),
  prompt: "Suggest me a good car to buy!",
});

Source: vercel-ai-sdk/README.md:60-75. A complementary retrieveMemories(prompt, { user_id }) helper returns the formatted memory string for use in manual system: prompts. Source: vercel-ai-sdk/README.md:80-95.

Configuration & Setup

Configuration is consistently modeled as a tree of { provider, config } pairs. The table below summarizes the principal provider slots and their typical values.

The CLI distribution is split across cli/node/ (@mem0/cli, Node ≥ 18) and cli/python/ (mem0-cli). Source: cli/README.md:1-15. Both read the same MEM0_API_KEY environment variable as the SDKs.

Common Failure Modes & Community Notes

A handful of issues recur across the community. They are worth understanding before shipping to production:

• Silent partial failure in batched add(): when an embedding provider returns an error for one item in a batch, the V3 pipeline logs at WARNING and drops the affected memories without raising. See #5245. Callers that need strict guarantees should check the returned result envelope and reconcile counts.
• encoding_format default base64: the TS embedder sends encoding_format="base64" by default, which some OpenAI-compatible proxies reject. The Python SDK fixed an analogous bug in #4057 and the TS port is tracked in #5168.
• Qdrant over HTTPS: configuring a self-hosted Qdrant with host + port + api_key can cause the client to upgrade to HTTPS. See #5378.
• Platform v3 user_id/agent_id not stored: the platform endpoint sometimes returns SUCCEEDED without persisting the supplied entity filter, leaving get_all() empty. See #5224.
• Malicious npm impersonator: a package named mem0-mcp-server (publisher shadowdqj) impersonates the official @mem0/mcp-server and exfiltrates data. See #5274. Always install the official scope.
• OpenAI token usage not surfaced: there is no first-class field for token counts on add/search/getAll responses; the feature is tracked in #2820.

The make bootstrap self-hosting flow also requires make and a recent Node with node:sqlite available natively; Windows users have reported CRLF and port-3000 conflicts. Source: openmemory/README.md:1-30, plus issue #2690.

See Also

• Mem0 REST API & filters — skills/mem0/references/api-reference.md
• Vercel AI SDK provider — vercel-ai-sdk/README.md
• TypeScript OSS pipeline — mem0-ts/src/oss/README.md
• OpenMemory self-hosting — openmemory/README.md
• Evaluation harness (LOCOMO) — evaluation/README.md

Related Pages

Related topics: Overview & V3 Memory Algorithm, Integrations, Extensibility & Common Failure Modes

Self-Hosting, Server Stack & OpenMemory

Overview

Mem0 is distributed across several independently deployable surfaces: the hosted Platform at app.mem0.ai, the open-source Python/TypeScript SDKs, and the self-hostable OpenMemory stack. Self-hosting is a recurring community theme — Issue #2694 ("self host website") and the open proposal in Issue #5354 ("Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends") both push for production-friendly, fully-owned deployments. Source: openmemory/README.md:1-25.

OpenMemory itself is a Docker-packaged bundle that combines a FastAPI/SQLAlchemy backend with a React dashboard and an MCP server. The openmemory/README.md describes the project as community-driven tooling for AI memory, with an explicit contribution flow and two top-level commands:

make build   # builds the mcp server and ui
make up      # runs openmemory mcp server and ui

Source: openmemory/README.md:30-50.

OpenMemory Stack Components

The stack is organized into two top-level packages per openmemory/README.md:

The backend Dockerfile workflow is documented in openmemory/api/README.md, which prescribes a make build / make env / make up lifecycle, with OPENAI_API_KEY injected into api/.env. Live API documentation is served at http://localhost:8765/docs (Swagger UI) and /redoc once the container is up. Source: openmemory/api/README.md:1-60.

A second surface, the mem0-plugin/, exposes the hosted Mem0 MCP server (mcp.mem0.ai) and lifecycle hooks for editor-style clients (Claude Code, Cursor, Codex, OpenCode, Antigravity). Its README.md clarifies that lifecycle hooks and the SDK skill are opt-in per client — for example, Codex only wires hooks via the scripts/install_codex_hooks.py installer. Source: mem0-plugin/README.md:1-40.

Architecture diagram

flowchart LR
  Client[Editor / Agent<br/>Claude Code, Cursor, etc.] -->|SSE| MCP[OpenMemory MCP<br/>:8765]
  MCP --> API[FastAPI<br/>api/]
  API --> DB[(SQLAlchemy<br/>SQLite/Postgres)]
  API --> Mem0[Mem0 SDK<br/>fact extraction + vector search]
  UI[React Dashboard<br/>ui/ :3000] --> API
  Plugin[mem0-plugin<br/>mcp.mem0.ai] -.optional.-> Client

Source: openmemory/README.md:30-50, openmemory/api/README.md:1-60, mem0-plugin/README.md:1-40.

Self-Hosting Setup and Known Failure Modes

The canonical setup path for OpenMemory is two make targets plus an npx @openmemory/install local one-liner that registers the MCP endpoint into a target editor:

npx @openmemory/install local http://localhost:8765/mcp/<client-name>/sse/<user-id> --client <client-name>

The <user-id> placeholder must match the value configured in the OpenMemory environment. Source: openmemory/README.md:50-65.

Several community-reported failure modes recur for self-hosters:

• Bootstrap failure on newer Node runtimes — Issue #5291 ("Self-hosting build fail") reports make bootstrap inside server/ aborting with No such built-in module: node:sqlite because the Makefile pulls a Node version older than the runtime that ships with node:sqlite. Workaround: use a Node ≥ the SQLite build, or run the dashboard image directly. Source: community context.
• Windows CRLF / port collisions — Issue #2690 reports entrypoint.sh breaking under CRLF line endings and the default UI port 3000 conflicting with other dev servers. The recommended fix is to run the UI manually via cd ui && pnpm install && pnpm dev. Source: openmemory/README.md:66-75, community context.
• UI not reachable on localhost:3000 — The project README already documents the manual pnpm dev fallback, indicating that the dev container occasionally fails to bind the port. Source: openmemory/README.md:66-75.
• MCP incompatibility with Claude Desktop 0.9.3 — Issue #2712 ("OpenMemory + Claude Desktop Alignment") describes a round-trip failure where the desktop client cannot enumerate memories from the OpenMemory SSE endpoint. Source: community context.
• Silent memory loss in batch embedding — Issue #5245 reports that the V3 Memory.add() pipeline drops individual items when the embedding provider fails inside a batch, only emitting a WARNING log. This affects any self-hosted deployment relying on OSS Qdrant/PGVector and motivates a defensive write-ahead layer. Source: community context.
• Qdrant HTTPS mis-detection — Issue #5378 notes that the Qdrant vector store forces HTTPS when host + port + api_key are configured, breaking plain-HTTP self-hosted Qdrant. Source: community context.

SDKs, Skills, and Plugin Surfaces

Self-hosters interact with Mem0 through three parallel layers.

Python/TypeScript SDKs. The OSS TypeScript port lives in mem0-ts/src/oss/ and ships an in-memory vector store, SQLite-based history, optional graph memory, and an OpenAI default configuration. Its README.md documents Memory instantiation with overridable embedder, llm, and vectorStore providers. Source: mem0-ts/src/oss/README.md:1-50.

Skills. Two on-demand documentation skills live under skills/: skills/mem0/ (Python/TypeScript SDK, REST API, and framework integrations) and skills/mem0-cli/ (terminal commands). Both reuse the same reference tree (quickstart.md, sdk-guide.md, api-reference.md, architecture.md, etc.). Source: skills/mem0/README.md:1-30, skills/mem0-cli/README.md:1-25.

Plugin & community packages. The mem0-plugin/ ships a Claude Code / Cursor / Codex / OpenCode / Antigravity installable that connects to mcp.mem0.ai and is documented as requiring a client restart after upgrades (stale MCP handles are not auto-rebound). Source: mem0-plugin/README.md:1-60.

The @mem0/community package (mem0-ts/src/community/package.json) bundles LangChain adapters, depends on mem0ai ^2.1.8 and axios ^1.16.0, and targets node >=18. The vercel-ai-sdk/ package adds pnpm overrides for transitive CVEs (e.g. glob, minimatch, picomatch) and exposes a Zod peer dependency. Source: mem0-ts/src/community/package.json:1-60, vercel-ai-sdk/package.json:1-60.

A cli/ folder distributes terminal clients in both languages (node/ → @mem0/cli, python/ → mem0-cli), documented at docs.mem0.ai/platform/cli. Source: cli/README.md:1-20.

See Also

• Mem0 Platform dashboard: app.mem0.ai
• Issue #5354 — Pluggable storage proposal
• Issue #5352 — Time-blindness / CRUD workarounds for OSS + Qdrant
• mem0-ts/src/oss/ — TypeScript OSS reference
• skills/mem0/references/architecture.md — Pipeline lifecycle

Related Pages

Related topics: Overview & V3 Memory Algorithm, SDK Quickstart & Memory Operations, Self-Hosting, Server Stack & OpenMemory

Integrations, Extensibility & Common Failure Modes

1. Integration Surfaces in the Mem0 Ecosystem

Mem0 is intentionally split into multiple integration surfaces so the same memory layer can be reached from many environments. The core OSS pipeline (Python and TypeScript) handles ingestion and retrieval, while a Platform REST API and a set of plug-ins expose the same capabilities to other runtimes.

The plugin README documents the distribution matrix: a single mem0-plugin package provides an MCP server, lifecycle hooks, and an SDK skill across eight host environments, with the MCP server connecting to mcp.mem0.ai rather than running locally (Source: mem0-plugin/README.md). Skills under skills/mem0/ and skills/mem0-cli/ package documentation in a way that AI agents can load on demand, separating "what to do" (SKILL.md) from "how to call the SDK" (the references/ directory) (Source: skills/mem0/README.md).

2. Extensibility Points

The OSS SDK is built around three swappable component classes: LLM, embedder, and vector store. The TypeScript implementation shows this pattern clearly. LangchainLLM accepts any pre-initialized LangChain BaseLanguageModel via config.model and translates internal Message objects into SystemMessage, HumanMessage, and AIMessage instances (Source: mem0-ts/src/oss/src/llms/langchain.ts:1-31). Unknown roles fall back to human with a console warning, which is a deliberate extensibility trade-off.

Extensibility also reaches into the retrieval and prompt layer. The hybrid scorer in scoring.ts exposes a tunable ENTITY_BOOST_WEIGHT = 0.5 and adapts BM25 sigmoid parameters to query length (Source: mem0-ts/src/oss/src/utils/scoring.ts:1-50). Prompts in prompts/index.ts emit a linked_memory_ids field, letting downstream code relate a newly extracted fact to existing memories by entity, updated preference, or continuation (Source: mem0-ts/src/oss/src/prompts/index.ts). The entity extractor in entity_extraction.ts is a pluggable NLP pipeline: it first attempts to require("compromise") and silently falls back to regex extraction if the package is absent, and it runs three independent extractors (proper-noun, compound, and quoted) followed by deduplication and artifact stripping (Source: mem0-ts/src/oss/src/utils/entity_extraction.ts). The Platform client surfaces additional extension points through WebhookCreatePayload, WebhookUpdatePayload, and CreateMemoryExportPayload types for outbound notifications and bulk export jobs (Source: mem0-ts/src/client/mem0.types.ts).

flowchart LR
  App[Host App / IDE] --> SDK[OSS SDK]
  SDK --> LLM[Pluggable LLM]
  SDK --> Emb[Pluggable Embedder]
  SDK --> VS[Pluggable Vector Store]
  SDK --> Ext[Entity Extractor<br/>compromise or regex]
  App -.->|webhooks| Hooks[Webhook Subscriptions]
  App -.->|exports| Exp[Bulk Export Jobs]

3. Common Failure Modes

Community-reported issues cluster around a small number of well-defined failure patterns. Understanding them is part of "extending" the system safely.

Silent partial failures during batch ingest. Issue #5245 reports that Memory.add() can drop individual items when an embedding provider fails on some elements of a batch; the failure is logged at WARNING but no exception bubbles up to the caller, so the returned list overstates what was stored.

Protocol mismatches in vector-store clients. Issue #5378 documents the Qdrant HTTP/HTTPS confusion: supplying host, port, and api_key to a self-hosted Qdrant instance can incorrectly upgrade the connection to HTTPS, because the client treats api_key as a signal of a managed (TLS) endpoint.

Default-value mismatches with OpenAI-compatible proxies. Issue #5168 notes that OpenAIEmbedder in the TypeScript SDK defaults to encoding_format="base64", which many third-party OpenAI proxies do not support. The Python equivalent was fixed in #4057, but the TypeScript default still causes embed() calls to fail against non-OpenAI endpoints.

Stale MCP server handles after plugin updates. The plugin README explicitly warns that when the plugin updates, the MCP server connection in an existing editor session holds a stale handle and stops responding; the user must restart the host client (Source: mem0-plugin/README.md).

Self-hosting build prerequisites. Issue #5291 reports that make bootstrap in server/ fails with No such built-in module: node:sqlite when run on Node versions older than the project's required baseline. Windows users also hit CRLF and port-3000 conflicts (issue #2690) because the bootstrap assumes Unix line endings and a free port.

Platform v3 parameter pass-through bugs. Issue #5224 shows that add() on the Platform v3 API accepts user_id and agent_id and returns SUCCEEDED, yet the stored records have user_id=None/agent_id=None, making get_all() return empty for the same identifiers. This is a contract mismatch between client expectations and server-side validation.

Supply-chain impersonation. Issue #5274 documents a malicious npm package named mem0-mcp-server (publisher shadowdqj) that impersonates the official @mem0/mcp-server and exfiltrates data. The official MCP server is hosted remotely and requires no local install, so the presence of a same-named local package is itself a red flag.

Semantic conflict and time-blindness in the ADD-only pipeline. Issue #5352 explains that issues #4896 and #4904 around conflict resolution were closed as "not planned" because the v3 SDK relies on memory linking and client-side retrieval prioritization. Self-hosted users who need time-aware updates or explicit CRUD must add a wrapper layer themselves.

4. Mitigation Patterns

A few patterns recur across these failure modes. First, treat the SDK's silent-warning behavior as a contract: when extending the pipeline, wrap batched operations in your own boundary that re-checks the returned list against the input, the same way you would for any partial-success API. Second, never rely on implicit defaults when targeting a non-vendor provider: pass encoding_format, scheme, and protocol explicitly. Third, pin SDK versions and prefer the official scoped npm package (@mem0/mcp-server) over un-scoped look-alikes, and verify that the MCP server URL is mcp.mem0.ai. Fourth, when self-hosting, verify the Node version and port availability before running make bootstrap, and read the structured exceptions raised by the TypeScript SDK (MemoryError, RateLimitError, MemoryNotFoundError) to drive retries and user messaging rather than treating failures as opaque strings (Source: mem0-ts/src/common/exceptions.ts:1-50).

Finally, prefer entity_extraction.ts's explicit "no-NLP fallback" path over silently degrading: if you ship without compromise, document that compound-entity quality is reduced, because the regex path is a documented degradation, not a bug.

See Also

• Quickstart (Python, TypeScript, cURL) — official entry point for the integration surfaces listed above.
• REST API Reference — typed equivalents of the payloads in mem0-ts/src/client/mem0.types.ts.
• mem0-plugin/README.md — host-matrix details and update-restart warning.
• openmemory/README.md — self-hosting entry point and contribution workflow.

Doramagic Pitfall Log

Found 29 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mem0ai/mem0/issues/5291

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mem0ai/mem0/issues/5245

3. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mem0ai/mem0/issues/5352

4. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mem0ai/mem0/issues/5224

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mem0ai/mem0/issues/5274

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK
• User impact: Developers may fail before the first successful local run: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5168

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Mem0 Node CLI (v0.2.8)
• User impact: Upgrade or migration may change expected behavior: Mem0 Node CLI (v0.2.8)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Mem0 Node CLI (v0.2.8). Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/cli-node-v0.2.8

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Mem0 Node SDK (v3.0.6)
• User impact: Upgrade or migration may change expected behavior: Mem0 Node SDK (v3.0.6)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Mem0 Node SDK (v3.0.6). Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/ts-v3.0.6

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Mem0 OpenClaw Plugin (v1.0.12)
• User impact: Upgrade or migration may change expected behavior: Mem0 OpenClaw Plugin (v1.0.12)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Mem0 OpenClaw Plugin (v1.0.12). Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/openclaw-v1.0.12

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Mem0 OpenCode Plugin (v0.1.1)
• User impact: Upgrade or migration may change expected behavior: Mem0 OpenCode Plugin (v0.1.1)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Mem0 OpenCode Plugin (v0.1.1). Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/opencode-v0.1.1

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Mem0 OpenCode Plugin (v0.1.2)
• User impact: Upgrade or migration may change expected behavior: Mem0 OpenCode Plugin (v0.1.2)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Mem0 OpenCode Plugin (v0.1.2). Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/opencode-v0.1.2

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Self-hosting build fail
• User impact: Developers may fail before the first successful local run: Self-hosting build fail
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Self-hosting build fail. Context: Observed when using node, docker, macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5291

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mem0 with real data or production workflows.

• Silent memory loss when batch embedding partially fails in V3 add pipeli - github / github_issue
• Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backend - github / github_issue
• Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for s - github / github_issue
• Workaround: Solving time-blindness, semantic conflicts, and missing CRUD - github / github_issue
• Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (enc - github / github_issue
• [[Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store](https://github.com/mem0ai/mem0/issues/5224) - github / github_issue
• 🚨 Malicious impersonator package 'mem0-mcp-server' on npm - github / github_issue
• Self-hosting build fail - github / github_issue
• Vercel AI SDK Provider (v2.4.6) - github / github_release
• Mem0 Node SDK (v3.0.6) - github / github_release
• Mem0 OpenClaw Plugin (v1.0.12) - github / github_release
• Mem0 Node CLI (v0.2.8) - github / github_release