Add MuscleMemory local MCP integration to the catalog #806

Problem

OpenHands users who choose MuscleMemory currently need to configure its local MCP connection manually. The extensions catalog has no entry exposing that connection and its setup requirements.

MuscleMemory provides procedural workflow memory through five MCP tools: recall, observe, learn, evaluate, and inspect. A procedure is eligible for recall only after later independent checks and operator approval.

Proposed change

Add integrations/catalog/musclememory.json and regenerate integrations/catalog-index.js using npm run build:integrations.

The proposed local stdio command is pinned to the published 0.1.7 release:

uvx --python 3.12 --from thewariend-musclememory==0.1.7 musclememory stdio

The entry documents:

• Initialize MuscleMemory on the host that launches MCP.
• Supply a read/write MM_API_KEY and optionally the matching initialized MM_HOME.
• The local stdio transport uses its database directly and needs no separate REST daemon.
• A workstation's local folder is not automatically available to a remote runner.
• Observation is explicit: this connection does not automatically capture OpenHands tool calls.

No provider-specific runtime code, automatic approval, or ranking changes are proposed.

Benefit

Users can discover and configure MuscleMemory through the existing integration flow, then recall previously verified workflow guidance across sessions. Agents can inspect that guidance and explicitly record and evaluate real task observations. No token or speed improvement is claimed.

Acceptance criteria

• One canonical integration JSON entry, with its generated JS index updated.
• Required API-key and optional local-folder fields match the catalog schema.
• Setup commands work with released packages.
• A live connection through openhands.sdk.mcp.create_mcp_tools discovers all five tools and exercises the workflow lifecycle.
• Existing catalog and repository tests pass.

Evidence already collected

The change is prepared locally against the current extensions main branch.

• npm run build:integrations succeeded.
• Focused catalog checks: 117 passed.
• Full uv run --group test pytest -q tests/: 1421 passed, 23 skipped.
• Live connection used released openhands-sdk==1.56.0, PyPI thewariend-musclememory==0.1.7, and the default semantic search model in an isolated temporary database.
• The SDK discovered all five tools; the fixture recorded four actual independently checked file reads, learned a procedure, and validated it in two later runs.
• Recall remained empty before approval. A separate fixture operator approved the procedure, after which recall and inspection succeeded. A deliberately failed later check flagged it and withheld recall again.
• No model-agent calls or real user data were involved.

PASS: released stdio command -> five tools -> real file reads -> learned -> two checks -> operator approval -> recall/inspect -> failed check withholds recall

Maintainer decision requested

Is this local MCP integration appropriate for the public catalog? Please triage it before a PR is opened. If accepted for development, the prepared change can be submitted under the repository's normal issue-readiness and human-review requirements.

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

Bounded scope: add one hand-authored integrations/catalog/musclememory.json and regenerate integrations/catalog-index.js with npm run build:integrations. The entry declares one local provider: "mcp" option with transport.kind: "stdio", serverName: "musclememory", and the pinned uvx invocation for the published thewariend-musclememory package, plus envFields for the read/write MM_API_KEY (required, secret) and the optional MM_HOME. This follows the documented contract in integrations/README.md and AGENTS.md: one JSON file is the single hand-authored source of truth and the generated index is derived. Closest existing schema references are integrations/catalog/obsidian.json (uvx stdio MCP with a required password envFields entry and auth.strategy: "api_key"), integrations/catalog/git.json and integrations/catalog/filesystem.json (local stdio MCP with argFields), and integrations/catalog/redis.json (uvx stdio using the --from <pkg> <cmd> form).

Curation: the catalog already carries third-party local stdio MCP servers (for example memory, obsidian, git, filesystem, redis, sequential-thinking), and neither integrations/README.md nor AGENTS.md states a first-party-only acceptance policy. An entry that meets the documented contract is therefore in scope, with maintainers retaining final curation discretion at PR review, as with comparable integration proposals. The repository's documented process (one JSON file, schema validation, regenerated index, catalog tests) resolves the open question, so no design decision is left unresolved.

Non-goals: no provider-specific runtime code, no automatic approval, no ranking changes, no skill/plugin/automation changes, no new catalog file format or aggregate catalog JSON, and no credential value committed in catalog data.

Priority is low: the request records no user report, support or customer evidence, or reproduced production failure. The author's own evidence is a local fixture run, which is a synthetic reproduction rather than observed user pain, so it stays low.

Acceptance Criteria

• integrations/catalog/musclememory.json exists with id: "musclememory" and validates against integrations/catalog.schema.json; tests/test_catalog_schema.py and tests/test_catalogs.py pass.
• connectionOptions contains exactly one provider: "mcp" option with transport.kind: "stdio", serverName: "musclememory", command: "uvx", and args running musclememory stdio from the published thewariend-musclememory package; no http-provider option and no oauth2 auth option are present.
• That option's auth.strategy is "api_key", and envFields declares MM_API_KEY with type: "password" and required: true, plus a helperText and a helperLink (or an inline markdown link in helperText) pointing to where the key is created; MM_HOME is declared with required: false.
• No token, key, or credential value appears anywhere in the file.
• docsUrl is a reachable https:// link documenting the MuscleMemory MCP setup; any appUrl/logoUrl values are reachable https:// links.
• The entry's notes/installHint state the setup facts the issue calls out: MuscleMemory must be initialized on the host that launches MCP; the local stdio transport uses its database directly and needs no separate REST daemon; a workstation's local folder is not automatically available to a remote runner; and connecting over MCP does not automatically capture OpenHands tool calls (observation is explicit via observe).
• The pinned thewariend-musclememory version satisfies the repository's seven-day release-recency guard at PR time (skills/code-review/references/supply-chain-security.md, referenced by .agents/skills/custom-codereview-guide.md); 0.1.7 was published 2026-10-21 and does not, so either an older release is pinned or the pin is updated once it is at least seven days old.
• integrations/catalog-index.js is regenerated with npm run build:integrations; tests/test_integration_catalog_in_sync.py passes and no hand-edited aggregate catalog is introduced.
• python scripts/sync_extensions.py --check passes, including any README entry-list update it requires.
• Live validation evidence: a released OpenHands client connects through openhands.sdk.mcp.create_mcp_tools using the released thewariend-musclememory package and discovers exactly the five tools (recall, observe, learn, evaluate, inspect); the run records the observed tool list and the outcome of the workflow lifecycle (learn a procedure from real observations, pass two later independent checks, operator-approve, then recall and inspect it).
• The recorded evidence shows recall returning nothing before approval and withholding recall again after a deliberately failed later check.
• uv run --group test pytest -q tests/ passes.