TencentDB-Agent-Memory 全局镜像本地部署指南memory-core / memory-hub / proxy 三件套一键拉起与配置详解【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory本指南围绕仓库 deploy/global-images 目录下的 Docker 全局镜像部署方案展开讲解如何在本机用一条命令拉起 TencentDB-Agent-Memory 的「全局三件套」——memory-core记忆内核 gateway、memory-hub管理面板 知识服务与proxyLLM 转发代理。读完本文你将掌握.env两组独立 LLM 参数的填法、启动前的 LLM 通路预检、内部凭据的安全边界、单组件独立使用与数据持久化等完整实操能力并能把proxy直接接入 Claude Code 等 coding agent 作为 API 入口。一、三件套是什么组件、镜像与端口全局三件套镜像将 TencentDB-Agent-Memory 的三大能力拆成三个可独立运行、也可串联的容器。它们都发布在 Docker Hub 的agentmemory命名空间下多架构linux/amd64linux/arm64公开可拉、无需登录组件容器名镜像Docker Hub 公开宿主机端口用途memory-coretdai-memory-coreagentmemory/memory-core8420内核 gateway记忆读写、鉴权、skill/RAG 数据面memory-hubtdai-memory-hubagentmemory/memory-hub8125/8424管理面板 (Panel) 知识服务 (Knowledge) 合并镜像proxytdai-proxyagentmemory/memory-proxy8096LLM 请求转发代理coding agent 的 API 入口三个镜像相互配合的分工是memory-core承担记忆与鉴权内核memory-hub提供 Panel 管理界面与 Knowledge 知识服务proxy则作为客户端尤其是 coding agent的统一 LLM 入口把请求转发到上游的同时完成记忆注入。想固定版本时把.env里的镜像 tag 从:latest换成具体版本即可例如:1.0.0-beta.1。腾讯内部同事也可以覆盖到内网私仓mirrors.tencent.com/memory-team-control/—— 见 deploy/global-images/.env.example 里注释掉的备选块。二、环境要求部署脚本对宿主机的依赖非常轻量macOS / LinuxDockerDocker Desktop / colima / OrbStack 任一bash4macOS 自带 3.2 也能跑值得注意的是脚本对 Docker 命令的定位做了兼容处理。在 deploy/global-images/_lib.sh 的find_docker()中查找优先级依次是PATH 中的docker→ Homebrew apple silicon Cellar → Homebrew intel Cellar →/usr/local兼容了 Homebrew 独立安装与 colima 场景。三、快速开始四步完成三件套部署# 1) 准备 .env cp .env.example .env # 2) 编辑 .env把两组 LLM 参数填成真值 # - MEMORY_LLM_* → memory-core memory-hub 内部用 # - PROXY_UPSTREAM_* → proxy 转发到的上游 LLM $EDITOR .env # 3) 干跑校验不启动容器 # 默认会同时校验 LLM 通路 —— 提前验证 API key/URL/模型名避免起服务后才发现配错 ./verify.sh # 不希望发外部请求离线环境等./verify.sh --skip-llm # 4) 一键拉起三件套 ./start-all.shstart-all.sh的启动顺序是有讲究的见 deploy/global-images/start-all.sh先起 memory内核等 healthy再起 memory-hub面板 知识等 healthy最后起 proxy。任意一步失败会立即中止并打印容器日志。在启动前它会一次性校验全部必填参数避免「拉起 memory 之后才发现 proxy 参数缺了」这种半途而废的情况。启动完成后各服务的访问地址Panel UIhttp://localhost:8125/Knowledge APIhttp://localhost:8424/v3/Knowledge Swaggerhttp://localhost:8424/docsMemory Gatewayhttp://localhost:8420/Proxyhttp://localhost:8096/脚本成功启动后print_endpoints()定义在_lib.sh还会在终端打印一张统一的服务地址表包含 Panel API、Knowledge Docs、Memory Core、Proxy 等全部入口。3.1 关于PULL1与镜像更新脚本默认不主动拉取镜像docker run在本地没有镜像时会自动拉但本地已有同名:latest时会直接复用不会感知远端更新。想升级到最新 latest就带环境变量执行PULL1 ./start-all.sh对应_lib.sh中的pull_image()只有PULL1时才执行docker pull。四、LLM 通路预检启动前的最后一道防线verify.sh是部署流程中最有价值的防错机制。它做「干跑校验」——不启动任何容器只检查环境是否就绪检查项依次为docker命令可用.env文件存在.env中所有必填参数已填写非REPLACE_ME且非空三个镜像是否已在本地未在本地不算失败只 warn目标端口是否被占用用lsof -iTCP:port -sTCP:LISTEN检测LLM 上游通路memory 组 proxy 组各自预检全部通过 →exit 0有错 →exit 1只 warn →exit 0。4.1 两种协议的预检方式verify.sh按协议分别处理实现见 deploy/global-images/verify.shOpenAI 兼容协议GET {base}/models只验证 API key URL不消耗任何 token。base URL 会被归一化去尾部/去/messages、/chat/completions后缀然后拼/models发起请求。若返回 200 还会宽松地检查 model 是否在列表内不在也只 warn因为部分厂商不显式列出。Anthropic 协议POST {base}/v1/messages发max_tokens1的最小消息消耗 ≤ 10 token能同时验证 URL / auth / model。401/403 判定 API key 无效404 判定 URL 不存在400 会进一步检查响应体里是否含model not found/invalid model等关键词以定位模型名错误。memory 组与 proxy 组独立验若两组配置完全相同自动跳过重复检查verify.sh会比较PROXY_UPSTREAM_URL/PROXY_UPSTREAM_API_KEY/PROXY_UPSTREAM_MODEL与 memory 组三者是否完全一致。proxy 组默认按 openai 协议检查。容器已运行时还会额外从容器内docker exec一次 curl验证「容器 → LLM」的网络可达性——这是为了覆盖一些企业代理 / DNS 隔离环境下「宿主机可达但容器不可达」的场景。容器内检查的关注点是网络可达只要能拿到任何 HTTP 状态码就算通000才算不可达auth 错在宿主机侧已经报过容器内不再重复触发 error。失败例子[error] memory 组 API key 无效HTTP 401https://api.deepseek.com/v1/models {error:{message:Authentication Fails, Your api key: ****abcd is invalid,...}}—— API key 错、URL 错、模型名错都会在启动前拦下不会等到 wiki ingest / chat 时才 401。此外verify.sh支持--skip-llm参数离线环境或不希望发外部请求时用未知参数会被 warn 后忽略--help/-h会打印脚本用法。五、两组独立参数脚本设计的核心这是脚本设计的核心—— memory 组和 proxy 组的 LLM 完全独立可以指向不同供应商 / 不同模型。完整参数模板见 deploy/global-images/.env.example。5.1 memory 组memory-core memory-hub 使用内核记忆 embed/summarize、knowledge 的 wiki ingest / 总结走这组配置。变量说明示例MEMORY_LLM_BASE_URLOpenAI 兼容 base URLhttps://api.deepseek.com/v1MEMORY_LLM_API_KEY上述端点的 API Keysk-xxxxxxxxMEMORY_LLM_MODEL模型 IDdeepseek-chatMEMORY_LLM_PROTOCOLopenai或anthropic默认openaiopenai5.2 proxy 组proxy 使用proxy 接到用户请求后转发到这组端点。变量说明示例PROXY_UPSTREAM_URL转发目标 base URLhttps://api.deepseek.com/v1PROXY_UPSTREAM_API_KEY转发用 API Keysk-xxxxxxxxPROXY_UPSTREAM_MODEL面向用户的模型 IDdeepseek-chat两组可以填相同值都指向同一个 LLM也可以完全不同例如 memory 组用便宜模型做 embeddingproxy 组用强模型做主对话。参数缺失时脚本会在启动前一次性列出所有缺失项并exit 1不会跑到一半才失败。这一行为由_lib.sh中的require_vars()实现它会遍历校验每个变量若为空或仍为REPLACE_ME则收集进缺失列表一次性打印后退出start-all.sh在拉起任何容器之前就会先调用require_vars把三件套涉及的全部必填参数校验一遍。5.3 脚本自动生成的配置两个start-*.sh会根据.env自动生成容器内挂载的 YAML 配置每次启动覆盖注释明确提示不要手动改start-memory-core.sh生成tdai-gateway.yaml挂载到容器/data/config/tdai-gateway.yaml:ro内容包含deployMode: standalone、stateBackend: local、server.port: 8420、data.baseDir: /data/tdai-memory、完整的llm段含maxTokens: 32000、timeoutMs: 300000以及memory段promptMode默认chat可通过MEMORY_PROMPT_MODE环境变量切换为codecapture/extraction/persona/pipeline/recall均含默认参数和skill段bm25 路由、队列参数等。配置落盘目录默认在./.memory-core-config可用MEMORY_CORE_CONFIG_DIR覆盖。start-proxy.sh生成 proxy 的config.yaml挂载到容器/data/config.yaml:ro因为 proxy 只从 YAML 读上游 URL / API key不认PROXY_UPSTREAM_URL环境变量。生成的配置含server、upstreamurl apiKey、tdai、skill、auth、sessionInit、injection默认打开skill/knowledge/tdai-memory三个注入器、costGuard.enabled: false、redis.enabled: false等段。完整配置参考在 MemoryProxy/config.example.yaml其中详细注释了请求处理流程客户端请求 → auth → sessionInit → injection → 转发上游 LLM → 用量/上报 → 返回客户端以及 per-agent 覆盖、状态存储后端等进阶项。六、内部凭据生产环境必看三件套之间用MEMORY_CORE_GATEWAY_API_KEY互相认证首次启动还会通过init-admin建一个system_admin账户。为了零配置本地体验脚本默认值是变量默认值用途MEMORY_CORE_GATEWAY_API_KEYlocalmemory-hub / proxy → memory-core 的 BearerMEMORY_CORE_ADMIN_USERNAMEadmin初始化的 system_admin 用户名MEMORY_CORE_ADMIN_USER_KEYadmin该 admin 用户的登录 key这三个默认值只适合个人本地跑通流程。生产/联调/公网暴露前必须替换成随机长串否则任何拿到端口的人都能拿到 system_admin 权限。在.env里取消对应三行的注释并覆盖即可_lib.sh会require_vars校验其他必填项但这三个变量因为有默认兜底脚本会在启动时打[warn]提醒你换。6.1 两条必须了解的已知约束从start-memory-core.sh的实现可以看到两条影响生产配置的重要约束MEMORY_CORE_GATEWAY_API_KEY默认留空当前 memory-core 的 Bearer gate 与 proxy auth 存在已知不兼容——proxy 调/v3/meta/auth/verify时不带 Bearer源码遗漏见MemoryProxy/src/auth.ts所以 proxy 启用 auth 时必须把该变量留空。脚本用${VAR-default}而非:-default读取允许在.env里显式设为空字符串来关闭 Bearer gate。若设非空start-memory-core.sh会打 warn 提示「proxy 的 sessionInit/auth 目前会因缺 Bearer 而失败」。admin user_key 的持久化与生命周期首次启动时脚本会生成一把 32 字节随机sk-mem-前缀的 key用openssl rand无 openssl 时兜底读/dev/urandom以umask 077收紧权限后写入宿主机文件./.admin-key路径可用MEMORY_CORE_ADMIN_KEY_FILE覆盖。重启时优先复用该文件如果 volume 是新造的但.admin-key是旧的key 无法恢复volume 与 key 必须同步此时需要./stop-all.sh --purge重建或手动创建新 admin user_key。stop-all.sh --purge会强制同步删除.admin-key文件避免下次启动读到旧 key 而 volume 已是新的导致 auth 校验失败。key 生成格式与MemoryCore/src/metadata/utils/user-key.ts保持一致。七、独立使用每个组件三个脚本可以单独执行方便调试或只需要部分能力时./start-memory-core.sh # 只跑内核 gateway8420 ./start-memory-hub.sh # 只跑面板 知识8125 8424需要 MEMORY_LLM_* 参数 ./start-proxy.sh # 只跑 proxy8096需要 PROXY_UPSTREAM_* 参数依赖关系memory-core无外部依赖可以独立起memory-hub能独立启动LLM_MODEcustom直连 LLM但内部 knowledge 调 memory-core 做 RAG 时会失败 → 建议 memory-core 先起proxy能独立启动cost-guard 不可用时自动降级 passthrough直接转发但 auth / tdai memory / skill 注入需要 memory-core 才有效任意组件缺失时脚本会warn提醒但不阻塞。例如start-memory-hub.sh在检测到tdai-memory-core容器未运行时会 warn「memory-hub 能启动但 knowledge 调 memory 时会失败」start-proxy.sh会分别检查 memory-coreauth / tdai memory / skill 注入降级与 memory-hubsessionInit control plane 不可达。7.1 共享 Docker 网络三个启动脚本都会幂等地创建共享网络tdai-memory-stack并通过--network-alias让容器以memory-core/memory-hub/proxy的别名互相访问。例如 memory-hub 通过REMOTE_INSTANCE_URLhttp://memory-core:8420访问内核proxy 生成的配置里tdai.endpoint: http://memory-core:8420、auth.url: http://memory-core:8420。7.2 proxy 的三大能力开关start-proxy.sh通过环境变量控制 proxy 的完整流水线默认最小可用只做纯转发PROXY_ENABLE_AUTH客户端凭x-tdai-user-key走内核auth/verify→ user_idPROXY_ENABLE_SESSION_INIT首轮弹表单选 team/agent/task依赖 auth tdaiPROXY_ENABLE_TDAIL2/L3 记忆注入 L1 召回依赖 memory-core便捷开关PROXY_FULL_STACK1一键把三个都开start-all.sh默认以PROXY_FULL_STACK1启动 proxy。同时脚本做了依赖自动补齐开 sessionInit 但没开 auth 时会 warn 并自动打开 auth。生成的 YAML 里sessionInit.headerAutoSelect支持从请求头x-team-id/x-agent-id/x-task-id自动选择上下文onMismatch: form表示不匹配时回退弹窗。八、数据持久化tdai-memory-core-datanamed volume→ memory-core 的 SQLite / 记忆数据tdai-panel-datanamed volume→ memory-hub 里 knowledge 的 SQLite / git clone / wiki 文件docker volume rm之前数据一直保留。改名可在.env里改MEMORY_CORE_VOLUME/PANEL_VOLUME。对应的容器挂载分别是-v ${MEMORY_CORE_VOLUME}:/data/tdai-memory与-v ${PANEL_VOLUME}:/data/knowledge。九、停止 / 清理./stop-all.sh # 停容器保留 volume下次启动数据还在 ./stop-all.sh --purge # 停容器 删 volume 删网络彻底清理stop-all.sh按tdai-proxy→tdai-memory-hub→tdai-memory-core的顺序移除容器.env不存在时也允许运行用默认卷名兜底。--purge模式下会删除两个 volume、tdai-memory-stack网络、.admin-key文件以及脚本自动生成的.proxy-config与.memory-core-config两个配置目录——保证彻底恢复到干净状态。十、查看日志docker logs -f tdai-memory-core docker logs -f tdai-memory-hub docker logs -f tdai-proxymemory-hub 内部有两个进程panel knowledge日志分别在容器内/data/knowledge/logs/panel.log和.../knowledge.log。wait_healthy在容器非 healthy 时会自动打印最近 30 行日志辅助排障。十一、端口冲突如果8125/8420/8424/8096与本地已有服务冲突直接在.env改MEMORY_CORE_PORT18420 PANEL_PORT18125 KNOWLEDGE_PORT18424 PROXY_PORT18096 # knowledge 对外可达地址要跟着 KNOWLEDGE_PORT 走 KNOWLEDGE_PUBLIC_BASE_URLhttp://host.docker.internal:18424/v3容器内部端口保持不变8420/8125/8424/8096宿主机映射端口完全由.env控制。注意KNOWLEDGE_PUBLIC_BASE_URL必须包含/v3前缀且端口要跟着KNOWLEDGE_PORT一起改否则 Panel 会报错。十二、使用 proxy 作为 coding agent 的 API base以 Claude Code 为例export ANTHROPIC_BASE_URLhttp://localhost:8096 export ANTHROPIC_API_KEYany-string-if-auth-disabled # 使用 openai 协议的客户端类似OPENAI_BASE_URLhttp://localhost:8096/v1使用start-all.sh完整拉起PROXY_FULL_STACK1后脚本还会打印一段可直接粘贴的 Claude Code 接入提示其中包含从.admin-key读取的真实 admin tokenexport ANTHROPIC_BASE_URLhttp://127.0.0.1:8096/claude-code/default export ANTHROPIC_AUTH_TOKENadmin key claude --model PROXY_UPSTREAM_MODEL12.1 Panel UI 的「客户端接入地址」卡片Panel UI 的「客户端接入地址」卡片会自动拼上宿主机的 LAN IP PROXY_PORT例如http://192.168.1.100:8096/codebuddy/default别人的电脑复制过去就能直接连过来。这个值由MEMORY_HUB_PROXY_PUBLIC_URL注入到 memory-hub 里的metadata-instances.json.proxy_endpoint未设置时start-memory-hub.sh按顺序自动探测宿主机对外可达地址——Linux 上hostname -I首个非 127 / 非 169.254 的 IPv4LAN IP→ macOS 上ipconfig getifaddr en0/en1/en2→ Linux 无hostname -I时用ip -4 route get 1取 src → 全部失败才回落localhost。自动探测的地址不对时多网卡 / 公网域名 / 反代前置在.env显式设MEMORY_HUB_PROXY_PUBLIC_URLhttp://真值:8096。想让 UI 卡片走老行为回落到 gateway_endpoint把MEMORY_HUB_PROXY_PUBLIC_URL显式设为空字符串。注意Panel 后端 → Kernel 的转发不受此变量影响始终走REMOTE_INSTANCE_URL→http://memory-core:8420。12.2 proxy 默认与完整流水线的差异proxy默认关闭auth/sessionInit/costGuard这些依赖内部服务只做纯转发 tdai-memory上下文注入injector 名称非容器名。要开启完整流水线用PROXY_FULL_STACK1或分别设置PROXY_ENABLE_AUTH/PROXY_ENABLE_SESSION_INIT/PROXY_ENABLE_TDAI完整配置语义参见 MemoryProxy/config.example.yaml。十三、容器外访问宿主机服务脚本已默认给 memory-hub 和 proxy 加了--add-hosthost.docker.internal:host-gateway。容器内用http://host.docker.internal:port即可访问宿主机上其它服务Ollama、Langfuse 等。KNOWLEDGE_PUBLIC_BASE_URL的默认值也正是利用了这一点http://host.docker.internal:8424/v3让容器内可回环到宿主端口。十四、常见问题Q:./start-all.sh卡在 wait_healthy镜像可能还在拉取。用docker pull IMAGE手动预拉一次再跑脚本或使用PULL1。wait_healthy默认最长等待 90 秒memory-hub 为 120 秒期间容器非 running / unhealthy / 超时都会打印最近 30 行日志后die。Q: memory-hub 起来但 Panel 打不开检查.env里KNOWLEDGE_PUBLIC_BASE_URL是不是含/v3—— 缺/v3panel 会报错。Q: proxy 转发返回 401PROXY_UPSTREAM_API_KEY无效或PROXY_UPSTREAM_URL不匹配。用docker logs tdai-proxy看错误。Q: 如何在容器外访问宿主机上其它服务Ollama、Langfuse 等脚本已默认--add-hosthost.docker.internal:host-gateway。容器内用http://host.docker.internal:port即可。Q:start-all.sh用:latest但跑的还是旧镜像本地已有同名:latest时脚本会直接复用。想升级用PULL1 ./start-all.sh强制拉取最新版。Q:stop-all.sh --purge后重启admin 登录失败.admin-key与 volume 强绑定purge 会同步删除两者属预期行为重启后脚本会重新生成一把新的随机 key 并写入.admin-key。反之若只删了 volume 没删 key 文件或只删 key 没删 volume都会出现 auth 校验失败需要保持一致。十五、小结deploy/global-images目录提供了一套完整的「零配置优先、生产可加固」的本地部署方案_lib.sh统一处理.env加载、必填参数一次性校验、Docker 定位、健康等待与地址表打印verify.sh在启动前就把 API key / URL / 模型名 / 端口冲突 / 容器内网络可达性全部拦下三个start-*.sh可组合可拆分并通过自动生成的 YAML 配置把 memory 组与 proxy 组的 LLM 彻底解耦。对于只需要跑通本地流程的场景cp .env.example .env→ 填两组 LLM 参数 →./verify.sh→./start-all.sh四步即可完成对于生产环境务必把内部凭据替换为随机长串并留意MEMORY_CORE_GATEWAY_API_KEY与 proxy auth 的已知兼容约束。【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TencentDB-Agent-Memory 全局镜像本地部署指南：memory-core / memory-hub / proxy 三件套一键拉起与配置详解
TencentDB-Agent-Memory 全局镜像本地部署指南memory-core / memory-hub / proxy 三件套一键拉起与配置详解【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory本指南围绕仓库 deploy/global-images 目录下的 Docker 全局镜像部署方案展开讲解如何在本机用一条命令拉起 TencentDB-Agent-Memory 的「全局三件套」——memory-core记忆内核 gateway、memory-hub管理面板 知识服务与proxyLLM 转发代理。读完本文你将掌握.env两组独立 LLM 参数的填法、启动前的 LLM 通路预检、内部凭据的安全边界、单组件独立使用与数据持久化等完整实操能力并能把proxy直接接入 Claude Code 等 coding agent 作为 API 入口。一、三件套是什么组件、镜像与端口全局三件套镜像将 TencentDB-Agent-Memory 的三大能力拆成三个可独立运行、也可串联的容器。它们都发布在 Docker Hub 的agentmemory命名空间下多架构linux/amd64linux/arm64公开可拉、无需登录组件容器名镜像Docker Hub 公开宿主机端口用途memory-coretdai-memory-coreagentmemory/memory-core8420内核 gateway记忆读写、鉴权、skill/RAG 数据面memory-hubtdai-memory-hubagentmemory/memory-hub8125/8424管理面板 (Panel) 知识服务 (Knowledge) 合并镜像proxytdai-proxyagentmemory/memory-proxy8096LLM 请求转发代理coding agent 的 API 入口三个镜像相互配合的分工是memory-core承担记忆与鉴权内核memory-hub提供 Panel 管理界面与 Knowledge 知识服务proxy则作为客户端尤其是 coding agent的统一 LLM 入口把请求转发到上游的同时完成记忆注入。想固定版本时把.env里的镜像 tag 从:latest换成具体版本即可例如:1.0.0-beta.1。腾讯内部同事也可以覆盖到内网私仓mirrors.tencent.com/memory-team-control/—— 见 deploy/global-images/.env.example 里注释掉的备选块。二、环境要求部署脚本对宿主机的依赖非常轻量macOS / LinuxDockerDocker Desktop / colima / OrbStack 任一bash4macOS 自带 3.2 也能跑值得注意的是脚本对 Docker 命令的定位做了兼容处理。在 deploy/global-images/_lib.sh 的find_docker()中查找优先级依次是PATH 中的docker→ Homebrew apple silicon Cellar → Homebrew intel Cellar →/usr/local兼容了 Homebrew 独立安装与 colima 场景。三、快速开始四步完成三件套部署# 1) 准备 .env cp .env.example .env # 2) 编辑 .env把两组 LLM 参数填成真值 # - MEMORY_LLM_* → memory-core memory-hub 内部用 # - PROXY_UPSTREAM_* → proxy 转发到的上游 LLM $EDITOR .env # 3) 干跑校验不启动容器 # 默认会同时校验 LLM 通路 —— 提前验证 API key/URL/模型名避免起服务后才发现配错 ./verify.sh # 不希望发外部请求离线环境等./verify.sh --skip-llm # 4) 一键拉起三件套 ./start-all.shstart-all.sh的启动顺序是有讲究的见 deploy/global-images/start-all.sh先起 memory内核等 healthy再起 memory-hub面板 知识等 healthy最后起 proxy。任意一步失败会立即中止并打印容器日志。在启动前它会一次性校验全部必填参数避免「拉起 memory 之后才发现 proxy 参数缺了」这种半途而废的情况。启动完成后各服务的访问地址Panel UIhttp://localhost:8125/Knowledge APIhttp://localhost:8424/v3/Knowledge Swaggerhttp://localhost:8424/docsMemory Gatewayhttp://localhost:8420/Proxyhttp://localhost:8096/脚本成功启动后print_endpoints()定义在_lib.sh还会在终端打印一张统一的服务地址表包含 Panel API、Knowledge Docs、Memory Core、Proxy 等全部入口。3.1 关于PULL1与镜像更新脚本默认不主动拉取镜像docker run在本地没有镜像时会自动拉但本地已有同名:latest时会直接复用不会感知远端更新。想升级到最新 latest就带环境变量执行PULL1 ./start-all.sh对应_lib.sh中的pull_image()只有PULL1时才执行docker pull。四、LLM 通路预检启动前的最后一道防线verify.sh是部署流程中最有价值的防错机制。它做「干跑校验」——不启动任何容器只检查环境是否就绪检查项依次为docker命令可用.env文件存在.env中所有必填参数已填写非REPLACE_ME且非空三个镜像是否已在本地未在本地不算失败只 warn目标端口是否被占用用lsof -iTCP:port -sTCP:LISTEN检测LLM 上游通路memory 组 proxy 组各自预检全部通过 →exit 0有错 →exit 1只 warn →exit 0。4.1 两种协议的预检方式verify.sh按协议分别处理实现见 deploy/global-images/verify.shOpenAI 兼容协议GET {base}/models只验证 API key URL不消耗任何 token。base URL 会被归一化去尾部/去/messages、/chat/completions后缀然后拼/models发起请求。若返回 200 还会宽松地检查 model 是否在列表内不在也只 warn因为部分厂商不显式列出。Anthropic 协议POST {base}/v1/messages发max_tokens1的最小消息消耗 ≤ 10 token能同时验证 URL / auth / model。401/403 判定 API key 无效404 判定 URL 不存在400 会进一步检查响应体里是否含model not found/invalid model等关键词以定位模型名错误。memory 组与 proxy 组独立验若两组配置完全相同自动跳过重复检查verify.sh会比较PROXY_UPSTREAM_URL/PROXY_UPSTREAM_API_KEY/PROXY_UPSTREAM_MODEL与 memory 组三者是否完全一致。proxy 组默认按 openai 协议检查。容器已运行时还会额外从容器内docker exec一次 curl验证「容器 → LLM」的网络可达性——这是为了覆盖一些企业代理 / DNS 隔离环境下「宿主机可达但容器不可达」的场景。容器内检查的关注点是网络可达只要能拿到任何 HTTP 状态码就算通000才算不可达auth 错在宿主机侧已经报过容器内不再重复触发 error。失败例子[error] memory 组 API key 无效HTTP 401https://api.deepseek.com/v1/models {error:{message:Authentication Fails, Your api key: ****abcd is invalid,...}}—— API key 错、URL 错、模型名错都会在启动前拦下不会等到 wiki ingest / chat 时才 401。此外verify.sh支持--skip-llm参数离线环境或不希望发外部请求时用未知参数会被 warn 后忽略--help/-h会打印脚本用法。五、两组独立参数脚本设计的核心这是脚本设计的核心—— memory 组和 proxy 组的 LLM 完全独立可以指向不同供应商 / 不同模型。完整参数模板见 deploy/global-images/.env.example。5.1 memory 组memory-core memory-hub 使用内核记忆 embed/summarize、knowledge 的 wiki ingest / 总结走这组配置。变量说明示例MEMORY_LLM_BASE_URLOpenAI 兼容 base URLhttps://api.deepseek.com/v1MEMORY_LLM_API_KEY上述端点的 API Keysk-xxxxxxxxMEMORY_LLM_MODEL模型 IDdeepseek-chatMEMORY_LLM_PROTOCOLopenai或anthropic默认openaiopenai5.2 proxy 组proxy 使用proxy 接到用户请求后转发到这组端点。变量说明示例PROXY_UPSTREAM_URL转发目标 base URLhttps://api.deepseek.com/v1PROXY_UPSTREAM_API_KEY转发用 API Keysk-xxxxxxxxPROXY_UPSTREAM_MODEL面向用户的模型 IDdeepseek-chat两组可以填相同值都指向同一个 LLM也可以完全不同例如 memory 组用便宜模型做 embeddingproxy 组用强模型做主对话。参数缺失时脚本会在启动前一次性列出所有缺失项并exit 1不会跑到一半才失败。这一行为由_lib.sh中的require_vars()实现它会遍历校验每个变量若为空或仍为REPLACE_ME则收集进缺失列表一次性打印后退出start-all.sh在拉起任何容器之前就会先调用require_vars把三件套涉及的全部必填参数校验一遍。5.3 脚本自动生成的配置两个start-*.sh会根据.env自动生成容器内挂载的 YAML 配置每次启动覆盖注释明确提示不要手动改start-memory-core.sh生成tdai-gateway.yaml挂载到容器/data/config/tdai-gateway.yaml:ro内容包含deployMode: standalone、stateBackend: local、server.port: 8420、data.baseDir: /data/tdai-memory、完整的llm段含maxTokens: 32000、timeoutMs: 300000以及memory段promptMode默认chat可通过MEMORY_PROMPT_MODE环境变量切换为codecapture/extraction/persona/pipeline/recall均含默认参数和skill段bm25 路由、队列参数等。配置落盘目录默认在./.memory-core-config可用MEMORY_CORE_CONFIG_DIR覆盖。start-proxy.sh生成 proxy 的config.yaml挂载到容器/data/config.yaml:ro因为 proxy 只从 YAML 读上游 URL / API key不认PROXY_UPSTREAM_URL环境变量。生成的配置含server、upstreamurl apiKey、tdai、skill、auth、sessionInit、injection默认打开skill/knowledge/tdai-memory三个注入器、costGuard.enabled: false、redis.enabled: false等段。完整配置参考在 MemoryProxy/config.example.yaml其中详细注释了请求处理流程客户端请求 → auth → sessionInit → injection → 转发上游 LLM → 用量/上报 → 返回客户端以及 per-agent 覆盖、状态存储后端等进阶项。六、内部凭据生产环境必看三件套之间用MEMORY_CORE_GATEWAY_API_KEY互相认证首次启动还会通过init-admin建一个system_admin账户。为了零配置本地体验脚本默认值是变量默认值用途MEMORY_CORE_GATEWAY_API_KEYlocalmemory-hub / proxy → memory-core 的 BearerMEMORY_CORE_ADMIN_USERNAMEadmin初始化的 system_admin 用户名MEMORY_CORE_ADMIN_USER_KEYadmin该 admin 用户的登录 key这三个默认值只适合个人本地跑通流程。生产/联调/公网暴露前必须替换成随机长串否则任何拿到端口的人都能拿到 system_admin 权限。在.env里取消对应三行的注释并覆盖即可_lib.sh会require_vars校验其他必填项但这三个变量因为有默认兜底脚本会在启动时打[warn]提醒你换。6.1 两条必须了解的已知约束从start-memory-core.sh的实现可以看到两条影响生产配置的重要约束MEMORY_CORE_GATEWAY_API_KEY默认留空当前 memory-core 的 Bearer gate 与 proxy auth 存在已知不兼容——proxy 调/v3/meta/auth/verify时不带 Bearer源码遗漏见MemoryProxy/src/auth.ts所以 proxy 启用 auth 时必须把该变量留空。脚本用${VAR-default}而非:-default读取允许在.env里显式设为空字符串来关闭 Bearer gate。若设非空start-memory-core.sh会打 warn 提示「proxy 的 sessionInit/auth 目前会因缺 Bearer 而失败」。admin user_key 的持久化与生命周期首次启动时脚本会生成一把 32 字节随机sk-mem-前缀的 key用openssl rand无 openssl 时兜底读/dev/urandom以umask 077收紧权限后写入宿主机文件./.admin-key路径可用MEMORY_CORE_ADMIN_KEY_FILE覆盖。重启时优先复用该文件如果 volume 是新造的但.admin-key是旧的key 无法恢复volume 与 key 必须同步此时需要./stop-all.sh --purge重建或手动创建新 admin user_key。stop-all.sh --purge会强制同步删除.admin-key文件避免下次启动读到旧 key 而 volume 已是新的导致 auth 校验失败。key 生成格式与MemoryCore/src/metadata/utils/user-key.ts保持一致。七、独立使用每个组件三个脚本可以单独执行方便调试或只需要部分能力时./start-memory-core.sh # 只跑内核 gateway8420 ./start-memory-hub.sh # 只跑面板 知识8125 8424需要 MEMORY_LLM_* 参数 ./start-proxy.sh # 只跑 proxy8096需要 PROXY_UPSTREAM_* 参数依赖关系memory-core无外部依赖可以独立起memory-hub能独立启动LLM_MODEcustom直连 LLM但内部 knowledge 调 memory-core 做 RAG 时会失败 → 建议 memory-core 先起proxy能独立启动cost-guard 不可用时自动降级 passthrough直接转发但 auth / tdai memory / skill 注入需要 memory-core 才有效任意组件缺失时脚本会warn提醒但不阻塞。例如start-memory-hub.sh在检测到tdai-memory-core容器未运行时会 warn「memory-hub 能启动但 knowledge 调 memory 时会失败」start-proxy.sh会分别检查 memory-coreauth / tdai memory / skill 注入降级与 memory-hubsessionInit control plane 不可达。7.1 共享 Docker 网络三个启动脚本都会幂等地创建共享网络tdai-memory-stack并通过--network-alias让容器以memory-core/memory-hub/proxy的别名互相访问。例如 memory-hub 通过REMOTE_INSTANCE_URLhttp://memory-core:8420访问内核proxy 生成的配置里tdai.endpoint: http://memory-core:8420、auth.url: http://memory-core:8420。7.2 proxy 的三大能力开关start-proxy.sh通过环境变量控制 proxy 的完整流水线默认最小可用只做纯转发PROXY_ENABLE_AUTH客户端凭x-tdai-user-key走内核auth/verify→ user_idPROXY_ENABLE_SESSION_INIT首轮弹表单选 team/agent/task依赖 auth tdaiPROXY_ENABLE_TDAIL2/L3 记忆注入 L1 召回依赖 memory-core便捷开关PROXY_FULL_STACK1一键把三个都开start-all.sh默认以PROXY_FULL_STACK1启动 proxy。同时脚本做了依赖自动补齐开 sessionInit 但没开 auth 时会 warn 并自动打开 auth。生成的 YAML 里sessionInit.headerAutoSelect支持从请求头x-team-id/x-agent-id/x-task-id自动选择上下文onMismatch: form表示不匹配时回退弹窗。八、数据持久化tdai-memory-core-datanamed volume→ memory-core 的 SQLite / 记忆数据tdai-panel-datanamed volume→ memory-hub 里 knowledge 的 SQLite / git clone / wiki 文件docker volume rm之前数据一直保留。改名可在.env里改MEMORY_CORE_VOLUME/PANEL_VOLUME。对应的容器挂载分别是-v ${MEMORY_CORE_VOLUME}:/data/tdai-memory与-v ${PANEL_VOLUME}:/data/knowledge。九、停止 / 清理./stop-all.sh # 停容器保留 volume下次启动数据还在 ./stop-all.sh --purge # 停容器 删 volume 删网络彻底清理stop-all.sh按tdai-proxy→tdai-memory-hub→tdai-memory-core的顺序移除容器.env不存在时也允许运行用默认卷名兜底。--purge模式下会删除两个 volume、tdai-memory-stack网络、.admin-key文件以及脚本自动生成的.proxy-config与.memory-core-config两个配置目录——保证彻底恢复到干净状态。十、查看日志docker logs -f tdai-memory-core docker logs -f tdai-memory-hub docker logs -f tdai-proxymemory-hub 内部有两个进程panel knowledge日志分别在容器内/data/knowledge/logs/panel.log和.../knowledge.log。wait_healthy在容器非 healthy 时会自动打印最近 30 行日志辅助排障。十一、端口冲突如果8125/8420/8424/8096与本地已有服务冲突直接在.env改MEMORY_CORE_PORT18420 PANEL_PORT18125 KNOWLEDGE_PORT18424 PROXY_PORT18096 # knowledge 对外可达地址要跟着 KNOWLEDGE_PORT 走 KNOWLEDGE_PUBLIC_BASE_URLhttp://host.docker.internal:18424/v3容器内部端口保持不变8420/8125/8424/8096宿主机映射端口完全由.env控制。注意KNOWLEDGE_PUBLIC_BASE_URL必须包含/v3前缀且端口要跟着KNOWLEDGE_PORT一起改否则 Panel 会报错。十二、使用 proxy 作为 coding agent 的 API base以 Claude Code 为例export ANTHROPIC_BASE_URLhttp://localhost:8096 export ANTHROPIC_API_KEYany-string-if-auth-disabled # 使用 openai 协议的客户端类似OPENAI_BASE_URLhttp://localhost:8096/v1使用start-all.sh完整拉起PROXY_FULL_STACK1后脚本还会打印一段可直接粘贴的 Claude Code 接入提示其中包含从.admin-key读取的真实 admin tokenexport ANTHROPIC_BASE_URLhttp://127.0.0.1:8096/claude-code/default export ANTHROPIC_AUTH_TOKENadmin key claude --model PROXY_UPSTREAM_MODEL12.1 Panel UI 的「客户端接入地址」卡片Panel UI 的「客户端接入地址」卡片会自动拼上宿主机的 LAN IP PROXY_PORT例如http://192.168.1.100:8096/codebuddy/default别人的电脑复制过去就能直接连过来。这个值由MEMORY_HUB_PROXY_PUBLIC_URL注入到 memory-hub 里的metadata-instances.json.proxy_endpoint未设置时start-memory-hub.sh按顺序自动探测宿主机对外可达地址——Linux 上hostname -I首个非 127 / 非 169.254 的 IPv4LAN IP→ macOS 上ipconfig getifaddr en0/en1/en2→ Linux 无hostname -I时用ip -4 route get 1取 src → 全部失败才回落localhost。自动探测的地址不对时多网卡 / 公网域名 / 反代前置在.env显式设MEMORY_HUB_PROXY_PUBLIC_URLhttp://真值:8096。想让 UI 卡片走老行为回落到 gateway_endpoint把MEMORY_HUB_PROXY_PUBLIC_URL显式设为空字符串。注意Panel 后端 → Kernel 的转发不受此变量影响始终走REMOTE_INSTANCE_URL→http://memory-core:8420。12.2 proxy 默认与完整流水线的差异proxy默认关闭auth/sessionInit/costGuard这些依赖内部服务只做纯转发 tdai-memory上下文注入injector 名称非容器名。要开启完整流水线用PROXY_FULL_STACK1或分别设置PROXY_ENABLE_AUTH/PROXY_ENABLE_SESSION_INIT/PROXY_ENABLE_TDAI完整配置语义参见 MemoryProxy/config.example.yaml。十三、容器外访问宿主机服务脚本已默认给 memory-hub 和 proxy 加了--add-hosthost.docker.internal:host-gateway。容器内用http://host.docker.internal:port即可访问宿主机上其它服务Ollama、Langfuse 等。KNOWLEDGE_PUBLIC_BASE_URL的默认值也正是利用了这一点http://host.docker.internal:8424/v3让容器内可回环到宿主端口。十四、常见问题Q:./start-all.sh卡在 wait_healthy镜像可能还在拉取。用docker pull IMAGE手动预拉一次再跑脚本或使用PULL1。wait_healthy默认最长等待 90 秒memory-hub 为 120 秒期间容器非 running / unhealthy / 超时都会打印最近 30 行日志后die。Q: memory-hub 起来但 Panel 打不开检查.env里KNOWLEDGE_PUBLIC_BASE_URL是不是含/v3—— 缺/v3panel 会报错。Q: proxy 转发返回 401PROXY_UPSTREAM_API_KEY无效或PROXY_UPSTREAM_URL不匹配。用docker logs tdai-proxy看错误。Q: 如何在容器外访问宿主机上其它服务Ollama、Langfuse 等脚本已默认--add-hosthost.docker.internal:host-gateway。容器内用http://host.docker.internal:port即可。Q:start-all.sh用:latest但跑的还是旧镜像本地已有同名:latest时脚本会直接复用。想升级用PULL1 ./start-all.sh强制拉取最新版。Q:stop-all.sh --purge后重启admin 登录失败.admin-key与 volume 强绑定purge 会同步删除两者属预期行为重启后脚本会重新生成一把新的随机 key 并写入.admin-key。反之若只删了 volume 没删 key 文件或只删 key 没删 volume都会出现 auth 校验失败需要保持一致。十五、小结deploy/global-images目录提供了一套完整的「零配置优先、生产可加固」的本地部署方案_lib.sh统一处理.env加载、必填参数一次性校验、Docker 定位、健康等待与地址表打印verify.sh在启动前就把 API key / URL / 模型名 / 端口冲突 / 容器内网络可达性全部拦下三个start-*.sh可组合可拆分并通过自动生成的 YAML 配置把 memory 组与 proxy 组的 LLM 彻底解耦。对于只需要跑通本地流程的场景cp .env.example .env→ 填两组 LLM 参数 →./verify.sh→./start-all.sh四步即可完成对于生产环境务必把内部凭据替换为随机长串并留意MEMORY_CORE_GATEWAY_API_KEY与 proxy auth 的已知兼容约束。【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考