企业官网建设流程全解析

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-Memory

MemoryCore 是 TencentDB Agent Memory 开源仓库中负责记忆与元数据存储的核心模块，它独立运行并通过 HTTP Gateway（默认127.0.0.1:8420）对外提供 L0 对话、L1 原子记忆、L2 场景记忆、L3 核心画像四层记忆的写入、召回与检索能力，同时登记 Knowledge（Wiki、Code Graph）元信息和 User/Team/Agent/Task/Skill/Asset 等资产元信息。本文以 MemoryCore/README_CN.md 为主线，结合仓库源码与配置模板，完整讲解其架构、单机部署、配置调优、v2→v3 数据迁移、Docker 运行、OpenClaw/Hermes 及自定义 Agent 接入方式，帮助你快速搭建一套可独立运行的团队级 Agent 记忆中枢。

MemoryCore 是什么：记忆与元数据核心

MemoryCore 在项目中的定位是"记忆与元数据核心"，统一存储并提供三类数据能力：

• Memory：L0 对话原始记录、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 本身。

核心能力一览

架构总览：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.ts（v3 数据面与 v2 共享同一组 handler，仅在 dispatch 层多做一层隔离校验）；
• /v3/skill/*：由 skill-handlers.ts 处理；
• /v3/knowledge/*：由 knowledge-handlers.ts 处理；
• /v3/meta/*：由 v3-meta-router.ts 处理。

核心业务逻辑通过TdaiCore（MemoryCore/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.0
• npm
• 一个 OpenAI-compatible LLM API；只读查询可以不触发 LLM，但记忆抽取和归纳需要有效凭证

快速开始：从源码启动 Standalone Gateway

1. 安装与构建

cd MemoryCore npm install npm run build

2. 启动 Standalone Gateway

export TDAI_GATEWAY_CONFIG="$PWD/tdai-gateway.standalone.yaml" export TDAI_LLM_API_KEY="your-api-key" export TDAI_LLM_BASE_URL="https://api.openai.com/v1" export TDAI_LLM_MODEL="gpt-4o-mini" node --import tsx src/gateway/server.ts

Gateway 启动后访问健康检查：

curl http://127.0.0.1:8420/health

如需从其他机器或容器访问，必须同时设置监听地址和鉴权：

export TDAI_GATEWAY_HOST="0.0.0.0" export TDAI_GATEWAY_API_KEY="replace-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.apiKey；MemoryCore/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()）：

1. TDAI_GATEWAY_CONFIG指定的 YAML 或 JSON；
2. 当前目录下的tdai-gateway.yaml或tdai-gateway.json；
3. 数据目录下的tdai-gateway.yaml或tdai-gateway.json；
4. 环境变量和内置默认值。

环境变量覆盖配置文件。配置文件中${VAR}形式的占位符会被递归替换为对应环境变量（仅整串匹配，保持 YAML 类型语义）。

常用环境变量

三个配置模板的定位

• tdai-gateway.standalone.yaml：最小单机 Memory 配置（零外部依赖，适合本地开发 / Hermes sidecar / 单 Agent 单机部署）；
• tdai-gateway.yaml：Standalone + Skill 默认配置，Memory 引擎与 Skill 模块共享同一个baseDir；
• tdai-gateway.proxy.yaml：通过 OpenAI-compatible Proxy 调用模型（仓库中注释说明 provider=proxy 时运行时会把 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。
• l0l1RetentionDays：0 表示禁用本地 JSONL 清理；合法非零值必须>= 3（1/2属于危险低保留期，需同时开启allowAggressiveCleanup）；清理任务每日默认03:00执行。
• capture.excludeAgents支持 glob 模式（如"bench-judge-*"），被匹配的 Agent 完全忽略。
• llm段支持provider: "openai" | "proxy"两种访问模式；provider=proxy时运行期 baseUrl 拼接为${baseUrl}/proxy/<instanceId>/v1，Authorization 默认使用 memory 系统用户 key（proxy.useMemorySystemUserKey默认true）。

启用 Skill 模块

在 tdai-gateway.yaml 中，Skill 是独立的顶层模块，启用后数据存于{baseDir}/skills/<name>/SKILL.md + files/，与 Memory 引擎互不干扰；也可通过环境变量TDAI_SKILL_ENABLED=true一键启用。关键子项：

skill: enabled: true routing: mode: "bm25" # bm25 | embedding | hybrid（后两者需 memory.embedding 启用） searchTopK: 20 # listing 接口最多注入多少条 skill（name+description） extraction: enabled: true # 需要顶层 llm 配置有效 maxIterations: 16 # Review Agent tool-calling 最大迭代轮数 queue: backend: "local" # standalone 用进程内队列；service 改 "redis" resultTtlSeconds: 86400 lockTtlMs: 600000 # agent 级锁 TTL（10 分钟） maxRetries: 2 retryBackoffsMs: [5000, 15000] resources: maxResourceSizeBytes: 5000000 # 单个资源文件上限 5MB，超限拒写

Skill 的 storeBackend 不填则继承memory.storeBackend；contentBackend 不填则自动探测（有 COS 凭证走 COS，否则走 local）。

可观测性与元数据模块

tdai-gateway.yaml中的observability段统一管理 OTel（默认关闭）、ClickHouse 双写、Kafka、Langfuse（本地默认开启，空凭证自动跳过上报，不阻塞业务）四类可观测后端；metadata段配置 v3 元数据模块（maxUsersPerInstance: 500、maxTeamsPerInstance: 100，store 支持 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+）。

脚本参数

迁移内容

1. 数据库表结构升级

2. L2/L3 文件迁移（迁移到 profiles 子目录下的 scoped 路径）

常见问题：脚本默认在迁移前自动备份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_KEY="your-api-key" \ -e TDAI_GATEWAY_API_KEY="replace-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 与自定义 Runtime

OpenClaw

推荐使用 MemoryCore/openclaw-plugin/ 中的轻量客户端 Adapter。它连接已运行的 MemoryCore Gateway，不在 OpenClaw 进程内重复运行记忆管线。

从仓库根目录执行：

bash MemoryCore/scripts/install-openclaw-plugin.sh

常用连接参数：

TDAI_MEMORY_ENDPOINT=http://127.0.0.1:8420 TDAI_MEMORY_API_KEY=<与 Gateway 相同的 API Key> TDAI_MEMORY_INSTANCE_ID=default

插件源码位于 MemoryCore/openclaw-plugin/src，包含 capture/recall 钩子（capture.ts、recall.ts）与 conversation-search / memory-search / read-cos 三个工具，安装脚本为 MemoryCore/scripts/install-openclaw-plugin.sh。

Hermes

MemoryCore/hermes-plugin/ 提供 Hermes Memory Provider（Python 实现，见 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 可以直接使用仓库中的 SDK：

• TypeScript SDK：sdk/memory-core/typescript/
• Python SDK：sdk/memory-core/python/

一个 Adapter 通常只需要完成三件事：

1. 会话结束或每轮完成后写入 L0；
2. 构造 Prompt 前召回 L1/L2/L3；
3. 将召回结果以有边界、可识别的上下文注入 Agent。

API 范围

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-v2

read-local-memory用于读取本地记忆数据（实现见 MemoryCore/scripts/read-local-memory/read-local-memory.ts），seed-v2用于批量灌入历史对话（对应 MemoryCore/src/cli/commands/seed.ts）。

安全建议

• 非回环地址监听时必须配置TDAI_GATEWAY_API_KEY；
• CORS 默认关闭；只允许明确可信的 Origin，不要在生产环境使用*（配置文件中corsOrigins: []表示完全不发送 CORS 头，最严格）；
• 所有 Secret 通过环境变量或 Secret Manager 注入；
• 不要提交.env、数据库文件、日志、导出数据或真实服务配置；
• 每个请求都应校验实例和 Team/User/Agent 归属，避免跨租户访问。

License

MemoryCore 采用 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