agent-memory
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseagent-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 / (see / 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 ( in , disabled by default) -- when a namespace is routed to it, gm's /// 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 's own docs when the ask is just "make gm's memory use the Tencent-compatible backend."
memorize-firerecallwfgy-methodgmmemory.tencentdb_backendgm.config.jsonmemorizerecallmemorize-firememorize-prunegmTencentDB Agent Memory为Agent团队提供了一套可共享、持续增长的记忆系统,无需每次会话都从零开始。它与gm自身的/(相关内容详见/技能)存在两种关联方式:(1) 作为完全独立的系统(即本技能的核心内容,见下文),适用于需求跨多个Agent框架、跨多个团队成员,或需要人工可审核面板的场景;(2) 作为gm记忆接口的可选存储后端(对应中的配置,默认禁用)——当某个命名空间路由至该后端时,gm的///接口会写入与本系统格式兼容的、以文件指针为索引的内容,而非gm默认的384维md语料库存储,且Agent调用的接口语法完全不变。如需独立部署,请参考本技能的搭建指南(Docker Compose、面板UI);若仅需“让gm的记忆使用兼容Tencent格式的后端”,则请查阅gm自身文档。
memorize-firerecallwfgy-methodgmgm.config.jsonmemory.tencentdb_backendmemorizerecallmemorize-firememorize-pruneWhat 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 '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.
agent-memory - Use gm's own /
memorize/recall/memorize-fireverbs (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 atmemorize-prune'sgm.config.jsonblock instead of a full standalone install.memory.tencentdb_backend
- 当用户明确提及TencentDB/memory-tencentdb/Memory Hub/team memory,需要跨不同Agent框架或团队成员的持久化记忆(不仅限于当前会话),需要从过往对话中提取Skill库,或需要针对代码库构建Wiki/CodeGraph时,请使用的独立搭建指南。
agent-memory - 若仅需当前会话的本地记忆,请使用gm原生的/
memorize/recall/memorize-fire接口(默认后端,无需搭建);若用户明确希望gm的记忆兼容Tencent格式但无需运行独立服务,请引导其查看memorize-prune中的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 setupOpen the panel at .
http://localhost:8125For a standalone Memory Hub, Proxy + Claude Code / CodeBuddy integration, port reference, and teardown, see in the repo ( for Chinese).
INSTALL.mdINSTALL_CN.mdbash
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.mdINSTALL_CN.md2. OpenClaw plugin install (if the host is OpenClaw, not Claude Code)
2. OpenClaw插件安装(若宿主为OpenClaw而非Claude Code)
bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdbMinimal config in :
~/.openclaw/openclaw.jsonjson
{ "memory-tencentdb": { "enabled": true } }Zero-config works for basic capability. Production tuning groups: , , , , , -- see for the full recommended template and failure-mode notes (embedding four-tuple, retention-day gating, etc.).
captureextractionpipelinerecallpersonaembeddingreferences/openclaw-config.mdbash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb~/.openclaw/openclaw.jsonjson
{ "memory-tencentdb": { "enabled": true } }零配置即可实现基础功能。生产环境调优分组包括:、、、、、——完整推荐模板及故障排查说明(嵌入四元组、保留天数限制等)请查看。
captureextractionpipelinerecallpersonaembeddingreferences/openclaw-config.md3. 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 in the repo. New installs skip this.
MemoryCore/scripts/migrate-v2-to-v3/README.md使用仓库中文档记录的迁移工具。全新安装可跳过此步骤。
MemoryCore/scripts/migrate-v2-to-v3/README.md4. Migrating gm's own memories into the tencentdb_backend
store
tencentdb_backend4. 将gm原生记忆迁移至tencentdb_backend
存储
tencentdb_backendDistinct from #3 above (that's the standalone system's own internal format
evolution). This is for a project that already has gm-native memories
(, written by / before
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.
.gm/memories/*.mdmemorizememorize-firememory.tencentdb_backendTwo ways to run this migration -- same underlying write path
(), pick whichever fits the situation:
tencentdb_memory::write_cfg- From within a live agent session: dispatch the
verb:
tencentdb-memory-import. It reads every{"source_namespace": "default", "dest_namespace": "<routed-namespace>", "kind": "l1"}doc in the source namespace and re-embeds through gm's own 384-dim pipeline..md - Batch/CLI, outside an agent session: . 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.
node scripts/migrate-memory-to-tencentdb.mjs --project <path> --namespace <ns> [--dry-run] [--archive]
Both refuse up front unless the destination namespace's resolved
is exactly -- 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 -routed namespaces, each at
its own dim.
memory.tencentdb_backend.vectors_db_dims384tencentdb_backendBy default this is a one-way copy, not a move: the source files and
their index rows are left untouched, so the default
backend keeps working for any namespace not also switched over. Pass
(verb) or (script) to opt into moving
each successfully-migrated source file to
instead of leaving
it in place -- content stays inspectable, but the live
corpus no longer duplicates what the new backend now serves.
.mdrssearch_vectorsarchive_source: true--archive.gm/memories-archive-tencentdb/<namespace>/<filename>.gm/memories/此步骤与上述第3步不同(第3步是独立系统自身的格式演进)。适用于已拥有gm原生记忆(,由/在启用前写入)的项目,当某个命名空间选择接入兼容Tencent的后端时,可将原有记忆迁移过去,避免切换后记忆丢失。
.gm/memories/*.mdmemorizememorize-firememory.tencentdb_backend有两种迁移方式——底层写入路径相同(),可根据场景选择:
tencentdb_memory::write_cfg- 在活跃Agent会话中执行:调用接口:
tencentdb-memory-import。该接口会读取源命名空间下所有{"source_namespace": "default", "dest_namespace": "<routed-namespace>", "kind": "l1"}文档,并通过gm自身的384维流水线重新嵌入。.md - 批量/CLI方式(Agent会话外执行):运行。写入路径相同,但会应用接口未实现的衍生状态丢弃过滤器(可从git日志推导的事实、过期审计条目、历史框架信息)——若需要批量迁移并丢弃冗余内容,推荐使用此方式;若仅需从已运行的会话中单次触发迁移,则使用接口方式。
node scripts/migrate-memory-to-tencentdb.mjs --project <path> --namespace <ns> [--dry-run] [--archive]
两种方式都会预先检查目标命名空间的是否恰好为——gm的嵌入器无法生成其他维度的向量,若命名空间配置为外部嵌入的768维内容(默认值),则无法安全接收迁移内容(该命名空间的查询会使用项目配置的维度,而非导入时的临时覆盖,维度不匹配属于实际缺陷,而非形式问题)。若项目需要同时存储两种维度的内容,需配置两个独立的路由命名空间,各自对应不同维度。
memory.tencentdb_backend.vectors_db_dims384tencentdb_backend默认情况下为单向复制,而非移动:源文件及其索引行将保持不变,因此默认后端仍可服务于未切换的命名空间。若选择移动,可在调用接口时传入,或在运行脚本时添加参数——成功迁移的源文件将被移动至,内容仍可查看,但活跃的语料库不再重复存储新后端已有的内容。
.mdrssearch_vectorsarchive_source: true--archive.gm/memories-archive-tencentdb/<namespace>/<filename>.gm/memories/Verification (do this before declaring setup done)
验证步骤(完成搭建前请执行)
- Confirm version prerequisites: (
node -v), and>=22.16(openclaw --version) if using the OpenClaw plugin path.>=2026.3.13 - After start/restart, confirm the service actually came up -- read logs (prefix for the OpenClaw plugin path, or the relevant container logs for Docker Compose) rather than assuming success from a clean exit code.
[memory-tdai] - Confirm the data directory exists and is non-empty (OpenClaw: containing
~/.openclaw/state/memory-tdai/,conversations/,records/,scene_blocks/).vectors.db - 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). A missing recall on this smoke test means setup is not done -- do not report success from config-file presence alone.tdai_conversation_search
- 确认版本要求:(
node -v);若使用OpenClaw插件方式,需确认>=22.16(openclaw --version)。>=2026.3.13 - 启动/重启后,确认服务实际运行——查看日志(OpenClaw插件方式为前缀,Docker Compose方式为对应容器日志),不要仅通过退出码判断成功。
[memory-tdai] - 确认数据目录存在且非空(OpenClaw:,包含
~/.openclaw/state/memory-tdai/、conversations/、records/、scene_blocks/)。vectors.db - 执行完整往返测试:进行2-3轮对话并包含可记忆的事实,启动新会话,确认记忆内容可被召回(通过面板或搜索工具调用,如/
tdai_memory_search)。若此冒烟测试中无法召回内容,则搭建未完成——不要仅通过配置文件存在就报告成功。tdai_conversation_search
Common failure modes
常见故障模式
- No logs at all: not
memory-tencentdb.enabled, or the gateway/service was never restarted after config changes.true - Records exist but nothing recalls: is false, or
recall.enabledis too high.recall.scoreThreshold - No vector results: the config is missing one of
embedding/apiKey/baseUrl/model-- any single missing field silently degrades to keyword-only mode rather than erroring.dimensions - History disappearing too fast: set too low (1-2) without explicitly enabling
l0l1RetentionDays.allowAggressiveCleanup
- 无任何日志:未设为
memory-tencentdb.enabled,或配置变更后未重启网关/服务。true - 记录存在但无法召回:为false,或
recall.enabled设置过高。recall.scoreThreshold - 无向量结果:配置缺失
embedding/apiKey/baseUrl/model中的任意一项——缺失单个字段会静默降级为仅关键词模式,而非报错。dimensions - 历史内容过快消失:设置过低(1-2天)且未明确启用
l0l1RetentionDays。allowAggressiveCleanup
Security
安全注意事项
Treat 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 /agent-memory section; do not overwrite unrelated plugin or service config.
embedding.apiKeymemory-tencentdb请将及所有LLM凭据视为敏感信息——不要在聊天、日志或截图中泄露。优先使用环境变量注入,而非在配置文件中写入明文值。编辑配置时,仅修改/agent-memory相关部分;不要覆盖无关的插件或服务配置。
embedding.apiKeymemory-tencentdb