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.
Integration principles (non-negotiable)
The goal is a PR the maintainers accept without argument.
- Additive, not replacing. If the repo already has a memory / session /
user-context layer, MemMesh sits alongside it. The existing system keeps
working unchanged.
- 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.
- 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.
- Minimal dependency surface. Add
@thinkfleet/memory-sdk (hosted) or the
memmesh binary (local) and nothing else.
- Separable commits. Code, tests, config/docs in separate commits.
- The null hypothesis wins. If no additive, gated fit exists, exit with a
rationale. A bad PR is worse than no PR.
- Backend only. Integration lives in server-side code. Keys never ship to
the client.
Pipeline
- Detect the stack (language, test runner, where user/session context is
handled). Record in
.memmesh-integration/detect.md.
- 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.
- 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.
- 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.
- Implement the smallest gated wiring that makes the tests pass. Delegate
call-site patterns to
memmesh-sdk / memmesh-cli.
- 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.
- 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.
1---2name: memmesh-integrate3description: 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.4license: Apache-2.05---67# memmesh-integrate89Wire MemMesh into an existing repo with a goal-driven, test-first pipeline.10Pairs with `memmesh-test-integration` for verification.1112## Canonical sources (fetch BEFORE deciding anything)1314`WebFetch` these and cite them in `plan.md`. They are ground truth — do not15rely on ambient knowledge of the API.1617- Docs index (agent-ready): https://docs.memmesh.ai/llms.txt18- Full docs (deep dives): https://docs.memmesh.ai/llms-full.txt19- Platform vs Local: https://docs.memmesh.ai/platform-vs-local20- Published skills to DELEGATE to (don't reimplement call-site patterns):21 - SDK: `memmesh-sdk` · CLI + MCP: `memmesh-cli` · MCP loop: `memmesh`2223## Integration principles (non-negotiable)2425The goal is a **PR the maintainers accept without argument.**26271. **Additive, not replacing.** If the repo already has a memory / session /28 user-context layer, MemMesh sits *alongside* it. The existing system keeps29 working unchanged.302. **Opt-in by default.** Gate all new code behind a flag (`MEMMESH_ENABLED=1`,31 a config key, or a strategy selector). Flag unset ⇒ original behavior,32 byte-for-byte.333. **No breakage.** No removed/renamed exports, no changed signatures, no34 modified existing tests. All pre-existing tests pass unchanged with the flag35 both set and unset.364. **Minimal dependency surface.** Add `@thinkfleet/memory-sdk` (hosted) or the37 `memmesh` binary (local) and nothing else.385. **Separable commits.** Code, tests, config/docs in separate commits.396. **The null hypothesis wins.** If no additive, gated fit exists, exit with a40 rationale. A bad PR is worse than no PR.417. **Backend only.** Integration lives in server-side code. Keys never ship to42 the client.4344## Pipeline45461. **Detect** the stack (language, test runner, where user/session context is47 handled). Record in `.memmesh-integration/detect.md`.482. **Choose surface** — ask the user: **Hosted** (managed, `mm-` key, best for49 prediction/calibration/verticals) or **Local** (CLI + MCP over SQLite, no50 key, best for dev tools / offline). Default to Local for CLIs and dev51 tooling, Hosted for user-facing apps.523. **Pick the seam.** The highest-value seam is usually the request/response53 loop around the LLM: `observe` the user turn, `search`/`buildContext` before54 generating, and — where it adds value — `predict` the next action. Write the55 goal in `plan.md` and cite the canonical sources.564. **Write failing tests first** into `.memmesh-integration/` and the repo's57 test dir: (a) flag-off ⇒ behavior unchanged; (b) flag-on ⇒ observe is called58 with the user turn; (c) flag-on ⇒ retrieved context reaches the prompt.595. **Implement** the smallest gated wiring that makes the tests pass. Delegate60 call-site patterns to `memmesh-sdk` / `memmesh-cli`.616. **Consider the moat.** If the app makes a decision about a user/account62 (offer, routing, retention), add an *optional* `predict` / `predictTarget`63 call and surface the calibrated confidence + abstention. Never let an64 abstention crash the flow — treat "I don't know yet" as a first-class branch.657. **Emit artifacts** in `.memmesh-integration/` (`detect.md`, `plan.md`,66 `changes.md`, seed test data) and stop. Then run `memmesh-test-integration`.6768## Definition of done6970Feature branch + `.memmesh-integration/` artifacts, all pre-existing tests green71with the flag both set and unset, and the new tests green with it set.