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
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 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.
Quickstarts (for bootstrapping unfamiliar stacks)
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.
- 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.
- 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.
- 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.
- 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.
- Separable commits. Code, tests, and config/docs land in separate
commits so reviewers can cherry-pick.
- 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.
- 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) |
integrations/mem0-agent-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
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. |
Artifacts (all under .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.
Modes
| 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. |
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
| 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. |
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.
1---
2name: mem0-integrate
3description: >
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 between
6 Mem0 Platform (managed) and Mem0 Open Source (self-hosted). Writes failing
7 tests before any implementation. Produces a local feature branch plus
8 `.mem0-integration/` artifacts consumed by the paired verification skill.
9 TRIGGER when: user says "integrate mem0", "add mem0 to this repo", "wire
10 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 same
14 workspace (loose coupling).
15license: Apache-2.0
16metadata:
17 source: https://skillmd.com/skills/mem0ai/mem0-integrate
18 author: mem0ai
19 version: "0.1.0"
20 category: ai-memory
21 tags: "memory, integration, tdd, platform, oss"
22 mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"
23---
24
25# mem0-integrate
26
27Wire Mem0 into an existing repo with a goal-driven, test-first pipeline.
28Pairs with `mem0-test-integration` for verification.
29
30## Canonical sources (fetch before deciding anything)
31
32The skill MUST `WebFetch` these URLs before step 3 and cite them in
33`plan.md`. They are the ground truth — do not rely on ambient knowledge
34of the Mem0 API.
35
36### Agent-ready docs
37- Scope-tagged docs index: https://docs.mem0.ai/llms.txt
38- Full docs (single file, deep dives): https://docs.mem0.ai/llms-full.txt
39- OpenAPI spec (Platform REST, machine-readable): https://docs.mem0.ai/openapi.json
40- Hosted MCP server: https://mcp.mem0.ai (requires Platform API key)
41- Integrations index: https://docs.mem0.ai/integrations
42
43### Published Mem0 skills — delegate; do not reimplement
44Prefer these over writing your own call-site patterns. Each is a
45standalone `SKILL.md` with triggers, examples, and version-pinned code.
46
47- SDK (Python + TS, Platform + OSS): https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md
48- CLI: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-cli/SKILL.md
49- Vercel AI SDK: https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md
50- Portable editor/MCP plugin: https://github.com/mem0ai/mem0/tree/main/integrations/mem0-agent-plugin
51
52### SDK source (read when docs are ambiguous)
53Public repo. Cross-check against the `mem0_tested_versions` range in this
54skill's frontmatter if the `main` branch has moved past a major.
55
56- Repo root: https://github.com/mem0ai/mem0
57- Python SDK: https://github.com/mem0ai/mem0/tree/main/mem0
58- TypeScript SDK: https://github.com/mem0ai/mem0/tree/main/mem0-ts
59
60### Quickstarts (for bootstrapping unfamiliar stacks)
61- Platform: https://docs.mem0.ai/platform/quickstart
62- OSS Python: https://docs.mem0.ai/open-source/python-quickstart
63- OSS Node: https://docs.mem0.ai/open-source/node-quickstart
64- Platform vs OSS comparison: https://docs.mem0.ai/platform/platform-vs-oss
65
66## Integration principles (non-negotiable)
67
68The true goal of this skill is to produce a **PR the maintainers can accept
69without argument**. That rules out anything invasive.
70
711. **Additive, not replacing.** If the target repo already has a memory
72 system, a session store, a user-context layer, or anything named
73 `Memory` / `memory_*`, Mem0 sits **alongside** it, not in place of it.
74 The existing system keeps working unchanged.
752. **Opt-in by default.** Gate all new Mem0 code behind a feature flag
76 (env var like `MEM0_ENABLED=1`, a config key, or a strategy selector).
77 With the flag unset, behavior is the repo's original behavior,
78 byte-for-byte.
793. **No breakage.** No removed exports, no renamed public functions,
80 no changed method signatures, no modified existing tests, no changed
81 behavior of existing tests. All pre-existing tests must pass unchanged
82 both with the flag set and unset.
834. **Minimal dependency surface.** Add `mem0ai` (plus any deps the
84 delegated skill requires) and nothing else. No new vector stores, no
85 graph databases, no provider SDKs the repo does not already use.
865. **Separable commits.** Code, tests, and config/docs land in separate
87 commits so reviewers can cherry-pick.
886. **The null hypothesis wins.** If no additive, gated fit exists after
89 step 6 (plan), exit with code 1 and a rationale. A bad PR is worse
90 than no PR.
917. **Backend only.** Mem0 integration lives in server-side code. API keys,
92 memory scope, and user-identity resolution are not safe client-side.
93 If the repo has both backend and frontend, the call sites live in
94 backend files. Frontend-only repos are rejected at preconditions.
95
96Enforced at four gates: **preconditions** (reject frontend-only repos
97and repos where additive fit is impossible), **step 2 comprehension**
98(confirm a backend exists and name candidate surfaces), **step 6 plan
99review** (reject plans that mutate existing exports or name client-side
100call sites), and **step 10 self-healing loop** (refuse to "fix" principle
101violations — surface them instead).
102
103## Skill delegation rules
104
105Before writing any code, check whether a published skill already covers
106the target stack. If yes, delegate — copy its call-site pattern into
107`plan.md` and into the tests; do not paraphrase.
108
109| Detected in target repo | Delegate to | Why |
110|---|---|---|
111| `@ai-sdk/*` + `ai` in `package.json` | `skills/mem0-vercel-ai-sdk` | Integration is via `createMem0` provider wrapper, not raw `MemoryClient`. |
112| 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. |
113| 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. |
114| Any other Python or TS repo with an LLM call site | `skills/mem0` | Default SDK integration path. |
115
116Record the delegated skill's raw URL in `plan.md` under a
117**"Delegated skill:"** field. The test writer in step 7 and the
118implementation subagent in step 8 both read this field.
119
120## Preconditions
121
122Refuse to start unless ALL of the following are true:
123
124- Current working directory is inside a git repository with a clean index
125 (no uncommitted changes). Protects the user's work — every edit lands on
126 a feature branch, not on top of in-progress changes.
127- Repo has a detectable language (`package.json` / `pyproject.toml` /
128 `requirements.txt`). No language → exit cleanly with a written rationale.
129- Repo has a **backend**. Detected by: a `backend/` or `server/` or `api/`
130 directory; a Python package with FastAPI/Flask/Django/Starlette; a Node
131 package with Express/Fastify/Koa/NestJS/Next-API-routes; an agent-loop
132 framework (LangGraph, LangChain, LlamaIndex, Agno). Frontend-only repos
133 (pure React/Vue/Svelte SPAs, static sites, mobile-only) → exit with
134 code 1 and a rationale. Mem0 is not installed client-side.
135- The user has already decided Mem0 fits this repo. This skill does NOT
136 survey the codebase to justify fit — bring a concrete goal. (Step 2
137 *does* read the repo to understand what it does and locate backend
138 integration surfaces; that is mechanics, not fit-justification.)
139
140Exit with a written rationale if any precondition fails. Do not try to
141"make it work anyway."
142
143## Pipeline
144
145Ten steps. Full mechanics, document templates, and gate rules are in
146[`references/pipeline.md`](references/pipeline.md). Read that file when you
147start executing a step; the summary below is only for routing.
148
149| # | Step | Gate |
150|---|---|---|
151| 1 | **Language detection.** `package.json` / `pyproject.toml` / `requirements.txt`. Monorepo, ask which subdirectory. | |
152| 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. |
153| 3 | **Product selection.** Platform vs OSS, recommended from dependency signals, never asked blank. | Locked into `goal.md`, never re-decided. |
154| 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. |
155| 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. |
156| 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. |
157| 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. |
158| 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. |
159| 9 | **Commit and handoff.** Branch `mem0-integrate/<slug>`, four separable commits: dependency, module, wiring, tests. | `--no-heal` stops here. |
160| 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. |
161
162## Artifacts (all under `.mem0-integration/`)
163
164| File | Purpose | Retention |
165|---|---|---|
166| `repo-summary.md` | Repo comprehension + candidate backend surfaces (step 2). | Keep across runs. |
167| `goal.md` | Approved intent. Never rewritten after step 6. | Keep across runs. |
168| `plan.md` | Approved mechanics (where, how, call sites, preserved behavior). | Keep across runs. |
169| `trace.jsonl` | Every tool call, decision, and subagent exchange this run. | Overwritten per run. |
170| `diff.patch` | The committed integration as a reviewable patch. | Overwritten per run. |
171| `heal-trace.md` | Per-attempt record of the self-healing loop (step 10). | Overwritten per run. |
172| `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. |
173
174`.mem0-integration/` is added to `.gitignore` on first run. Nothing is
175written outside this directory and the repo's source tree.
176
177## Modes
178
179| Mode | Trigger | Behavior |
180|---|---|---|
181| Interactive (default) | TTY present, `MEM0_INTEGRATE_CI` unset | Asks for keys, confirms goal doc, shows recommendations. |
182| CI | `MEM0_INTEGRATE_CI=1` | Requires keys in env, requires `--product`, auto-approves goal doc from `goal.md` if present, fails fast otherwise. |
183
184## Invocation
185
186 /mem0-integrate # interactive, heal ON
187 /mem0-integrate --no-heal # stop after commit; manual verify
188 /mem0-integrate --heal-max 5 # cap heal attempts per category (default 3)
189 /mem0-integrate --product platform # skip the product ask
190 /mem0-integrate --product oss
191 /mem0-integrate --ci # non-interactive (for test harness)
192
193## Exit codes
194
195| Code | Meaning |
196|---|---|
197| 0 | Success. Feature branch committed; verification skill ready to run. |
198| 1 | Precondition failed (dirty repo, no detectable language, etc.). |
199| 2 | Missing env key in CI mode. |
200| 3 | Goal doc rejected 3+ times — integration is not well-specified. |
201| 4 | Subagent review loop did not converge in 3 rounds. |
202| 5 | Integration plan rejected 3+ times, or no plausible additive call site found. |
203| 6 | Self-healing loop did not converge, detected a non-invasiveness violation, or a pre-existing test failed. |
204
205## Explicitly out of scope
206
207- Surveying the repo for fit points. Humans decide where Mem0 helps before
208 invoking this skill.
209- Replacing any existing memory / session / state system. Always additive
210 and feature-flagged; see "Integration principles."
211- Modifying pre-existing tests, even to "fix" them under self-heal. Tests
212 that fail after integration with the flag unset are a non-invasiveness
213 violation, not a bug to patch.
214- Deciding Platform vs OSS silently. Always ask with a recommendation.
215- Switching branches, pushing, or opening PRs. Commits locally and stops
216 (or enters the heal loop, still local).
217- Data migration between stores. Point user at `migration/oss-to-platform`
218 docs if they ask.
219- Provider selection beyond the default LLM for OSS. If they need a custom
220 LLM / embedder / vector store, route to `components/*` docs and re-run
221 step 4 with the new key.