skills/mem0-integrate/SKILL.md
Wire Mem0 into an existing repo with a goal-driven, test-first pipeline.
Pairs with mem0-test-integration for verification.
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.
Prefer these over writing your own call-site patterns. Each is a
standalone SKILL.md with triggers, examples, and version-pinned code.
Public repo. Cross-check against the mem0_tested_versions range in this
skill's frontmatter if the main branch has moved past a major.
The true goal of this skill is to produce a PR the maintainers can accept without argument. That rules out anything invasive.
Memory / memory_*, Mem0 sits alongside it, not in place of it.
The existing system keeps working unchanged.MEM0_ENABLED=1, a config key, or a strategy selector).
With the flag unset, behavior is the repo's original behavior,
byte-for-byte.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.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).
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) | integrations/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.
Refuse to start unless ALL of the following are true:
package.json / pyproject.toml /
requirements.txt). No language → exit cleanly with a written rationale.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.Exit with a written rationale if any precondition fails. Do not try to "make it work anyway."
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.
| # | Step | Gate |
|---|---|---|
| 1 | Language detection. package.json / pyproject.toml / requirements.txt. Monorepo, ask which subdirectory. | |
| 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. |
| 3 | Product selection. Platform vs OSS, recommended from dependency signals, never asked blank. | Locked into goal.md, never re-decided. |
| 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. |
| 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. |
| 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. |
| 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. |
| 8 | Implementation. Fresh-context subagent, prompt in references/subagent-prompts.md, returns a diff reviewed against plan.md and goal.md. | 3 review loops, then exit 4. |
| 9 | Commit and handoff. Branch mem0-integrate/<slug>, four separable commits: dependency, module, wiring, tests. | --no-heal stops here. |
| 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. |
.mem0-integration/)| File | Purpose | Retention |
|---|---|---|
repo-summary.md | Repo comprehension + candidate backend surfaces (step 2). | Keep across runs. |
goal.md | Approved intent. Never rewritten after step 6. | Keep across runs. |
plan.md | Approved mechanics (where, how, call sites, preserved behavior). | Keep across runs. |
trace.jsonl | Every tool call, decision, and subagent exchange this run. | Overwritten per run. |
diff.patch | The committed integration as a reviewable patch. | Overwritten per run. |
heal-trace.md | Per-attempt record of the self-healing loop (step 10). | Overwritten per run. |
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. |
.mem0-integration/ is added to .gitignore on first run. Nothing is
written outside this directory and the repo's source tree.
| Mode | Trigger | Behavior |
|---|---|---|
| Interactive (default) | TTY present, MEM0_INTEGRATE_CI unset | Asks for keys, confirms goal doc, shows recommendations. |
| CI | MEM0_INTEGRATE_CI=1 | Requires keys in env, requires --product, auto-approves goal doc from goal.md if present, fails fast otherwise. |
/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)
| Code | Meaning |
|---|---|
| 0 | Success. Feature branch committed; verification skill ready to run. |
| 1 | Precondition failed (dirty repo, no detectable language, etc.). |
| 2 | Missing env key in CI mode. |
| 3 | Goal doc rejected 3+ times — integration is not well-specified. |
| 4 | Subagent review loop did not converge in 3 rounds. |
| 5 | Integration plan rejected 3+ times, or no plausible additive call site found. |
| 6 | Self-healing loop did not converge, detected a non-invasiveness violation, or a pre-existing test failed. |
migration/oss-to-platform
docs if they ask.components/* docs and re-run
step 4 with the new key.