mem0-integrate

Wire Mem0 into an existing repo with a goal-driven, test-first pipeline. Pairs with mem0-test-integration for verification.

Canonical sources (fetch before deciding anything)

The skill MUST WebFetch these URLs before step 3 and cite them in plan.md. They are the ground truth — do not rely on ambient knowledge of the Mem0 API.

Agent-ready docs

• Scope-tagged docs index: https://docs.mem0.ai/llms.txt
• Full docs (single file, deep dives): https://docs.mem0.ai/llms-full.txt
• OpenAPI spec (Platform REST, machine-readable): https://docs.mem0.ai/openapi.json
• Hosted MCP server: https://mcp.mem0.ai/mcp (requires Platform API key)
• Integrations index: https://docs.mem0.ai/integrations

Published Mem0 skills — delegate; do not reimplement

Prefer these over writing your own call-site patterns. Each is a standalone SKILL.md with triggers, examples, and version-pinned code.

• SDK (Python + TS, Platform + OSS): https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md
• CLI: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-cli/SKILL.md
• Vercel AI SDK: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md
• Portable editor/MCP plugin: https://github.com/mem0ai/mem0/tree/main/integrations/mem0-agent-plugin

SDK source (read when docs are ambiguous)

Public repo. Cross-check against the mem0_tested_versions range in this skill's frontmatter if the main branch has moved past a major.

• Repo root: https://github.com/mem0ai/mem0
• Python SDK: https://github.com/mem0ai/mem0/tree/main/mem0
• TypeScript SDK: https://github.com/mem0ai/mem0/tree/main/mem0-ts

Quickstarts (for bootstrapping unfamiliar stacks)

• Platform: https://docs.mem0.ai/platform/quickstart
• OSS Python: https://docs.mem0.ai/open-source/python-quickstart
• OSS Node: https://docs.mem0.ai/open-source/node-quickstart
• Platform vs OSS comparison: https://docs.mem0.ai/platform/platform-vs-oss

Integration principles (non-negotiable)

The true goal of this skill is to produce a PR the maintainers can accept without argument. That rules out anything invasive.

1. Additive, not replacing. If the target repo already has a memory system, a session store, a user-context layer, or anything named Memory / memory_*, Mem0 sits alongside it, not in place of it. The existing system keeps working unchanged.
2. Opt-in by default. Gate all new Mem0 code behind a feature flag (env var like MEM0_ENABLED=1, a config key, or a strategy selector). With the flag unset, behavior is the repo's original behavior, byte-for-byte.
3. No breakage. No removed exports, no renamed public functions, no changed method signatures, no modified existing tests, no changed behavior of existing tests. All pre-existing tests must pass unchanged both with the flag set and unset.
4. Minimal dependency surface. Add mem0ai (plus any deps the delegated skill requires) and nothing else. No new vector stores, no graph databases, no provider SDKs the repo does not already use.
5. Separable commits. Code, tests, and config/docs land in separate commits so reviewers can cherry-pick.
6. The null hypothesis wins. If no additive, gated fit exists after step 6 (plan), exit with code 1 and a rationale. A bad PR is worse than no PR.
7. Backend only. Mem0 integration lives in server-side code. API keys, memory scope, and user-identity resolution are not safe client-side. If the repo has both backend and frontend, the call sites live in backend files. Frontend-only repos are rejected at preconditions.

Enforced at four gates: preconditions (reject frontend-only repos and repos where additive fit is impossible), step 2 comprehension (confirm a backend exists and name candidate surfaces), step 6 plan review (reject plans that mutate existing exports or name client-side call sites), and step 10 self-healing loop (refuse to "fix" principle violations — surface them instead).

Skill delegation rules

Before writing any code, check whether a published skill already covers the target stack. If yes, delegate — copy its call-site pattern into plan.md and into the tests; do not paraphrase.

Record the delegated skill's raw URL in plan.md under a "Delegated skill:" field. The test writer in step 7 and the implementation subagent in step 8 both read this field.

Preconditions

Refuse to start unless ALL of the following are true:

• Current working directory is inside a git repository with a clean index (no uncommitted changes). Protects the user's work — every edit lands on a feature branch, not on top of in-progress changes.
• Repo has a detectable language (package.json / pyproject.toml / requirements.txt). No language → exit cleanly with a written rationale.
• Repo has a backend. Detected by: a backend/ or server/ or api/ directory; a Python package with FastAPI/Flask/Django/Starlette; a Node package with Express/Fastify/Koa/NestJS/Next-API-routes; an agent-loop framework (LangGraph, LangChain, LlamaIndex, Agno). Frontend-only repos (pure React/Vue/Svelte SPAs, static sites, mobile-only) → exit with code 1 and a rationale. Mem0 is not installed client-side.
• The user has already decided Mem0 fits this repo. This skill does NOT survey the codebase to justify fit — bring a concrete goal. (Step 2 does read the repo to understand what it does and locate backend integration surfaces; that is mechanics, not fit-justification.)

Exit with a written rationale if any precondition fails. Do not try to "make it work anyway."

Pipeline

Ten steps. Full mechanics, document templates, and gate rules are in references/pipeline.md. Read that file when you start executing a step; the summary below is only for routing.

Artifacts (all under .mem0-integration/)

.mem0-integration/ is added to .gitignore on first run. Nothing is written outside this directory and the repo's source tree.

Modes

Invocation

/mem0-integrate                            # interactive, heal ON
/mem0-integrate --no-heal                  # stop after commit; manual verify
/mem0-integrate --heal-max 5               # cap heal attempts per category (default 3)
/mem0-integrate --product platform         # skip the product ask
/mem0-integrate --product oss
/mem0-integrate --ci                       # non-interactive (for test harness)

Exit codes

Explicitly out of scope

• Surveying the repo for fit points. Humans decide where Mem0 helps before invoking this skill.
• Replacing any existing memory / session / state system. Always additive and feature-flagged; see "Integration principles."
• Modifying pre-existing tests, even to "fix" them under self-heal. Tests that fail after integration with the flag unset are a non-invasiveness violation, not a bug to patch.
• Deciding Platform vs OSS silently. Always ask with a recommendation.
• Switching branches, pushing, or opening PRs. Commits locally and stops (or enters the heal loop, still local).
• Data migration between stores. Point user at migration/oss-to-platform docs if they ask.
• Provider selection beyond the default LLM for OSS. If they need a custom LLM / embedder / vector store, route to components/* docs and re-run step 4 with the new key.