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 / ods-native-integration

ODS native integration

The ODS native integration connects claude-mem to ODS at the admitted conversation boundary. It adds persistent memory recall and capture without an agent plugin, while keeping the ODS request path, model gateway, and verified delivery as the source of truth. This page is part of Agent integrations and distribution; related host integrations include Native harness integrations, Plugin hooks and agent modes, and Installation and NPX CLI.

Integration boundary

The integration treats ODS as the host product. ODS admits a request, supplies its public activity view, and returns the verified final answer. Claude-mem adds historical context before model execution and stores the approved result after delivery. It does not need an ODS agent plugin or changes to the agent's own configuration. ods/README.md• L3-10

The boundary has three important properties:

  • Host-owned truth: ODS decides which request was admitted and which answer was verified.
  • Memory-owned history: Claude-mem supplies bounded prior context and stores observations for later recall.
  • Local deployment: The worker stores data under the ODS installation and uses the existing ODS model gateway for observation work.

The native path therefore keeps memory assistance separate from visible ODS history. Recalled context is model-only reference data and does not become a user message or a new permission. ods/…/claude_mem.mjs• L193-223

Installation lifecycle

The ODS installer prepares a source tree for the integration. It first checks that the selected tree matches the qualified ODS release and that every patch can apply. It then adds the native bridge and disabled service definition. The installer records owned files so later runs can be safe, repeatable, and reversible. ods/install.mjs• L53-82, ods/install.mjs• L113-177

The normal lifecycle is:

  1. Run node ods/install.mjs --ods-dir /path/to/ODS --check to validate compatibility without changing the tree.
  2. Run the installer without --check to prepare the native sources and service files.
  3. Deploy the changed ODS tree through its normal installation flow so the ingress process receives the patch.
  4. Set the ODS memory settings, then enable and start the claude-mem service.
  5. On removal, disable the service first and run the installer with --uninstall.

The installer refuses an incompatible source tree, an unowned integration directory, or local edits to files that it owns. A receipt lets an interrupted removal resume without treating a local change as installer data. Existing data/claude-mem data remains outside the removal operation. ods/install.mjs• L85-110, ods/README.md• L19-46, ods/README.md• L126-138

This diagram shows how source preparation becomes a running ODS service.

flowchart LR
    A[ODS source tree] --> B[Compatibility check]
    B --> C[Native bridge and service files]
    C --> D[ODS deployment]
    D --> E[Ingress process]
    D --> F[claude-mem service]
    E <--> F

Service topology

The ODS service is an optional Docker feature named claude-mem. It provides the worker API, durable memory storage, and the model-backed observation runtime. The service manifest makes LiteLLM a required dependency and exposes a local health and viewer address through the configured host port. ods/…/manifest.yaml• L1-54

The deployment separates the unauthenticated worker API from the shared ODS container network. The worker uses a private network and binds the host-facing port to loopback. A small gateway is the only claude-mem container on the shared ODS network. It relays model traffic to LiteLLM and forwards only the worker health probe for the ODS dashboard. ods/service/compose.yaml.disabled#L13-L41, ods/…/gateway.mjs• L1-43

This layout limits which ODS containers can reach the worker. It does not provide user authentication for a local host process, so loopback placement remains part of the trust boundary. ods/README.md• L48-65

Memory scope

The integration supports two operator-selected memory scopes. Conversation scope is the default and gives each ODS conversation its own project. Installation scope shares one ods project across the installation and is intended only for a single-owner appliance. The model and request body cannot select or change this scope. ods/…/claude_mem.mjs• L73-91, ods/…/claude_mem.mjs• L162-168

ScopeMemory boundaryIntended use
conversationOne persistent project per ODS conversationDefault isolation, including across replaced or compacted sessions
installationOne shared ods projectPersonal, single-owner ODS installation

The service stores its data in data/claude-mem. SQLite search is enabled in this deployment, while Chroma and telemetry are disabled. ods/README.md• L7-10, ods/service/compose.yaml.disabled#L13-L32

Conversation flow

Each admitted, non-cached request creates one native memory turn. The bridge removes private blocks before it applies size limits. It then asks claude-mem whether the turn should be captured and, when allowed, retrieves at most five recent observations as bounded reference context. ods/…/claude_mem.mjs• L153-170, ods/…/claude_mem.mjs• L195-224

ODS activity is captured from its validated public activity projection. Running events are not stored as completed observations, and the final activity snapshot is collected even when a fast request completes before the first activity poll. The final verified delivery and its verification evidence are stored as separate records before the turn is summarized. ods/…/claude_mem.mjs• L227-247, ods/README.md• L78-95

This diagram shows the relationship between the ODS request lifecycle and the memory lifecycle.

sequenceDiagram
    participant O as ODS ingress
    participant M as Claude-mem worker
    participant G as ODS model gateway

    O->>M: Start admitted conversation turn
    M-->>O: Bounded historical context
    O->>G: Execute current request
    G-->>O: ODS response and activity projection
    O->>M: Validated activity events
    O->>M: Verified final delivery
    M-->>M: Summarize and retain the turn

Cached response replay does not start model execution or create another memory turn. Conversation deletion fences queued writes before it requests deletion of the exact native session. ods/…/claude_mem.mjs• L142-151, ods/README.md• L80-88

Worker-facing ingress contract

The native bridge is attached to ODS's chat ingress. It receives the conversation identity, request identity, messages, and ODS's activity and completion callbacks. It sends memory operations to the local worker over loopback HTTP and returns only a bounded system reference to the ODS model request. ods/patches/ods-native.patch#L101-L109, ods/patches/ods-native.patch#L189-L211

The contract maps ODS events to claude-mem operations:

ODS boundary eventClaude-mem action
New admitted requestInitialize the native session with platformSource: ods and the ODS request ID
Prior memory availableAdd bounded historical observations as model-only reference data
Validated terminal activityStore an ODSActivity observation with its source and status
Verified final deliveryStore an ODSConversation record and separate ODSVerification evidence, then summarize
Cached replayDo nothing
Conversation deletionFence pending writes and delete the exact native session

The bridge accepts only the expected ODS session and request identity forms. It uses request IDs and activity IDs to prevent duplicate writes. This gives the worker a stable session boundary without allowing model output to choose a different memory target. ods/…/claude_mem.mjs• L144-190

Privacy and availability behavior

Private blocks are removed before capture or truncation. Nested blocks and unfinished blocks remain private, and a prompt that becomes entirely private skips the turn. The final answer is taken from ODS's public verified delivery rather than from hidden agent activity. ods/…/claude_mem.mjs• L21-35, ods/…/claude_mem.mjs• L239-247

Memory is an optional aid to chat. Reads and writes use short timeouts, and an unavailable worker leaves the ODS request usable while emitting only a fixed warning. A failed write stops the current write chain; the bridge does not claim that an incomplete turn was saved and does not provide an offline outbox. ods/…/claude_mem.mjs• L98-123, ods/…/claude_mem.mjs• L175-180, ods/README.md• L97-101

Configuration surface

ODS enables the integration through three environment values. The installer validates these values before placing them in the ingress environment. The service manifest presents the same values to the ODS operator and keeps the feature disabled by default. ods/patches/ods-native.patch#L215-L233, ods/…/manifest.yaml• L30-40

SettingPurposeDefault
ODS_CLAUDE_MEM_ENABLEDTurns native capture and recall on or offfalse
ODS_CLAUDE_MEM_PORTSelects the local host port for the worker37778
ODS_CLAUDE_MEM_SCOPESelects conversation or installation memory scopeconversation

The worker uses the existing ODS LiteLLM route and the ods/current model identity for observation extraction. This integration does not add a model route or change ODS's local or cloud routing policy. ods/service/compose.yaml.disabled#L18-L27, ods/README.md• L63-65

Change checklist

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

  • Keep the ODS patch, installer compatibility check, and qualified ODS revision aligned. A source change can make a clean install fail before any files are written.
  • Keep the ingress identity rules aligned with the worker's session and deletion paths. A mismatch can split one conversation across projects or leave its memory undeleted.
  • Keep the service manifest, Compose port, and ingress environment defaults aligned. A mismatch can make the dashboard probe one port while the worker uses another.
  • Keep the gateway's narrow health route and private worker network boundary intact when changing service topology. The worker API has no authentication.
  • Keep privacy filtering before byte limits and before every capture path. Moving truncation earlier can expose part of a private block.
  • Keep final activity collection and verified completion ordering intact. The summary must follow the last activity snapshot.

Important failure modes

TriggerConsequenceGuard
ODS source no longer matches the qualified patchInstallation stops before mutationRun the installer check against the supported ODS revision
Ingress source is changed but ODS is not redeployedThe running process has no native memory bridgeDeploy the prepared ODS tree through its normal workflow
Worker API is exposed beyond the local trust boundaryLocal API callers can read, write, or delete memory without authenticationKeep the worker on its private network and bind the host port to loopback
Memory worker or gateway is unavailableThe turn continues without recalled context or a saved memory claimTreat memory as optional and inspect the fixed health and warning signals
Deletion occurs while observer writes are activeODS reports memory-deletion-unconfirmed instead of claiming deletionRetry after the observer is idle
Installation scope is used for a multi-user serviceConversations share one memory projectUse conversation scope unless one owner controls the installation

Key files

FileWhy to read it
ods/README.mdGives the operator view of install, topology, scope, capture behavior, validation, and removal
ods/install.mjsDefines compatibility checks, owned-file tracking, idempotent install, and reversible removal
ods/patches/ods-native.patchShows the ODS ingress attachment points and the environment passed to the native bridge
ods/…/claude_mem.mjsDefines the worker-facing memory contract, privacy boundary, scope rules, and failure behavior
ods/…/manifest.yamlDefines the ODS service identity, feature, dependency, port, health path, and operator settings
ods/service/compose.yaml.disabledDescribes the worker and gateway placement, storage, model route, and local exposure
ods/…/gateway.mjsDefines the two narrow network relays between the worker, LiteLLM, and ODS health probe
ods/…/ingress.test.mjsShows end-to-end capture, recall, final activity, replay, and visible-history behavior
ods/…/native.test.mjsShows identity, privacy, bounded context, failure, deletion, and scope guarantees
ods/…/install.test.mjsShows install safety, rollback, local-edit protection, and removal behavior