Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / additional-agent-integrations

Additional agent integrations

Additional agent integrations connect supported hosts to the Claude-Mem worker without requiring each host to use the main plugin package. They install the host's native hook, plugin, or context-file shape, translate host events into shared session events when the host supports capture, and return memory context in the format that the host accepts. This page complements distribution integrations, native harness integrations, plugin hooks and agent modes, and installation and the npx CLI. Dedicated host pages cover Cursor, Grok Bot, Cowork, OpenClaw, and external notifications.

Integration model

Each bridge has two parts. An installer places a small host-specific entry in the user's configuration, and a runtime adapter sends prompts, tool activity, summaries, or context requests to the local worker. Hosts without a capture interface use a file-based context bridge instead. The worker remains the shared source for session memory, so activity from supported hosts can appear with activity from the main agent integrations.

HostInstallation shapeRuntime bridgeMain result
Kimi CodeManaged hook block plus MCP registrationNative lifecycle hooksCaptures tools, injects first-session context, and supports memory search
OMP (Oh My Pi)Copied TypeScript hook moduleIn-process event handlersRecords prompts and tools, injects context, and summarizes sessions
OpenCodeCopied plugin plus version-aware config registration and MCP entryNative plugin hooksCaptures chat and tools, injects project context, and exposes memory search
WindsurfUser-level hook configuration plus workspace context fileHost commands that call the workerCaptures prompts and actions, then refreshes workspace context
AiderProject memory file referenced by .aider.conf.ymlFile-based context refreshLoads shared project memory into every session without automatic capture
DeepSeek HarnessSource-installable host pluginNative tools and lifecycle callbacksSearches and injects memory, with optional capture and summarization
Other host adaptersHost-specific hook files and adaptersShared hook command pipelineNormalizes host payloads into common session events

Installation boundaries

The CLI keeps host setup separate from worker runtime. An install changes only the host configuration that the bridge needs, while an uninstall removes the Claude-Mem-managed entry and preserves unrelated host settings where the bridge supports that boundary.

Use the host-specific install target for OMP, OpenCode, or Windsurf. Kimi and Aider also have direct commands because they need host-specific setup:

npx claude-mem install --ide omp
npx claude-mem install --ide opencode
npx claude-mem install --ide windsurf
npx claude-mem kimi install
npx claude-mem aider install

The normal uninstall path cleans these bridges with the other integrations. Kimi provides kimi status, and the other installers provide status or clear install output so an engineer can tell whether the host entry exists. Aider's status checks the project configuration and memory file separately. The worker must still be running for capture and context exchange; installation alone does not create stored memory. Aider is an exception to capture: it can load existing memory without hooks, and aider sync refreshes its local context file.

Runtime event flow

The common flow turns a host event into a normalized action, sends it to the local worker, and returns host-safe output or context. File-based hosts instead refresh a project context file that the host reads on its next session.

flowchart LR
    A[Host lifecycle event] --> B[Host bridge]
    B --> C[Shared session action]
    C --> D[Claude-Mem worker]
    D --> E[Stored observation or summary]
    D --> F[Formatted memory context]
    F --> B
    B --> G[Host continues with context]
    H[Project sync] --> I[Worker context endpoint]
    I --> J[Project memory file]
    J --> K[Host reads context]

Hook-based hosts use one shared command path after their payload is normalized. Runtime plugin hosts such as OpenCode and OMP call the worker from their loaded bridge. Native harness hosts expose tools and lifecycle callbacks through the same worker boundary. Aider uses the worker context endpoint during an explicit sync instead of sending host events. All paths that exchange context carry the host session or working directory so the worker can group events under the correct project.

Host bridges

Kimi Code

Kimi Code uses native lifecycle hooks for worker start, prompt initialization, tool capture, file context, and session summarization. The adapter converts Kimi's structured prompt parts and tool result fields into the shared session shape. It can also find the session transcript when Kimi does not include its path in the hook payload. The installer adds a managed block to Kimi's TOML configuration and adds a memory-search MCP server to Kimi's MCP configuration without replacing other entries. KIMI_CODE_HOME selects the Kimi data root when a non-default location is needed.

The installer uses absolute runtime paths because Kimi does not expand variables in hook commands. It creates a dated, owner-only backup of an existing Kimi configuration before the first change on that date. During uninstall, it removes only the managed hook block and removes the MCP entry only when its server path identifies the Claude-Mem server.

Kimi's hook output is plain context text rather than the JSON envelope used by some other hosts. The bridge injects the shared timeline on the first prompt of a session and after compaction. It also records failed tool calls as observations, so a failed action remains part of the session history.

flowchart TD
    A[Session start] --> B[Start worker]
    C[User prompt] --> D[Initialize session]
    D --> E[First prompt context]
    F[Tool success or failure] --> G[Observation]
    H[Stop or compaction] --> I[Summarize]
    I --> J[Next post-compaction prompt]
    J --> E

The Kimi bridge validates the working directory and session identity before it sends an event. It fails open when the worker is unavailable or the hook payload is not usable, so memory support does not block the user's session.

References: src/…/KimiHooksInstaller.ts• L20-43 src/…/KimiHooksInstaller.ts• L67-75 src/…/KimiHooksInstaller.ts• L77-146 src/…/KimiHooksInstaller.ts• L148-200 src/…/kimi.ts• L11-131 docs/…/kimi-integration.mdx• L7-17

OMP (Oh My Pi)

OMP loads a TypeScript hook module from its agent hook directory. The OMP installer copies the trusted shipped claude-mem.ts bridge there, so no OMP plugin or source change is required. The destination follows OMP's active profile or explicit agent-directory selection, which lets separate OMP profiles keep separate hook installations.

The bridge keeps one Claude-Mem session for an OMP process and sends every user prompt in order. Tool results become observations after their prompt, the context event adds recent memory to the existing conversation, and session shutdown or compaction sends a summary. It skips Claude-Mem's own memory tools to avoid recording its search work as user work.

OMP does not wait for most worker writes. Requests have a time limit, and repeated worker failures open a short circuit so a slow or stopped worker does not hold up the agent. The installer copies from the marketplace bundle by default; resolving a hook from the current checkout requires an explicit development opt-in because the destination is a persistent user hook. The bridge sends the current working directory instead of inventing a project name, which lets the worker use the same project identity rules as the other integrations.

References: src/…/OmpHooksInstaller.ts• L8-20 src/…/OmpHooksInstaller.ts• L25-75 src/…/OmpHooksInstaller.ts• L78-115 omp/…/claude-mem.ts• L1-35 omp/…/claude-mem.ts• L248-356 omp/README.md• L13-49

OpenCode

OpenCode uses a loaded plugin rather than shell commands for each event. Installation copies the built plugin into OpenCode's plugin directory and registers the local MCP server when its server script is available. OpenCode 1 needs a plugin entry in opencode.json, while OpenCode 2 loads the copied plugin from its plugin directory and must not receive that file entry. The installer detects the available OpenCode version and applies the matching setup; supported loading starts at OpenCode 1.3.4. It also removes an old global memory block from AGENTS.md because current context is project-specific and comes from the plugin.

The plugin supports OpenCode's two host contracts. Older supported releases use a server function that returns named hooks, while newer releases use an identified setup function that registers hooks through the host context. One entry point supports both contracts, and a shared runtime core keeps prompt capture, tool capture, memory context, summaries, and search consistent between them.

The bridge starts a memory session for each real user prompt, captures assistant messages and tool activity, and uses the current checkout as the project identity. It marks requests as OpenCode activity so source-scoped memory and session lookups stay correct. Memory context is scoped to OpenCode by default, with the shared include-all-sources setting available when a user needs memory from other hosts. The bridge uses idle or execution and compaction signals to summarize sessions, refreshes context after compaction, and adds project memory to the system prompt.

OpenCode's two contracts use different event shapes, so the adapters map their prompt, tool, context, compaction, completion, and deletion signals into the same core actions. V2 also filters events by checkout and tracks the last assistant reply because its event stream covers more than one host location. Context blocks are replaced instead of stacked on repeated prompt builds. The bridge exposes a three-step claude_mem_search flow that lets the model find an index, inspect nearby timeline context, and fetch selected observations.

Worker requests have a time limit. A refused connection can retry in the background, while a failed context request waits before it is tried again. The V2 event subscription also reopens after a stream failure, so later summaries still have a path to the worker. OpenCode reports partial installation when the plugin is present but MCP registration cannot complete. It also reports a warning when an old global context block cannot be removed. These distinctions matter because the host bridge can capture and inject context while memory search remains unavailable, or while stale context remains visible in every project. Restart OpenCode after installation so it loads the copied plugin.

References: src/…/OpenCodeInstaller.ts• L22-30 src/…/OpenCodeInstaller.ts• L44-105 src/…/OpenCodeInstaller.ts• L227-273 src/…/OpenCodeInstaller.ts• L317-353 src/…/OpenCodeInstaller.ts• L395-535 src/…/contract.ts• L15-140 src/…/core.ts• L55-135 src/…/core.ts• L156-232 src/…/core.ts• L273-445 src/…/index.ts• L9-37 src/…/v1.ts• L72-182 src/…/v2.ts• L224-431

Windsurf

Windsurf uses a user-level hook file for lifecycle events and a workspace rule file for visible memory context. Installation merges Claude-Mem entries into Windsurf's hook configuration, creates or refreshes the workspace context, and records the workspace for later context updates. A running worker can provide initial context during install; otherwise the bridge leaves a placeholder until a session produces memory.

The hook mapping treats prompt submission as session initialization. Code writes, shell commands, MCP results, and the full cascade response become observation events. The workspace rule file is limited in size, so detailed history remains available through MCP search rather than being copied into the rule file.

The installer reads existing hook files with support for a byte-order mark and refuses to overwrite a file that it cannot parse. It owns only complete Claude-Mem worker commands, so similar user commands remain in place during reinstall or uninstall. The workspace context file and its auto-update registry entry are removed with the integration.

References: src/…/WindsurfHooksInstaller.ts• L30-43 src/…/WindsurfHooksInstaller.ts• L45-107 src/…/WindsurfHooksInstaller.ts• L122-175 src/…/WindsurfHooksInstaller.ts• L177-237 src/…/WindsurfHooksInstaller.ts• L239-293 src/…/WindsurfHooksInstaller.ts• L296-363 src/…/windsurf.ts• L4-71

Aider

Aider has no hook, plugin, or MCP interface for automatic session capture. Its integration therefore uses a project memory file at .claude-mem/aider-memory.md, which Aider loads read-only through the project's .aider.conf.yml read: setting. The file is refreshed from the worker's shared context endpoint when the user runs npx claude-mem aider sync.

Installation merges only the Claude-Mem path into the existing read: setting and keeps the rest of the Aider configuration unchanged. It supports common scalar, block-list, and flow-list forms, but refuses ambiguous or malformed read: data instead of rewriting the file. The installer creates a dated backup before a change and adds the memory path to the repository's local Git exclude file so recalled context does not enter version control.

The integration is project-scoped. Aider install and sync resolve the project from the selected working directory and request all memory keys that the checkout reads, including inherited project keys. Install creates a placeholder when no context exists and treats a failed refresh as a setup warning; an explicit sync reports the failure instead of claiming that the file was refreshed. Uninstall removes only entries owned by Claude-Mem and leaves the memory file in place until the user deletes it, so the Git exclude remains protective while that file exists. The home directory is refused because a home-level Aider config would expose one project's memory to every Aider session.

flowchart LR
    A[Project working directory] --> B[aider sync]
    B --> C[Worker context endpoint]
    C --> D[.claude-mem/aider-memory.md]
    D --> E[.aider.conf.yml read:]
    E --> F[Aider session]

References: src/…/AiderInstaller.ts• L1-23 src/…/AiderInstaller.ts• L375-507 src/…/AiderInstaller.ts• L513-591 src/…/AiderInstaller.ts• L593-707 src/…/AiderInstaller.ts• L710-732

DeepSeek Harness

The DeepSeek Harness integration is a native host plugin that exposes Claude-Mem through tools, skills, and agent lifecycle callbacks. It uses the shared worker address, injects project context when an agent starts, and can optionally save selected successful tool results or summarize a turn. Its default mode reads existing memory without automatically ingesting host activity.

The plugin gives the model a staged memory workflow: search for an index, select useful observation IDs, and fetch full details or nearby timeline context. Search results remove repeated observations by matching normalized content rather than generated IDs or timestamps. This keeps repeated worker records from consuming the harness context while preserving records that have different content; explicit fetch-by-ID results remain unchanged.

References: src/…/index.ts• L21-49 src/…/hooks.ts• L27-65 src/…/tools.ts• L136-185 src/…/worker.ts• L148-161 src/…/dedupe.ts• L30-63 src/…/dedupe.ts• L67-113

Host-specific hook adapters

Cursor and Antigravity also use host hook files that call the shared worker service. Their adapters translate each host's event names and payload fields before the common hook command runs. Cursor has a dedicated page for its install targets, while Antigravity follows its own Gemini configuration tree and host event rules.

Cursor installation identifies both current unified worker-service commands and known legacy Claude-Mem shell scripts. Reinstallation replaces only those managed entries. Status reports whether the current or legacy form is present, and uninstall removes those entries while preserving unrelated hooks. If hooks.json is malformed or has a shape the installer cannot understand, it leaves the file and legacy scripts in place rather than risk damaging another integration.

These bridges differ in where they install and how they format output, but they share the same product boundary: a host event becomes session initialization, context, observation, file context, summarization, or session completion. Use the dedicated Cursor integration page for Cursor targets and the distribution integrations page for the full host map.

References: src/…/index.ts• L1-24 src/…/hook-command.ts• L60-75 src/…/CursorHooksInstaller.ts• L116-179 src/…/CursorHooksInstaller.ts• L187-224 src/…/CursorHooksInstaller.ts• L236-299 src/…/CursorHooksInstaller.ts• L396-473 src/…/AntigravityCliHooksInstaller.ts• L66-119

Runtime contracts

Worker availability

The bridges depend on a per-user local worker. When it is not ready, hook-based integrations return a safe no-op and runtime plugins use bounded requests or background retry. OpenCode also avoids repeating a failed context request on every system-prompt build for a short retry window. Aider install can leave a placeholder and an explicit sync reports the error. This keeps agent work moving, but it also means that events or context can be absent until the worker is available.

References: src/…/hook-command.ts• L108-161 src/…/core.ts• L95-153 src/…/core.ts• L312-339 src/…/v2.ts• L169-193 omp/…/claude-mem.ts• L173-225 src/…/AiderInstaller.ts• L530-591

Project identity

The working directory is the key input for project identity across these bridges. The host supplies its current checkout, and the worker resolves the project so sessions from different hosts can share the same project memory without each bridge copying the identity rules. Aider sync also requests inherited project keys for the selected checkout. OpenCode adds its platform source to worker requests so source-scoped context and session lookups remain tied to the right host. It also uses one stable local session identity for a host session, but it sends session initialization only when a real user prompt occurs.

References: src/…/core.ts• L81-84 src/…/core.ts• L175-231 src/…/core.ts• L312-354 omp/…/claude-mem.ts• L32-34 omp/…/claude-mem.ts• L270-307 src/…/types.ts• L1-8 src/…/AiderInstaller.ts• L566-589

Change checklist

When these files or sections are changed, remember to consider these:

  • When a host event name or payload field changes, update both its installer mapping and its runtime adapter so the event still reaches the intended shared handler.
  • When the worker session contract changes, check OpenCode V1 and V2 direct requests as well as the normalized hook path. They do not all use the same host-side event shape.
  • When context output rules change, check Kimi's plain-text output, Windsurf's workspace rule file, Aider's Markdown memory file, and OpenCode's system-prompt transform separately.
  • When an install path changes, check uninstall and status behavior together. These bridges must remove or report the same managed entry that installation creates.
  • When Aider configuration handling changes, check scalar, block-list, and flow-list read: forms, ownership markers, backups, Git exclusion, home-directory refusal, and the distinction between best-effort install refresh and explicit sync failure.
  • When OMP profile or source selection changes, check the active profile directory, explicit agent-directory override, trusted marketplace source, and development-only source opt-in together.
  • When Kimi configuration ownership changes, preserve its dated backup, managed TOML block, and ownership check for the MCP entry. Do not remove a pre-existing server that has the same generic name.
  • When Cursor hook ownership rules change, update unified-hook detection, legacy-script detection, merge behavior, status reporting, and uninstall cleanup together. Preserve unrelated entries in shared hooks.json files.
  • When project identity or platform source changes, check all bridges that send a working directory or source label so sessions do not split across hosts.
  • When OpenCode context injection changes, preserve source filtering, the include-all-sources setting, per-session caching, and replacement of old V2 context blocks.
  • When DeepSeek Harness query output changes, keep content-based result deduplication separate from explicit ID fetches so search stays compact without hiding a requested observation.
  • When OpenCode changes its plugin contract or version loading rules, update the installer version choice, V1 hook names, V2 registrations, bus event allowlists, and the single entry-point export together.

Important failure modes

TriggerConsequenceGuard
Worker is stopped or its port cannot be reachedCapture or context is skipped while the host continuesHook no-op output, bounded plugin requests, OMP circuit breaker, Aider placeholder or explicit sync error, and later retry paths
Kimi receives a non-text output envelopeContext is not added to the Kimi promptKimi adapter returns plain context text
Kimi configuration or MCP data is malformedInstallation or cleanup cannot safely update the host setupManaged-block edits, ownership checks, and error reporting stop the change instead of replacing unrelated data
Aider project is the home directoryA home-level config could expose one project's memory to every Aider sessionInstaller refuses setup outside a project folder
Aider read: data is duplicate, malformed, or ambiguousThe project configuration is left unchanged and context is not installedText-level merge refuses unsafe shapes and reports the error
Aider memory file is removed before its Git exclude entryA later recreated memory file can appear in Git statusUninstall keeps the exclude until the memory file is gone
OpenCode plugin bundle is missing during installPlugin cannot loadInstaller reports failure and asks for a build before retry
OpenCode receives a plugin definition for the wrong contractThe plugin is rejected before event capture startsThe entry point exposes the required identity and both supported setup shapes
OpenCode tool arguments are read from the result instead of the event inputObservations lose the input that explains the tool actionV1 and V2 adapters pass the host's input field to the shared core
OpenCode initializes a session before a real user promptTool activity can attach to a synthetic prompt or the wrong session rowCreate session initialization from user prompt events only
OpenCode's event stream ends and is not reopenedLater completion or compaction events are missedV2 bus consumption retries the subscription after a delay
OpenCode V2 starts without a checkout directoryWorker writes fail because they have no project identityV2 skips registration when neither location nor legacy directory data is available
OpenCode V2 context is added on every prompt build without removing the old blockThe system prompt accumulates duplicate memory contextTagged memory parts are removed before the current block is added
OpenCode context fetch fails on every prompt buildEach model request waits for another worker timeoutFailed context requests stay cached for a retry window
OpenCode MCP server cannot be resolvedPlugin is installed but memory search is unavailableInstaller returns a partial-install warning instead of reporting full success
OpenCode is older than the supported plugin loaderThe plugin may not load even though installation writes its filesInstaller detects the version and warns that OpenCode 1.3.4 or later is required
The old OpenCode context block cannot be removed from global AGENTS.mdStale memory context remains visible in every projectInstaller returns a warning result and names the file that needs cleanup
Windsurf hooks.json is malformedHook changes cannot be merged safelyInstaller refuses to overwrite the file and reports the path
Windsurf hook file has a byte-order mark or another supported encoding detailA valid host file can be misread during install or uninstallJSON parsing accepts the host file format before entries are merged or removed
Windsurf contains a similar user command that is not a complete Claude-Mem hookUninstall could delete the user's automationExact worker-service command matching limits ownership to entries written by the installer
Cursor hooks.json is malformed or an entry has an unsupported shapeInstallation or cleanup stops before changing shared hooksInstaller refuses to overwrite or remove entries it cannot safely parse
Cursor contains a legacy Claude-Mem script from an older installStatus can misreport the integration or uninstall can leave a live old hookExact legacy path matching covers known shell and PowerShell names while preserving similar user hooks
OMP profile is invalid or the hook bundle is missingOMP installation or removal cannot target the intended hookProfile validation and trusted marketplace-source checks stop the operation with an error
OMP hook is copied from an untrusted working directoryA persistent user hook could run unintended codeInstaller uses the shipped source unless explicit development opt-in is set
DeepSeek Harness search returns repeated records with different IDsThe model sees redundant memory and spends more context on duplicate contentSearch results use normalized content fingerprints; empty-content records are retained
A host sends an invalid or incomplete session payloadThe event is ignored or becomes a safe no-opAdapter validation and fail-open hook handling

Key files

FileWhy to read it
src/…/KimiHooksInstaller.tsKimi installation, MCP setup, status, backups, and managed cleanup
src/…/kimi.tsKimi payload normalization, transcript association, and output boundary
src/…/OmpHooksInstaller.tsOMP profile-aware discovery, trusted source selection, and copy-based installation
omp/…/claude-mem.tsOMP prompt, tool, context, and session bridge
src/…/OpenCodeInstaller.tsOpenCode version detection, plugin registration, MCP setup, partial-install status, and cleanup
src/…/index.tsOpenCode's shared entry point for the supported plugin contracts
src/…/contract.tsOpenCode hook names, event contracts, and search response boundary
src/…/core.tsOpenCode worker requests, source-scoped context, session identity, summaries, and search
src/…/v1.tsOpenCode's returned-hook adapter for older supported releases
src/…/v2.tsOpenCode's setup, typed context injection, event filtering, and reconnecting event-stream adapter for newer releases
src/…/WindsurfHooksInstaller.tsWindsurf hook merge, exact ownership checks, safe config handling, workspace context, and project registry lifecycle
src/…/windsurf.tsWindsurf action normalization
src/…/AiderInstaller.tsAider project-file installation, safe read: merging, worker sync, Git exclusion, status, and cleanup
src/…/index.tsDeepSeek Harness plugin surface and default read-focused behavior
src/…/hooks.tsHarness agent, tool, and turn lifecycle bridge
src/…/tools.tsMemory search, timeline, fetch, save, and context tools
src/…/dedupe.tsContent-based result deduplication for harness search output
src/…/hook-command.tsShared hook execution and fail-open behavior
src/…/index.tsHost-to-adapter selection
src/…/CursorHooksInstaller.tsCursor hook installation, shared-config preservation, legacy cleanup, and status
src/…/install.tsCLI installation entry points for the additional hosts