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 area | Shared behavior |
|---|---|
| Platform identity | Requests identify themselves as Cowork and use the claude-mem-cowork plugin version. |
| Event envelope | Captured 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 scope | Project names use the cmem_work_ prefix and derive from the working folder. Generic folder names map to the root project. |
| Capture endpoint | Events go to POST /api/hooks/ingest. Failed sends wait in a private local spool and retry on a later successful send. |
| Retrieval contract | Context first uses GET /api/hooks/context; memory search uses POST /api/mcp with the memory_search tool when the context endpoint is unavailable. |
| Session safety | Hook 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 event | Memory role | Session effect |
|---|---|---|
SessionStart | Registers the session and retrieves prior project context. | Adds a bounded context block when injection is enabled. |
UserPromptSubmit | Records the opening prompt for the session. | No direct context output. |
PostToolUse | Records tool activity and results as observations. | Runs asynchronously so capture does not hold up the session. |
PreToolUse for Task or Agent | Searches for context related to the child prompt. | Adds project-scoped observations to the child prompt. |
SubagentStop | Records the end of a child-agent run. | Runs asynchronously. |
Stop | Signals that the service can summarize the session. | Runs asynchronously. |
SessionEnd | Records 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
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.
- Run one to three broad searches using project names, file names, feature names, or error text.
- Narrow the search with exact terms found in the first pass and use a smaller result limit.
- 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 source | Priority and purpose |
|---|---|
| Environment variables | Highest priority. CMEM_API_KEY, CMEM_USER_ID, CMEM_SYNC_HUB_URL, and CMEM_API_BASE can supply the connection without file edits. |
| Plugin config.json | Normal Cowork configuration. It holds the API base and pairing values plus injection and capture choices. |
| Local Claude-Mem settings | Compatibility 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.
| Area | Default | Effect |
|---|---|---|
| Session-start injection | On | Adds prior project observations to a new session. |
| Agent injection | On | Adds prior project observations to a Task or Agent prompt. |
| Maximum injected context | 6,000 characters | Bounds the context returned to the session or child agent. |
| Skipped tools | None from the user list | Prevents selected tool payloads from being sent. Memory and cmem tool calls are always skipped. |
| Project naming | Automatic | Uses 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:
- Distribution integrations explains how this adapter fits the wider distribution model.
- Plugin hooks and agent modes explains the general hook and agent behavior used by Claude-Mem.
- Installation and npx CLI explains local installation and command-line setup.
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, andsession_idenvelope 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/contextand the/api/mcpmemory_searchfallback. - 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
| Trigger | Consequence | Guard |
|---|---|---|
| No API key is paired | Capture and injection stay inactive. | Setup writes the key or environment variables provide it; status reports MISSING. |
| cmem.ai cannot be reached during ingest | The 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 404 | Purpose-built context is unavailable. | Retrieval falls back to project-scoped memory_search through /api/mcp. |
| A tool payload contains a secret or private tag | Sensitive 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 results | Context from another project could be injected. | Unparseable or unscoped search output is treated as no data. |
| Pairing is written only to the installed Cowork copy | The next ephemeral container loses the connection. | Repackage and reinstall the configured plugin for persistent pairing. |
Key files
| File | Why to read it |
|---|---|
| cowork/…/plugin.json | Defines the package identity and its relationship to cmem.ai. |
| cowork/…/hooks.json | Shows which Cowork lifecycle events activate capture and context injection. |
| cowork/…/cmem-hook.mjs | Defines the integration contract, project scope, safety behavior, retrieval paths, and CLI checks. |
| cowork/config.json | Shows the default service, pairing fields, injection controls, and capture exclusions. |
| cowork/…/SKILL.md | Explains how an agent should search and present persistent memory. |
| cowork/…/SKILL.md | Explains pairing, secret handling, persistence, and connection checks. |