ai-memory 家庭服务器Homelab部署指南从 Docker 模板到生产级 MCP 服务的完整落地【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory本文基于 ai-memory 仓库官方部署文档与真实部署脚本系统讲解如何在一台家庭服务器homelab上用 Docker 部署一个长期运行的 ai-memory MCP 服务覆盖首次配置、密钥注入、bearer-token 鉴权、TLS 加密传输、例行更新、备份、容量规划、磁盘回收与回滚排障。读完你可以完整复现bin/deploy文档化的部署模式把单机单用户的记忆服务升级为LAN 内多 Agent、多人共享的稳定服务。部署形态总览两种目标架构ai-memory 提供两条部署路径选择取决于你的主机形态Docker 部署本文主线按照 bin/deploy 脚本封装的模式在 homelab 主机上跑一个长期运行的容器LAN 内通过http://host:49374/mcp访问配置好 LLM/Embedding API 密钥后即可供各 Agent CLI 使用。备份沿用你现有对/var/opt/docker/...目录的备份方案。原生 Linux systemd 服务若你不想用 Docker可走 docs/install.md 中的 Arch/AUR 安装路径。该模式系统服务使用/var/lib/ai-memory与/etc/ai-memory/用户服务则使用 XDG 用户路径而 Docker 部署的数据目录始终是容器内/data、宿主机/var/opt/docker/...。两条路径的行为差异在优雅停机一节还会体现容器内服务是 PID 1systemd 下不是二者的信号处理历史教训完全不同。多架构支持发布的 Docker 镜像同时包含linux/amd64与linux/arm64两种 manifest因此 x86_64 与 ARM64 的 homelab 主机都能以原生架构拉取同一 tag树莓派等 ARM 主机无需模拟运行。仓库只提交模板真实配置全部 gitignore仓库奉行一条明确原则只提交.example模板绝不提交真实配置。你的 homelab 专属值与 API 密钥存放在去掉.example后缀的同名文件里这些文件全部被.gitignore排除。提交的模板实际使用的gitignored存放内容bin/deploy脚本本身可安全提交构建/推送/重启逻辑bin/deploy.env.examplebin/deploy.envSERVER、DEPLOY_DIR、IMAGEdocker/docker-compose.prod.yml.exampledocker/docker-compose.prod.yml镜像 tag、端口映射、卷路径docker/.env.production.exampledocker/.env.productionLLM Embedding API 密钥如果哪天在 git status 里看到这些真实文件被暂存说明发生了漂移有人误提交提交前务必取消暂存。模板内容逐项解读bin/deploy.env.example见 bin/deploy.env.example定义三个必填变量SERVERmehomelab.example.comSSH 目标userhost或已在~/.ssh/config配好则直接写 hostDEPLOY_DIR/var/opt/docker/utils/ai-memoryhomelab 上docker-compose.yml与.env.production所在的绝对路径脚本在其中执行docker compose pull/down/upIMAGEakitaonrails/ai-memory:homelab要构建推送拉取的镜像 tag。必须使用你自己的私有 tag详见下文多架构防误覆盖另有可选的CONTAINER_NAME用于覆盖默认容器名ai-memory。docker/docker-compose.prod.yml.example见 docker/docker-compose.prod.yml.example与本地开发用的docker/docker-compose.yml有四点关键差异引用 registry 镜像而不是内联构建绑定0.0.0.0:49374让 LAN 可以访问 MCP 端点密钥通过env_file: .env.production注入而不是内联卷挂载宿主路径/var/opt/docker/utils/ai-memory/data:/data使 rsync 等工具可直接备份 wiki 与 db无需绕道 Docker volume API。模板还预置了两个值得注意的细节security_opt: - label:disable # openSUSE MicroOS / Fedora / RHEL 等默认对 bind mount 强制 SELinux # 不加此行容器读不了自己的 /data。对不启用 SELinux 的主机是 no-op healthcheck: test: [CMD, /usr/local/bin/ai-memory, status] # 容器内嵌健康检查 interval: 30s timeout: 5s retries: 3 start_period: 5sRUST_LOGai_memoryinfo,ai_memory_storeinfo,ai_memory_wikiinfo,ai_memory_mcpinfo,tracing_appenderwarn是预置的日志过滤规则需要排查某模块时可以不改镜像、直接在此提升日志级别。健康检查复用二进制自身的ai-memory status子命令见 docker/Dockerfile 中同款HEALTHCHECK这也是后面排障一节unhealthy状态的直接来源。docker/.env.production.example见 docker/.env.production.example是密钥与行为开关的集中地。它的注释透露一个重要的降级逻辑不设置任何 LLM/Embedding 密钥ai-memory 依然可以运行——退回纯 FTS5 模式 基于规则的会话摘要。所有变量都是可选的。首次配置一次性操作官方文档给出了标准四步# 1. 将 homelab 专属值写入本地配置 cp bin/deploy.env.example bin/deploy.env $EDITOR bin/deploy.env # 填写 SERVER / DEPLOY_DIR / IMAGE cp docker/docker-compose.prod.yml.example docker/docker-compose.prod.yml $EDITOR docker/docker-compose.prod.yml # 设置镜像 tag必要时调整端口 cp docker/.env.production.example docker/.env.production $EDITOR docker/.env.production # 填入凭据选择 LLM provider模型覆盖可选 # 2. 在 homelab 上创建部署目录。source bin/deploy.env 让 SERVER/DEPLOY_DIR # 在当前 shell 中导出 source bin/deploy.env ssh $SERVER sudo mkdir -p $DEPLOY_DIR/data \ sudo chown -R 1000:1000 $DEPLOY_DIR # 3. 把 compose 与 env 拷贝到 homelab scp docker/docker-compose.prod.yml $SERVER:$DEPLOY_DIR/docker-compose.yml scp docker/.env.production $SERVER:$DEPLOY_DIR/.env.production # 4. 执行首次部署 bin/deploy关于第 2 步的chown 1000:1000容器以 uid 1000 的非 root 用户运行docker/Dockerfile 中useradd --system --uid 1000 ... --home-dir /data创建数据目录属主必须是 1000否则容器内写/data会失败表现为健康检查unhealthy。第 4 步bin/deploy的真实执行序列见 bin/deploy是读取并校验bin/deploy.env三个必填变量缺失任一即退出exit 64并提示如何初始化docker build -t $IMAGE -f docker/Dockerfile .——本地构建镜像docker push $IMAGE——推送到 registrySSH 到 homelab 执行docker compose pull docker compose down docker compose up -d——拉取新 tag、停旧容器、起新容器服务器上不做docker compose build二进制已经烤进镜像sleep 3后docker inspect --format{{.State.Status}} ({{.State.Health.Status}}) ai-memory打印容器状态与健康状态提示验证命令curl ${SERVER#*}:49374/mcp。多架构防误覆盖bin/deploy 的 fail-closed 保护bin/deploy 内有一段关键保护逻辑如果$IMAGE当前解析为多架构 manifestdocker manifest inspect结果含manifests脚本会拒绝执行并提示改用私有 tag。原因写得很清楚docker build只产出本机架构的镜像。把它 push 到一个原本是多架构的 tag 上会把 manifest 列表替换成单架构另一架构的主机下次 pull 就会exec format error。这不是假设——2026-08-18 它真实发生在:latest上issue #427CI 发布的 release tag 是 amd64arm64 联合 manifest一台 x86 工作站的 homelab 部署曾静默把它压扁成 amd64-only。因此release tag:latest、:X.Y.Z只允许 CI 发布部署不得覆盖部署请用私有 tag如IMAGEakitaonrails/ai-memory:homelab若只想跑已发布镜像而不重建直接在服务器上ssh $SERVER cd $DEPLOY_DIR docker compose pull docker compose up -d即可完全不需要bin/deploy。部署后验证curl http://homelab:49374/mcp # 期望看到 JSON-RPC 错误 —— 说明端口可达、服务在响应。 # Connection refused 说明容器没起来或端口映射错误。 ssh $SERVER docker inspect --format{{.State.Health.Status}} ai-memory # 期望输出: healthy/mcp是 MCP 协议端点不带凭据直接 curl 它必然返回协议层错误这恰恰证明 HTTP 层已经通了。安全第一道闸bearer-token 鉴权 加密传输模板默认把端口绑定在0.0.0.0:49374让 LAN 可达但这带来一个必须正视的威胁模型无鉴权的 LAN 绑定服务让网络上任何人都能调用破坏性 MCP 工具——删除所有页面、注入伪造 observation、耗尽你的 LLM 预算。因此官方文档明确要求首次部署前就打开鉴权。生成并启用 token# 1. 生成 token32 字节 64 个十六进制字符 ai-memory generate-auth-token docker/.env.production $EDITOR docker/.env.production # 把新行前缀改成 AI_MEMORY_AUTH_TOKEN # 2. 同步到 homelab 并重启 scp docker/.env.production $SERVER:$DEPLOY_DIR/.env.production ssh $SERVER cd $DEPLOY_DIR docker compose up -dai-memory generate-auth-token的实现位于 crates/ai-memory-cli/src/commands/generate_auth_token.rs底层调用ai_memory_mcp::auth::generate_token_hex(32)用操作系统 RNG 填充 32 字节熵池再十六进制编码得到 64 字符 tokencrates/ai-memory-mcp/src/auth.rs。默认 32 字节256 bit熵足以覆盖任何合理威胁模型。启动日志随后会出现authtrue。从笔记本上验证curl -sI http://homelab:49374/handoff # → HTTP/1.1 401 Unauthorized curl -sI http://homelab:49374/handoff \ -H Authorization: Bearer $TOKEN # → HTTP/1.1 200 OK然后为每个 MCP 客户端配置同一个 tokenai-memory install-mcp --client name --auth-token token会为 README 支持矩阵 中的每种客户端打印精确的配置片段ai-memory install-mcp --help可查看当前接受的取值。Agent CLI 会在每次调用时携带Authorization: Bearer token头。常量时间比较防 LAN 时序侧信道ai-memory 的鉴权中间件位于 crates/ai-memory-mcp/src/auth.rs。其中最关键的实现细节是 token 比较使用了subtle::ConstantTimeEqauth.rsif let Some(expected) state.expected.as_deref() bool::from(provided.as_bytes().ct_eq(expected.as_bytes())) { req.extensions_mut().insert(state.root_actor.clone()); req.extensions_mut().insert(AuthLevel::Root); return Ok(BearerAuth::Authenticated); }文件头注释点明了原因同一 LAN 上的攻击者无法通过响应时间差异逐字节还原 token。中间件还做了 fail-closed 设计未配置任何 token 时中间件是 no-op保留零配置 loopback 的可用性auth.rs未配置 token 却收到一个意外 bearer 头时按匿名请求放行而非拒绝兼容曾加固过的旧部署Basic 认证、Cookie 永远不是机器凭据有专项测试覆盖401 响应只声明WWW-Authenticate: Bearer绝不广告 Basicauth.rs。加密传输什么时候必须上 TLS明文 HTTP 意味着任何能抓包的人都能读到传输中的 bearer token多用户模式开启后还包括原生aim_密钥。当绑定范围超出 loopback、或开启多用户时必须在 ai-memory 前面加 TLS 终止反向代理。完整部署指南见 docs/https-via-proxy.md包括何时需要 TLS、何时可以跳过loopback stdio 的场景诚实地说并不需要可直接复制的 docker compose 模板docker/compose.tls.caddy.ymlCaddy Lets Encrypt 或 Caddy 内部 CA与 docker/compose.tls.cloudflared.ymlCloudflare Tunnel各操作系统信任库安装内部 CA 路径中承重的关键手工步骤子路径托管https-via-proxy.md 中的 Hosting under a subpath通过--base-path/AI_MEMORY_BASE_PATH让 ai-memory 与其他应用共享同一主机名官方文档专门保留了哪里会出错章节避免你意外部署出安全剧场。对单用户 loopback 快速上手场景仅 bearer token 依然可接受——token 挡住 LAN 邻居loopback 挡住抓包一旦部署形态不再是单用户、单机器TLS 就物有所值了。例行部署一次bin/deploy完成构建-推送-拉取-重启首次配置完成后后续每次部署都简化为bin/deploy脚本在本地构建镜像 → 推送到你的 registry → homelab 拉取 → 重启。homelab 上的 compose 文件与 env 文件在部署间保持不变如果需要改它们重新 scp 新副本后再跑bin/deploy。优雅停机5 秒有界 drain 与 PID 1 的历史教训重启步骤用 SIGTERM 停止运行中的容器。服务在两个传输stdio 与 HTTP上都安装 SIGINT/SIGTERM 处理器且关闭路径上的每次等待都限制在 5 秒因此一次重启或普通的docker stop、docker compose down只需几秒即可 drain 并退出而不是耗尽 supervisor 的宽限期后以 SIGKILL 收场。这个 5 秒常量在源码中有明确出处crates/ai-memory-cli/src/commands/serve.rs/// How long a wait on the shutdown path may run before the drain it is /// waiting for is abandoned. axums graceful shutdown waits for every /// in-flight connection and a stateful or SSE MCP client can hold one open /// indefinitely, so an unbounded drain is indistinguishable from ignoring the /// signal: docker stop and systemctl stop would still burn their own /// grace period and finish with SIGKILL (#699). Each wait is bounded on its /// own, so a stop can take a small multiple of this. const SHUTDOWN_GRACE: Duration Duration::from_secs(5);这段注释背后的历史很值得了解。在信号处理器存在之前两种部署形态以不同方式失败容器内服务是 PID 1。Linux 内核会丢弃没有安装处理器的信号因此docker stop白白烧掉整个宽限期只能docker kill强杀原生 systemd 单元下服务不是 PID 1systemctl stop直接落入内核默认处置瞬间被杀——快是快但没有 drain进行中的持久化 SessionEnd 合并 worker 会被拦腰斩断。现在那次停机更慢但干净。5 秒上界是固定值、不可配置docker kill仍是不等 drain 直接停的途径。不需要任何 init shim二进制自己安装信号处理器作为 PID 1 也能正确停机你无需tini或docker run --init相关测试见 tests/suite/shutdown_signals.rs 与 tests/suite/serve_shutdown.rs。更新 API 密钥$EDITOR docker/.env.production scp docker/.env.production $SERVER:$DEPLOY_DIR/.env.production ssh $SERVER cd $DEPLOY_DIR docker compose up -ddocker compose up -d会读取 env 文件并用新值重建容器无需重新构建镜像。LLM Provider 选型.env.production.example 默认配置是Kimi 2.6 走 OpenRouteropenai-compat 传输$0.73/$3.49 每百万 token。官方文档给出的合理备选Provider模型单次合并consolidation约计成本备注anthropicclaude-haiku-4-5~$0.02推荐默认。速度、克制与分类质量的最佳平衡。非推理模型openai-compat (OpenRouter)moonshotai/kimi-k2.6~$0.013推理模型单次合并延迟约 2–3 分钟。可接受因为合并是 fire-and-forgetopenaigpt-5.4-mini~$0.002更便宜、更快质量尚可openai-oauthgpt-5.5ChatGPT 订阅ChatGPT/Codex 后端。需在服务器主机执行docker exec -it ai-memory ai-memory auth login openai-oauth让data_dir/auth.json落在挂载的数据卷内copilotgpt-5.5GitHub Copilot 订阅GitHub Copilot Chat 后端。同样在服务器主机执行docker exec -it ai-memory ai-memory auth login copilot或设置COPILOT_GITHUB_TOKENgeminigemini-3.5-flash免费额度覆盖个人使用Google 托管原生responseSchema结构化输出。设置GEMINI_API_KEY或GOOGLE_API_KEYopenai-compat (Ollama)qwen3:32b$0自托管。设置AI_MEMORY_LLM_BASE_URLhttp://host.docker.internal:11434/v1。质量取决于模型官方不推荐推理模式模型Kimi-K2.6 推理模式、开启 extended thinking 的 Claude、GPT-o3、Gemini thinking 变体——它们会在输出前烧 token 做内部推理并且面对严格 JSON 的合并提示词容易挂起或返回空响应。若必须用请关闭推理。provider 细节与兼容性开关ai-memory 托管的 OpenAI 系 provider 对结构化输出使用json_schema严格模式OpenAI provider 会把 schemars 输出归一化为 OpenAI 支持的子集additionalProperties: false、完整required、生成的 enumanyOf、纯$ref节点。openai-compat的本地与网关端点默认使用同样的 schema 约束请求对明确的能力拒绝或畸形输出有宽容回退。对不兼容端点可设AI_MEMORY_LLM_COMPAT_STRICTfalse。换成小众本地模型前先跑一次ai-memory llm-test验证。每个 chat provider 将单个 HTTP 请求上限设为300 秒。慢速托管网关免费聚合层实测会出现流式输出长完成可能超过这个上限导致每个请求都报http: error sending request此时在容器环境中调高AI_MEMORY_LLM_TIMEOUT_SECS以匹配网关最坏情况的生成时间。额外请求头.env.production.example还支持AI_MEMORY_LLM_HEADERS逗号分隔的NameValue或Name: Value条目为需要请求关联的网关附加自定义头。注意header 值内不能包含逗号否则用 config.toml 的llm_headers [...]ai-memory 自己会设置的头authorization、content-type、x-api-key 等在启动时被拒绝设置值永不记日志。opencodeprovider 无需此项——它已为每个逻辑操作发送稳定的x-opencode-session覆盖它仅用于区分多个实例。备份策略2.0 升级提示2.0 镜像首次启动会执行 OKF 格式迁移在触碰任何数据前先把整个数据目录归档到卷上的/data/backups/容器会被自动检测到AI_MEMORY_BACKUP_DIR可覆盖。wiki 主页会一直显示归档位置直到你删除它。详见 docs/MIGRATION-2.0.md。数据目录就是你在docker-compose.prod.yml里挂载的目录默认/var/opt/docker/utils/ai-memory/data/结构如下data/ ├── wiki/ # markdown —— 用 rsync 或 git push 到远端备份 ├── raw/ # 不可变的会话日志归档 ├── db/ # memory.sqlite (FTS5 entities page_embeddings) ├── logs/ # 每日滚动追踪日志 └── models/ # 预留给未来的本地 embedder点时间一致性快照ssh $SERVER docker exec ai-memory /usr/local/bin/ai-memory backup --to /data/snapshot-$(date %F).tar.gz scp $SERVER:$DEPLOY_DIR/data/snapshot-$(date %F).tar.gz ./backups/ai-memory backup命令的实现位于 crates/ai-memory-cli/src/commands/backup.rs它向服务器的/admin/backup端点发起 POST把返回的 gzip 压缩包流式写入目标路径。文档明确说明服务器端使用SQLite 的 online backup API因此快照期间正在进行的写入也能保持一致——数据库不会被争用。多人 / 多 harness 共享一台服务器部署形态的最终形态通常是共享同事之间共享一个项目或你自己的多个 harness 共用一个后端。发 URL 前有两件事必须知道。一个数据目录只能跑一个 server。让两个ai-memory serve进程指向同一份data/同步文件夹、NFS 挂载、共享卷上的两个容器它们会各自运行自己的 writer 与 wiki git 句柄。SQLite 扛得住这种并发wiki 与进程内状态扛不住。正确做法是只跑一个 server让所有人连它——这也正是共享知识模型成立的前提。检查隔离模式。无作用域unscopedMCP 调用通过一个指针解析当前项目自 v1.39 起该指针按调用方PerActor键控。启动日志会打印当前生效的模式active-project isolation mode modePerActor …PerActor是默认值也是共享服务器上想要的那个。Single是进程级单槽位——单个 harness 没问题但并发会话会共享它且无作用域的写入也通过它解析。详见 docs/auto-scope.md 与 docs/users.md。一台服务器能扛多少负载所有写入都经过单一 writer actor——这对 SQLite 是正确设计随之而来的问题自然是它何时成为瓶颈。以下数据是实测而非估算复现命令cargo test -p ai-memory-store --test writer_throughput -- --ignored --nocapture并发写入者吞吐平均延迟142/s23.9 ms8295/s3.4 ms32698/s1.43 ms128700/s1.43 ms分两部分解读天花板约 700 次写入/秒在约 32 个并发写入者时触达并保持平直——128 个写入者得到相同吞吐与延迟。饱和之后服务器施加背压而非降级队列上限 1024配以 awaiting send所以超过队列的突发会放慢生产者但每条写入最终都会落盘。没有丢弃也没有无界增长。单写入者延迟由fsync主导而非 CPU。每次提交一条 observation 约等于一次磁盘同步并发让 SQLite 合并 WAL 提交这正是吞吐提升 17 倍而单写延迟反而下降的原因。容量规划参考一个活跃工作的 Agent 每个工具调用约产生一条生命周期写入。即便按悲观的每个 Agent 每秒一次工具调用估算~700/s 也对应数百个同时活跃的 Agent——远超一个团队也超过大多数共享安装。writer 不会是第一个坏掉的东西。两条使用前提数据测自本地快速磁盘因为成本在fsync网络文件系统或慢卷会显著降低数字——这是数据目录必须放本地存储的又一理由。且测的是 store 而非 HTTP 前门——真能打满它的安装瓶颈更可能出在 Agent 侧而不是 SQLite。回收磁盘空间SQLite不会把删除的空间还给文件系统。被删行留下的页挂在freelist上数据库再次增长时会被复用。对稳态使用的 store这是正确行为无需关注。ai-memory status会报告决策依据的数字storage: 2.4 GiB on disk, 610.0 MiB reclaimable (25.4%) ai-memory compact --confirm would return it (blocks writes while it runs)这行建议只在积压值得处理时才出现。出现时ssh $SERVER docker exec ai-memory /usr/local/bin/ai-memory compact --confirm压缩不删除任何数据——它重建 FTS 索引并执行VACUUMcompact.rs 会打印bytes_reclaimed无空闲页可回收时也会如实说明。不要安排无条件的每日 VACUUM最自然的想法是每天 cron 一次官方文档明确反对VACUUM需要排他锁并重写整个数据库。期间所有写入阻塞——在大 store 上是分钟级。而这台服务器的本职是响应 hook 流量阻塞写入 丢捕获它需要大约数据库自身大小的空闲磁盘等于给每日任务设置了永久的空闲空间下限SQLite 复用空闲页稳态使用的 store 通常几乎无可回收。夜间跑一次大多数晚上付出全价却毫无收益。真正会留下大 freelist 的是一次性删除——purge-project、大范围保留期清扫、跨数月 episodic 页面的forget-sweep。这些是事件而非节奏且破坏性命令本身就提供内联--compact用于那一刻。若仍要自动化请条件化触发并放在非高峰时段#!/usr/bin/env bash # /usr/local/bin/ai-memory-compact-if-worthwhile set -euo pipefail RECLAIMABLE$(ai-memory status --json | jq .storage.reclaimable_bytes) THRESHOLD$((1024 * 1024 * 1024)) # 1 GiB —— 按你的 store 调 if [ $RECLAIMABLE -ge $THRESHOLD ]; then ai-memory compact --confirm fi用 systemd timerOnCalendarSun 04:00、Persistenttrue或主机 cron 驱动。每周一次通常什么都不做的检查代价只是一次廉价的status调用每晚一次通常什么都没用的VACUUM代价是每晚一次写入停顿。压缩不是什么它不是擦除。wiki 的 git 历史把页面内容保留在对象与提交信息中之前任何备份也仍保有全部内容。压缩只是从活跃的 SQLite 文件中归还字节——按它自身的价值值得做但不保证内容不可恢复。完整边界见 docs/lifecycle-ops.md。回滚ssh $SERVER cd $DEPLOY_DIR \ docker tag $IMAGE $IMAGE-rollback \ docker pull $IMAGEsha256:old-digest ssh $SERVER cd $DEPLOY_DIR docker compose up -d最简单的回滚是按 digest 找回旧镜像。项目没有bin/rollback脚本因为正确做法是每次部署前保留上一个镜像 tagDocker Hub 免费按 digest 保留每次推送。先docker tag当前镜像为-rollback再拉旧 digest是为了给当前部署留一条退路避免拉取失败后两头落空。查看日志ssh $SERVER docker logs -f --tail 100 ai-memory或在主机上翻阅每日滚动日志ssh $SERVER ls -la $DEPLOY_DIR/data/logs/ ssh $SERVER tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date %F)排障手册curl http://host:49374/mcp报Connection refused容器没起来或端口映射绑到了127.0.0.1而非0.0.0.0。在 homelab 上查docker ps。状态unhealthy容器在运行但内嵌的ai-memory status健康检查失败。最常见原因是数据目录权限与容器用户uid 1000不匹配。在主机上修复sudo chown -R 1000:1000 $DEPLOY_DIR/data。更换模型后 Embedding 不匹配存储的(provider, model, dim)三元组与配置不一致时启动日志会告警。混合检索会忽略过期行直到它们被重新嵌入。正常启动服务器后执行ai-memory embed --force重建工作区所有项目或加--project name限定范围。启用定时 embedding backfill 也能补缺失行。捕获看起来延迟或 observation 缺失ai-memory status报告本地 hook-spool 健康度——客户端排队了多少事件、最老事件年龄、失败投递总次数spool: pending: 2 oldest: 15m 0s retries: 4非空 spool 且最老条目持续老化 hook 已到达本地队列但没到服务器事件不会丢服务器可达后会自动 drain。pending: 0说明捕获跟上了。注意 spool 是客户端侧的因此这段反映的是你执行命令的那台机器而非服务器——即使AI_MEMORY_SERVER_URL指向 homelab它也读取本地数据目录。服务器完全不可达时它也会打印输出到 stderr--json消费者仍能在 stdout 拿到单一对象——这正是积压最值得看的时候。--json以spool对象携带同样数字pending、oldest_age_ms、retries_total。Provider 失败ai-memory status报告最近一次真实 provider 调用得到的被动式 LLM 与 embedding 健康度。新进程在服务器真正使用该角色前显示unknown它不会主动探测 provider、也不会为健康报告花费 token。容器重启循环查看docker logs ai-memory——顶部的ai-memory starting行报告解析后的配置缺少必要 env var例如选了openai-compat但没设LLM_API_KEY也没有模型会在这里以清晰错误失败退出。小结把 docs/deploy.md 的部署模式落地为生产服务核心动作可以压缩成一句话模板复制 → 填值 → 首次 scp bin/deploy→ 打开 bearer 鉴权 → 按需上 TLS → 例行bin/deploy。真正决定部署质量的不是命令本身而是几个容易被跳过的细节数据目录必须chown 1000:1000、镜像 tag 必须用私有 tag 以免压扁多架构 manifest、LAN 绑定必须配AI_MEMORY_AUTH_TOKEN、备份要认准 SQLite online backup 的一致性保证、磁盘回收要条件化而非无条件每晚 VACUUM。理解了 5 秒有界 shutdown 与单 writer 背压设计之后你对这台服务器的运维判断会从照抄命令升级为理解机理。【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考