memmesh-integrate

name	memmesh-integrate
description	Integrate MemMesh into an existing repository using a goal-driven, test-first (TDD) pipeline. Detects the repo's language/stack, asks whether to use MemMesh Hosted (SDK, managed) or Local (CLI + MCP over SQLite), writes failing tests before any implementation, and lands additive, feature-flag-gated code that a maintainer can accept without argument. Produces `.memmesh-integration/` artifacts for the paired verification skill. TRIGGER when: user says "integrate memmesh", "add memmesh to this repo", "wire memmesh into <repo>", "add memory to this app", or "add prediction to this app". DO NOT TRIGGER for: general SDK usage (use `memmesh-sdk`), CLI usage (use `memmesh-cli`), or migrating off another vendor (use `memmesh-migrate`). After success, invoke `memmesh-test-integration` in the same workspace.
license	Apache-2.0
metadata	{"author":"thinkfleet","category":"ai-memory","tags":"memory, prediction, integration, tdd"}

memmesh-integrate

Wire MemMesh into an existing repo with a goal-driven, test-first pipeline. Pairs with memmesh-test-integration for verification.

Canonical sources (fetch BEFORE deciding anything)

WebFetch these and cite them in plan.md. They are ground truth — do not rely on ambient knowledge of the API.

• Docs index (agent-ready): https://docs.memmesh.ai/llms.txt
• Full docs (deep dives): https://docs.memmesh.ai/llms-full.txt
• Platform vs Local: https://docs.memmesh.ai/platform-vs-local
• Published skills to DELEGATE to (don't reimplement call-site patterns):
  • SDK: memmesh-sdk · CLI + MCP: memmesh-cli · MCP loop: memmesh

Integration principles (non-negotiable)

The goal is a PR the maintainers accept without argument.

1. Additive, not replacing. If the repo already has a memory / session / user-context layer, MemMesh sits alongside it. The existing system keeps working unchanged.
2. Opt-in by default. Gate all new code behind a flag (MEMMESH_ENABLED=1, a config key, or a strategy selector). Flag unset ⇒ original behavior, byte-for-byte.
3. No breakage. No removed/renamed exports, no changed signatures, no modified existing tests. All pre-existing tests pass unchanged with the flag both set and unset.
4. Minimal dependency surface. Add @thinkfleet/memory-sdk (hosted) or the memmesh binary (local) and nothing else.
5. Separable commits. Code, tests, config/docs in separate commits.
6. The null hypothesis wins. If no additive, gated fit exists, exit with a rationale. A bad PR is worse than no PR.
7. Backend only. Integration lives in server-side code. Keys never ship to the client.

Pipeline

1. Detect the stack (language, test runner, where user/session context is handled). Record in .memmesh-integration/detect.md.
2. Choose surface — ask the user: Hosted (managed, mm- key, best for prediction/calibration/verticals) or Local (CLI + MCP over SQLite, no key, best for dev tools / offline). Default to Local for CLIs and dev tooling, Hosted for user-facing apps.
3. Pick the seam. The highest-value seam is usually the request/response loop around the LLM: observe the user turn, search/buildContext before generating, and — where it adds value — predict the next action. Write the goal in plan.md and cite the canonical sources.
4. Write failing tests first into .memmesh-integration/ and the repo's test dir: (a) flag-off ⇒ behavior unchanged; (b) flag-on ⇒ observe is called with the user turn; (c) flag-on ⇒ retrieved context reaches the prompt.
5. Implement the smallest gated wiring that makes the tests pass. Delegate call-site patterns to memmesh-sdk / memmesh-cli.
6. Consider the moat. If the app makes a decision about a user/account (offer, routing, retention), add an optional predict / predictTarget call and surface the calibrated confidence + abstention. Never let an abstention crash the flow — treat "I don't know yet" as a first-class branch.
7. Emit artifacts in .memmesh-integration/ (detect.md, plan.md, changes.md, seed test data) and stop. Then run memmesh-test-integration.

Definition of done

Feature branch + .memmesh-integration/ artifacts, all pre-existing tests green with the flag both set and unset, and the new tests green with it set.