fix(health): measure heap severity against the V8 heap limit

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+.git
+dist
+eval
+benchmark
+test
+.claude
+.serena
+docs
+*.log

deploy/README.md

@@ -1,15 +1,10 @@
 # One-click deploy templates
 
 Stand up agentmemory on managed infrastructure without rolling your own
-Docker host. Each template ships a self-contained Dockerfile that pulls
-`@agentmemory/agentmemory` from npm at build time and copies the iii
-engine binary in from the official `iiidev/iii` image — no pre-built
-agentmemory image required. Storage mounts at `/data`; an HMAC secret
-is generated by the first-boot entrypoint and persisted to the volume.
-The entrypoint overwrites the npm-bundled iii config with a
-deploy-tuned one that binds `0.0.0.0` and uses absolute `/data` paths,
-then drops privileges from `root` to `node` via `gosu` before
-exec'ing the agentmemory CLI.
+Docker host. Each template ships a self-contained Dockerfile. Fly, Render, and Coolify
+install `@agentmemory/agentmemory` from npm at build time. Railway builds it
+from this repo's source instead (see `deploy/railway/README.md`). All four
+copy the iii engine binary in from the `iiidev/iii` image.
 
 | Platform | Pitch | Cost floor |
 |----------|-------|------------|
@@ -95,6 +90,7 @@ agentmemory worker reg :  2.0 s
 healthcheck passes     : ~9-10 s
 ```
 
-Every template's health-check `grace_period` (or compose
+Railway's `healthcheckTimeout` is 60 s (the BM25 startup backfill needs it).
+Every other template's health-check `grace_period` (or compose
 `start_period`) is set to 30 s for a 3x safety margin. Tune lower
 once you've measured your own platform's image-pull characteristics.

deploy/railway/Dockerfile

@@ -2,9 +2,29 @@ ARG III_VERSION=0.11.2
 
 FROM iiidev/iii:${III_VERSION} AS iii-image
 
+# Build the package from this repo rather than pulling it from the registry, so
+# fixes that live on a fork actually reach the deployed container. `npm pack`
+# produces the same tarball shape the registry would serve, which keeps the
+# install layout below identical to the previous registry install.
+FROM node:22-slim AS builder
+WORKDIR /build
+# No lockfile: .gitignore:23 excludes it by repo policy, so it is absent from
+# any git-based build context and `npm ci` cannot run. This trades build
+# reproducibility away, which is the policy's cost, not a choice made here.
+COPY package.json ./
+# node:22-slim ships npm 10.9.x, whose arborist fails this dependency tree with
+# "Cannot read properties of null (reading 'edgesOut')" when resolving without a
+# lockfile. Reproduced on a clean git-only context; npm 11 resolves it cleanly.
+RUN npm install -g npm@11.19.0 --no-fund --no-audit \
+ && npm install --no-fund --no-audit
+COPY . .
+# npm pack does not create --pack-destination, so make it first.
+RUN mkdir -p /out \
+ && npm run build \
+ && npm pack --pack-destination /out
+
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.29
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
@@ -14,21 +34,44 @@ RUN apt-get update \
 
 COPY --from=iii-image /app/iii /usr/local/bin/iii
 
-# Install agentmemory into a dedicated prefix so the local package.json's
-# `overrides` field pins iii-sdk down to match the engine (agentmemory's
-# caret range `^0.11.2` otherwise resolves to 0.11.6, the version that
-# requires the new sandbox-everything worker model the agentmemory CLI
-# is not refactored for yet). `npm install -g` ignores overrides, hence
-# the local prefix.
+# Install into a dedicated prefix. The path below is load-bearing: entrypoint.sh
+# writes the iii worker config to
+# /opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml
+# under `set -eu`, so moving this prefix kills the container at boot rather than
+# at build time. Installing the packed tarball keeps npm placing the package at
+# node_modules/<pkg-name>/, which reproduces that exact path.
 WORKDIR /opt/agentmemory
-RUN printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":{"iii-sdk":"%s"}}\n' "${III_SDK_VERSION}" > package.json \
- && npm install "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}" --omit=optional --no-fund --no-audit \
+COPY --from=builder /out/*.tgz /tmp/agentmemory.tgz
+# The runtime install resolves the tarball's dependencies against the registry,
+# so the repo's `overrides` never reach it on their own. These are CVE pins
+# (added by 91c78e7, "clear all 8 audit vulns"). Read them out of the packed
+# tarball rather than retyping them, so a new pin in package.json cannot ship
+# unpinned here without anyone noticing.
+RUN OVERRIDES="$(tar -xzOf /tmp/agentmemory.tgz package/package.json | node -p 'JSON.stringify((JSON.parse(require("fs").readFileSync(0,"utf8")).overrides)||{})')" \
+ && printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":%s}\n' "$OVERRIDES" > package.json \
+ && npm install /tmp/agentmemory.tgz --omit=optional --no-fund --no-audit \
+ && rm -f /tmp/agentmemory.tgz \
  && ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory
 
+# The previous Dockerfile pinned iii-sdk through an `overrides` block to stop a
+# caret range resolving past the engine. Both this repo and the published package
+# now pin iii-sdk exactly, so the override is redundant. Assert the resolved
+# version instead of carrying a workaround for a condition that may not hold: a
+# mismatch fails the build here rather than at runtime in production.
+RUN RESOLVED="$(node -p "require('/opt/agentmemory/node_modules/iii-sdk/package.json').version")" \
+ && echo "resolved iii-sdk: ${RESOLVED} (expected ${III_SDK_VERSION})" \
+ && [ "${RESOLVED}" = "${III_SDK_VERSION}" ]
+
+# Prove the build produced a usable install at the path the entrypoint expects.
+# Without this the image can ship a broken layout that only fails at boot, where
+# failure costs a restart-budget entry instead of a build.
+RUN test -f /opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml \
+ && test -x /usr/local/bin/agentmemory
+
 ENV AGENTMEMORY_III_VERSION=${III_VERSION} \
     TINI_SUBREAPER=1
 
-COPY --chmod=0755 entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
+COPY --chmod=0755 deploy/railway/entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
 
 EXPOSE 3111
 

deploy/railway/README.md

@@ -65,7 +65,9 @@ For an authenticated call, your client must send `Authorization: Bearer <secret>
 ## Viewer access (port 3113 stays internal)
 
 Railway only exposes the single public port from your service's
-`PORT` env var (which we map to 3111). The viewer stays bound to
+`PORT` env var. The container always serves on 3111 (the app reads
+`III_REST_PORT`, never `PORT`), so the service's target port must be set to
+3111 in the Railway dashboard. The viewer stays bound to
 localhost inside the container. `railway ssh` is an interactive shell
 only — it does not support `-L`-style port forwarding, so reach the
 viewer with one of the following.
@@ -90,6 +92,39 @@ expose that port through a second Railway TCP Proxy, then use a native
 `ssh -L 3113:localhost:3113 <proxy-host> -p <proxy-port>` from your laptop.
 This is the heavier path; option A is what most users will want.
 
+## Self-healing
+
+Railway only queries `healthcheckPath` at deploy time and only restarts on a
+process **exit**, so a container that stops serving without exiting is invisible
+to the platform. Every wedge observed so far has the same shape: the iii engine
+process dies and the node process keeps running, reconnecting forever. The
+engine owns the REST listener, the stream port, and the state store, so nothing
+can be served once it is gone.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `AGENTMEMORY_EXIT_ON_ENGINE_DEATH` | **on** | Exits non-zero when the engine dies more than 5s after it was spawned, so the platform restarts the container. Set `0` to disable. |
+| `AGENTMEMORY_HEALTH_ESCALATE` | unset (**off**) | Exits after 10 consecutive failures of the 30s KV probe. |
+
+`AGENTMEMORY_EXIT_ON_ENGINE_DEATH` is on by default because it acts on a
+process-exit event rather than a probe: there is no threshold to tune and no
+false positive to trade against. Deaths within the first 5 seconds keep the
+startup-failure path, which reports a clearer message.
+
+`AGENTMEMORY_HEALTH_ESCALATE` is a probe and stays off. Do not enable it until an
+external uptime check exists against `/agentmemory/livez`. It forces process
+exits and `restartPolicyMaxRetries` is 10, so a wedge recurring on every boot
+reaches a stopped deployment in under an hour with nothing notifying you.
+Truthy spellings are `1`, `true`, `TRUE`. **`yes` and `on` are rejected.**
+
+`restartPolicyType` is `ALWAYS` rather than `ON_FAILURE`: the SIGTERM shutdown
+path ends in `process.exit(0)`, which `ON_FAILURE` reads as success and would not
+restart.
+
+An earlier revision of this file documented an in-container shell watchdog
+(`AGENTMEMORY_WATCHDOG*`). That was removed on 2026-08-26 in favour of the
+engine-exit handler above plus external uptime monitoring.
+
 ## Rotate the HMAC secret
 
 ```bash
@@ -132,5 +167,5 @@ See <https://railway.com/pricing> for the current rate card.
   or use the dashboard's manual snapshot feature.
 - The Dockerfile builds on Railway's builder on every deploy. First
   deploy is ~2 minutes; cached layers make subsequent rebuilds quick.
-  Pin `AGENTMEMORY_VERSION` / `III_VERSION` build args in the
+  Pin the `III_VERSION` build arg in the
   service's *Variables* tab to lock a specific release.

deploy/railway/entrypoint.sh

@@ -67,7 +67,9 @@ workers:
           file_path: /data/stream_store
   - name: iii-observability
     config:
-      enabled: true
+      # false, unlike the other three deploy targets: the in-memory OTEL
+      # exporter drove heap growth that crashed the container (2026-08-23).
+      enabled: false
       service_name: agentmemory
       exporter: memory
       sampling_ratio: 1.0

deploy/railway/railway.json

@@ -7,8 +7,8 @@
   "deploy": {
     "numReplicas": 1,
     "healthcheckPath": "/agentmemory/livez",
-    "healthcheckTimeout": 30,
-    "restartPolicyType": "ON_FAILURE",
+    "healthcheckTimeout": 60,
+    "restartPolicyType": "ALWAYS",
     "restartPolicyMaxRetries": 10,
     "requiredMountPath": "/data"
   }