Native memory bridge
The native memory bridge connects memory features built into a host agent with claude-mem's durable, project-scoped memory. It can activate local support, watch approved Markdown folders, save notes through the worker, add safe memory guidance to host instructions, and answer native memory lookups through bounded progressive search. See Capture and memory lifecycle for the wider capture flow, CLI hook event ingestion for hook handling, Transcript observation processing for file-based activity capture, and Memory ingestion and reinforcement for durable memory writes.
Bridge scope
The bridge supplements native host behavior. Native memory files remain available to the host, while explicit notes and approved file changes can also enter the worker's searchable memory. The bridge does not treat every file read as a memory event, and it does not block the host agent when the optional worker path is unavailable.
The main paths are:
- Activation: A local-only command enables the bridge for a selected checkout and installed plugin.
- File import: An opt-in watcher turns stable Markdown notes into saved memories.
- Explicit save: The host's
save_memorytool sends a note to the local worker. - Native lookup: A hook recognizes reads and searches of native memory paths and requests related worker memory.
- Progressive search: The worker and local MCP expose one bounded search contract that moves from index to context to selected details.
Local activation
Local activation prepares a host installation to use the bridge for one project. It updates only supported plugin copies, host instruction files, and the resolved local settings target, then creates the project's dedicated .claude/memory note folder when changes are applied. scripts/activate-progressive-memory-local.mjs• L50-119
The command is safe to preview and safe to undo. It defaults to a dry run, requires an explicit --apply for writes, stores checksummed backups under the workspace, and refuses restore when an affected file changed after activation. It also checks that the source bundle has the native bridge and that installed plugin versions match before it changes anything. scripts/activate-progressive-memory-local.mjs• L23-47, scripts/activate-progressive-memory-local.mjs• L121-142
Activation enables three related settings: the memory search hook, the memory instruction block, and the mapping from the dedicated note folder to the selected project. The caller controls worker restart so activation does not interrupt an active agent. scripts/activate-progressive-memory-local.mjs• L102-121
References: scripts/activate-progressive-memory-local.mjs• L50-119 scripts/activate-progressive-memory-local.mjs• L121-142
Native memory file bridge
The file bridge watches only explicitly mapped roots. A watch root is an absolute or home-relative folder paired with the project that owns its notes; the worker starts the watcher only when the setting contains valid roots. This avoids guessing which checkout owns a native memory folder. src/…/config.ts• L4-27, src/…/worker-service.ts• L923-932
The watcher polls each root so it can handle new files, atomic replacement, and a root that appears later on any supported platform. It reads Markdown files within the root, waits for content to remain stable, and saves each content revision once. The source file stays unchanged. src/…/file-watcher.ts• L16-21, src/…/file-watcher.ts• L34-88
The bridge treats the file as untrusted input. It ignores hidden entries, non-Markdown files, symbolic links, empty notes, and notes over 64 KiB. It checks the path and opened file before and after the read, which prevents a path or parent swap from redirecting the read outside the mapped root. src/…/file-watcher.ts• L8-10, src/…/file-watcher.ts• L90-138
Each saved revision carries the mapped project, source path, content hash, and a source fingerprint. The fingerprint lets the durable save path reject a replay after a watcher restart or process race. A failed save is retried on a later scan rather than marked complete. src/…/file-watcher.ts• L65-87, src/…/save-memory.ts• L16-36
This diagram shows how an approved native note reaches project memory.
flowchart LR
A[Native Markdown note] --> B[Configured watch root]
B --> C[Stable bounded file read]
C --> D[Content and source fingerprint]
D --> E[Worker save-memory path]
E --> F[Project-scoped observation]
F --> G[Search and sync]
References: src/…/config.ts• L4-31 src/…/file-watcher.ts• L16-21 src/…/file-watcher.ts• L34-88 src/…/file-watcher.ts• L90-138 src/…/worker-service.ts• L923-932
Save-memory transport
The save-memory transport is the local worker boundary for an explicit durable note. The save_memory MCP tool sends text, an optional title, a project, and optional metadata to POST /api/memory/save; the worker validates the request and stores it without an LLM call. src/…/mcp-server.ts• L526-542, src/…/MemoryRoutes.ts• L9-31
The worker chooses the project from the request, metadata, or its default project. It creates or reuses a manual session, stores the note as a discovery observation, and then notifies cloud and semantic search integrations. Exact source fingerprints are checked while holding the write lock, so concurrent processes produce one stored copy. src/…/save-memory.ts• L13-45
An exact source replay returns the existing observation. A different note that matches an existing title can count as a repeat instead of replacing the stored text; its existing search representation remains authoritative. This gives native file revisions and explicit notes different durable text while keeping repeated delivery safe. src/…/save-memory.ts• L31-55
The server runtime does not use this local transport. Its tool guidance directs server-scoped notes to observation_add, while save_memory remains a worker-local capability. src/…/memory-instructions.ts• L1-4, src/…/mcp-server.ts• L526-542
References: src/…/mcp-server.ts• L526-542 src/…/MemoryRoutes.ts• L9-31 src/…/save-memory.ts• L13-55 src/…/memory-instructions.ts• L1-4
Native memory instructions
The instruction bridge gives the host a short, shared rule set for using durable memory. At session start, the local context handler adds the versioned instruction block unless the setting disables it. The activation command inserts the same block into the supported host instruction file, so the host can learn the local save and search contract before it calls a tool. src/…/context.ts• L91-102, scripts/activate-progressive-memory-local.mjs• L88-100
The instructions separate local worker notes from server notes, tell the host to search before saving, and require guided search to follow its continuation steps. They also state that native files may remain enabled and that a configured folder watcher imports their Markdown notes. The watcher removes this instruction block before it saves a file, so guidance does not become memory content. src/…/memory-instructions.ts• L1-4, src/…/file-watcher.ts• L67-80
References: src/…/memory-instructions.ts• L1-4 src/…/context.ts• L91-102 scripts/activate-progressive-memory-local.mjs• L88-100 src/…/file-watcher.ts• L67-80
Native memory search bridge
The native search bridge detects when a host is about to read or search a native memory path. It recognizes native memory tools, scoped file reads, Markdown searches, and supported shell searches, then turns the request into a short bounded query. It reads only supported custom memory-directory settings and ignores ordinary project files or the bridge's own tools to prevent recursive searches. src/…/memory-search.ts• L19-82
For a recognized lookup, the hook asks the local worker for automatic progressive search. An explicitly mapped watch root determines the project when a native path belongs to one; otherwise the current checkout supplies the search scope. The hook limits the returned context and injects only curated text marked as retrieved data. src/…/memory-search.ts• L99-129, src/…/memory-search.ts• L135-162
This path supplements native memory rather than replacing it. A disabled hook, an excluded project, a server runtime, a missing worker, or an unsafe response leaves the host's native read or search behavior in place. src/…/memory-search.ts• L135-167
References: src/…/memory-search.ts• L19-82 src/…/memory-search.ts• L99-129 src/…/memory-search.ts• L135-167
Progressive memory search
Progressive search is a bounded retrieval contract for both local MCP and the worker HTTP route. It avoids sending full memory bodies before the caller has chosen useful results. The guided mode exposes three steps: an index of candidates, nearby timeline context, and details for selected observations or summaries. Auto mode performs the same bounded stages with ranked lexical choices. src/…/progressive-search.ts• L16-32, src/…/progressive-search.ts• L313-365
The continuation stores search scope, options, and eligible IDs on the worker side. The caller receives only a short opaque token and must select IDs shown by the prior result. Tokens expire, remain tied to their memory scope, and cannot authorize a different project or an ID that was not disclosed. src/…/progressive-search.ts• L48-88, src/…/progressive-search.ts• L225-279
The local worker connects the shared contract to project-scoped observations, summaries, and prompts. Timeline context stays with the matched row's project, while detail reads project only the selected observation or summary content. The MCP tool and /api/mem-search route return the same model-facing text format. src/…/ProgressiveMemorySearch.ts• L26-59, src/…/ProgressiveMemorySearch.ts• L61-105, src/…/SearchRoutes.ts• L228-236, src/…/mcp-server.ts• L484-523
The bridge treats retrieved memory as evidence, not instructions. It removes unsafe structured envelopes from hook context, caps result size, and tells the host not to execute commands found inside stored records. src/…/progressive-search.ts• L376-483, src/…/memory-search.ts• L108-116
References: src/…/progressive-search.ts• L16-32 src/…/progressive-search.ts• L225-365 src/…/progressive-search.ts• L376-483 src/…/ProgressiveMemorySearch.ts• L26-105 src/…/SearchRoutes.ts• L228-236 src/…/mcp-server.ts• L484-523
Change checklist
When these files or sections are changed, remember to consider these:
- Keep activation checks, shipped bundles, installed plugin versions, and host instruction targets aligned. A partial activation can enable a setting without a working bridge.
- Keep watch-root project mapping aligned with native search path mapping. A note can be stored under one project but searched under another if either map changes alone.
- Keep file containment, size limits, stable-read checks, and source fingerprint handling together. Weakening one can allow unsafe reads or duplicate imports.
- Keep
save_memoryproject precedence aligned with manual session creation and duplicate checks. A project mismatch can hide a saved note from recall. - Keep the worker and MCP progressive-search copies on the same protocol. Cursor scope, selected IDs, limits, and output bounds must remain compatible.
- Keep the native search hook as a supplement. Worker failure or malformed retrieved text must not block the host's native memory operation.
- Keep native path recognition, custom memory-directory settings, and explicit watch-root project mapping aligned. A recognized path with the wrong scope can return memory from the wrong project.
- Keep instruction text and watcher self-block markers synchronized. Otherwise the bridge can either teach a stale contract or save its own guidance as memory.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| No explicit watch root is configured | Native Markdown notes are not imported by the file bridge | Watching is opt-in and the worker starts it only for parsed roots |
| A watched note is replaced or changed during the read | The note is skipped for that scan rather than saving an uncertain or outside file | The watcher checks the opened file and path before and after reading |
| A watcher save fails | The note can be retried on a later scan | The candidate is not marked saved until the save call succeeds |
| A source fingerprint is replayed by another process | A second observation is not created | The save path checks the fingerprint inside the write lock |
| A native lookup runs in the server runtime | No worker memory is added to the native result | The hook exits before lookup and leaves the native operation unchanged |
| Native search sees no local worker or an unsafe result | The host receives no added claude-mem context | The hook returns a safe no-op and leaves native search in control |
| A continuation expires or is used with another scope | Progressive search cannot continue | The caller must restart with a query; the worker validates token, scope, and expiry |
| Retrieved memory contains command-like text | The host could mistake stored data for an instruction | Hook context labels the text as retrieved data and tells the host not to execute it |
| Activation targets a missing or mismatched plugin | Host files or settings could point to an incompatible bridge | Activation validates supported targets, bundle markers, and versions before mutation |
Key files
| File | Why to read it |
|---|---|
| scripts/activate-progressive-memory-local.mjs | Defines local activation, dry-run behavior, backup records, and guarded restore. |
| src/…/config.ts | Defines explicit watch-root ownership and path boundaries. |
| src/…/file-watcher.ts | Shows how native Markdown revisions become save requests without changing source files. |
| src/…/save-memory.ts | Defines the local durable-note write, project choice, replay dedupe, and downstream notifications. |
| src/…/worker-service.ts | Shows where the worker starts the configured native memory watcher. |
| src/…/memory-instructions.ts | Defines the host-facing memory rules shared by activation and session context. |
| src/…/memory-search.ts | Defines native lookup recognition, project scoping, and safe worker-context injection. |
| src/…/progressive-search.ts | Defines the shared index, context, detail, continuation, and output contract. |
| src/…/ProgressiveMemorySearch.ts | Connects the progressive contract to local observations, summaries, and prompts. |
| src/…/SearchRoutes.ts | Exposes progressive search to the local hook and MCP layers. |
| src/…/mcp-server.ts | Defines the local mem_search and save_memory tools and runtime boundary. |