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 / capture-and-memory

Capture and memory lifecycle

The capture and memory lifecycle turns coding-agent activity into project-scoped memory that engineers can search and receive in later work. It accepts hook events, transcript activity, direct memory notes, and related media. It keeps the host session responsive while local or remote workers normalize, retain, and index accepted data.

Capture paths

The system accepts activity through host hooks and transcript processing. Each host is mapped to one shared input shape before project, session, privacy, and activity rules run.

CLI hook capture

The CLI hook path handles events that a coding environment sends directly. Platform adapters preserve the host's session, project, prompt, tool, result, transcript, and agent identity in a common contract. The adapter set includes Gemini and Codex and keeps host-specific MCP names, shell actions, failed tool results, and transcript paths distinct enough for later filtering and recall.

Codex requires a valid session and working directory. Its adapter accepts only known hook events and can add the files affected by a pre-tool action to the shared tool input. It also preserves bounded agent identity and session-source data so context recovery and subagent activity remain tied to the right thread.

Cursor can recover a transcript from its workspace and conversation identity when the host does not send a path. Gemini requires a valid session and maps its tool names into the shared vocabulary. Windsurf keeps the MCP server in the tool identity so the system can block its own memory calls without blocking unrelated tools.

The hook boundary is non-blocking. A durable local spool or a bounded live handoff lets the host continue while the worker receives the event. Invalid input, missing dependencies, and unexpected capture errors return a host-valid no-op instead of blocking the agent. Claude Code can also restore the tail of a large persisted Bash result, so the observer receives final errors or summaries without exceeding the existing field bound. See CLI hook event ingestion.

Explicit memory writes use the direct memory path rather than becoming a second ordinary tool observation. File edits use the observation path and therefore remain part of the same searchable activity history.

References: src/…/hook-command.ts• L73-95 src/…/hook-command.ts• L97-199 src/…/index.ts• L12-26 src/…/claude-code.ts• L67-111 src/…/claude-code-persisted-output.ts• L8-67 src/…/codex.ts• L68-115 src/…/cursor.ts• L23-74 src/…/gemini.ts• L5-61 src/…/windsurf.ts• L4-79

Transcript capture

The transcript path reads local JSONL records for environments that do not expose every event through hooks. A watcher sends new records to a processor, which maps them to session starts, prompts, tool activity, file edits, observations, summaries, and closeout events. See Transcript observation processing.

The hook and transcript paths converge before retention. Both use the same project and session boundaries, so an event source changes the way activity is found but not the memory model.

References: src/…/watcher.ts• L14-83 src/…/processor.ts• L40-102 src/…/processor.ts• L243-272

Media retention

Media attachments extend an accepted observation with stable references to related images. Capture accepts bounded inline data or a trusted project file. Private-tagged media is removed from the capture path before its pixels are read, stored, uploaded, or sent to the observer.

The local store keeps converted viewer and model copies. It identifies replayed input from its event and source identity, publishes both copies as one ready asset, and checks their size and checksum when read. A failed or abandoned conversion becomes a retryable cleanup state. A second device can hold an unresolved replica until verified converted bytes arrive. Cloud upload and second-device resolution run beside text retention, so an image outage leaves the text observation searchable. See Media artifact lifecycle.

References: src/…/capture.ts• L198-237 src/…/capture.ts• L239-332 src/…/converter.ts• L198-303 src/…/store.ts• L29-45 src/…/store.ts• L62-124 src/…/store.ts• L138-219 src/…/store.ts• L222-267 src/…/cloud.ts• L285-341

Observation acceptance

An observation is a project-scoped record of useful agent activity. Capture does not guarantee retention. The system first checks that the event belongs to a tracked project and that its source, tool, content, and agent state are allowed.

The acceptance boundary applies the same safeguards to server and local routes:

  • Missing tool data is ignored.
  • Recursive memory tools do not create new observations.
  • Excluded projects and configured tools are skipped.
  • Configured subagent activity can be skipped before worker, server, or provider work.
  • Explicit memory writes stay separate from ordinary observation generation.
  • Large media fields are bounded before dispatch.

Accepted activity uses the selected runtime. The server records an event directly. A local route writes a durable spool entry before it nudges the worker. A recoverable server failure can use the worker route for eligible events. A non-recoverable failure stays non-blocking but does not claim that the event was saved. See Remote worker capture.

The hook command also keeps the host contract valid when capture is disabled or input is rejected. It emits the platform's no-op response and exits without denying the tool, changing its arguments, or turning a capture fault into a blocked session.

References: src/…/observation.ts• L30-49 src/…/observation.ts• L52-100 src/…/observation.ts• L103-149 src/…/hook-command.ts• L109-134 src/…/hook-command.ts• L146-199 src/…/spool-hook-event.ts• L23-82

Session and turn boundaries

Session identity links prompts, tool activity, summaries, media, and project scope. Platform source remains part of that identity so similar external session IDs from different environments do not mix.

Prompt capture is anchored at the host's user-submit event. A submitted prompt takes precedence over fields that can also carry tool results. An explicit empty submitted prompt means that the event is not a user turn. A missing field follows host-specific rules. Continuation and internal protocol events are rejected so helper work does not become a false prompt. See CLI hook event ingestion.

At prompt start, the selected runtime creates or initializes the project session. For a sufficiently long prompt, it can add bounded semantic context from related observations. A failed context lookup does not block the prompt. Hosts without a dedicated prompt event can use a pre-invocation event for the first prompt and later calls for file context.

Summary handling closes a turn with the last assistant message and session metadata. It can also capture opted-in advisor calls and project deliverables. Deliverables are person-facing files declared by the agent or inferred from safe writes outside the source tree. Local capture copies safe files into the project bucket and spools their records. See Media artifact lifecycle for media files and Historical session and owner-prompt import for older activity.

Session-end and subagent-stop are separate local closeout signals. They ignore missing or untracked identities, then spool completion without waiting for the worker. Fresh and forked subagents receive different context treatment so a fork does not receive a duplicate timeline.

References: src/…/claude-code.ts• L56-108 src/…/antigravity-cli.ts• L128-181 src/…/session-init.ts• L139-225 src/…/session-init.ts• L234-340 src/…/summarize.ts• L107-180 src/…/summarize.ts• L185-270 src/…/deliverables-capture.ts• L23-46 src/…/deliverables-capture.ts• L249-338 src/…/index.ts• L141-178

Compaction recovery

Compaction recovery restores memory context after a host replaces a thread's history. A compaction hook marks the thread. The next context-capable event supplies the timeline once, while the event's observation is recorded first.

This diagram illustrates how compaction marks a thread and how the next eligible event restores its memory timeline.

flowchart LR
    A[Thread compaction] --> B[Mark context pending]
    B --> C{Next eligible event}
    C -->|Root start| D[Context handler]
    C -->|Subagent tool event| D
    C -->|Fresh subagent start| D
    D --> E[Return timeline once]

Kimi clears its one-shot marker only at compaction. Codex uses a post-compaction marker because subagent threads do not receive the root start event. The context handler clears the Codex marker when it returns the re-injected timeline. See Automatic context clearing.

References: src/…/index.ts• L105-137 src/…/codex-compaction-gate.ts• L1-38 src/…/codex.ts• L5-22 src/…/context.ts• L311-333 src/…/context.ts• L445-451 src/…/summarize.ts• L138-145 src/…/subagent-context.ts• L49-63

Memory retention

Accepted activity becomes durable memory after processing. The local worker keeps a short-lived handoff before an observer turns raw activity into structured observations and summaries. Direct memory writes use the same project-scoped store without an LLM call. See Direct memory ingestion and reinforcement.

The same direct path can import already distilled local memory. Supported markdown memory files become observations without another model pass. The import stays inside the allowed Claude Code project tree, skips the link-only MEMORY.md index, and uses content deduplication so repeated runs do not create duplicate knowledge. It ignores symlinked notes and oversized files. It reads sibling transcript records until it can resolve the original checkout, even when a record is larger than one read chunk. It uses a best-effort project key when no sibling transcript resolves the original checkout. The CLI can scan one memory directory or all project directories with a no-write dry run before storage. See Historical session and owner-prompt import.

The retained record keeps project, session, source, searchable text, and related media references. A spool entry or worker handoff is not searchable memory. Searchable memory exists only after the retention path stores the observation and updates its search index.

References: src/…/file-watcher.ts• L17-22 src/…/file-watcher.ts• L49-89 src/…/cli.ts• L23-102 src/…/ingest.ts• L17-23 src/…/ingest.ts• L296-345 src/…/ingest.ts• L364-420 src/…/ingest.ts• L421-484 src/…/ingest.ts• L517-583 src/…/ingest.ts• L624-753 src/…/save-memory.ts• L9-23 src/…/save-memory.ts• L25-76

Project-local activity views

Retained observations can become a bounded generated activity section in project CLAUDE.md files. The view groups recent observations by day and related file, replaces only its tagged block, and leaves authored content intact. Cleanup removes generated blocks without removing unrelated content.

References: src/…/claude-md-commands.ts• L203-233 src/…/claude-md-commands.ts• L255-332 src/…/claude-md-commands.ts• L430-465 src/…/claude-md-commands.ts• L500-584

Search and context delivery

Search turns retained memory into context for later coding work. Session-start handlers request a bounded project context and return it through the host's model context channel. The selected runtime, cache, and worker fallback determine where the read comes from.

The context request normally uses the current checkout. A local worker can include other tracked projects when configured. Platform-source filtering keeps context separate by host unless a setting requests all sources. Excluded projects are suppressed on the read path as well as the write path. Output limits keep memory, notices, and team information inside the host's delivery budget. A worker outage can use an eligible cache; a server read failure does not substitute stale local rows.

The server runtime reads the shared server directly, while the worker runtime can use a precomputed local context cache or a live worker request. This keeps reads aligned with the runtime that accepted writes. Codex receives the timeline through its model-context field rather than a duplicate terminal message, which protects the host hook output limit.

File reads can receive a compact history of prior observations. The file path is checked in absolute, project-relative, and home-relative forms. A durable local gate injects a file timeline once per session and file, then allows it again after a newer observation. Large parseable whole-file reads can be directed to structural or targeted reads, while uncertain checks fail open. Native memory search takes precedence over file history and returns bounded observation IDs rather than full records. See Native memory bridge.

User-message delivery can show the current context as a host-visible banner. Claude Code can place the repeated timeline portion in a session-start card while keeping notices and the closing link in the hook message, which avoids repeated hook labels in mirrored views. Kimi combines session initialization with context delivery because its host does not append SessionStart output. Antigravity uses pre-invocation inspection to choose prompt capture or file context. The context handler fits notices, team briefs, and memory into the host field limit without cutting a rendered timeline entry. See Automatic context clearing.

References: src/…/context.ts• L242-270 src/…/context.ts• L311-345 src/…/context.ts• L445-529 src/…/context.ts• L547-585 src/…/context.ts• L608-672 src/…/file-context.ts• L372-487 src/…/file-context.ts• L511-638 src/…/memory-search.ts• L138-183 src/…/user-message.ts• L16-59 src/…/index.ts• L38-101

Change checklist

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

  • Keep every platform adapter aligned with the normalized hook contract. New host fields must still preserve project, session, prompt, tool, result, and media identity.
  • Keep Codex event names, session validation, file-path extraction, and output formatting aligned with the host hook contract.
  • Keep host tool identities and MCP server identities aligned with recursive-memory filtering. A new host spelling must not turn a memory lookup into a stored observation.
  • Keep failed tool responses distinct from absent and empty submitted prompts. These states affect both failure records and turn anchoring.
  • Keep server, worker, live handoff, and durable spool routing aligned. A failed route must not claim persistence.
  • Keep Claude Code's persisted-output recovery inside its trusted project results path and within the observer field budget. A read failure must preserve the original bounded result.
  • Keep project, source, privacy, recursive-memory, and subagent filters ahead of every observation and media entry point.
  • Keep media replay identity, source checks, variant checksums, and cleanup states aligned. A replay must reuse an attachment, while changed bytes at the same path must not reuse old media.
  • Keep private media out of local storage, cloud upload, and observer requests.
  • Keep session and platform identity consistent across observations, summaries, direct writes, media, subagents, deliverables, and context reads.
  • Keep watched memory files inside configured roots and preserve their project mapping. A changed file must create a new searchable revision.
  • Keep imported memory limits, index exclusion, symlink handling, and content deduplication aligned with the direct observation store.
  • Keep direct-memory replay deduplication scoped by both project and normalized platform source. A note from one coding environment must not suppress the same note from another environment.
  • Keep generated CLAUDE.md blocks bounded and tagged. Folder matching must not overwrite authored content.
  • Keep native memory lookup ahead of file history. A native result must not cause a second context response.
  • Keep compaction markers one-time and attached to the hook that can return context. Recovery must not block the observation that triggers it.
  • Keep fresh and forked subagent behavior distinct. A fork must not receive duplicate context.
  • Keep context output within host limits. An empty or failed read must not consume a one-shot injection marker.

Important failure modes

TriggerConsequenceGuard
A host sends an invalid project path or session identityActivity cannot be linked to project memory.Adapters validate identity and path before normalization completes.
A host omits a required session or sends an unsafe transcript identityThe hook cannot safely find or group activity.The adapter rejects the input or derives only a validated local transcript path.
A failed tool event has no normal resultThe stored activity can lose its failure or interruption state.Adapters convert host failure fields to the shared result shape.
A follow-up model call is treated as a new promptMemory gains false user turns and later observations shift.Adapters preserve submitted-prompt presence and host turn signals.
A memory MCP call uses a host-specific tool spellingThe system can record its own search as new activity.Adapters normalize known MCP server names before the recursion gate.
A project or tool is excludedActivity is not retained or returned as context.Shared filters run before worker, server, provider, or context work.
A server or worker route failsThe host continues, but the event may not be saved.Hooks return a no-op and only claim persistence after an accepted handoff.
A remote spool upload lacks a token or exact receiptEvents remain local and are retried later.The outbox is kept until the remote worker accepts the matching receipt.
A memory file is outside its configured root or changes during a readUnsafe or partial text is not imported.The watcher checks location, file identity, size, and content stability.
An imported memory file is symlinked, oversized, empty, or has no usable project matchThe note is skipped or may be assigned to a best-effort project key.Ingest stays inside the projects root, refuses symlinks and large files, skips empty bodies, and reports unresolved project mapping.
A direct memory write is replayed after checkpoint lossThe same note could be stored twice.A project-scoped source fingerprint is checked under the write lock.
A direct memory note is replayed from a different coding environmentA valid note can be incorrectly treated as an existing replay.Replay fingerprints are matched by project and normalized platform source.
Claude Code stores only the head of a large Bash result in the hook payloadThe observer can miss the final error or test summary.The adapter reads the trusted persisted result and restores its tail within the existing bound.
An image is private, invalid, too large, or unavailableText memory remains searchable without the image.Capture records a bounded media status and isolates media failure from observation storage.
A media conversion stops or its files fail checksum validationThe attachment stays unavailable and temporary files can remain.Conversion leases, atomic publication, checksums, and bounded cleanup reconcile the asset.
Cloud media upload or replica download failsThe image remains pending while local text and references remain usable.Durable media queues retry transient failures with backoff and verify checksums.
Codex compaction replaces thread historyThe prior timeline disappears from the thread.A pending marker causes one re-injection on the next eligible event.
File history is stale, unavailable, or slowNo timeline is added, but the host read continues.The lookup uses a short budget and fails open.
A full-file read cannot use smart toolsThe host could be blocked without a usable replacement.Unsupported files, uncertain checks, and unavailable parsers allow the read.
Context plus notices exceed a host field limitThe host can discard the whole context response.The handler reserves space and omits or fits whole rendered sections before delivery.

Key files

FileWhy to read it
src/…/hook-command.tsShows the shared hook boundary, output contract, and graceful failure behavior.
src/…/hook-entry.tsShows the lightweight hook process used for frequent events.
src/…/run-hook-subcommand.tsShows the common hook subcommand used by hook and worker entry points.
src/…/types.tsDefines the normalized input and host output contracts.
src/…/index.tsShows how supported coding environments select a shared adapter.
src/…/codex.tsShows Codex event validation, file-context normalization, session identity, and output formatting.
src/…/gemini.tsShows Gemini session, tool, MCP, and output normalization.
src/…/cursor.tsShows Cursor transcript recovery and failed tool response mapping.
src/…/windsurf.tsShows Windsurf action and MCP identity mapping.
src/…/claude-code.tsShows how common Claude-compatible payloads become shared hook input.
src/…/claude-code-persisted-output.tsShows how large Claude Code tool results retain their final lines without expanding the hook field.
src/…/antigravity-cli.tsShows how a host without a prompt-submit hook separates turns and file context.
src/…/observation.tsShows the shared acceptance boundary and event routing.
src/…/session-init.tsShows prompt anchoring, session start, and prompt-time context.
src/…/summarize.tsShows turn closeout, advisor capture, deliverables, and summary routing.
src/…/deliverables-capture.tsShows how safe person-facing files become project deliverables.
src/…/spool-hook-event.tsShows durable handoff, live delivery, worker nudging, and remote upload.
src/…/context.tsShows how retained memory becomes bounded host context across worker and server runtimes.
src/…/file-context.tsShows file-history lookup, read gating, and context delivery.
src/…/memory-search.tsShows native memory search supplementation.
src/…/cli.tsShows single-source, all-project, and dry-run entry points for native memory import.
src/…/save-memory.tsShows direct memory persistence and replay deduplication.
src/…/file-watcher.tsShows configured local markdown memory import.
src/…/ingest.tsShows safe scanning and mechanical import of already distilled memory files.
src/…/capture.tsShows the boundary between observations and retained media.
src/…/store.tsShows media states, replay identity, variants, replica resolution, and cleanup.
src/…/inference.tsShows bounded image delivery to the observer.
src/…/cloud.tsShows optional cloud upload, replica resolution, and retry behavior.
src/…/converter.tsShows the conversion contract for viewer and model variants.