memmesh-integrate

# 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.