mem0-integrate

1---2name: mem0-integrate3description: >4  Integrate Mem0 into an existing repository using a goal-driven, TDD pipeline.5  Detects the repo's language automatically and asks the user to pick between6  Mem0 Platform (managed) and Mem0 Open Source (self-hosted). Writes failing7  tests before any implementation. Produces a local feature branch plus8  `.mem0-integration/` artifacts consumed by the paired verification skill.9  TRIGGER when: user says "integrate mem0", "add mem0 to this repo", "wire10  mem0 into <repo>", or asks how to add memory to an existing project.11  DO NOT TRIGGER when: the user wants general SDK usage (use skill:mem0),12  CLI usage (use skill:mem0-cli), or Vercel AI SDK (use skill:mem0-vercel-ai-sdk).13  After success, invoke skill:mem0-test-integration to verify in the same14  workspace (loose coupling).15license: Apache-2.016metadata:17  author: mem0ai18  version: "0.1.0"19  category: ai-memory20  tags: "memory, integration, tdd, platform, oss"21  mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"22---23 24# mem0-integrate25 26Wire Mem0 into an existing repo with a goal-driven, test-first pipeline.27Pairs with `mem0-test-integration` for verification.28 29## Canonical sources (fetch before deciding anything)30 31The skill MUST `WebFetch` these URLs before step 3 and cite them in32`plan.md`. They are the ground truth — do not rely on ambient knowledge33of the Mem0 API.34 35### Agent-ready docs36- Scope-tagged docs index: https://docs.mem0.ai/llms.txt37- Full docs (single file, deep dives): https://docs.mem0.ai/llms-full.txt38- OpenAPI spec (Platform REST, machine-readable): https://docs.mem0.ai/openapi.json39- Hosted MCP server: https://mcp.mem0.ai (requires Platform API key)40- Integrations index: https://docs.mem0.ai/integrations41 42### Published Mem0 skills — delegate; do not reimplement43Prefer these over writing your own call-site patterns. Each is a44standalone `SKILL.md` with triggers, examples, and version-pinned code.45 46- SDK (Python + TS, Platform + OSS): https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md47- CLI: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-cli/SKILL.md48- Vercel AI SDK: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md49- Portable editor/MCP plugin: https://github.com/mem0ai/mem0/tree/main/integrations/mem0-agent-plugin50 51### SDK source (read when docs are ambiguous)52Public repo. Cross-check against the `mem0_tested_versions` range in this53skill's frontmatter if the `main` branch has moved past a major.54 55- Repo root: https://github.com/mem0ai/mem056- Python SDK: https://github.com/mem0ai/mem0/tree/main/mem057- TypeScript SDK: https://github.com/mem0ai/mem0/tree/main/mem0-ts58 59### Quickstarts (for bootstrapping unfamiliar stacks)60- Platform: https://docs.mem0.ai/platform/quickstart61- OSS Python: https://docs.mem0.ai/open-source/python-quickstart62- OSS Node: https://docs.mem0.ai/open-source/node-quickstart63- Platform vs OSS comparison: https://docs.mem0.ai/platform/platform-vs-oss64 65## Integration principles (non-negotiable)66 67The true goal of this skill is to produce a **PR the maintainers can accept68without argument**. That rules out anything invasive.69 701. **Additive, not replacing.** If the target repo already has a memory71   system, a session store, a user-context layer, or anything named72   `Memory` / `memory_*`, Mem0 sits **alongside** it, not in place of it.73   The existing system keeps working unchanged.742. **Opt-in by default.** Gate all new Mem0 code behind a feature flag75   (env var like `MEM0_ENABLED=1`, a config key, or a strategy selector).76   With the flag unset, behavior is the repo's original behavior,77   byte-for-byte.783. **No breakage.** No removed exports, no renamed public functions,79   no changed method signatures, no modified existing tests, no changed80   behavior of existing tests. All pre-existing tests must pass unchanged81   both with the flag set and unset.824. **Minimal dependency surface.** Add `mem0ai` (plus any deps the83   delegated skill requires) and nothing else. No new vector stores, no84   graph databases, no provider SDKs the repo does not already use.855. **Separable commits.** Code, tests, and config/docs land in separate86   commits so reviewers can cherry-pick.876. **The null hypothesis wins.** If no additive, gated fit exists after88   step 6 (plan), exit with code 1 and a rationale. A bad PR is worse89   than no PR.907. **Backend only.** Mem0 integration lives in server-side code. API keys,91   memory scope, and user-identity resolution are not safe client-side.92   If the repo has both backend and frontend, the call sites live in93   backend files. Frontend-only repos are rejected at preconditions.94 95Enforced at four gates: **preconditions** (reject frontend-only repos96and repos where additive fit is impossible), **step 2 comprehension**97(confirm a backend exists and name candidate surfaces), **step 6 plan98review** (reject plans that mutate existing exports or name client-side99call sites), and **step 10 self-healing loop** (refuse to "fix" principle100violations — surface them instead).101 102## Skill delegation rules103 104Before writing any code, check whether a published skill already covers105the target stack. If yes, delegate — copy its call-site pattern into106`plan.md` and into the tests; do not paraphrase.107 108| Detected in target repo | Delegate to | Why |109|---|---|---|110| `@ai-sdk/*` + `ai` in `package.json` | `skills/mem0-vercel-ai-sdk` | Integration is via `createMem0` provider wrapper, not raw `MemoryClient`. |111| CLI-only repo (Typer, Commander, Click, Cobra) with no LLM call sites | `skills/mem0-cli` | Call sites are command handlers, not model wrappers. Consider whether mem0 actually fits first. |112| Target is an MCP client / editor config (Claude Code, Cursor, Codex settings) | `integrations/mem0-agent-plugin` | Wire via MCP server URL + hooks; no SDK code usually needed. |113| Any other Python or TS repo with an LLM call site | `skills/mem0` | Default SDK integration path. |114 115Record the delegated skill's raw URL in `plan.md` under a116**"Delegated skill:"** field. The test writer in step 7 and the117implementation subagent in step 8 both read this field.118 119## Preconditions120 121Refuse to start unless ALL of the following are true:122 123- Current working directory is inside a git repository with a clean index124  (no uncommitted changes). Protects the user's work — every edit lands on125  a feature branch, not on top of in-progress changes.126- Repo has a detectable language (`package.json` / `pyproject.toml` /127  `requirements.txt`). No language → exit cleanly with a written rationale.128- Repo has a **backend**. Detected by: a `backend/` or `server/` or `api/`129  directory; a Python package with FastAPI/Flask/Django/Starlette; a Node130  package with Express/Fastify/Koa/NestJS/Next-API-routes; an agent-loop131  framework (LangGraph, LangChain, LlamaIndex, Agno). Frontend-only repos132  (pure React/Vue/Svelte SPAs, static sites, mobile-only) → exit with133  code 1 and a rationale. Mem0 is not installed client-side.134- The user has already decided Mem0 fits this repo. This skill does NOT135  survey the codebase to justify fit — bring a concrete goal. (Step 2136  *does* read the repo to understand what it does and locate backend137  integration surfaces; that is mechanics, not fit-justification.)138 139Exit with a written rationale if any precondition fails. Do not try to140"make it work anyway."141 142## Pipeline143 144Ten steps. Full mechanics, document templates, and gate rules are in145[`references/pipeline.md`](references/pipeline.md). Read that file when you146start executing a step; the summary below is only for routing.147 148| # | Step | Gate |149|---|---|---|150| 1 | **Language detection.** `package.json` / `pyproject.toml` / `requirements.txt`. Monorepo, ask which subdirectory. | |151| 2 | **Repo comprehension.** Budgeted read of README, contributor docs, entry points, top two directory levels. Produces `repo-summary.md` with ranked backend surfaces. | User confirms the summary and picks a surface. No backend surface, exit 1. |152| 3 | **Product selection.** Platform vs OSS, recommended from dependency signals, never asked blank. | Locked into `goal.md`, never re-decided. |153| 4 | **API key check.** `MEM0_API_KEY` (Platform) or `OPENAI_API_KEY` (OSS). Missing on Platform, default to Agent Mode via `mem0 init --agent`. | CI mode with a missing key, exit 2. |154| 5 | **Goal doc.** `goal.md`: what gets stored, when it is retrieved, why, product, delegated skill, out of scope. | **Hard gate.** Explicit approval required. 3 rejections, exit 3. |155| 6 | **Integration plan.** Scoped grep for call sites and identity source. `plan.md`: write/read patterns, scoping, call sites, dependencies, preserved behavior, coexistence, feature flag, sources, E2E recipe. | **Hard gate.** No plausible additive call site or 3 rejections, exit 5. |156| 7 | **Tests first.** Failing write and read tests in the repo's native framework, assertion shapes lifted from the canonical signatures. Must be importable with `MEM0_API_KEY` unset. | Tests must fail. If they pass, they are wrong. |157| 8 | **Implementation.** Fresh-context subagent, prompt in [`references/subagent-prompts.md`](references/subagent-prompts.md), returns a diff reviewed against `plan.md` and `goal.md`. | 3 review loops, then exit 4. |158| 9 | **Commit and handoff.** Branch `mem0-integrate/<slug>`, four separable commits: dependency, module, wiring, tests. | `--no-heal` stops here. |159| 10 | **Self-healing loop.** Runs `/mem0-test-integration --ci`, categorizes the failure, spawns a bounded remediation subagent, reverts on regression. | Pre-existing test failure, **stop**, exit 6. Never "fix" it. |160 161## Artifacts (all under `.mem0-integration/`)162 163| File | Purpose | Retention |164|---|---|---|165| `repo-summary.md` | Repo comprehension + candidate backend surfaces (step 2). | Keep across runs. |166| `goal.md` | Approved intent. Never rewritten after step 6. | Keep across runs. |167| `plan.md` | Approved mechanics (where, how, call sites, preserved behavior). | Keep across runs. |168| `trace.jsonl` | Every tool call, decision, and subagent exchange this run. | Overwritten per run. |169| `diff.patch` | The committed integration as a reviewable patch. | Overwritten per run. |170| `heal-trace.md` | Per-attempt record of the self-healing loop (step 10). | Overwritten per run. |171| `product.json` | `{"product": "platform"\|"oss", "language": "...", "mem0_version": "...", "write_site": "file:line", "read_site": "file:line", "feature_flag": "MEM0_ENABLED"}` — consumed by the verification skill. | Overwritten per run. |172 173`.mem0-integration/` is added to `.gitignore` on first run. Nothing is174written outside this directory and the repo's source tree.175 176## Modes177 178| Mode | Trigger | Behavior |179|---|---|---|180| Interactive (default) | TTY present, `MEM0_INTEGRATE_CI` unset | Asks for keys, confirms goal doc, shows recommendations. |181| CI | `MEM0_INTEGRATE_CI=1` | Requires keys in env, requires `--product`, auto-approves goal doc from `goal.md` if present, fails fast otherwise. |182 183## Invocation184 185    /mem0-integrate                            # interactive, heal ON186    /mem0-integrate --no-heal                  # stop after commit; manual verify187    /mem0-integrate --heal-max 5               # cap heal attempts per category (default 3)188    /mem0-integrate --product platform         # skip the product ask189    /mem0-integrate --product oss190    /mem0-integrate --ci                       # non-interactive (for test harness)191 192## Exit codes193 194| Code | Meaning |195|---|---|196| 0 | Success. Feature branch committed; verification skill ready to run. |197| 1 | Precondition failed (dirty repo, no detectable language, etc.). |198| 2 | Missing env key in CI mode. |199| 3 | Goal doc rejected 3+ times — integration is not well-specified. |200| 4 | Subagent review loop did not converge in 3 rounds. |201| 5 | Integration plan rejected 3+ times, or no plausible additive call site found. |202| 6 | Self-healing loop did not converge, detected a non-invasiveness violation, or a pre-existing test failed. |203 204## Explicitly out of scope205 206- Surveying the repo for fit points. Humans decide where Mem0 helps before207  invoking this skill.208- Replacing any existing memory / session / state system. Always additive209  and feature-flagged; see "Integration principles."210- Modifying pre-existing tests, even to "fix" them under self-heal. Tests211  that fail after integration with the flag unset are a non-invasiveness212  violation, not a bug to patch.213- Deciding Platform vs OSS silently. Always ask with a recommendation.214- Switching branches, pushing, or opening PRs. Commits locally and stops215  (or enters the heal loop, still local).216- Data migration between stores. Point user at `migration/oss-to-platform`217  docs if they ask.218- Provider selection beyond the default LLM for OSS. If they need a custom219  LLM / embedder / vector store, route to `components/*` docs and re-run220  step 4 with the new key.221