add-mnemon

Add Mnemon — Persistent Memory

Installs mnemon in the agent container image. On each container start, mnemon setup registers Claude Code hooks that surface relevant memory before the agent responds and store new insights after each turn. Memory is written to the per-agent-group .claude/ mount and survives container restarts.

Provider Compatibility

mnemon hooks fire only under --target claude-code. Use this skill on agent groups that run the default Claude provider. The provider is the materialized provider key in each group's container.json (absent or claude = default Claude provider). Confirm it before applying:

grep -H '"provider"' groups/*/container.json 2>/dev/null   # no match, or "provider": "claude" = Claude

If a group sets a different provider (e.g. "provider": "opencode"), it spawns its own process and never invokes the claude CLI, so the hooks registered by mnemon setup do not run for that group.

Phase 1: Pre-flight

Check if already applied

grep -q 'MNEMON_VERSION' container/Dockerfile && echo "Already applied" || echo "Not applied"

If already applied, re-run Phase 2 anyway — every step is idempotent and skips work that is already in place — then continue to Phase 3 (Verify).

Check latest mnemon version

curl -fsSL https://api.github.com/repos/mnemon-dev/mnemon/releases/latest | grep '"tag_name"'

Note the version (e.g. v0.1.1) — use it as MNEMON_VERSION in the next step.

Phase 2: Apply Changes

1. Dockerfile — install mnemon binary

Insert the mnemon block immediately above the # ---- Bun runtime section of container/Dockerfile (skip if grep -q 'MNEMON_VERSION' container/Dockerfile already matches):

# ---- mnemon — persistent agent memory ----------------------------------------
ARG MNEMON_VERSION=0.1.1
RUN ARCH=$(dpkg --print-architecture) && \
    curl -fsSL "https://github.com/mnemon-dev/mnemon/releases/download/v${MNEMON_VERSION}/mnemon_${MNEMON_VERSION}_linux_${ARCH}.tar.gz" \
    | tar -xz -C /usr/local/bin mnemon && \
    chmod +x /usr/local/bin/mnemon

ENV MNEMON_DATA_DIR=/home/node/.claude/mnemon

MNEMON_DATA_DIR points into the per-agent-group .claude/ mount, so memory persists across container restarts.

2. Entrypoint — run mnemon setup on each container start

mnemon setup is idempotent. Run it once per container/entrypoint.sh. First check whether the line is already present:

grep -q 'mnemon setup' container/entrypoint.sh && echo "Already wired" || echo "Wire it"

If it prints Wire it, add the setup call right after set -e, before the cat that captures stdin, so the result looks like:

#!/bin/bash
# NanoClaw agent container entrypoint.
#
# ...existing header comment...

set -e

mnemon setup --target claude-code --yes --global >/dev/stderr 2>&1

cat > /tmp/input.json

exec bun run /app/src/index.ts < /tmp/input.json

>/dev/stderr 2>&1 routes all mnemon output to stderr (docker logs) so it doesn't interfere with the JSON stdin handshake between host and agent-runner.

3. Copy the integration tests

Both reach-ins are into container build/runtime files that aren't importable or typed (a GitHub-release binary in the Dockerfile, a shell line in the entrypoint), so structural tests guard them. Copy them into the host test tree:

cp .claude/skills/add-mnemon/mnemon-dockerfile.test.ts src/mnemon-dockerfile.test.ts
cp .claude/skills/add-mnemon/mnemon-entrypoint.test.ts src/mnemon-entrypoint.test.ts
pnpm exec vitest run src/mnemon-dockerfile.test.ts src/mnemon-entrypoint.test.ts

mnemon-dockerfile.test.ts asserts the MNEMON_VERSION ARG and MNEMON_DATA_DIR ENV are present (red if the install layer is dropped on an upgrade). mnemon-entrypoint.test.ts asserts the entrypoint invokes mnemon setup --target claude-code (red if the wiring is removed).

4. Rebuild and smoke-test the image

./container/build.sh
docker run --rm --entrypoint mnemon nanoclaw-agent:latest --version

Phase 3: Restart and Verify

Restart the service

Run from your NanoClaw project root:

source setup/lib/install-slug.sh
systemctl --user restart $(systemd_unit)              # Linux
# launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS

Confirm mnemon hooks are registered

After the next container starts, check that setup ran:

docker logs $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) 2>&1 | grep -i mnemon

Then inspect the hooks inside the running container:

docker exec $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) \
  cat /home/node/.claude/settings.json | grep -A5 mnemon

Test memory recall

Have a conversation with the agent, then start a new session and reference something from the earlier one. Mnemon should surface the relevant context automatically without you restating it.

Memory Storage

Mnemon writes to /home/node/.claude/mnemon/ inside the container, which maps to the per-agent-group .claude/ directory on the host. To find the exact host path:

docker inspect $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) \
  --format '{{range .Mounts}}{{if eq .Destination "/home/node/.claude"}}{{.Source}}{{end}}{{end}}'

To reset all memory for an agent, stop the container and delete the mnemon/ subdirectory from that host path.

Troubleshooting

mnemon: command not found in container

The image wasn't rebuilt after adding the Dockerfile layer. Run ./container/build.sh and restart.

Memory not persisting across restarts

Verify MNEMON_DATA_DIR resolves to a mounted path (not an in-container ephemeral directory):

docker exec <container> sh -c 'ls -la $MNEMON_DATA_DIR'

If the directory is empty after conversations, the mount is missing or the path is wrong. Check the host mount with the docker inspect command above.

Agent not using past memory

mnemon setup writes hooks into /home/node/.claude/settings.json. Verify:

docker exec <container> cat /home/node/.claude/settings.json

If the hooks are absent, mnemon setup may have failed silently. Check container startup logs for errors from mnemon.

Setup fails at container start

Run setup manually inside a running container to see the full error:

docker exec -it <container> mnemon setup --target claude-code --yes --global