thinkfleetai/memmesh/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.

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

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

1. Minimal dependency surface. Add @thinkfleet/memory-sdk (hosted) or the

memmesh binary (local) and nothing else.

1. Separable commits. Code, tests, config/docs in separate commits.
2. The null hypothesis wins. If no additive, gated fit exists, exit with a

rationale. A bad PR is worse than no PR.

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

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

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

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

1. Implement the smallest gated wiring that makes the tests pass. Delegate

call-site patterns to memmesh-sdk / memmesh-cli.

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

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