Build a Claude-Mem integration
Anyone who uses Claude-Mem or CMEM Pro is welcome to contribute an integration. Pick an open integration issue, tell us what you plan to build, and open a pull request against main in thedotmack/claude-mem. Documentation-only integrations are welcome when an existing protocol already does the job.
Start with the Development Guide and Platform Integration Guide. This checklist applies their contribution workflow to new integrations. It does not require a new service, SDK, or database when the existing worker or MCP server is sufficient.
Choose the connection you are building
Name the target product, supported versions, operating systems, and connection type in the issue and PR. Link the target's official extension, hook, API, or MCP documentation. Describe one useful end-to-end workflow.
| Connection | What the contribution needs to prove |
|---|---|
| Capture adapter | Real host events reach the existing observation pipeline with the correct session, project, platform, tool input, and tool result. Document the events the host cannot provide. |
| MCP recall client | A user can connect, authenticate when required, discover the tools, search, and retrieve a saved observation. State whether the client can explicitly save memory. MCP access alone is not automatic conversation capture. |
| Model provider or gateway | The observer can use the provider through an existing supported protocol where possible. Test response parsing and errors. Keep it opt-in and preserve the user's provider and model choices. |
| Notification or export | A user can opt in to a specific destination and receive the documented event or record. State exactly which content leaves the user’s machine or account. Avoid duplicates on retries and provide a way to disconnect. |
| Agent framework | Show the smallest working example using the existing worker API or MCP tools. Explain whether memory is saved explicitly, captured from lifecycle events, recalled on demand, or injected as context. |
An issue is an invitation to investigate, not a promise of a release date. If the target has no usable public extension surface, record that limitation instead of inventing an API or shipping unsupported scraping.
Acceptance checklist
1. Use the existing memory contract
- Reuse the current worker API, MCP server, shared handlers, configuration helpers, and installers where they fit. Keep target-specific translation in the adapter.
- For a native hook adapter, normalize host input to
NormalizedHookInputand format the existingHookResultthroughPlatformAdapter. Preserve stable session and tool-call identifiers when the host provides them. - Keep projects, sessions, accounts, and platform attribution separate. Do not merge unrelated work or silently import old conversations.
- Preserve the existing privacy filters, excluded projects, and storage rules. A new integration must not create a second path around them.
2. Make setup safe and reversible
- Give the user an explicit install or connect action, prerequisites, and a way to check status.
- Re-running installation must not create duplicate hooks, plugins, or MCP entries. Preserve unrelated user configuration and back up files before changing existing configuration.
- Uninstall or disconnect must remove only the integration's own entries. Never erase memory or unrelated settings as a side effect.
- Use shared path and runtime resolution helpers. Test paths containing spaces and document the operating systems actually verified.
3. Protect data and credentials
- Keep credentials out of source, screenshots, test fixtures, logs, model context, and URLs intended for sharing. Use the project's existing secret storage and authentication mechanisms.
- Request only the access the integration needs. Explain what is captured, what is sent to an external service, and how users disable it.
- Treat tool results, imported content, and external messages as untrusted data. They must not become instructions that authorize new actions or expose another user's memory.
- Use sanitized fixtures and respect privacy exclusions in tests as well as implementation.
4. Keep the host usable when memory is unavailable
- Use bounded requests and the existing error-handling path. A stopped worker, timeout, invalid payload, or revoked credential must produce an actionable, redacted failure without hanging the host.
- Optional capture hooks must fail open: a Claude-Mem failure must not block a user prompt, deny a tool, or restart the agent's turn.
- In native hooks, keep diagnostics separate from model-bound output and use the shared hook I/O layer. Adapters and handlers must not write directly to stdout/stderr or terminate the process.
- Explicit user requests such as search or export must report failures honestly. Never display a successful save, sync, or connection before it succeeds.
5. Include tests and a reproducible demonstration
- Test the behavior added by the integration: event mapping, session/project isolation, supported input shapes, and the relevant failure cases.
- If it changes configuration, test first install, repeated install, unrelated configuration preservation, and uninstall. If it retries writes, test duplicate delivery. If it handles authentication, test missing or rejected credentials.
- Demonstrate the advertised workflow in the real target product. For capture, record a harmless event and retrieve its resulting memory. For recall, retrieve a known saved observation. For a provider or export, show the documented output and one failure path.
- Include exact versions, commands, and sanitized results in the PR. Run the applicable current build, type-check, test, and discipline checks from
package.json; disclose any check you could not run. Mocked tests do not replace the real-client demonstration.
6. Ship documentation and accurate status
- Add setup, verification, troubleshooting, limitations, and uninstall/disconnect instructions under
docs/public/, and add the page todocs/public/docs.json. Follow the product’s writing guide for user-facing words. - State whether the connection supports automatic capture, explicit saves, recall, context injection, notifications, or export. Identify local-only and CMEM Pro requirements separately, including required target-product plans.
- Include a catalog-ready description, exact capabilities, and a working documentation link in your PR. The site maintainers update the CMEM Pro catalog; you do not need access to its repository. A proposed integration stays labeled as open for contribution until implementation is merged, documented, and verified.
- Regenerate affected shipped artifacts using the repository's build process. Do not hand-edit generated bundles or the generated changelog.
What to put in the pull request
Use a focused PR with this information:
Closes #<integration-issue>
Target and versions:
Connection type and capabilities:
Official API/hook/MCP reference:
User workflow before and after:
Data captured or sent, authentication, and opt-out:
Setup and uninstall documentation:
Tests and commands run:
Real-client verification steps and sanitized results:
Known limitations / checks not run:
Existing contribution rules still apply: automated checks must pass, a maintainer reviews the change, and release decisions remain with the maintainers. You do not need to implement capabilities the target cannot support; you do need to describe those boundaries clearly.
