Skip to content

armgit / mem0

Public Imported from GitHub
0

The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.

feat(skills): add mem0-integrate + mem0-test-integration pipeline skills (#4961)

Saket Aryan0fdaa29b4a27
diff --git a/AGENTS.md b/AGENTS.md
index 1fe035342..52d8ffc1e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,7 +27,7 @@ This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs,
| `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + PostgreSQL/pgvector + Neo4j) |
| `openmemory/` | Self-hosted memory platform — `api/` (FastAPI + Alembic + MCP server) and `ui/` (Next.js 15 + React 19) |
| `mem0-plugin/` | AI editor plugins (Claude Code, Cursor, Codex) — MCP server connection, lifecycle hooks, skills |
-| `skills/` | Claude Code skill definitions — `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/` |
+| `skills/` | Claude Code skill definitions. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/` |
| `docs/` | Documentation site (Mintlify) |
| `tests/` | Python SDK tests (pytest) |
| `evaluation/` | Benchmarking framework — LOCOMO evals, experiment runner, score generation |
@@ -387,7 +387,9 @@ Model Context Protocol support in multiple places:
### Plugin & Skills System
- `mem0-plugin/` provides integrations for Claude Code, Cursor, and Codex via MCP server connections and lifecycle hooks for automatic memory capture.
-- `skills/` contains structured skill definitions for AI agents, covering SDK usage, CLI workflows, and Vercel AI SDK patterns.
+- `skills/` contains structured skill definitions for AI agents, split into two categories:
+ - **Reference skills** (always-on SDK knowledge): `mem0` (Python + TS SDKs, framework integrations), `mem0-cli` (terminal workflows), `mem0-vercel-ai-sdk` (Vercel AI provider).
+ - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch. The two are loosely coupled via `.mem0-integration/` artifacts.
### Adding a New Provider
diff --git a/README.md b/README.md
index 9eef64f7c..1dea670c0 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,27 @@ mem0 search "What does Alice prefer?" --user-id alice
See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full command reference.
+### Agent Skills
+
+Teach your AI coding assistant (Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw, and any tool that supports the skills standard) how to build with Mem0. Two categories:
+
+**Reference skills — always on** (SDK knowledge loaded into the assistant's context):
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk
+```
+
+**Pipeline skills — run on demand** (execute an end-to-end workflow in an existing repo):
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+```
+
+Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
+
### Basic Usage
Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
diff --git a/docs/vibecoding.mdx b/docs/vibecoding.mdx
index 07949f437..118f587ec 100644
--- a/docs/vibecoding.mdx
+++ b/docs/vibecoding.mdx
@@ -22,13 +22,35 @@ We follow the llms.txt standard:
## Agent Skills
-Teach your coding assistant how to build with Mem0:
+Mem0 ships two kinds of skills for AI coding assistants. Both work with Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw, and any assistant that supports the skills standard.
+
+### Reference skills — always on
+
+Teach your assistant Mem0's SDK surface so it writes correct code in everyday development:
```bash
npx skills add https://github.com/mem0ai/mem0 --skill mem0
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk
```
-Works with Claude Code, Cursor, Windsurf, and any assistant that supports skills. Once installed, your assistant understands Mem0's full API, framework integrations, and common patterns.
+- `mem0` — Python and TypeScript SDKs (Platform + OSS), plus framework integrations (LangChain, CrewAI, OpenAI Agents, LangGraph, LlamaIndex, etc.)
+- `mem0-cli` — terminal workflows for the `mem0` CLI (both Node and Python builds)
+- `mem0-vercel-ai-sdk` — `@mem0/vercel-ai-provider` and `createMem0`
+
+### Pipeline skills — run on demand
+
+Let your assistant execute an end-to-end workflow in an existing repo. Invoked as slash commands:
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+```
+
+- `/mem0-integrate` — wire Mem0 into an existing repository using a goal-driven, test-first pipeline. Detects the stack, asks whether to use Platform or OSS, writes failing tests first, and keeps the integration additive and feature-flagged.
+- `/mem0-test-integration` — verify what `/mem0-integrate` produced. Runs the repo's native test suite and a real end-to-end smoke flow against your API key, then produces a scorecard.
+
+See the [skills index](https://github.com/mem0ai/mem0/tree/main/skills) for the full catalog.
## MCP Server Setup
diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 000000000..c14b5cab2
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,49 @@
+# Mem0 Skills for AI Coding Assistants
+
+Mem0 ships structured skill definitions for Claude Code, Codex, Cursor, OpenCode, OpenClaw, and any assistant that supports the [skills standard](https://github.com/anthropic-experimental/skills). Skills teach the assistant how to work with Mem0 — either by loading SDK knowledge into context, or by executing an end-to-end workflow on demand.
+
+## Two Categories
+
+### Reference skills — always on
+
+Installed once, loaded into context so the assistant writes correct Mem0 code. Use these for day-to-day development.
+
+| Skill | Surface | Install |
+|-------|---------|---------|
+| [`mem0`](./mem0/) | Python + TypeScript SDKs (Platform + OSS), framework integrations | `npx skills add https://github.com/mem0ai/mem0 --skill mem0` |
+| [`mem0-cli`](./mem0-cli/) | Terminal workflows (`mem0` CLI, both Node and Python) | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli` |
+| [`mem0-vercel-ai-sdk`](./mem0-vercel-ai-sdk/) | `@mem0/vercel-ai-provider` and `createMem0` | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk` |
+
+### Pipeline skills — run on demand
+
+Invoked as a slash command to execute a specific end-to-end workflow. These do real work: they create branches, write tests, run code.
+
+| Skill | Trigger | Install |
+|-------|---------|---------|
+| [`mem0-integrate`](./mem0-integrate/) | `/mem0-integrate` — wire Mem0 into an existing repo via TDD | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate` |
+| [`mem0-test-integration`](./mem0-test-integration/) | `/mem0-test-integration` — verify what `/mem0-integrate` produced | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration` |
+
+The two pipeline skills are designed to run in sequence on the same workspace:
+
+```
+/mem0-integrate → mem0-integrate/<slug> branch + .mem0-integration/ artifacts
+/mem0-test-integration → scorecard (compile + runtime verification, real API smoke test)
+```
+
+## Choosing a Skill
+
+- **Writing Mem0 code in a new or existing project?** → `mem0`
+- **Using the terminal CLI?** → `mem0-cli`
+- **Building with `@ai-sdk/*`?** → `mem0-vercel-ai-sdk`
+- **Want the assistant to wire Mem0 into an existing repo for you?** → `mem0-integrate`, then `mem0-test-integration`
+
+## Links
+
+- [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) — canonical landing page
+- [Claude Code integration](https://docs.mem0.ai/integrations/claude-code)
+- [Mem0 Platform Dashboard](https://app.mem0.ai)
+- [Mem0 Documentation](https://docs.mem0.ai)
+
+## License
+
+Apache-2.0
diff --git a/skills/mem0-integrate/LICENSE b/skills/mem0-integrate/LICENSE
new file mode 100644
index 000000000..78c99ae28
--- /dev/null
+++ b/skills/mem0-integrate/LICENSE
@@ -0,0 +1,189 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but not
+ limited to compiled object code, generated documentation, and
+ conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work.
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to the Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by the Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding any notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ Copyright 2024 Mem0.ai
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/skills/mem0-integrate/README.md b/skills/mem0-integrate/README.md
new file mode 100644
index 000000000..3c8e47478
--- /dev/null
+++ b/skills/mem0-integrate/README.md
@@ -0,0 +1,89 @@
+# mem0-integrate — Pipeline Skill
+
+Wire [Mem0](https://mem0.ai) into an existing repository end-to-end, using a goal-driven, test-first pipeline.
+
+> **This is a pipeline skill, not a reference skill.** Invoke it as `/mem0-integrate` when you want your assistant to do the work of integrating Mem0 into a target repo. For day-to-day SDK coding help, install [`mem0`](../mem0/SKILL.md) instead.
+>
+> **Part of the Mem0 Skill Graph:**
+> - Reference: [mem0](../mem0/SKILL.md) · [mem0-cli](../mem0-cli/SKILL.md) · [mem0-vercel-ai-sdk](../mem0-vercel-ai-sdk/SKILL.md)
+> - Pipeline: **mem0-integrate** (this skill) → [mem0-test-integration](../mem0-test-integration/SKILL.md)
+
+## What This Skill Does
+
+When invoked, your assistant will:
+
+- **Detect** the target repo's language and stack automatically
+- **Ask** whether to integrate with Mem0 Platform (managed) or Mem0 Open Source (self-hosted)
+- **Write failing tests first** — no implementation until tests exist
+- **Keep the integration additive and feature-flagged** — existing behavior stays byte-for-byte identical when the flag is unset
+- **Produce a local feature branch** (`mem0-integrate/...`) and a `.mem0-integration/` directory of artifacts (`goal.md`, `plan.md`, `product.json`) consumed by the companion verification skill
+
+## When to Use
+
+Trigger phrases:
+
+- "Integrate Mem0 into this repo"
+- "Add Mem0 to my project"
+- "Wire Mem0 into `<repo>`"
+- "How do I add memory to an existing project?"
+
+Do **not** use this skill for general SDK usage (install [`mem0`](../mem0/SKILL.md)), terminal workflows (install [`mem0-cli`](../mem0-cli/SKILL.md)), or Vercel AI SDK integration (install [`mem0-vercel-ai-sdk`](../mem0-vercel-ai-sdk/SKILL.md)).
+
+## Installation
+
+### CLI (Claude Code, Codex, OpenCode, OpenClaw, or any tool that supports skills)
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+```
+
+For verification on the same branch, also install the companion skill:
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+```
+
+### Claude.ai
+
+1. Download this `skills/mem0-integrate` folder as a ZIP
+2. Go to **Settings > Capabilities > Skills**
+3. Click **Upload skill** and select the ZIP
+
+### Claude API (Skills API)
+
+```bash
+curl -X POST https://api.anthropic.com/v1/skills \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"name": "mem0-integrate", "source": "https://github.com/mem0ai/mem0/tree/main/skills/mem0-integrate"}'
+```
+
+### Prerequisites
+
+- A Mem0 Platform API key ([get one](https://app.mem0.ai/dashboard/api-keys)) *or* a working OSS setup (LLM + vector store)
+- Python 3.10+ or Node.js 18+ in the target repo
+- A clean working tree on the target repo's default branch
+
+## Workflow
+
+```
+/mem0-integrate → creates mem0-integrate/<slug> branch,
+ writes .mem0-integration/ artifacts,
+ implements against failing tests
+/mem0-test-integration → runs the repo's native test suite,
+ executes a real end-to-end smoke flow,
+ produces a scorecard
+```
+
+The two skills are loosely coupled — they share the same workspace and branch via `.mem0-integration/`, but the verifier never modifies source.
+
+## Links
+
+- [Mem0 Platform Dashboard](https://app.mem0.ai)
+- [Mem0 Documentation](https://docs.mem0.ai)
+- [Mem0 GitHub](https://github.com/mem0ai/mem0)
+- [Platform vs OSS comparison](https://docs.mem0.ai/platform/platform-vs-oss)
+
+## License
+
+Apache-2.0
diff --git a/skills/mem0-integrate/SKILL.md b/skills/mem0-integrate/SKILL.md
new file mode 100644
index 000000000..8230a63b3
--- /dev/null
+++ b/skills/mem0-integrate/SKILL.md
@@ -0,0 +1,620 @@
+---
+name: mem0-integrate
+description: >
+ Integrate Mem0 into an existing repository using a goal-driven, TDD pipeline.
+ Detects the repo's language automatically and asks the user to pick between
+ Mem0 Platform (managed) and Mem0 Open Source (self-hosted). Writes failing
+ tests before any implementation. Produces a local feature branch plus
+ `.mem0-integration/` artifacts consumed by the paired verification skill.
+ TRIGGER when: user says "integrate mem0", "add mem0 to this repo", "wire
+ mem0 into <repo>", or asks how to add memory to an existing project.
+ DO NOT TRIGGER when: the user wants general SDK usage (use skill:mem0),
+ CLI usage (use skill:mem0-cli), or Vercel AI SDK (use skill:mem0-vercel-ai-sdk).
+ After success, invoke skill:mem0-test-integration to verify in the same
+ workspace (loose coupling).
+license: Apache-2.0
+metadata:
+ author: mem0ai
+ version: "0.1.0"
+ category: ai-memory
+ tags: "memory, integration, tdd, platform, oss"
+ mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"
+---
+
+# 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 / orchestration: <LangGraph? custom? none?>
+ - Existing memory/session/state systems: <name them — these are
+ what step 6 Coexistence must preserve>
+
+ **Candidate backend integration surfaces** (ranked, best first):
+ 1. `<backend-file>:<line_range>` — <function> — <one-sentence
+ reason this is where write/read could slot in without
+ replacing anything existing>
+ 2. ...
+ 3. ...
+
+ **Not a fit here:** <list anything the skill considered but ruled
+ out — e.g., "frontend chat component: client-side, excluded by
+ backend-only rule"; "existing memory subsystem X: would require
+ replacement, excluded by additive principle">
+
+ **Sources read:** <list the files actually opened, with line counts,
+ so reviewers can verify coverage.>
+
+Show the user the rendered summary and ask: *"Is this understanding
+correct? Which of the candidate surfaces (1, 2, 3 ...) should step 3
+forward target?"*
+
+Gate rules:
+
+- If no backend surface is found → exit code 1. The preconditions
+ should already have caught frontend-only repos; reaching this point
+ means a more subtle miss (e.g., the "backend" is actually just a
+ static build). Do not force a fit.
+- If every candidate surface would require replacing an existing
+ memory/session system → exit code 1 with the "additive principle"
+ rationale. The user can manually point at a non-conflicting location
+ and re-run.
+- User corrections update `repo-summary.md` and re-confirm. Max 3
+ rounds; beyond that, exit code 1.
+
+The user's chosen surface index is baked into `product.json` as
+`preferred_site` and referenced by steps 5 and 6.
+
+### 3. Product selection — Platform vs OSS (ask with a recommendation)
+
+Read the `## Identify the User's Setup` block in
+`https://docs.mem0.ai/llms.txt` for the Platform-first routing rules, then
+apply the heuristics below. Ask, but never blank:
+
+- Other managed-service SDKs present (`@clerk/*`, `stripe`, `@supabase/*`,
+ `openai`, `@upstash/*`, `posthog-*`) — 3+ → recommend **Platform**.
+- Local-infra signals (`docker-compose.yml` with postgres / redis / qdrant /
+ neo4j, ollama configs, self-hosted auth) — 2+ → recommend **OSS**.
+- No strong signal → default recommendation: **Platform** (lower integration
+ cost; migration later is supported).
+
+Example:
+
+> I see `stripe`, `@clerk/nextjs`, and `@supabase/supabase-js` — managed
+> services throughout. I recommend **Mem0 Platform** (4-line integration).
+> Override and use open source?
+
+Bake the choice into the goal doc in step 5. Do not re-decide later.
+
+### 4. API key check (env-first, then ask)
+
+| Track | Key | Where to find |
+|---|---|---|
+| Platform | `MEM0_API_KEY` | https://app.mem0.ai |
+| OSS (default LLM) | `OPENAI_API_KEY` | https://platform.openai.com/api-keys |
+
+If present in env → continue.
+If missing → **interactive mode** asks; **CI mode** (`MEM0_INTEGRATE_CI=1`)
+exits with code 2 and the name of the missing key.
+
+Never echo key values into `trace.jsonl`. Persist to `.env` only with
+explicit user consent, and append `.env` to `.gitignore` if not already there.
+
+If the user is on OSS and wants a non-OpenAI LLM, route them to the
+`components/llms/*` docs and re-run this step with the chosen provider's key.
+
+### 5. Goal doc — the hard gate
+
+Write `.mem0-integration/goal.md` and **require user approval before step 6**.
+
+Template:
+
+ # Mem0 Integration Goal
+
+ **What gets stored:** <one sentence — user utterances? extracted
+ preferences? a specific domain fact like "dietary restrictions"?>
+
+ **When it gets retrieved:** <one sentence — on each user turn? before a
+ specific tool call? at session start?>
+
+ **Why:** <one sentence — the user-visible behavior change. "Assistant
+ remembers previous orders across sessions," not "we added memory.">
+
+ **Product:** Platform | OSS (locked from step 3, do not change)
+
+ **Delegated skill:** <raw URL of the published skill being used
+ from "Skill delegation rules" above, or "none — custom integration
+ against `skills/mem0`">.
+
+ **Out of scope:** <anything explicitly excluded: "no graph memory,"
+ "no multimodal," "no migration from existing store">
+
+Rules:
+
+- User must approve explicitly. If they edit the doc, reload and re-confirm.
+- `goal.md` is the contract the test suite is written against. Never
+ rewrite it after step 6 starts.
+- Max 3 rejection rounds. On the 4th, exit with code 3 and the rejection
+ notes — the integration is not well-specified enough to proceed.
+
+### 6. Integration plan — how and where (hard gate)
+
+Given `goal.md` is "what and why," this step produces "where and how" and
+gets explicit user sign-off before any code is written.
+
+The skill does a **scoped** read of the repo (no wide survey):
+
+- Grep for the LLM call sites that match the goal (e.g., `openai.chat.`,
+ `anthropic.messages.`, `model.generateContent`, `ChatOpenAI`, `createLLM`).
+- Grep for the user-identity source (`req.user`, `session.user`, `auth()`,
+ `ctx.userId`, cookies).
+- Check `package.json` / `pyproject.toml` / `requirements.txt` for
+ conflicts (e.g., existing `mem0ai` at a different version).
+
+Then write `.mem0-integration/plan.md`:
+
+ # Mem0 Integration Plan
+
+ **Write pattern:** <one sentence — e.g., "After each assistant reply,
+ call client.add([user_msg, assistant_msg], user_id=<source>).">
+
+ **Read pattern:** <one sentence — e.g., "Before building the LLM prompt,
+ call client.search(query=latest_user_msg, user_id=<source>, limit=5)
+ and inject results as a system message.">
+
+ **User identifier source:** <code path — e.g., `req.auth.userId`,
+ `session.user.email`, `ctx.params.user_id`. If none, ask the user.>
+
+ **Session scoping:**
+ - user_id: <source>
+ - agent_id: <static slug | null>
+ - run_id: <source | null>
+
+ **Write call site:** `<file:line_range>` — inside `<function>`
+ **Read call site:** `<file:line_range>` — inside `<function>`
+
+ **Dependencies to add:**
+ - `<package>@<version pinned in frontmatter>`
+
+ **Preserved behavior:** <list the existing repo behaviors that must
+ keep working after this edit — e.g., "existing OpenAI streaming still
+ works," "existing Redis session store still used," "existing tests
+ still pass unchanged.">
+
+ **Coexistence:** <one bullet per existing system the integration sits
+ alongside. Name the files/classes. Example: "The existing
+ `agents/memory/storage.py` MemoryStorage class remains untouched and
+ keeps its LangGraph SummarizationEvent flow. Mem0 is added as a
+ parallel long-term-facts store, in a new file, invoked only when
+ MEM0_ENABLED=1 is set.">
+
+ **Feature flag:** <the exact mechanism and the default. Required.
+ Example: `env MEM0_ENABLED=1`, default unset / off; `config.mem0.enabled`,
+ default false. With the flag in its default state, the repo must
+ behave exactly like `main`.>
+
+ **Sources consulted:** <minimum 2 URLs from "Canonical sources" above
+ that informed this plan. At least one `docs.mem0.ai` URL and one
+ delegated-skill URL. Cite the specific section or heading.>
+
+ **E2E recipe:** <how the verification skill should drive the app
+ end-to-end. Omit only if the repo is a pure library with no runnable
+ entry point — in which case the E2E step will skip with a warning.>
+
+ start: <shell command to launch the app locally,
+ using $PORT for any network port>
+ ready_probe: <one of: url=<URL> status=<code> /
+ log="<substring to wait for>" /
+ sleep=<seconds, last resort>>
+ compose_services: <optional: whitespace-separated service
+ names in docker-compose.yml to start first;
+ use label mem0-e2e: "true" to mark them>
+ write_call: <command that triggers the Mem0 write path
+ exactly once; ≤ 60s runtime>
+ write_async_wait_ms: <milliseconds to wait after write_call for
+ async memory flush; default 0>
+ read_call: <command that triggers the Mem0 read path,
+ typically a fresh session / new request>
+ read_assert: <substring, regex, or jsonpath=<expr>=<value>
+ that MUST appear in read_call's output for
+ the E2E to pass. Derived from goal.md's
+ "What gets stored.">
+
+ **Rejected alternatives:** <briefly, 1–2 bullets — patterns the skill
+ considered but did not pick, and why. Helps the user decide.>
+
+Rules:
+
+- Show the user the proposed call sites with 10 lines of context around
+ each before asking for approval.
+- If the skill can't find a plausible call site for either write or read,
+ it exits with code 5 and asks the user to name the file(s) manually
+ (this is the "no fit here" signal — don't guess).
+- Max 3 rejection rounds on the plan. On the 4th, exit code 5 with the
+ last plan and the user's notes.
+- If the user edits `plan.md` by hand, reload and re-confirm.
+
+`plan.md` (not `goal.md`) is the contract the subagent implements against
+in step 8.
+
+### 7. Tests first (TDD)
+
+Main agent writes failing tests against `goal.md` in the repo's native
+test framework:
+
+| Track | Default framework |
+|---|---|
+| Python | `pytest` |
+| TypeScript | `vitest` if detected, else `jest` |
+| JavaScript | same |
+
+Test assertion shapes must match the **canonical signatures**:
+
+- Platform method signatures: `https://docs.mem0.ai/openapi.json`
+ (request body schemas for `/v1/memories/` and `/v1/memories/search/`).
+- OSS method signatures: the delegated skill named in `plan.md`
+ (fetched from its raw URL) or `skills/mem0/SKILL.md` as the default.
+- Do not hand-roll request shapes. If the delegated skill has an
+ example block, lift it verbatim.
+
+Minimum two test files (paths taken from `plan.md` call sites):
+
+- `test_mem0_write.<ext>` — asserts `add()` is called at the Write call
+ site with the right payload shape (Platform messages-array vs OSS string)
+ and the right `user_id` source.
+- `test_mem0_read.<ext>` — asserts `search()` runs before the Read call
+ site and the result is wired into the LLM prompt / response path.
+
+Tests MUST be importable with `MEM0_API_KEY` unset. This is the design
+pressure that forces step 8's lazy `MemoryClient()` / `Memory()`
+construction — eager module-level init hits the API on import and
+breaks pre-existing test collection when the key is missing.
+
+Run the tests. They **must fail**. If they pass before any implementation,
+the tests are wrong — rewrite them.
+
+### 8. Implementation (subagent, fresh context)
+
+Spawn a subagent with:
+
+- **Inputs**: the repo, `goal.md`, `plan.md`, the two test files, and
+ direct URLs to: the delegated skill (from `plan.md`), the SDK source
+ (pinned per `mem0_tested_versions`), `https://docs.mem0.ai/llms.txt`,
+ and `https://docs.mem0.ai/openapi.json`.
+- **No access** to main agent's reasoning trace or scratchpad.
+- **System prompt** (verbatim):
+
+ You are implementing a Mem0 integration for an existing repo.
+
+ Read these first:
+ - plan.md (the mechanical contract)
+ - goal.md (the intent — do not change it)
+ - the test files (do not change them either)
+ - <delegated skill raw URL from plan.md>
+ - https://docs.mem0.ai/llms.txt
+ - https://docs.mem0.ai/openapi.json (Platform only)
+
+ Constraints — all required, all enforced at review:
+
+ 1. Touch only the files named in plan.md's call sites, or add
+ strictly new files.
+ 2. Do not remove or rename any existing symbol. Do not change
+ any public signature.
+ 3. Do not modify any existing test.
+ 4. Gate every line of new Mem0 code behind the feature flag from
+ plan.md. With the flag in its default state, the repo must
+ behave exactly like `main` — byte-for-byte, including stdout
+ and return values.
+ 5. Use only the <Platform | OSS> SDK surface. No new dependencies
+ beyond those listed under plan.md's "Dependencies to add."
+ 6. Preserve everything listed under plan.md's "Preserved behavior"
+ and "Coexistence."
+ 7. Lazy client construction. `MemoryClient()` validates the API
+ key in `__init__` (it makes a network call). Never instantiate
+ it at module-import time — construct on first use inside the
+ request / handler path. The same rule applies to OSS `Memory()`,
+ which can eagerly initialize embedding and LLM providers. Use
+ a function-local singleton (`functools.lru_cache`, a module-level
+ `_client = None` + getter, or DI scope) — never a top-level
+ global. Eager init breaks the pre-existing test suite at
+ collection time whenever the key is missing or invalid, which
+ is a non-invasiveness violation.
+
+ Implement the plan to make the new tests pass while all
+ pre-existing tests continue to pass unchanged.
+
+Subagent returns a diff. Main agent reviews against `plan.md` (the
+mechanical contract) and `goal.md` (the intent):
+
+- Approved → apply the diff, commit.
+- Rejected → return with specific, actionable feedback (not "try again").
+- Max 3 review loops. Beyond that → exit code 4 with the last diff and
+ reviewer feedback.
+
+### 9. Commit + handoff
+
+Create branch `mem0-integrate/<short-goal-slug>` and commit in
+**separate commits** so reviewers can cherry-pick:
+
+1. `mem0: add gated dependency` — just the `pyproject.toml` / `package.json`
+ change.
+2. `mem0: add integration module` — the new file(s).
+3. `mem0: wire into <call site>` — the call-site edit(s), still gated.
+4. `mem0: add tests` — the new test files.
+
+If `--no-heal` is set → print `Run /mem0-test-integration to verify.`
+and exit. Otherwise proceed to step 10.
+
+### 10. Self-healing loop (default ON; disable with `--no-heal`)
+
+Run `/mem0-test-integration --ci` in a subprocess. If `scorecard.json`
+reports `overall: pass` → done, exit 0.
+
+Otherwise loop:
+
+1. **Categorize the failing check** from `scorecard.json`. Route per
+ category:
+ - `install` / `static_checks` → dependency or import fix.
+ - `unit_tests` → wiring or assertion fix.
+ - `smoke_test` → API key or SDK call-shape fix.
+ - `e2e_test` → recipe, flag-wiring, or integration-point fix.
+ - **Pre-existing test failure (test skill exit code 7,
+ `non_invasive: false` in scorecard) → STOP.** This is a
+ non-invasiveness violation. Do NOT attempt to "fix" it (that
+ breaks principle 3). Exit code 6 with rationale.
+
+2. **Spawn a remediation subagent**, fresh context. Inputs:
+ `plan.md`, `goal.md`, `scorecard.md`, `scorecard.json`, the last
+ committed diff, and the relevant log file for the failing category
+ (`test-stdout.log` / `smoke-stdout.log` / `e2e-app.log` /
+ `e2e-calls.log`).
+
+ System prompt (verbatim):
+
+ You are fixing a failing Mem0 integration test.
+
+ Non-negotiable constraints:
+ - Do not modify test files.
+ - Do not remove or rename any existing symbol or signature.
+ - Do not change pre-existing behavior. The feature flag from
+ plan.md must still default to OFF, and with the flag in its
+ default state the repo must behave exactly like main.
+ - Touch only the files named in plan.md's call sites, or add
+ strictly new files.
+ - Return the smallest possible diff that fixes the single
+ failing check listed in scorecard.md. No drive-by cleanup.
+
+3. **Apply the diff**; commit on the same branch with message
+ `mem0-heal: <category> attempt <N>`. Do NOT amend earlier commits
+ (reviewers need the heal trail).
+
+4. **Re-run `/mem0-test-integration --ci`**. Outcomes:
+ - `overall: pass` → done, exit 0.
+ - Same check still failing → increment attempt counter; loop.
+ - A *different* check now failing → regression. Revert the heal
+ commit (`git revert HEAD --no-edit`), record the regression in
+ `.mem0-integration/heal-trace.md`, exit code 6.
+
+5. **Bounded iterations.** Default 3 attempts per failing category.
+ Override with `--heal-max N` (hard cap 10). On exhaustion, exit 6
+ with the full attempt trace: each diff, each scorecard, final log
+ tail.
+
+6. **Post-loop summary** written to `.mem0-integration/heal-trace.md`:
+ which category failed, how many attempts, each diff's intent, final
+ status, and — on success — the delta from initial scorecard to final.
+
+## 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.
diff --git a/skills/mem0-test-integration/LICENSE b/skills/mem0-test-integration/LICENSE
new file mode 100644
index 000000000..78c99ae28
--- /dev/null
+++ b/skills/mem0-test-integration/LICENSE
@@ -0,0 +1,189 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but not
+ limited to compiled object code, generated documentation, and
+ conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work.
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to the Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by the Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding any notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ Copyright 2024 Mem0.ai
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/skills/mem0-test-integration/README.md b/skills/mem0-test-integration/README.md
new file mode 100644
index 000000000..da905006c
--- /dev/null
+++ b/skills/mem0-test-integration/README.md
@@ -0,0 +1,81 @@
+# mem0-test-integration — Pipeline Skill
+
+Verify a Mem0 integration produced by [`/mem0-integrate`](../mem0-integrate/SKILL.md). Runs in the same workspace on the same branch — installs dependencies, runs the repo's native test suite, then exercises a real end-to-end smoke flow against the user's API key.
+
+> **This is a pipeline skill, not a reference skill.** Invoke it as `/mem0-test-integration` after `/mem0-integrate` has produced a branch to verify. It catches compile and runtime bugs by design — logical integration errors (wrong data stored, wrong scoping) are for human review.
+>
+> **Part of the Mem0 Skill Graph:**
+> - Reference: [mem0](../mem0/SKILL.md) · [mem0-cli](../mem0-cli/SKILL.md) · [mem0-vercel-ai-sdk](../mem0-vercel-ai-sdk/SKILL.md)
+> - Pipeline: [mem0-integrate](../mem0-integrate/SKILL.md) → **mem0-test-integration** (this skill)
+
+## What This Skill Does
+
+When invoked, your assistant will:
+
+- **Refuse to start** unless the branch has `.mem0-integration/` artifacts, the working tree is clean, and the right API key is in the environment
+- **Install** the repo's dependencies using its native tooling (pip, pnpm, npm, hatch, etc.)
+- **Run the native test suite** in two passes: flag-unset (must behave like `main`) and flag-set (new tests run)
+- **Execute a real end-to-end smoke flow** against Mem0 Platform (`MEM0_API_KEY`) or OSS (`OPENAI_API_KEY`)
+- **Produce a scorecard** — `overall: pass | fail`, per-check reasons, and the reproduction command for each failure
+
+## When to Use
+
+Trigger phrases:
+
+- "Verify the integration"
+- "Test the Mem0 integration"
+- "Run `/mem0-test-integration`"
+
+Do **not** use this skill to run general project tests (defer to the repo's native test command) or before `/mem0-integrate` has produced a branch on the current workspace.
+
+## Installation
+
+### CLI (Claude Code, Codex, OpenCode, OpenClaw, or any tool that supports skills)
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+```
+
+Typically installed alongside the companion pipeline skill:
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+```
+
+### Claude.ai
+
+1. Download this `skills/mem0-test-integration` folder as a ZIP
+2. Go to **Settings > Capabilities > Skills**
+3. Click **Upload skill** and select the ZIP
+
+### Claude API (Skills API)
+
+```bash
+curl -X POST https://api.anthropic.com/v1/skills \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"name": "mem0-test-integration", "source": "https://github.com/mem0ai/mem0/tree/main/skills/mem0-test-integration"}'
+```
+
+### Preconditions
+
+The skill refuses to start unless all of the following are true:
+
+- `.mem0-integration/` directory exists in the repo root
+- Current branch starts with `mem0-integrate/`
+- Working tree is clean
+- The same API key used during `/mem0-integrate` is exported in the environment
+
+## What This Skill Does *Not* Catch
+
+By design, this skill only catches compile and runtime bugs. Logical errors — memories stored with the wrong scoping, retrieval returning the wrong user's data, filter mismatches — are the human reviewer's responsibility.
+
+## Links
+
+- [Mem0 Documentation](https://docs.mem0.ai)
+- [Mem0 GitHub](https://github.com/mem0ai/mem0)
+- [API Reference](https://docs.mem0.ai/api-reference)
+
+## License
+
+Apache-2.0
diff --git a/skills/mem0-test-integration/SKILL.md b/skills/mem0-test-integration/SKILL.md
new file mode 100644
index 000000000..773d0dd26
--- /dev/null
+++ b/skills/mem0-test-integration/SKILL.md
@@ -0,0 +1,368 @@
+---
+name: mem0-test-integration
+description: >
+ Verify a Mem0 integration produced by /mem0-integrate. Runs in the same
+ workspace on the same branch (loose coupling) — installs dependencies,
+ runs the repo's native test suite, then exercises a real end-to-end
+ smoke flow against the user's API key. Produces a scorecard.
+ TRIGGER when: user has just run /mem0-integrate and says "verify",
+ "test the integration", "run /mem0-test-integration", or when a
+ .mem0-integration/ directory exists and tests have not been run yet
+ on the current branch.
+ DO NOT TRIGGER when: the user wants to run general project tests
+ (defer to the repo's native test command), or when no prior /mem0-integrate
+ run exists in the current branch (ask them to run /mem0-integrate first).
+ This skill ONLY catches compile and runtime bugs by design. Logical
+ integration errors — wrong data stored, wrong time retrieved, wrong
+ user scoping — are on the human reviewer.
+license: Apache-2.0
+metadata:
+ author: mem0ai
+ version: "0.1.0"
+ category: ai-memory
+ tags: "memory, integration, testing, tdd, platform, oss"
+ coupling: loose
+ mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"
+---
+
+# mem0-test-integration
+
+Verifies what `/mem0-integrate` produced. Runs in the same workspace,
+on the same feature branch. Loose coupling — fast, catches compile and
+runtime bugs, does not catch logical errors.
+
+## Canonical sources (use these, not ambient knowledge)
+
+All static checks and smoke-test shapes validate against these URLs.
+`WebFetch` each before running step 3.
+
+- Scope-tagged docs index: https://docs.mem0.ai/llms.txt
+- OpenAPI (Platform REST): https://docs.mem0.ai/openapi.json
+- Published SDK skill (canonical call patterns): https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md
+- Vercel AI SDK skill (if the target repo uses `@ai-sdk/*`): https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md
+- SDK source (cross-check version against frontmatter `mem0_tested_versions`):
+ - Repo root: https://github.com/mem0ai/mem0
+ - Python: https://github.com/mem0ai/mem0/tree/main/mem0
+ - TypeScript: https://github.com/mem0ai/mem0/tree/main/mem0-ts
+
+Read the `Delegated skill:` field in `.mem0-integration/plan.md` — if it
+names a skill URL, fetch that skill and use its example blocks as the
+reference for both static checks (step 3) and the smoke test (step 5).
+
+## Non-invasiveness contract
+
+Every check in this skill assumes the integration is **additive and
+feature-flagged** (see `/mem0-integrate` "Integration principles").
+Specifically:
+
+- `product.json` must contain a `feature_flag` field.
+- Steps 4–6 run in two passes:
+ - **Pass A — flag unset.** All pre-existing tests must pass, smoke/E2E
+ skip. The repo must behave like `main`. Any failure here is a
+ **hard fail** — do not let the self-heal loop attempt a patch.
+ - **Pass B — flag set.** New tests must pass, smoke and E2E run.
+- If Pass A fails, the scorecard marks `non_invasive: false` and sets
+ `overall: fail` with a distinct reason code the integrator's heal
+ loop refuses to touch.
+
+## Preconditions
+
+Refuse to start unless ALL of the following are true:
+
+- `.mem0-integration/` directory exists in the repo root.
+- `.mem0-integration/product.json`, `goal.md`, and `plan.md` are readable
+ and internally consistent (JSON parses, docs non-empty).
+- Current branch name begins with `mem0-integrate/` (set by the companion
+ skill). Prevents accidental runs on unrelated branches.
+- Working tree is clean. The skill never modifies source files; any dirty
+ state means the integration is mid-edit and not ready to verify.
+- The same API key the integration used is available in the environment
+ (`MEM0_API_KEY` for Platform, `OPENAI_API_KEY` for OSS — read which from
+ `product.json`). Interactive mode asks if missing; CI mode exits 2.
+
+Exit with a written rationale on any precondition failure. Never attempt
+to "fix up" state.
+
+## Pipeline
+
+### 1. Read the contract
+
+Load:
+
+- `product.json` → which language, which product (Platform vs OSS), which
+ mem0 version, `write_site`, `read_site`.
+- `plan.md` → the mechanical contract (write pattern, read pattern,
+ preserved behavior).
+- `goal.md` → the intent (displayed in the scorecard only; not tested).
+
+### 2. Install dependencies
+
+Route by language from `product.json`:
+
+| Language | Command |
+|---|---|
+| Python | `pip install -e .` if editable, else `pip install -r requirements.txt`. Then `pip install mem0ai` if not already present at the pinned version. |
+| TypeScript / JavaScript | `npm install` (or `pnpm install` / `yarn install` if detected by lockfile). |
+
+If install fails → exit code 2 with stderr tail. Never move to testing
+if dependencies don't resolve.
+
+### 3. Static sanity checks (fast, local, no API calls)
+
+- **Import check**: does the write-site file import the expected Mem0
+ surface? Authoritative list comes from `## Identify the User's Setup`
+ in `https://docs.mem0.ai/llms.txt`:
+ - Platform Python → `from mem0 import MemoryClient`
+ - Platform TS → `import MemoryClient from "mem0ai"`
+ - OSS Python → `from mem0 import Memory`
+ - OSS TS → `import { Memory } from "mem0ai/oss"`
+
+ If `plan.md` names a delegated skill (e.g., Vercel AI), use *that*
+ skill's import signature instead of the list above. Mismatch → fail
+ with line number.
+- **Version check**: installed `mem0ai` version falls in the range from
+ this skill's `mem0_tested_versions`. Out of range → warn but continue.
+- **Type check** (TS tracks only): run `tsc --noEmit` or `tsup --dts`.
+ Non-zero → fail.
+- **Lint** (if the repo has a linter configured): run the repo's own
+ lint command. Lint failures from this skill's changes → fail; pre-existing
+ lint failures → surface as a warning.
+- **Eager-init check**: grep the `write_site` and `read_site` files (paths
+ from `product.json`) for `MemoryClient(` or `Memory(` at module scope —
+ i.e., not inside a function, method, or class body. `MemoryClient()`
+ validates the API key in `__init__` (network call) and OSS `Memory()`
+ can eagerly initialize embedding/LLM providers — module-level
+ instantiation hits the wire on import and breaks Pass A's test
+ collection whenever the key is unset. Hit → fail with `file:line` and
+ the lazy-init guidance from `/mem0-integrate` step 8 constraint #7.
+
+### 4. Run the repo's native test suite (two passes)
+
+| Language | Test command (in priority order) |
+|---|---|
+| Python | `pytest` with the test files from step 5 of the companion skill, else `python -m unittest discover`. |
+| TypeScript / JavaScript | `npm test` if defined in package.json; else auto-detect `vitest` or `jest`. |
+
+**Pass A — `feature_flag` unset.** Run the *entire* pre-existing suite
+(excluding the new `test_mem0_*` files). **Must be 100% green.** Any
+failure here marks `non_invasive: false` in the scorecard and is
+a **hard fail** — the integrator's self-heal loop refuses to touch it.
+
+**Pass B — `feature_flag` set** (value from `product.json`). Run the
+full suite including the new tests. All must pass.
+
+Isolate integration-introduced failures using `git diff main..HEAD
+--name-only`. A test file that exists on `main` and fails only under
+the integration branch (flag set *or* unset) counts against the
+scorecard regardless of pass. A test file that already failed on `main`
+is surfaced as `pre_existing_unrelated` and does not count — but is
+still reported so the user can clean it up.
+
+Capture output to `.mem0-integration/test-stdout-flag-off.log` and
+`.mem0-integration/test-stdout-flag-on.log`. Scorecard reports pass/fail
+per pass.
+
+### 5. Smoke test (real API call, shortest round-trip)
+
+Scripted end-to-end flow tailored to `product.json`. The call shapes
+below are the minimal ones; if `plan.md` names a delegated skill, use
+*that skill's* minimal example verbatim instead — it is the canonical
+shape for the detected stack.
+
+**Platform (Python):**
+
+ from mem0 import MemoryClient
+ c = MemoryClient() # uses MEM0_API_KEY
+ uid = f"mem0-test-integration-{os.urandom(4).hex()}"
+ c.add([{"role": "user", "content": "I prefer aisle seats"}], user_id=uid)
+ hits = c.search("seat preference", user_id=uid)
+ assert any("aisle" in h.get("memory", "") for h in hits), hits
+ c.delete_all(user_id=uid) # clean up
+
+**Platform (TS):** same shape with `MemoryClient` from `"mem0ai"`.
+
+**OSS (Python / TS):** uses `Memory()` / `new Memory()` with default config
+(OpenAI LLM via `OPENAI_API_KEY`, local Qdrant). If the repo ships a
+`docker-compose.yml` with a Qdrant service, the skill starts it first and
+tears it down after. If no backing store is reachable → fail with a
+clear message naming the fix.
+
+The smoke test always uses a **disposable random user_id** prefixed with
+`mem0-test-integration-` so a failed cleanup doesn't pollute the user's
+real data. A background tidy step deletes any prefix-matching entries
+older than 24 hours on the next run.
+
+Capture output to `.mem0-integration/smoke-stdout.log`.
+
+### 6. E2E integration test (run the app, exercise the flow)
+
+Unit tests + smoke prove the SDK works in isolation. This step is the
+real signal: **does memory actually appear in the app's user-visible
+output when the integration runs end-to-end?**
+
+Requires `plan.md` to contain an `E2E recipe:` section (authored by
+`/mem0-integrate` step 5). If absent → status `skipped` (not `fail`),
+note in scorecard that the repo has no runnable entry point.
+
+Recipe fields the skill reads:
+
+- `start` — shell command to launch the app using `$PORT` for any network
+ port. Run in background with stdout/stderr teed to
+ `.mem0-integration/e2e-app.log`.
+- `ready_probe` — how to detect readiness. `url=... status=...` polls an
+ HTTP endpoint; `log="..."` waits for a substring in `e2e-app.log`;
+ `sleep=N` waits N seconds (last resort). 60-second hard timeout.
+- `compose_services` — optional. If set, bring them up via
+ `docker compose up -d <services>` before `start`, tear them down with
+ `docker compose down` at the end.
+- `write_call` — triggers the Mem0 write path exactly once. Output is
+ captured and surfaced on failure. 60-second hard timeout.
+- `write_async_wait_ms` — pause after `write_call` to let async memory
+ flushes land. Default 0.
+- `read_call` — triggers the Mem0 read path. Typically a fresh session
+ or new request that should surface the stored memory.
+- `read_assert` — substring, `regex=...`, or `jsonpath=<expr>=<value>`
+ that must appear in `read_call`'s stdout. This is the E2E pass gate.
+
+Execution order:
+
+1. Allocate an ephemeral TCP port; export as `PORT`.
+2. Set `MEM0_USER_ID` to a disposable `mem0-test-integration-<rand>` value
+ and export it, so the app can use the same scoping the smoke test does
+ if the recipe wants cleanup.
+3. Bring up `compose_services` if named.
+4. Run `start` in the background.
+5. Poll `ready_probe` until success or 60s timeout. Timeout → fail.
+6. Run `write_call`. Non-zero exit → fail (but continue to cleanup).
+7. Sleep `write_async_wait_ms`.
+8. Run `read_call`.
+9. Evaluate `read_assert` against `read_call`'s stdout. Miss → fail.
+10. Cleanup (always, even on failure): SIGTERM the app, SIGKILL after
+ 5s, `docker compose down` if services were started, `delete_all`
+ memories matching `mem0-test-integration-*` on Platform scenarios.
+
+On any failure, the scorecard includes:
+
+- Last 40 lines of `e2e-app.log`
+- Full `write_call` output
+- Full `read_call` output
+- The expected vs actual for `read_assert`
+
+### 7. Scorecard
+
+Write `.mem0-integration/scorecard.md` and `.mem0-integration/scorecard.json`:
+
+ {
+ "timestamp": "2026-04-20T14:03:11Z",
+ "branch": "mem0-integrate/remember-user-preferences",
+ "product": "platform",
+ "language": "python",
+ "mem0_version": "2.0.0",
+ "non_invasive": true,
+ "feature_flag": "MEM0_ENABLED",
+ "results": {
+ "install": {"status": "pass", "duration_ms": 12043},
+ "static_checks":{"status": "pass", "duration_ms": 812},
+ "unit_tests_flag_off": {"status": "pass", "duration_ms": 3920, "count": 47,
+ "reason": "all pre-existing tests green with flag unset"},
+ "unit_tests_flag_on": {"status": "pass", "duration_ms": 4321, "count": 49},
+ "smoke_test": {"status": "pass", "duration_ms": 2890, "memory_id": "mem_..."},
+ "e2e_test": {"status": "pass", "duration_ms": 14200,
+ "ready_probe_ms": 3100, "write_exit": 0,
+ "read_assert_matched": true}
+ },
+ "friction": {
+ "dependency_install_retries": 0,
+ "pre_existing_test_failures": 0,
+ "warnings": ["mem0ai 2.0.0 pinned; consider 2.0.1 for fix X"]
+ },
+ "overall": "pass"
+ }
+
+The markdown version is human-readable and includes:
+
+- Goal doc + plan doc reprinted at top (so reviewers don't have to hunt).
+- Each check with pass/fail + log excerpt.
+- Friction summary.
+- Verbatim warnings from mem0 SDK (if any — e.g., deprecated field usage).
+- **Explicit "NOT checked" section** listing what loose coupling misses:
+ "Whether the stored data is what the user wants stored. Whether search
+ runs at the right moment. Whether user_id matches the actual session
+ scope. Human review required."
+
+### 8. Report + exit
+
+- Print the scorecard path + overall pass/fail to stdout.
+- **Do not commit the scorecard files.** They live in `.mem0-integration/`,
+ which is gitignored. The user can inspect and optionally pin.
+- On fail: print the first failing step's log tail (last 40 lines) and
+ stop. Do not attempt to fix anything.
+
+## Artifacts (all under `.mem0-integration/`)
+
+| File | Purpose | Retention |
+|---|---|---|
+| `scorecard.md` | Human-readable verdict. | Overwritten per run. |
+| `scorecard.json` | Machine-readable verdict. Consumed by the CI scorecard workflow later. | Overwritten per run. |
+| `test-stdout-flag-off.log` | Step 4 Pass A (pre-existing suite, flag unset). | Overwritten per run. |
+| `test-stdout-flag-on.log` | Step 4 Pass B (full suite, flag set). | Overwritten per run. |
+| `smoke-stdout.log` | Full output from step 5. | Overwritten per run. |
+| `e2e-app.log` | Background app stdout/stderr from step 6. | Overwritten per run. |
+| `e2e-calls.log` | write_call + read_call invocations and outputs. | Overwritten per run. |
+
+## Modes
+
+| Mode | Trigger | Behavior |
+|---|---|---|
+| Interactive (default) | TTY present, `MEM0_TEST_CI` unset | Asks for missing keys, prints friendly summaries. |
+| CI | `MEM0_TEST_CI=1` | Keys must be in env, no prompts, non-zero exit on any fail. JSON scorecard goes to stdout's tail for workflow parsing. |
+
+## Invocation
+
+ /mem0-test-integration # interactive, all steps
+ /mem0-test-integration --ci # non-interactive
+ /mem0-test-integration --skip-smoke # no API calls, no E2E
+ /mem0-test-integration --skip-e2e # unit + smoke only (faster CI)
+ /mem0-test-integration --only-smoke # just smoke
+ /mem0-test-integration --only-e2e # just E2E (assumes deps installed)
+
+Composition: `--skip-*` can stack (`--skip-smoke --skip-e2e` = static +
+unit only, zero API cost). `--only-*` is mutually exclusive with all
+other flags.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | All checks passed. |
+| 1 | Precondition failed (no `.mem0-integration/`, wrong branch, dirty tree). |
+| 2 | Missing env key (CI mode) or dependency install failure. |
+| 3 | Static sanity check failed (wrong import, type error). |
+| 4 | Unit tests failed (Pass B — integration itself broken). |
+| 5 | Smoke test failed. |
+| 6 | E2E test failed (ready_probe timeout, write/read call failed, or read_assert miss). |
+| 7 | Non-invasiveness violation: Pass A failed (pre-existing tests broke). Integrator's heal loop refuses to touch this. |
+| 8 | Internal error (skill bug — report it). |
+
+## Explicitly out of scope
+
+- **Modifying source files.** The skill is read-only against the repo.
+ If verification exposes a bug, re-run `/mem0-integrate` on the same
+ goal + plan; do not hand-patch.
+- **Fixing broken tests.** Failing unit tests are a signal that the
+ integration is wrong, not that the tests are wrong. The skill does
+ not "try a different test."
+- **Deep logical correctness.** The E2E step proves "something the user
+ said earlier comes back later," which is a useful but shallow signal.
+ It does NOT prove the integration picks the *right* facts to store,
+ scopes `user_id` correctly across real users, or handles conflict
+ resolution well. That's human review territory.
+- **Self-healing.** This skill never modifies source files. The paired
+ `/mem0-integrate` skill in its default `--heal` mode consumes the
+ scorecard produced here and drives its own remediation loop. Exit
+ code 7 (non-invasiveness violation) is the explicit signal the heal
+ loop must stop and surface to the user.
+- **Cross-branch comparisons.** No `main` baseline diffing. The
+ scorecard reflects this branch only.
+- **Running against production data.** Every smoke test uses a disposable
+ random user_id and cleans up after. Never touches any other user's data.