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:
- Run
node ods/install.mjs --ods-dir /path/to/ODS --checkto validate compatibility without changing the tree. - Run the installer without
--checkto prepare the native sources and service files. - Deploy the changed ODS tree through its normal installation flow so the ingress process receives the patch.
- Set the ODS memory settings, then enable and start the
claude-memservice. - 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
| Scope | Memory boundary | Intended use |
|---|---|---|
conversation | One persistent project per ODS conversation | Default isolation, including across replaced or compacted sessions |
installation | One shared ods project | Personal, 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 event | Claude-mem action |
|---|---|
| New admitted request | Initialize the native session with platformSource: ods and the ODS request ID |
| Prior memory available | Add bounded historical observations as model-only reference data |
| Validated terminal activity | Store an ODSActivity observation with its source and status |
| Verified final delivery | Store an ODSConversation record and separate ODSVerification evidence, then summarize |
| Cached replay | Do nothing |
| Conversation deletion | Fence 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
| Setting | Purpose | Default |
|---|---|---|
ODS_CLAUDE_MEM_ENABLED | Turns native capture and recall on or off | false |
ODS_CLAUDE_MEM_PORT | Selects the local host port for the worker | 37778 |
ODS_CLAUDE_MEM_SCOPE | Selects conversation or installation memory scope | conversation |
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
| Trigger | Consequence | Guard |
|---|---|---|
| ODS source no longer matches the qualified patch | Installation stops before mutation | Run the installer check against the supported ODS revision |
| Ingress source is changed but ODS is not redeployed | The running process has no native memory bridge | Deploy the prepared ODS tree through its normal workflow |
| Worker API is exposed beyond the local trust boundary | Local API callers can read, write, or delete memory without authentication | Keep the worker on its private network and bind the host port to loopback |
| Memory worker or gateway is unavailable | The turn continues without recalled context or a saved memory claim | Treat memory as optional and inspect the fixed health and warning signals |
| Deletion occurs while observer writes are active | ODS reports memory-deletion-unconfirmed instead of claiming deletion | Retry after the observer is idle |
| Installation scope is used for a multi-user service | Conversations share one memory project | Use conversation scope unless one owner controls the installation |
Key files
| File | Why to read it |
|---|---|
| ods/README.md | Gives the operator view of install, topology, scope, capture behavior, validation, and removal |
| ods/install.mjs | Defines compatibility checks, owned-file tracking, idempotent install, and reversible removal |
ods/patches/ods-native.patch | Shows the ODS ingress attachment points and the environment passed to the native bridge |
| ods/…/claude_mem.mjs | Defines the worker-facing memory contract, privacy boundary, scope rules, and failure behavior |
| ods/…/manifest.yaml | Defines the ODS service identity, feature, dependency, port, health path, and operator settings |
ods/service/compose.yaml.disabled | Describes the worker and gateway placement, storage, model route, and local exposure |
| ods/…/gateway.mjs | Defines the two narrow network relays between the worker, LiteLLM, and ODS health probe |
| ods/…/ingress.test.mjs | Shows end-to-end capture, recall, final activity, replay, and visible-history behavior |
| ods/…/native.test.mjs | Shows identity, privacy, bounded context, failure, deletion, and scope guarantees |
| ods/…/install.test.mjs | Shows install safety, rollback, local-edit protection, and removal behavior |