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 / cowork-integration

Cowork integration

The Cowork integration connects Claude-Mem to Claude app cloud sessions through a small plugin package. It sends cleaned session activity to cmem.ai for storage and processing, then brings relevant past observations into new sessions and spawned agents. The design keeps the Cowork session usable when the cloud service is not paired or cannot be reached.

Integration contract

The integration contract is the shared agreement between Cowork hooks, the hook bridge, and cmem.ai. Cowork supplies hook event payloads; the bridge adds platform and project identity, sends capture events to the cloud service, and returns context in Cowork's hook output format.

The bridge uses the user's cmem.ai credentials. It does not run the local memory worker inside Cowork because Cowork containers are short-lived. The cloud service receives raw event envelopes for server-side processing and provides a context endpoint or a memory-search fallback for retrieval.

Contract areaShared behavior
Platform identityRequests identify themselves as Cowork and use the claude-mem-cowork plugin version.
Event envelopeCaptured events carry version 1, the cowork platform, an event name, an automatic project name, a session ID when available, a timestamp, and the event payload.
Project scopeProject names use the cmem_work_ prefix and derive from the working folder. Generic folder names map to the root project.
Capture endpointEvents go to POST /api/hooks/ingest. Failed sends wait in a private local spool and retry on a later successful send.
Retrieval contractContext first uses GET /api/hooks/context; memory search uses POST /api/mcp with the memory_search tool when the context endpoint is unavailable.
Session safetyHook errors do not fail the Cowork session. An unpaired plugin remains inactive for capture and injection.

The integration's package identity and service relationship are declared in cowork/…/plugin.json. The hook bridge defines the event envelope and HTTP contract in cowork/…/cmem-hook.mjs.

References: cowork/…/plugin.json• L1-18 cowork/…/cmem-hook.mjs• L3-18 cowork/…/cmem-hook.mjs• L196-205 cowork/…/cmem-hook.mjs• L270-279 cowork/…/cmem-hook.mjs• L355-375

Hook lifecycle

The hook lifecycle turns Cowork activity into memory and makes that memory available at the points where it can guide work. Session start retrieves background context, tool use creates observations, agent creation receives scoped prior context, and session end gives the service a final lifecycle signal.

The following diagram shows how Cowork events move through the bridge and the cmem.ai service.

flowchart LR
    A[SessionStart] --> B[Retrieve project context]
    B --> C[Inject context into session]
    D[UserPromptSubmit] --> E[Register prompt]
    F[PostToolUse] --> G[Clean and ingest observation]
    H[PreToolUse Task or Agent] --> I[Retrieve agent context]
    I --> J[Inject context into agent prompt]
    K[SubagentStop] --> L[Record subagent end]
    M[Stop] --> N[Request summary]
    O[SessionEnd] --> P[Record session end]
    E --> Q[cmem.ai]
    G --> Q
    L --> Q
    N --> Q
    P --> Q
    Q --> B
    Q --> I

The bridge strips private and system-tagged regions, limits large fields, and redacts secret-shaped values before it creates an ingest request. It skips memory-related tool calls so injected memory does not create a feedback loop. The local spool uses private file permissions and retains only a bounded set of pending events.

Cowork eventMemory roleSession effect
SessionStartRegisters the session and retrieves prior project context.Adds a bounded context block when injection is enabled.
UserPromptSubmitRecords the opening prompt for the session.No direct context output.
PostToolUseRecords tool activity and results as observations.Runs asynchronously so capture does not hold up the session.
PreToolUse for Task or AgentSearches for context related to the child prompt.Adds project-scoped observations to the child prompt.
SubagentStopRecords the end of a child-agent run.Runs asynchronously.
StopSignals that the service can summarize the session.Runs asynchronously.
SessionEndRecords the final session state and reason.Sends the last lifecycle event before exit.

References: cowork/…/hooks.json• L1-87 cowork/…/cmem-hook.mjs• L146-168 cowork/…/cmem-hook.mjs• L208-267 cowork/…/cmem-hook.mjs• L390-472

Memory search gives Cowork a direct way to answer questions about earlier work across the user's agents. The mem-search skill calls the bundled bridge CLI, which uses the configured service connection and returns search text without exposing the transport details to the user.

The skill uses a progressive search model so broad results guide a smaller and more exact follow-up search. It asks the agent to summarize the useful observations instead of showing raw service output.

  1. Run one to three broad searches using project names, file names, feature names, or error text.
  2. Narrow the search with exact terms found in the first pass and use a smaller result limit.
  3. Answer from the returned observations and include timestamps when the user asks when work happened.

The bridge can search through the purpose-built context service or the /api/mcp memory-search tool. It keeps injected fallback results within the current automatic project scope, which prevents context from another project from entering the session.

References: cowork/…/SKILL.md• L1-58 cowork/…/cmem-hook.mjs• L282-375 cowork/…/cmem-hook.mjs• L475-500

Setup and pairing

Pairing links the installed Cowork plugin to the user's cmem.ai account. The mem-setup skill collects a sync token plus optional user and SyncHub values, writes them to the plugin configuration, and checks the connection without printing the secret.

Cowork's installed copy is temporary because its container is ephemeral. A pairing that must survive a new session requires the plugin to be repackaged and installed again with the saved configuration. If a local Claude-Mem installation is present, the same cloud values can also serve the local worker through its settings file.

Setting sourcePriority and purpose
Environment variablesHighest priority. CMEM_API_KEY, CMEM_USER_ID, CMEM_SYNC_HUB_URL, and CMEM_API_BASE can supply the connection without file edits.
Plugin config.jsonNormal Cowork configuration. It holds the API base and pairing values plus injection and capture choices.
Local Claude-Mem settingsCompatibility source for shared cloud-sync values when the host also has a local installation.

The default service is https://cmem.ai. Setup treats the sync token as a bearer key and requires that it never appear in conversation, command arguments, or logs. The status check masks the key and distinguishes a missing key from an unavailable newer context endpoint.

References: cowork/config.json• L1-14 cowork/…/SKILL.md• L1-64 cowork/…/cmem-hook.mjs• L35-70 cowork/…/cmem-hook.mjs• L487-500

Configuration controls

Configuration controls whether Cowork injects memory and which tool payloads it captures. The settings change the amount and scope of integration activity without changing the event contract or the automatic project naming rule.

AreaDefaultEffect
Session-start injectionOnAdds prior project observations to a new session.
Agent injectionOnAdds prior project observations to a Task or Agent prompt.
Maximum injected context6,000 charactersBounds the context returned to the session or child agent.
Skipped toolsNone from the user listPrevents selected tool payloads from being sent. Memory and cmem tool calls are always skipped.
Project namingAutomaticUses cmem_work_root or cmem_work_<folder>; it is not a user setting.

The configuration file is the package's starting point. Environment variables can replace connection values, while the bridge keeps injection defaults enabled unless the file explicitly disables them.

References: cowork/config.json• L1-14 cowork/…/cmem-hook.mjs• L50-67 cowork/…/cmem-hook.mjs• L72-82 cowork/…/cmem-hook.mjs• L397-410 cowork/…/cmem-hook.mjs• L438-453

Cross-integration boundaries

The Cowork package is a cloud-session adapter for Claude-Mem. It shares the memory service and cloud-sync identity with other Claude-Mem clients, but its transport and lifecycle are shaped by Cowork's hook interface and ephemeral runtime.

Use the related pages for the boundaries outside this package:

References: cowork/…/plugin.json• L1-18 cowork/…/hooks.json• L1-87 cowork/…/cmem-hook.mjs• L170-192

Change checklist

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

  • Keep the event names in cowork/…/hooks.json aligned with the handler map in cmem-hook.mjs and the event names accepted by /api/hooks/ingest.
  • Preserve the v, platform, project, and session_id envelope fields when capture or server-side processing changes.
  • Keep project derivation consistent with local Claude-Mem cloud-sync naming so Cowork and local sessions share memory without crossing project boundaries.
  • Update both context retrieval paths when the service contract changes: /api/hooks/context and the /api/mcp memory_search fallback.
  • Keep setup guidance aligned with configuration precedence and with the temporary nature of edits inside Cowork containers.
  • Recheck the injection size and secret-cleaning rules before changing the fields sent in prompts or tool observations.

Important failure modes

TriggerConsequenceGuard
No API key is pairedCapture and injection stay inactive.Setup writes the key or environment variables provide it; status reports MISSING.
cmem.ai cannot be reached during ingestThe current event is stored in the private local spool for a later retry.The bridge spools failed requests and never fails the Cowork session.
The context endpoint returns 404Purpose-built context is unavailable.Retrieval falls back to project-scoped memory_search through /api/mcp.
A tool payload contains a secret or private tagSensitive content could enter memory if cleaning is bypassed.Tag stripping, size limits, and secret redaction run before ingest and retry spooling.
Project scope cannot be parsed in fallback resultsContext from another project could be injected.Unparseable or unscoped search output is treated as no data.
Pairing is written only to the installed Cowork copyThe next ephemeral container loses the connection.Repackage and reinstall the configured plugin for persistent pairing.

Key files

FileWhy to read it
cowork/…/plugin.jsonDefines the package identity and its relationship to cmem.ai.
cowork/…/hooks.jsonShows which Cowork lifecycle events activate capture and context injection.
cowork/…/cmem-hook.mjsDefines the integration contract, project scope, safety behavior, retrieval paths, and CLI checks.
cowork/config.jsonShows the default service, pairing fields, injection controls, and capture exclusions.
cowork/…/SKILL.mdExplains how an agent should search and present persistent memory.
cowork/…/SKILL.mdExplains pairing, secret handling, persistence, and connection checks.