TencentDB Agent Memory MemoryCore 实战指南L0–L3 分层记忆存储、Gateway 部署与 Agent 接入【免费下载链接】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-MemoryMemoryCore 是 TencentDB Agent Memory 开源仓库中负责记忆与元数据存储的核心模块它独立运行并通过 HTTP Gateway默认127.0.0.1:8420对外提供 L0 对话、L1 原子记忆、L2 场景记忆、L3 核心画像四层记忆的写入、召回与检索能力同时登记 KnowledgeWiki、Code Graph元信息和 User/Team/Agent/Task/Skill/Asset 等资产元信息。本文以 MemoryCore/README_CN.md 为主线结合仓库源码与配置模板完整讲解其架构、单机部署、配置调优、v2→v3 数据迁移、Docker 运行、OpenClaw/Hermes 及自定义 Agent 接入方式帮助你快速搭建一套可独立运行的团队级 Agent 记忆中枢。MemoryCore 是什么记忆与元数据核心MemoryCore 在项目中的定位是记忆与元数据核心统一存储并提供三类数据能力MemoryL0 对话原始记录、L1 原子记忆、L2 场景记忆和 L3 核心画像。Knowledge 元信息Wiki、Code Graph 等知识源的标识、类型、状态、关联关系和服务地址注意只保存元信息不保存或处理 Knowledge 内容——Wiki 解析、代码图谱构建、索引和内容检索由仓库中的MemoryKnowledge/模块提供。资产管理元信息User、Team、Agent、Task、Skill、Knowledge Asset以及成员、归属和访问关系。MemoryCore 独立运行通过 HTTP Gateway 对外提供能力OpenClaw、Hermes 和自定义应用通过轻量 Adapter 或 SDK 接入。需要特别强调的边界是Agent 是调用方也可以作为一种被管理的元数据实体但 MemoryCore 不负责托管、调度或运行 Agent 本身。核心能力一览能力说明Memory 存储与处理记录 L0 对话并维护 L1 原子记忆、L2 场景记忆和 L3 核心画像Memory 召回支持关键词、Embedding 与混合检索没有 Embedding Provider 时仍可使用 BM25Knowledge 元信息登记登记知识源并维护其标识、类型、状态、关联关系和服务地址资产元信息管理管理 User、Team、Agent、Task、Skill、Knowledge Asset以及成员、归属和访问关系Skill Memory支持 Skill 创建、版本、资源、搜索、路由和对话抽取统一访问接口通过 HTTP API 和 TypeScript/Python SDK 为 Adapter 与应用提供能力架构总览Gateway 数据面与管理面README 给出的架构如下OpenClaw / Hermes / 自定义应用 │ │ HTTP API / SDK ▼ MemoryCore Gateway :8420 ├─ Memory │ └─ L0 / L1 / L2 / L3 ├─ Knowledge 元信息 ├─ 资产管理元信息 └─ SQLite 本地文件 MemoryKnowledge └─ Knowledge 解析 / 索引 / 检索从源码看Gateway 实现位于 MemoryCore/src/gateway/server.ts基于Node.js 原生http模块构建无 Express/Fastify 依赖路由按前缀分发/v2/*与/v3/*走 v2-router.tsv3 数据面与 v2 共享同一组 handler仅在 dispatch 层多做一层隔离校验/v3/skill/*由 skill-handlers.ts 处理/v3/knowledge/*由 knowledge-handlers.ts 处理/v3/meta/*由 v3-meta-router.ts 处理。核心业务逻辑通过TdaiCoreMemoryCore/src/core/tdai-core.ts承载底层存储为 SQLite 本地文件Pipeline 状态由进程内维护。src/core/abstractions/定义了 IConfigSource、IQuotaReporter 等与部署形态解耦的抽象接口Gateway 启动时依据 deployMode 组装具体依赖。运行方式与环境要求MemoryCore 以Standalone Runtime形式开源适合本地开发、单机部署和 Agent sidecar 场景默认监听127.0.0.1:8420使用 SQLite、本地文件和进程内状态除 LLM API 外没有必需的外部服务默认关闭远程 Embedding使用 BM25 召回数据默认写入~/.memory-tencentdb/memory-tdai。环境要求Node.js 22.16.0npm一个 OpenAI-compatible LLM API只读查询可以不触发 LLM但记忆抽取和归纳需要有效凭证快速开始从源码启动 Standalone Gateway1. 安装与构建cd MemoryCore npm install npm run build2. 启动 Standalone Gatewayexport TDAI_GATEWAY_CONFIG$PWD/tdai-gateway.standalone.yaml export TDAI_LLM_API_KEYyour-api-key export TDAI_LLM_BASE_URLhttps://api.openai.com/v1 export TDAI_LLM_MODELgpt-4o-mini node --import tsx src/gateway/server.tsGateway 启动后访问健康检查curl http://127.0.0.1:8420/health如需从其他机器或容器访问必须同时设置监听地址和鉴权export TDAI_GATEWAY_HOST0.0.0.0 export TDAI_GATEWAY_API_KEYreplace-with-a-strong-random-token除/health和 CORS 预检外启用鉴权后所有接口均需携带Authorization: Bearer TDAI_GATEWAY_API_KEY x-tdai-service-id: memory-instance-id源码层面的印证在 MemoryCore/src/gateway/config.ts 中loadGatewayConfig()会解析server.apiKeyMemoryCore/src/gateway/server.ts 的logSecurityPosture()在启动时输出安全态势——若 Gateway 绑定到非回环地址非127.0.0.1/localhost/::1且未设置 API Key会输出显式 WARN 提醒暴露风险。鉴权比较使用crypto.timingSafeEqual恒定时间比较避免时序侧信道。配置详解优先级、环境变量与 YAML 模板配置加载优先级Gateway 按以下优先级加载配置实现见 MemoryCore/src/gateway/config.ts 的resolveConfigPath()TDAI_GATEWAY_CONFIG指定的 YAML 或 JSON当前目录下的tdai-gateway.yaml或tdai-gateway.json数据目录下的tdai-gateway.yaml或tdai-gateway.json环境变量和内置默认值。环境变量覆盖配置文件。配置文件中${VAR}形式的占位符会被递归替换为对应环境变量仅整串匹配保持 YAML 类型语义。常用环境变量环境变量默认值说明TDAI_GATEWAY_CONFIG自动发现配置文件路径TDAI_GATEWAY_HOST127.0.0.1Gateway 监听地址TDAI_GATEWAY_PORT8420Gateway 端口TDAI_GATEWAY_API_KEY未设置HTTP Bearer 鉴权非回环监听必须设置TDAI_CORS_ORIGINS空允许的 Origin逗号分隔TDAI_DATA_DIR~/.memory-tencentdb/memory-tdai本地数据目录TDAI_LLM_API_KEY空LLM API KeyTDAI_LLM_BASE_URLhttps://api.openai.com/v1OpenAI-compatible API 地址TDAI_LLM_MODELgpt-4oLLM 模型TDAI_SKILL_ENABLED配置文件值强制启用 Skill 模块三个配置模板的定位tdai-gateway.standalone.yaml最小单机 Memory 配置零外部依赖适合本地开发 / Hermes sidecar / 单 Agent 单机部署tdai-gateway.yamlStandalone Skill 默认配置Memory 引擎与 Skill 模块共享同一个baseDirtdai-gateway.proxy.yaml通过 OpenAI-compatible Proxy 调用模型仓库中注释说明 providerproxy 时运行时会把 baseUrl 拼成${baseUrl}/proxy/instanceId/v1。memory 引擎配置段解读以 tdai-gateway.standalone.yaml 为例memory段覆盖 capture / extraction / persona / pipeline / recall / embedding / bm25 等子模块。结合 MemoryCore/src/config.ts 的parseConfig()解析逻辑各参数的默认值与影响如下memory: capture: enabled: true # L0 自动采集开关默认 true extraction: enabled: true # 后台 L1 抽取开关默认 true enableDedup: true # L1 智能去重默认 true maxMemoriesPerSession: 20 # 单会话最多记忆条数默认 20 persona: triggerEveryN: 50 # 每新增 N 条记忆触发一次画像生成默认 50 maxScenes: 15 # 最大场景块数量默认 15 pipeline: everyNConversations: 5 # 每 N 轮对话触发一次 L1默认 5 enableWarmup: true # 预热阈值从 1 开始每次 L1 后翻倍直至 everyN l1IdleTimeoutSeconds: 600 # L1 空闲超时秒 l2DelayAfterL1Seconds: 90 # L1 完成后延迟多少秒再触发 L2 l2MinIntervalSeconds: 900 # 每会话 L2 最小间隔15 分钟 l2MaxIntervalSeconds: 3600 # 即使无新对话L2 最长间隔60 分钟 recall: enabled: true maxResults: 5 # 召回最大条数默认 5 scoreThreshold: 0.3 # 最低分数阈值默认 0.3 strategy: hybrid # embedding | keyword | hybrid默认 hybrid timeoutMs: 5000 # 召回整体超时超时跳过并告警 storeBackend: sqlite # sqlite | tcvdb腾讯云向量数据库 embedding: provider: none # 默认关闭向量搜索仅用 BM25 bm25: enabled: true language: zh # BM25 预训练语言参数zh | en默认 zh几个值得注意的解析细节源码可查证embedding.provider为none默认时parseConfig()会把 embedding 强制置为禁用并将dimensions置为0从而跳过 vec0 向量表的创建避免占位维度与未来真实 provider 不匹配若配置了远程 provider如openai、deepseek但缺少apiKey/baseUrl/model/dimensions任一必填项Embedding 会被静默禁用并记录configError不会导致进程启动失败。sendDimensions默认true兼容 OpenAI text-embedding-3-* 的 Matryoshka 模型自托管/开源模型如 BGE-M3 会因不支持 matryoshka 表示返回 HTTP 400应将其设为false。l0l1RetentionDays0 表示禁用本地 JSONL 清理合法非零值必须 31/2属于危险低保留期需同时开启allowAggressiveCleanup清理任务每日默认03:00执行。capture.excludeAgents支持 glob 模式如bench-judge-*被匹配的 Agent 完全忽略。llm段支持provider: openai | proxy两种访问模式providerproxy时运行期 baseUrl 拼接为${baseUrl}/proxy/instanceId/v1Authorization 默认使用 memory 系统用户 keyproxy.useMemorySystemUserKey默认true。启用 Skill 模块在 tdai-gateway.yaml 中Skill 是独立的顶层模块启用后数据存于{baseDir}/skills/name/SKILL.md files/与 Memory 引擎互不干扰也可通过环境变量TDAI_SKILL_ENABLEDtrue一键启用。关键子项skill: enabled: true routing: mode: bm25 # bm25 | embedding | hybrid后两者需 memory.embedding 启用 searchTopK: 20 # listing 接口最多注入多少条 skillnamedescription extraction: enabled: true # 需要顶层 llm 配置有效 maxIterations: 16 # Review Agent tool-calling 最大迭代轮数 queue: backend: local # standalone 用进程内队列service 改 redis resultTtlSeconds: 86400 lockTtlMs: 600000 # agent 级锁 TTL10 分钟 maxRetries: 2 retryBackoffsMs: [5000, 15000] resources: maxResourceSizeBytes: 5000000 # 单个资源文件上限 5MB超限拒写Skill 的 storeBackend 不填则继承memory.storeBackendcontentBackend 不填则自动探测有 COS 凭证走 COS否则走 local。可观测性与元数据模块tdai-gateway.yaml中的observability段统一管理 OTel默认关闭、ClickHouse 双写、Kafka、Langfuse本地默认开启空凭证自动跳过上报不阻塞业务四类可观测后端metadata段配置 v3 元数据模块maxUsersPerInstance: 500、maxTeamsPerInstance: 100store 支持 MongoDB 或 SQLite敏感项通过${TDAI_METADATA_*}环境变量注入。从旧版升级v2 → v3 数据迁移如果从 v1.x 或 v0.x数据格式 v2升级到 v2.0.0数据格式 v3启动新版 Gateway 前需要先运行数据迁移脚本。⚠️ 迁移前请务必备份整个数据目录。# dry-run 检查 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --dry-run # 执行迁移 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai迁移脚本的完整说明见 MemoryCore/scripts/migrate-v2-to-v3/README_CN.md脚本位于 MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py前置条件 Python 3.8。脚本参数参数说明/path/to/memory-tdai数据目录路径必填--dry-run仅检查不实际修改--db-only仅迁移vectors.db表结构跳过 L2/L3 文件--no-backup跳过自动备份默认会自动创建.bak文件迁移内容1. 数据库表结构升级表变更l1_records新增team_id、task_id、user_id、agent_id、version字段l0_conversations新增team_id、task_id、user_id、agent_id字段l1_fts/l0_fts重建 FTS5 索引增加租户隔离列memory_audit新增审计表skills新增技能表skill_fts新增技能全文索引表2. L2/L3 文件迁移迁移到 profiles 子目录下的 scoped 路径源路径目标路径{data_dir}/scene_blocks/{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/scene_blocks/{data_dir}/persona.md{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/persona.md{data_dir}/.metadata/{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/.metadata/常见问题脚本默认在迁移前自动备份vectors.db生成.bak.{timestamp}L2/L3 文件采用复制而非移动迁移失败可直接用备份恢复脚本是幂等的已存在的字段和文件会跳过全新安装不需要跑迁移新版 Gateway 会自动创建 v3 格式数据。Docker 部署在MemoryCore/目录构建docker build -t memory-core:local .启动 Standalone 容器docker run --rm \ -p 8420:8420 \ -e TDAI_LLM_API_KEYyour-api-key \ -e TDAI_GATEWAY_API_KEYreplace-with-a-strong-random-token \ -v $PWD/tdai-gateway.standalone.yaml:/data/config/tdai-gateway.yaml:ro \ -v memory-core-data:/data/tdai-memory \ memory-core:local通过环境变量或 Secret Manager 注入凭证不要把 API Key 或其他凭证写入镜像和配置仓库。Dockerfile 位于 MemoryCore/Dockerfile。Agent 接入OpenClaw、Hermes 与自定义 RuntimeOpenClaw推荐使用 MemoryCore/openclaw-plugin/ 中的轻量客户端 Adapter。它连接已运行的 MemoryCore Gateway不在 OpenClaw 进程内重复运行记忆管线。从仓库根目录执行bash MemoryCore/scripts/install-openclaw-plugin.sh常用连接参数TDAI_MEMORY_ENDPOINThttp://127.0.0.1:8420 TDAI_MEMORY_API_KEY与 Gateway 相同的 API Key TDAI_MEMORY_INSTANCE_IDdefault插件源码位于 MemoryCore/openclaw-plugin/src包含 capture/recall 钩子capture.ts、recall.ts与 conversation-search / memory-search / read-cos 三个工具安装脚本为 MemoryCore/scripts/install-openclaw-plugin.sh。HermesMemoryCore/hermes-plugin/ 提供 Hermes Memory ProviderPython 实现见 MemoryCore/hermes-plugin/memory/memory_tencentdb 下的 client.py / supervisor.py / plugin.yaml。它遵循同样的 Adapter 模式通过 Gateway 完成对话写入与记忆召回。安装脚本为 MemoryCore/scripts/install-hermes-plugin.sh另有 MemoryCore/scripts/install_hermes_memory_tencentdb.sh 提供数据目录迁移等额外步骤。自定义 Agent自定义 Runtime 可以直接使用仓库中的 SDKTypeScript SDKsdk/memory-core/typescript/Python SDKsdk/memory-core/python/一个 Adapter 通常只需要完成三件事会话结束或每轮完成后写入 L0构造 Prompt 前召回 L1/L2/L3将召回结果以有边界、可识别的上下文注入 Agent。API 范围API用途状态/capture、/recall、/search/*早期 Gateway 兼容接口兼容保留/v2/conversation/*L0 写入、查询、搜索、删除和计数稳定/v2/atomic/*L1 查询、搜索、更新、删除和计数稳定/v2/scenario/*、/v2/core/*L2/L3 读写稳定/v3/conversation/*、/v3/atomic/*、/v3/scenario/*、/v3/core/*强隔离的 L0–L3 数据面推荐新接入使用/v3/skill/*Skill 管理、检索、版本、资源和抽取稳定/v3/meta/*User、Team、Agent、Task、Asset 和权限关系管理面/v3/knowledge/*知识资产元数据登记管理面/health健康检查公共v3 记忆数据面要求team_id、agent_id、user_id可以通过请求体或对应的x-tdai-*Header 传入session_id可选用于限定会话范围。从源码看/v3L0–L3 的严格隔离程度还受环境变量V3_STRICT_ISOLATION控制生产环境建议开启。存储与隔离Memory 和 Metadata 使用 SQLite 存储文件与大对象保存在本地数据目录Pipeline State 由当前进程维护BM25 无需外部 Embedding 服务需要时可配置 OpenAI-compatible Embedding API。所有业务调用都应明确x-tdai-service-id。新 Adapter 建议使用 v3 数据面并始终提供 Team、Agent、User 隔离维度——这也是 v2→v3 迁移中l0_conversations、l1_records新增team_id/agent_id/user_id等字段的原因。目录结构MemoryCore/ ├── src/core/ L0–L3 Memory、Skill、Store 和 Storage 抽象 ├── src/gateway/ HTTP Gateway 与 v2/v3 Router ├── src/services/ Pipeline Scanner、Worker 和调度服务 ├── openclaw-plugin/ OpenClaw 轻量客户端 Adapter ├── hermes-plugin/ Hermes Memory Provider ├── scripts/ 安装、构建、迁移和运维工具 │ ├── install-hermes-plugin.sh Hermes provider 安装脚本 │ ├── install-openclaw-plugin.sh OpenClaw 插件安装脚本 │ └── migrate-v2-to-v3/ 数据迁移工具v2 → v3 ├── Dockerfile MemoryCore Gateway 镜像 ├── tdai-gateway*.yaml Gateway 配置模板 └── package.json Node.js 包与构建命令本地数据工具npm run read-local-memory npm run seed-v2read-local-memory用于读取本地记忆数据实现见 MemoryCore/scripts/read-local-memory/read-local-memory.tsseed-v2用于批量灌入历史对话对应 MemoryCore/src/cli/commands/seed.ts。安全建议非回环地址监听时必须配置TDAI_GATEWAY_API_KEYCORS 默认关闭只允许明确可信的 Origin不要在生产环境使用*配置文件中corsOrigins: []表示完全不发送 CORS 头最严格所有 Secret 通过环境变量或 Secret Manager 注入不要提交.env、数据库文件、日志、导出数据或真实服务配置每个请求都应校验实例和 Team/User/Agent 归属避免跨租户访问。LicenseMemoryCore 采用 MIT License。【免费下载链接】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），仅供参考