mem0-integrate

What this skill does

# 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 (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
- Editor/MCP plugin glue (9 MCP tools): https://github.com/mem0ai/mem0/tree/main/mem0-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.

| Detected in target repo | Delegate to | Why |
|---|---|---|
| `@ai-sdk/*` + `ai` in `package.json` | `skills/mem0-vercel-ai-sdk` | Integration is via `createMem0` provider wrapper, not raw `MemoryClient`. |
| 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. |
| Target is an MCP client / editor config (Claude Code, Cursor, Codex settings) | `mem0-plugin` | Wire via MCP server URL + hooks; no SDK code usually needed. |
| Any other Python or TS repo with an LLM call site | `skills/mem0` | Default SDK integration path. |

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

### 1. Language detection

| Signal | Track |
|---|---|
| `package.json` + TypeScript config | Node / TypeScript |
| `package.json` (no TS config) | Node / JavaScript |
| `pyproject.toml` or `requirements.txt` | Python |

Monorepo with both → ask which subdirectory to operate in, then recurse.

### 2. Repo comprehension — what does this repo do, and where is the backend?

Before any decision (product, goal, plan), understand the repo enough
to locate *where in the backend* the integration belongs. This is not
fit-surveying — the user already decided Mem0 fits. This is mechanics:
you cannot write a plan without knowing what files matter.

Read, in order, with a token budget — do not scan the whole tree:

1. `README.md` (root) + first-page of any `README_*.md` variants.
2. `CONTRIBUTING.md` / `AGENTS.md` / `CLAUDE.md` at root if present —
   these often spell out architecture and entry points.
3. `package.json` / `pyproject.toml` scripts + entry points.
4. The layout of the top two directory levels (not recursive).
5. Key config files: `docker-compose.yml`, `Dockerfile`, `Makefile`,
   `langgraph.json`, `next.config.*`, `nuxt.config.*`.

Produce `.mem0-integration/repo-summary.md`:

    # Repo comprehension

    **What this repo does:** <one paragraph in plain English. Who is
    the end user? What does the app do for them? What LLM / agent
    behavior is central? Do not list dependencies — describe behavior.>

    **Architecture at a glance:**
      - Backend: <path(s), framework, primary entry point>
      - Frontend: <path(s) if any, framework — for context only; no
        integration here>
      - Agent loop / orchestratio