Native harness integrations
Native harness integrations connect Claude-Mem to hosts that can load a plugin or extension directly. The DSH plugin and Pi extension provide memory recall and session hooks through a shared local worker. The T3 Code installer registers Claude-Mem with the native Codex or Claude provider that T3 Code launches. See Distribution integrations for the wider integration map and Plugin hooks and agent modes for the shared hook model.
Integration model
Each host keeps its own session and tool model. Claude-Mem adapts to that model at the host boundary, then sends memory requests to the local worker instead of creating a second memory store. This keeps recall, context, and capture aligned with the worker used by the main product.
| Host path | Host-facing role | Worker handoff |
|---|---|---|
| DSH plugin | Adds memory tools, a search skill, context injection, optional tool-result capture, and optional turn summaries. | Direct local HTTP requests from the plugin. |
| Pi extension | Adds recall tools and manages prompt, tool, and summary events for a Pi session. | A queued local HTTP client with session identity from Pi. |
| T3 Code installer | Registers Claude-Mem with each enabled native provider used by T3 Code. | The provider runs the normal Claude-Mem plugin or Codex plugin path. |
The host remains responsible for its own approval, session, and launch rules. The integration supplies the memory capability without taking ownership of the host's agent runtime.
Shared worker handoff
The shared worker handoff gives the DSH plugin and Pi extension one local service boundary. src/…/harness-worker.ts resolves a per-user address from environment values, persisted settings, or a user-specific default, then uses bounded health checks and requests.
Worker address
The worker address is a host contract rather than a fixed port. resolveHarnessWorkerUrl() reads CLAUDE_MEM_WORKER_HOST and CLAUDE_MEM_WORKER_PORT, with settings-file values and per-user defaults as fallbacks. IPv6 host values are formatted for HTTP URLs. References: src/…/harness-worker.ts• L10-28
Worker lifecycle
The client checks the worker before use and starts it only when the connection is refused. Startup uses the installed marketplace files under the Claude configuration directory, never the current source checkout. A shared in-flight startup promise prevents parallel host events from starting more than one worker. References: src/…/harness-worker.ts• L30-80
Both native integrations use the worker's HTTP boundary for context, search, observation, session initialization, and summaries. A worker error is therefore visible at the host boundary, while context injection and background capture can remain best effort where the host must not be blocked.
DeepSeek Harness plugin
The DSH plugin is a self-contained host adapter named claude-mem. Its public contract uses the DSH context to register tools and skills and to observe agent lifecycle events. src/…/index.ts resolves configuration, creates the worker client, and attaches the host-facing features. References: src/…/index.ts• L13-23, src/…/sdk-contract.ts• L1-17
DSH host contract
The plugin depends on three host capabilities: event subscription, tool registration, and skill registration. It also uses the host agent's session working directory and injection method to seed context. The host supplies these runtime objects; the plugin does not bundle a DSH runtime. References: src/…/sdk-contract.ts• L6-17, src/…/hooks.ts• L27-34
DSH memory tools
The plugin exposes search, timeline, full observation lookup, manual save, and rendered context. Search and timeline return a small index first, so the agent can fetch full observations only when needed. Requests can carry project and platform filters, while result handling normalizes worker responses and removes duplicate query content by default. References: src/…/tools.ts• L136-143, src/…/tools.ts• L145-185, src/…/worker.ts• L73-115, src/…/worker.ts• L148-161
DSH lifecycle hooks
The plugin injects session-start context through agent/created. Optional hooks save selected successful tool results and summarize a session when a turn stops. These write paths are disabled by default, so a plain installation can read existing memory without automatic capture or summaries. The platform value is a signal for filtering, not a hard access boundary. References: src/…/hooks.ts• L27-48, src/…/hooks.ts• L50-109, src/…/index.ts• L31-64
DSH installation
The DSH installer adds the first-party package to one or more DSH profiles and adds a managed transcript watch for the DSH session directory. It records ownership before changing the profile, rolls that state back when the external install fails, and avoids adding a second DSH writer when an existing DSH watch is authoritative. After installation, DSH must restart to load the plugin and the worker must start or restart to load the watch. References: src/…/DeepSeekHarnessInstaller.ts• L22-64, src/…/DeepSeekHarnessInstaller.ts• L89-135
Pi extension
The Pi extension uses Pi's event API to provide memory tools and to connect a Pi session to the worker. It keeps one current session with a serial queue, which preserves the order of prompt capture, tool observations, and summaries. References: src/…/index.ts• L10-70, src/…/index.ts• L81-94
Pi host contract
Pi supplies event hooks, tool registration, the current working directory, and a session manager. The extension gets the current session ID from that manager, then uses the active branch's persisted user entry to identify the prompt being processed. Pi's session-start event carries a reason rather than a session ID, so the extension does not infer prompt identity from that event. References: src/…/index.ts• L23-57, src/…/index.ts• L95-115, src/…/index.ts• L153-168
Pi session capture
The extension loads context when a session starts, switches, or forks. Before a request is captured, it waits for Pi to persist the user entry, confirms that the active branch still matches the request, and initializes the worker with that entry's identity. It injects memory into the system message only when the worker accepts the current turn. This prevents observations from attaching to a different prompt when a session changes or an older branch is retried. References: src/…/index.ts• L95-129, src/…/index.ts• L135-231
Successful tool results then become observations, and the last assistant message is summarized at agent end, before compaction, or at shutdown. A serial queue keeps prompt capture, tool results, and summaries in order. The extension captures text blocks only, so image-only turns do not enter automatic text capture. If the worker is unavailable, Pi receives one warning and the host can continue without memory capture for that session. References: src/…/index.ts• L72-79, src/…/index.ts• L233-267
Pi memory tools
Pi exposes mem_search, mem_timeline, and mem_get_observations. The tool contract follows a staged recall pattern: find useful IDs, inspect their time neighborhood, then request full records. Errors return as tool text so the Pi agent can handle a failed memory request as part of its turn. References: src/…/index.ts• L269-310
Pi installation
The Pi installer copies a validated extension bundle and its required license and provenance files into Pi's extension directory. It replaces only Claude-Mem-owned files and removes only those files during uninstall. Installation reports manual recall as supported, but it does not prove automatic capture compatibility; the supported capture versions are source-reviewed separately. References: src/…/PiInstaller.ts• L8-13, src/…/PiInstaller.ts• L15-55, src/…/PiInstaller.ts• L57-86
T3 Code provider registration
T3 Code delegates work to native Codex or Claude providers. Its installer discovers those providers from T3 Code settings and registers the matching native Claude-Mem or Codex plugin in each provider home. T3 Code does not receive a separate memory database or transcript writer. References: src/…/T3CodeInstaller.ts• L1-4, src/…/T3CodeInstaller.ts• L20-35
Provider discovery
Provider discovery resolves the T3 Code settings file, prefers explicit provider instances over legacy entries, and carries each provider's home, environment, command, and launch arguments into setup. It can infer built-in Codex and Claude providers when T3 Code has not saved their default entries, but only uses an inferred provider when its home exists. Disabled providers are skipped during install and included during removal so the installer can clean up its own setting. Managed Codex installations use T3 Code's active executable, while a missing inferred CLI is skipped rather than treated as a requested provider error. References: src/…/T3CodeInstaller.ts• L55-61, src/…/T3CodeInstaller.ts• L81-149, src/…/T3CodeInstaller.ts• L189-198
Provider loading contract
The installer rejects launch settings that suppress the user settings source, plugin MCP, hooks, or Claude-Mem itself. This check protects the contract that the native provider can load the plugin and its hooks. It also checks that the registered plugin has its marketplace, worker, MCP, and host-specific hook assets before status reports success. Codex plugin setup requires a marketplace-capable CLI, and the installer verifies that Codex lists the plugin after setup. References: src/…/T3CodeInstaller.ts• L151-170, src/…/T3CodeInstaller.ts• L200-240, src/…/CodexCliInstaller.ts• L429-450, src/…/CodexCliInstaller.ts• L674-700
Codex hook registration
Codex receives Claude-Mem hooks through the provider home's hooks.json. The installer derives event names, matchers, and timeouts from the bundled hook definitions, then replaces only Claude-Mem commands with the stable claude-mem launcher. This keeps hook approval tied to the hook declaration instead of the full plugin bundle, so normal plugin updates do not require approval again. Before writing, the installer checks that the existing hook file can be merged. References: src/…/codex-user-hooks.ts• L69-107, src/…/codex-user-hooks.ts• L116-180, src/…/CodexCliInstaller.ts• L542-558
T3 Code installation
Installation validates the main bundle before changing provider homes, then checks provider launch flags before making any changes. It installs the Codex plugin, enables its hooks, and registers user-level hook commands. Codex setup repairs a stale local marketplace registration when needed, removes legacy global context paths and old plugin-managed MCP search settings, and confirms that the plugin is visible after installation. Duplicate provider homes are handled once, while an inferred provider with no CLI is skipped rather than treated as a user setup error. Removal discovers providers without filtering disabled entries and disables only Claude-Mem, leaving native provider configuration and shared CLI homes in place. T3 Code must restart and start a new thread before the provider loads the change. References: src/…/T3CodeInstaller.ts• L243-299, src/…/T3CodeInstaller.ts• L307-335, src/…/CodexCliInstaller.ts• L321-358, src/…/CodexCliInstaller.ts• L395-413, src/…/CodexCliInstaller.ts• L614-670, src/…/CodexCliInstaller.ts• L702-759
Host boundaries
These integrations share memory behavior but not host lifecycle semantics. DSH starts from an agent-created event, Pi binds capture to a persisted branch entry, and T3 Code relies on the native provider's hooks after registration.
The main operational boundary is approval and restart behavior. DSH and Pi need a host restart after their bundle is installed. T3 Code may ask for native hook approval and requires a new thread. For related host-specific paths, see Cursor integration, Grok bot integration, Cowork integration, OpenClaw integration, Additional agent integrations, Installation and npx CLI, and External notification integrations.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep DSH event names and the structural host contract aligned with the DSH SDK that loads the self-contained package.
- Keep Pi prompt identity, worker session initialization, and persisted branch checks aligned so observations cannot attach to a different turn.
- Keep worker URL resolution consistent with the worker service and with both native clients.
- Keep installer ownership markers, managed transcript watches, and uninstall filters aligned so removal does not delete user-managed watches or provider settings.
- Keep T3 Code provider discovery, inferred default handling, and shared CLI home rules aligned so install and removal do not change a home that belongs to the native CLI.
- Keep T3 Code launch-argument checks aligned with the provider flags that can disable user settings, hooks, MCP, or Claude-Mem.
- Keep the native plugin asset checks aligned with the files required by each provider's hook and MCP loader.
- Keep Codex's marketplace source repair, plugin visibility check, legacy MCP cleanup, bundled hook definitions, user-level hook merge rules, launcher path, and plugin hook feature aligned so updates do not leave a stale registration, duplicate hooks, or repeated approvals.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The local worker is not installed or cannot start. | DSH tools fail at use time, or Pi shows an unavailable-memory warning. | Install the worker bundle first; the shared client starts only the installed marketplace worker. |
| DSH transcript capture is disabled. | DSH recall may work, but new DSH sessions are not captured automatically. | The installer reports a partial result when CLAUDE_MEM_TRANSCRIPTS_ENABLED=false. |
| Pi runs an unreviewed version for automatic capture. | Manual recall can work while automatic capture is not verified. | Check the Pi version and the capture compatibility guidance after installation. |
| Pi cannot match the active branch entry to the current request. | The turn is excluded from capture and memory is not injected for that request. | Keep the Pi session branch and persisted user-entry identity available through the context hook. |
| A T3 provider disables user settings, hooks, MCP, or Claude-Mem. | The provider starts without the native Claude-Mem integration. | Installation rejects incompatible launch flags and status checks plugin assets and enablement. |
| Codex is below the marketplace-supported version. | Codex cannot install or load the native plugin marketplace. | The installer requires Codex 0.128.0 or newer. |
| A stale local Codex marketplace points to a moved or incomplete directory. | Codex can stop loading all marketplaces and silently stop loading Claude-Mem. | Installation removes the stale local registration before adding the current marketplace source. |
| Legacy Codex MCP search settings remain after native plugin setup. | Codex can keep using an old memory search declaration instead of the plugin-managed one. | Enabling the current plugin removes the Claude-Mem-owned legacy MCP search subtree. |
| Codex does not list the plugin after installation. | Codex starts without memory context even though setup commands completed. | Installation verifies codex plugin list and reports a failure when the plugin is positively absent. |
| Codex hook definitions or the user-level hook file cannot be merged. | Codex may load the plugin without capture hooks, or installation can leave the existing hook file unchanged. | The installer validates the hook file before writing and preserves other tools' groups. |
| A T3 provider home points to a missing or invalid native CLI. | That provider cannot be configured, or an inferred default can be mistaken for a requested setup. | Managed Codex setup checks the active executable; missing inferred defaults are skipped and explicit provider errors are reported. |
A user-managed DSH watch already owns the dsh name. | Installation cannot safely add the managed watch. | Configuration validation stops before external profile changes. |
Key files
| File | Why to read it |
|---|---|
| src/…/harness-worker.ts | Defines the shared worker address, health check, startup, and bounded request boundary. |
| src/…/index.ts | Shows how the DSH host contract is assembled into tools, skills, and hooks. |
| src/…/hooks.ts | Shows DSH context injection, optional capture, and turn summary behavior. |
| src/…/tools.ts | Defines the DSH recall and manual-save surface. |
| src/…/index.ts | Shows Pi session identity, native prompt anchoring, event ordering, capture handoff, and recall tools. |
| src/…/DeepSeekHarnessInstaller.ts | Shows DSH profile installation, transcript-watch ownership, and rollback behavior. |
| src/…/PiInstaller.ts | Shows Pi bundle validation, owned-file replacement, and compatibility limits. |
| src/…/T3CodeInstaller.ts | Shows T3 provider discovery, native plugin registration, loading checks, status, and removal. |
| src/…/CodexCliInstaller.ts | Shows Codex marketplace repair, plugin enablement, legacy MCP cleanup, hook registration, plugin verification, and legacy context cleanup. |
| src/…/codex-user-hooks.ts | Shows how Codex hook definitions become stable user-level launcher hooks without changing other tools' hooks. |