agent-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

agent-memory

agent-memory

TencentDB Agent Memory gives an agent team a shared, growing memory instead of starting cold every session. Two ways it relates to gm's own
memorize-fire
/
recall
(see
wfgy-method
/
gm
skills for that): (1) as a fully standalone system (this skill's main content, below) when the ask spans multiple agent frameworks, multiple team members, or needs a human-reviewable panel; (2) as an opt-in storage backend for gm's own memory verbs (
memory.tencentdb_backend
in
gm.config.json
, disabled by default) -- when a namespace is routed to it, gm's
memorize
/
recall
/
memorize-fire
/
memorize-prune
write file-pointer-indexed content compatible with this system's format instead of gm's default 384-dim md-corpus store, with no change to the verb surface an agent calls. Reach for THIS skill's setup instructions (Docker Compose, panel UI) for the standalone deployment; reach for
gm
's own docs when the ask is just "make gm's memory use the Tencent-compatible backend."
TencentDB Agent Memory为Agent团队提供了一套可共享、持续增长的记忆系统,无需每次会话都从零开始。它与gm自身的
memorize-fire
/
recall
(相关内容详见
wfgy-method
/
gm
技能)存在两种关联方式:(1) 作为完全独立的系统(即本技能的核心内容,见下文),适用于需求跨多个Agent框架、跨多个团队成员,或需要人工可审核面板的场景;(2) 作为gm记忆接口的可选存储后端(对应
gm.config.json
中的
memory.tencentdb_backend
配置,默认禁用)——当某个命名空间路由至该后端时,gm的
memorize
/
recall
/
memorize-fire
/
memorize-prune
接口会写入与本系统格式兼容的、以文件指针为索引的内容,而非gm默认的384维md语料库存储,且Agent调用的接口语法完全不变。如需独立部署,请参考本技能的搭建指南(Docker Compose、面板UI);若仅需“让gm的记忆使用兼容Tencent格式的后端”,则请查阅gm自身文档。

What it provides

功能特性

  • Chat Memory: retains preferences, facts, decisions, and interaction history per agent. Distilled in layers: L0 raw conversation -> L1 atom -> L2 scenario -> L3 persona.
  • Skill library: after complex work, an agent can extract a reusable Skill (versioned, with resource files, trigger boundaries, execution steps, validation rules) from its own conversation/tool-call history, then share it with the team after review.
  • Wiki + CodeGraph: turns docs/specs/runbooks into a linked Wiki; indexes code symbols, files, call relationships, and impact paths into a CodeGraph, both queryable on demand rather than injected wholesale into context.
  • Memory Panel: a human-controlled review/control surface (not just a dashboard) for what gets promoted, shared, or pruned.
Assets are portable across agent frameworks and shareable across a team -- a new agent or team member can load existing memory instead of relearning from scratch.
  • Chat Memory:保留每个Agent的偏好、事实、决策及交互历史,并分层提炼:L0原始对话→L1原子信息→L2场景→L3角色。
  • Skill库:完成复杂任务后,Agent可从自身对话/工具调用历史中提取可复用的Skill(带版本管理,包含资源文件、触发边界、执行步骤、验证规则),经审核后共享给团队。
  • Wiki + CodeGraph:将文档/规格/运行手册转换为关联Wiki;对代码符号、文件、调用关系及影响路径建立索引形成CodeGraph,两者均可按需查询,无需整体注入上下文。
  • Memory Panel:一个人工可控的审核/操作界面(而非仅仪表盘),用于管理内容的升级、共享或清理。
所有资产可跨Agent框架移植,并在团队内共享——新Agent或团队成员可加载现有记忆,无需从头学习。

When to use this skill vs. gm's own memory verbs

本技能与gm原生记忆接口的适用场景区分

  • Use
    agent-memory
    's standalone setup instructions when: the user explicitly names TencentDB/memory-tencentdb/Memory Hub/team memory, wants memory that survives across different agent frameworks or team members (not just this session), wants a Skill library extracted from past conversations, or wants a Wiki/CodeGraph over a codebase.
  • Use gm's own
    memorize
    /
    recall
    /
    memorize-fire
    /
    memorize-prune
    verbs (default backend, no setup) for this session's own local recall -- and if the user specifically wants gm's memory to be Tencent-format-compatible without running the standalone services, point them at
    gm.config.json
    's
    memory.tencentdb_backend
    block instead of a full standalone install.
  • 当用户明确提及TencentDB/memory-tencentdb/Memory Hub/team memory,需要跨不同Agent框架或团队成员的持久化记忆(不仅限于当前会话),需要从过往对话中提取Skill库,或需要针对代码库构建Wiki/CodeGraph时,请使用
    agent-memory
    的独立搭建指南。
  • 若仅需当前会话的本地记忆,请使用gm原生的
    memorize
    /
    recall
    /
    memorize-fire
    /
    memorize-prune
    接口(默认后端,无需搭建);若用户明确希望gm的记忆兼容Tencent格式但无需运行独立服务,请引导其查看
    gm.config.json
    中的
    memory.tencentdb_backend
    配置块,而非进行完整的独立安装。

Setup

搭建步骤

1. Fastest path: Docker Compose (all three services)

1. 快速部署:Docker Compose(启动全部三个服务)

bash
git clone https://github.com/AnEntrypoint/agent-memory.git
cd agent-memory/deploy/global-images
cp .env.example .env
$EDITOR .env       # fill in LLM params for both the memory group and the proxy group
./start-all.sh     # starts memory-core + memory-hub + proxy; prints a one-liner for Claude Code setup
Open the panel at
http://localhost:8125
.
For a standalone Memory Hub, Proxy + Claude Code / CodeBuddy integration, port reference, and teardown, see
INSTALL.md
in the repo (
INSTALL_CN.md
for Chinese).
bash
git clone https://github.com/AnEntrypoint/agent-memory.git
cd agent-memory/deploy/global-images
cp .env.example .env
$EDITOR .env       # 为memory组和proxy组填写LLM参数
./start-all.sh     # 启动memory-core + memory-hub + proxy;输出Claude Code搭建的单行命令
访问面板:
http://localhost:8125
如需独立部署Memory Hub、Proxy与Claude Code/CodeBuddy集成、端口参考及服务销毁,请查看仓库中的
INSTALL.md
(中文版本为
INSTALL_CN.md
)。

2. OpenClaw plugin install (if the host is OpenClaw, not Claude Code)

2. OpenClaw插件安装(若宿主为OpenClaw而非Claude Code)

bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
Minimal config in
~/.openclaw/openclaw.json
:
json
{ "memory-tencentdb": { "enabled": true } }
Zero-config works for basic capability. Production tuning groups:
capture
,
extraction
,
pipeline
,
recall
,
persona
,
embedding
-- see
references/openclaw-config.md
for the full recommended template and failure-mode notes (embedding four-tuple, retention-day gating, etc.).
bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
~/.openclaw/openclaw.json
中的最简配置:
json
{ "memory-tencentdb": { "enabled": true } }
零配置即可实现基础功能。生产环境调优分组包括:
capture
extraction
pipeline
recall
persona
embedding
——完整推荐模板及故障排查说明(嵌入四元组、保留天数限制等)请查看
references/openclaw-config.md

3. Migrating from an older install (v1.x/v0.x -> v2.0.0+)

3. 从旧版本迁移(v1.x/v0.x -> v2.0.0+)

Use the migration tool documented at
MemoryCore/scripts/migrate-v2-to-v3/README.md
in the repo. New installs skip this.
使用仓库中
MemoryCore/scripts/migrate-v2-to-v3/README.md
文档记录的迁移工具。全新安装可跳过此步骤。

4. Migrating gm's own memories into the
tencentdb_backend
store

4. 将gm原生记忆迁移至
tencentdb_backend
存储

Distinct from #3 above (that's the standalone system's own internal format evolution). This is for a project that already has gm-native memories (
.gm/memories/*.md
, written by
memorize
/
memorize-fire
before
memory.tencentdb_backend
was enabled) and wants them carried over once a namespace opts into the Tencent-compatible backend, so recall doesn't go cold on the switch.
Two ways to run this migration -- same underlying write path (
tencentdb_memory::write_cfg
), pick whichever fits the situation:
  • From within a live agent session: dispatch the
    tencentdb-memory-import
    verb:
    {"source_namespace": "default", "dest_namespace": "<routed-namespace>", "kind": "l1"}
    . It reads every
    .md
    doc in the source namespace and re-embeds through gm's own 384-dim pipeline.
  • Batch/CLI, outside an agent session:
    node scripts/migrate-memory-to-tencentdb.mjs --project <path> --namespace <ns> [--dry-run] [--archive]
    . Same write path, but also applies the derivable-state discard filter (git-log-derivable facts, dated audit entries, historical framing) the verb does not -- prefer this for a bulk migration where discarding superfluous content matters, and the verb for a single dispatch from an already-running session.
Both refuse up front unless the destination namespace's resolved
memory.tencentdb_backend.vectors_db_dims
is exactly
384
-- gm's embedder cannot produce vectors at any other width, and a namespace configured for externally-embedded 768-dim content (the default) cannot safely receive them (recall queries that namespace through the project-resolved dim, not a per-import override, so a dim mismatch there is a real defect, not a formality). A project wanting both kinds of content needs two separate
tencentdb_backend
-routed namespaces, each at its own dim.
By default this is a one-way copy, not a move: the source
.md
files and their
rssearch_vectors
index rows are left untouched, so the default backend keeps working for any namespace not also switched over. Pass
archive_source: true
(verb) or
--archive
(script) to opt into moving each successfully-migrated source file to
.gm/memories-archive-tencentdb/<namespace>/<filename>
instead of leaving it in place -- content stays inspectable, but the live
.gm/memories/
corpus no longer duplicates what the new backend now serves.
此步骤与上述第3步不同(第3步是独立系统自身的格式演进)。适用于已拥有gm原生记忆(
.gm/memories/*.md
,由
memorize
/
memorize-fire
在启用
memory.tencentdb_backend
前写入)的项目,当某个命名空间选择接入兼容Tencent的后端时,可将原有记忆迁移过去,避免切换后记忆丢失。
有两种迁移方式——底层写入路径相同(
tencentdb_memory::write_cfg
),可根据场景选择:
  • 在活跃Agent会话中执行:调用
    tencentdb-memory-import
    接口:
    {"source_namespace": "default", "dest_namespace": "<routed-namespace>", "kind": "l1"}
    。该接口会读取源命名空间下所有
    .md
    文档,并通过gm自身的384维流水线重新嵌入。
  • 批量/CLI方式(Agent会话外执行):运行
    node scripts/migrate-memory-to-tencentdb.mjs --project <path> --namespace <ns> [--dry-run] [--archive]
    。写入路径相同,但会应用接口未实现的衍生状态丢弃过滤器(可从git日志推导的事实、过期审计条目、历史框架信息)——若需要批量迁移并丢弃冗余内容,推荐使用此方式;若仅需从已运行的会话中单次触发迁移,则使用接口方式。
两种方式都会预先检查目标命名空间的
memory.tencentdb_backend.vectors_db_dims
是否恰好为
384
——gm的嵌入器无法生成其他维度的向量,若命名空间配置为外部嵌入的768维内容(默认值),则无法安全接收迁移内容(该命名空间的查询会使用项目配置的维度,而非导入时的临时覆盖,维度不匹配属于实际缺陷,而非形式问题)。若项目需要同时存储两种维度的内容,需配置两个独立的
tencentdb_backend
路由命名空间,各自对应不同维度。
默认情况下为单向复制,而非移动:源
.md
文件及其
rssearch_vectors
索引行将保持不变,因此默认后端仍可服务于未切换的命名空间。若选择移动,可在调用接口时传入
archive_source: true
,或在运行脚本时添加
--archive
参数——成功迁移的源文件将被移动至
.gm/memories-archive-tencentdb/<namespace>/<filename>
,内容仍可查看,但活跃的
.gm/memories/
语料库不再重复存储新后端已有的内容。

Verification (do this before declaring setup done)

验证步骤(完成搭建前请执行)

  1. Confirm version prerequisites:
    node -v
    (
    >=22.16
    ), and
    openclaw --version
    (
    >=2026.3.13
    ) if using the OpenClaw plugin path.
  2. After start/restart, confirm the service actually came up -- read logs (
    [memory-tdai]
    prefix for the OpenClaw plugin path, or the relevant container logs for Docker Compose) rather than assuming success from a clean exit code.
  3. Confirm the data directory exists and is non-empty (OpenClaw:
    ~/.openclaw/state/memory-tdai/
    containing
    conversations/
    ,
    records/
    ,
    scene_blocks/
    ,
    vectors.db
    ).
  4. Run a real round-trip: have 2-3 turns that state memorable facts, start a fresh session, and confirm recall actually surfaces that content (via the panel, or a search tool call such as
    tdai_memory_search
    /
    tdai_conversation_search
    ). A missing recall on this smoke test means setup is not done -- do not report success from config-file presence alone.
  1. 确认版本要求:
    node -v
    >=22.16
    );若使用OpenClaw插件方式,需确认
    openclaw --version
    >=2026.3.13
    )。
  2. 启动/重启后,确认服务实际运行——查看日志(OpenClaw插件方式为
    [memory-tdai]
    前缀,Docker Compose方式为对应容器日志),不要仅通过退出码判断成功。
  3. 确认数据目录存在且非空(OpenClaw:
    ~/.openclaw/state/memory-tdai/
    ,包含
    conversations/
    records/
    scene_blocks/
    vectors.db
    )。
  4. 执行完整往返测试:进行2-3轮对话并包含可记忆的事实,启动新会话,确认记忆内容可被召回(通过面板或搜索工具调用,如
    tdai_memory_search
    /
    tdai_conversation_search
    )。若此冒烟测试中无法召回内容,则搭建未完成——不要仅通过配置文件存在就报告成功。

Common failure modes

常见故障模式

  • No logs at all:
    memory-tencentdb.enabled
    not
    true
    , or the gateway/service was never restarted after config changes.
  • Records exist but nothing recalls:
    recall.enabled
    is false, or
    recall.scoreThreshold
    is too high.
  • No vector results: the
    embedding
    config is missing one of
    apiKey
    /
    baseUrl
    /
    model
    /
    dimensions
    -- any single missing field silently degrades to keyword-only mode rather than erroring.
  • History disappearing too fast:
    l0l1RetentionDays
    set too low (1-2) without explicitly enabling
    allowAggressiveCleanup
    .
  • 无任何日志:
    memory-tencentdb.enabled
    未设为
    true
    ,或配置变更后未重启网关/服务。
  • 记录存在但无法召回:
    recall.enabled
    为false,或
    recall.scoreThreshold
    设置过高。
  • 无向量结果:
    embedding
    配置缺失
    apiKey
    /
    baseUrl
    /
    model
    /
    dimensions
    中的任意一项——缺失单个字段会静默降级为仅关键词模式,而非报错。
  • 历史内容过快消失:
    l0l1RetentionDays
    设置过低(1-2天)且未明确启用
    allowAggressiveCleanup

Security

安全注意事项

Treat
embedding.apiKey
and any LLM credentials as sensitive -- do not echo them into chat, logs, or screenshots. Prefer environment-variable injection over literal values in config files. When editing config, touch only the
memory-tencentdb
/agent-memory section; do not overwrite unrelated plugin or service config.
请将
embedding.apiKey
及所有LLM凭据视为敏感信息——不要在聊天、日志或截图中泄露。优先使用环境变量注入,而非在配置文件中写入明文值。编辑配置时,仅修改
memory-tencentdb
/agent-memory相关部分;不要覆盖无关的插件或服务配置。