claude-mem Docker 测试容器完全指南构建、认证、版本锁定与运行模式解析【免费下载链接】claude-memPersistent 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项目地址: https://gitcode.com/GitHub_Trending/cl/claude-memdocker/claude-mem是 claude-mem 仓库内置的一个最小化 Docker 测试容器harness它在隔离的环境里启动 Claude Code CLI 与本地构建的插件让 AI 生成的 observations 落入一个可丢弃的 SQLite 库结束后你可以直接把数据库拿到宿主机上检查。读完本文你将掌握该镜像的完整构建流程、三级认证回退机制、可复现的版本锁定参数、容器三种运行模式server / worker / shell的切换方式以及手动docker run的全部变体。一、Docker harness 的定位与文件组成该目录的设计目标很明确见 READMEA minimal container for exercising claude-mem end-to-end without polluting your host——它不是开发环境只提供启动claude并捕获 observations 所需的最小运行时。目录内共 4 个文件各司其职文件职责Dockerfile镜像定义node:20 Bun uv Claude Code CLI 本地plugin/build.sh先执行npm run build再执行docker build镜像 tag 默认为claude-mem:basicentrypoint.sh容器内入口。若挂载了 OAuth 凭据则写入$HOME/.claude/然后exec $或按模式启动服务run.sh宿主机侧启动器。按优先级提取凭据Keychain → 文件 → 环境变量挂载持久化数据目录进入交互 shellbuild.sh的实际逻辑build.sh会先切换到仓库根目录执行npm run build保证plugin/目录是最新编译产物后再交给docker buildrun.sh则在运行时通过SCRIPT_DIR/../..推导仓库根目录并据此设置默认数据目录$REPO_ROOT/.docker-claude-mem-datarun.sh。二、快速上手构建与运行从仓库根目录执行docker/claude-mem/build.sh docker/claude-mem/run.shrun.sh会把你带进容器内的bash其中claude已在PATH上插件预置于/opt/claude-mem。启动会话时使用claude --plugin-dir /opt/claude-mem会话结束后SQLite 数据库留在宿主机的./.docker-claude-mem-data/claude-mem.db可用 sqlite3 直接验证 observations 是否被捕获sqlite3 .docker-claude-mem-data/claude-mem.db select count(*) from observations需要注意一个入口行为从 entrypoint.sh 的源码看CLAUDE_MEM_CONTAINER_MODE的默认值是server此时容器会exec bun /opt/claude-mem/scripts/server-service.cjs --daemon启动 server-beta 运行时而不是进入 shell。若要获得 README 快速开始中描述的交互 shell 体验需要把模式切到shell或别名tooling该模式在无参数时exec bash有参数时exec $。三、镜像解剖运行时、层级与缓存设计README 说明镜像布局对标 anthropics/claude-code 的 devcontainerFROM node:20、非 root 的node用户、全局安装anthropic-ai/claude-code同时去掉了防火墙、zsh、fzf、delta、git-hist 等编辑向工具因为这个镜像是为了跑 claude-mem而不是写代码。对照 Dockerfile 逐层验证基础层L2-L17node:20 apt 安装git curl ca-certificates unzip jq less procps uuid-runtime sqlite3其中sqlite3正是快速开始里检查 DB 所依赖的客户端。Bun 运行时L19-L23通过官方bun.sh/install脚本安装到/usr/local/bun这是 claude-mem worker/service 脚本如 server-service.cjs的运行环境PATH已前置。uvL25-L29通过版本化安装脚本装到/usr/local/bin为 Chroma 向量检索提供 Python 运行时。Claude Code CLIL31-L38先切到node用户再执行npm install -g anthropic-ai/claude-code${CLAUDE_CODE_VERSION}npm 全局前缀指向/usr/local/share/npm-global。插件层L41-L46以 root 身份COPY plugin/ /opt/claude-mem/并归还属主再以node用户执行npm install --omitdev --legacy-peer-deps。挂载点预创建L49-L50/home/node/.claude、/home/node/.claude-mem、/data/claude-mem。入口与模式L52-L67entrypoint 拷入/usr/local/bin/claude-mem-entrypoint并预置CLAUDE_MEM_CONTAINER_MODEserver、CLAUDE_MEM_RUNTIMEserver-beta。README 特别强调层级顺序是刻意为之插件文件放在npm install层之后这样在插件上反复迭代时不会击穿 CLI 安装层的构建缓存显著提升开发迭代速度。四、版本锁定用 build-arg 换取可复现性镜像中一切影响可复现性的组件都暴露为--build-arg——需要复现时锁定追求最新时省略即可docker build \ -f docker/claude-mem/Dockerfile \ --build-arg BUN_VERSION1.3.12 \ --build-arg UV_VERSION0.11.7 \ --build-arg CLAUDE_CODE_VERSION1.2.3 \ -t claude-mem:basic .Arg默认值说明BUN_VERSION1.3.12通过官方bun.sh/install脚本安装tag 为bun-v${BUN_VERSION}UV_VERSION0.11.7通过带版本号的astral.sh/uv/${UV_VERSION}/install.sh安装CLAUDE_CODE_VERSIONlatestnpm tag 或精确版本号。建议在 CI 中锁定本地可让其浮动这三个默认值与 Dockerfile 中的ARG BUN_VERSION1.3.12、ARG UV_VERSION0.11.7、ARG CLAUDE_CODE_VERSIONlatest一一对应。其中 Bun 的安装命令带-s bun-v${BUN_VERSION}参数L21uv 的安装 URL 直接嵌入版本号L28因此两个默认值天然是可复现的而CLAUDE_CODE_VERSIONlatest意味着每次构建的 CLI 版本可能不同README 给出的实践建议是CI 锁定、本地浮动。五、认证链三级回退与临时凭据的安全处理run.sh按固定顺序选择第一个可用的认证源run.shANTHROPIC_API_KEY环境变量——直接挂载进容器CREDS_MOUNT_ARGS(-e ANTHROPIC_API_KEY)跳过 OAuth 凭据提取macOS Keychain——仅在uname为Darwin时执行security find-generic-password -s Claude Code-credentials -w~/.claude/.credentials.json——旧版磁盘形式仍存在于一些老 CLI 安装和迁移后的机器上。当走凭据文件路径时安全处理链条如下凭据先写入mktemp生成的临时文件并chmod 600以只读方式挂载到容器内/auth/.credentials.json同时注入-e CLAUDE_MEM_CREDENTIALS_FILE/auth/.credentials.json容器端 entrypoint.sh 在启动时检查该文件存在缺失则报错退出cp到$HOME/.claude/.credentials.json并再次chmod 600run.sh通过trap rm -f $CREDS_FILE EXIT在返回时删除宿主机临时文件。README 特别指出docker run被刻意没有exec目的正是让EXITtrap 有机会触发。若三级认证源全部落空run.sh会以错误退出提示先在宿主机执行claude login或设置ANTHROPIC_API_KEYrun.sh。六、手动 docker run不经过 run.sh需要完全控制挂载与环境变量时可以绕过run.sh直接调用镜像。OAuth 凭据文件方式docker run --rm -it \ -v $(mktemp -d):/home/node/.claude-mem \ -e CLAUDE_MEM_CREDENTIALS_FILE/auth/.credentials.json \ -v /path/to/creds.json:/auth/.credentials.json:ro \ claude-mem:basicAPI key 方式docker run --rm -it \ -v $(mktemp -d):/home/node/.claude-mem \ -e ANTHROPIC_API_KEY \ claude-mem:basic两个示例都把/home/node/.claude-mem挂到一个mktemp -d目录保证数据落盘在宿主机且随时可弃-e ANTHROPIC_API_KEY不带值的形式表示透传宿主机已导出的同名变量。另外注意run.sh中有对应的 TTY 处理[[ -t 0 -t 1 ]]才加-itrun.sh手动调用时非交互场景应去掉-it。七、环境变量速查表变量作用位置用途TAGbuild.sh、run.sh覆盖镜像 tag默认claude-mem:basicHOST_MEM_DIRrun.sh覆盖宿主机持久化.claude-mem卷路径默认$REPO_ROOT/.docker-claude-mem-dataANTHROPIC_API_KEYrun.sh、entrypointAPI key 认证跳过 OAuth 凭据提取CLAUDE_MEM_CREDENTIALS_FILEentrypoint容器内已挂载 OAuth 凭据 JSON 的路径启动时复制到$HOME/.claude/.credentials.json补充两个未在表中列出但由源码确认的容器内变量CLAUDE_MEM_DOCKER1entrypoint 强制导出entrypoint.sh。在服务端代码 create-server-service.ts 中detectDockerEnvironment会把CLAUDE_MEM_DOCKER1/true或/.dockerenv存在性都识别为 Docker 环境其后果是环境校验拒绝local-dev认证旁路——从源码结构看因为容器可通过服务间网络与暴露端口被访问回环地址假设不再成立CLAUDE_MEM_RUNTIMEentrypoint 以server-beta为默认导出服务端校验只接受server或旧字面量server-betacreate-server-service.ts。八、参数透传与清理run.sh后面的任何参数都会作为命令转发进容器例如免交互直接提问docker/claude-mem/run.sh claude --plugin-dir /opt/claude-mem --print what did we learn yesterday?用完后的清理动作rm -rf .docker-claude-mem-data # 抹掉持久化 DB Chroma 存储 docker rmi claude-mem:basic # 删除镜像九、容器运行模式与 server-beta 运行时entrypoint.sh 通过CLAUDE_MEM_CONTAINER_MODE实现了三模式分发server默认exec bun /opt/claude-mem/scripts/server-service.cjs --daemon运行 HTTP server-beta 运行时不启动 legacy workerworkerexec bun ... worker start只跑 BullMQ 生成 worker无 HTTP并强制unset CLAUDE_MEM_GENERATION_DISABLED——因为 worker 进程本身就是生成进程shell/tooling落入$无参数时进入bash用于插件调试等工具类场景其他值打印ERROR: unknown CLAUDE_MEM_CONTAINER_MODE...并exit 1。README 还给出了生产化拆分思路在本服务上设置CLAUDE_MEM_GENERATION_DISABLEDtrue把生成任务拆到兄弟容器中的claude-mem server worker start进程里实现 HTTP 服务与生成 worker 的水平分离。与根目录 docker-compose.yml 的全量部署见 docs/docker.md相比本 harness 是单机验证路线compose 栈带 Valkey sidecar 与 api-key 认证、监听 37777 端口的/healthz而本目录镜像面向端到端观察捕获验证两者共用同一套CLAUDE_MEM_DOCKER/CLAUDE_MEM_RUNTIME环境契约但用途不重叠。十、小结docker/claude-mem展示了测试容器设计的几个可复用要点以 build-arg 显式暴露所有版本旋钮以换取可复现性用插件层后置的层级顺序保护昂贵的 CLI 安装缓存认证链按 Keychain → 磁盘文件 → 环境变量的确定优先级回退并配合chmod 600、只读挂载与 EXIT trap 形成完整的临时凭据生命周期再以一个环境变量CLAUDE_MEM_CONTAINER_MODE切换 server / worker / shell 三种前台进程让同一镜像既能做交互调试也能拆分为服务与 worker 两个部署单元。所有脚本与镜像定义均为可读的 shell/多行 Dockerfile适合作为自研 agent 插件的容器化测试参考。【免费下载链接】claude-memPersistent 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项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
