transcendence-memory

此技能的功能

通过连接 transcendence-memory-server 后端，为 AI Agent 提供可自托管的长期记忆。

核心功能：

• 连接：使用连接令牌或手动配置，一步完成身份验证
• 文本记忆：通过轻量级 CRUD 端点管理结构化记忆
• 多模态 RAG：将文档（PDF、图像或 Markdown）或原始文本上传到 RAG-Anything 流水线，然后提出自然语言问题并获取由大模型生成的答案
• 容器管理：列出并删除容器
• 治理（服务端 v0.20）：运行时配置中心、包含 6 种工具的治理工具箱（SAFE / LLM / 可撤销的破坏性操作）、梦境子系统（后台／手动整理记忆），以及启用后才运行、需人工审批的 LLM 工具使用编排 Agent——全部优先采用 dry-run，且默认关闭。参见 references/governance.md。
• 故障排查：诊断连接和检索问题

安装

Claude Code（推荐）

在 Claude Code 会话中：

/plugin marketplace add leekkk2/transcendence-memory
/plugin install transcendence-memory@transcendence-memory

@transcendence-memory 后缀用于命名市场（由 .claude-plugin/marketplace.json 中的 .name 设置）。请务必包含该后缀——根据官方文档，Claude Code 使用 <plugin>@<marketplace> 解析插件安装。

或者使用图形界面：运行 /plugin 打开插件管理器 → 发现选项卡 → 搜索 "transcendence-memory" → 安装。

安装后，请重启 Claude Code。 /reload-plugins 会将钩子和技能正文加载到上下文中，但不会重建斜杠命令解析器（已知问题 anthropics/claude-code#37862）——只有完全重启后，/tm / /transcendence-memory 斜杠命令才会注册。四个生命周期钩子（SessionStart / UserPromptSubmit / PostToolUse / Stop）会在下次启动时立即生效。

之后更新：/plugin update transcendence-memory@transcendence-memory（由 Claude Code 管理缓存）。 或使用内置的 /tm upgrade 命令，通过受管理的安装清单更新单独的源代码检出目录（参见安装兼容性）。

其他 Agent（Cursor / Codex / 手动 git clone）

适用于没有兼容 Claude Code 的插件管理器的 Agent：

# Community installer (3rd-party — wraps a git clone into a stable layout)
npx skills add https://github.com/leekkk2/transcendence-memory --skill transcendence-memory

请将源代码检出目录与已安装的技能分开：

git clone https://github.com/leekkk2/transcendence-memory.git ~/src/transcendence-memory
cd ~/src/transcendence-memory
python3 scripts/install.py --agents codex gemini

Cursor 的目录为 ~/.cursor/skills/；规范路径请参阅你的 Agent 文档。对于受管理的安装，/tm upgrade 会从 ~/.transcendence-memory/install.json 读取检出目录路径。

原则

• 检索只有一条正确路径——仅限 HTTP（严格）。 回忆／搜索记忆只能通过 HTTP 调用此技能的后端：已配置 endpoint 的 /search 或 /query（推荐封装命令：bash scripts/tm-search.sh search <query>）。绝不能通过 docker exec 进入任何本地数据库查找记忆——无论是 supabase_db_*、claude-mem postgres、memory-app／memory-copilot，还是任何应用的本地 supabase／psql。这些都是其他项目的私有存储，与此技能的后端无关；查询它们既不正确（其中没有数据），也违反了跨项目污染禁令。如果 scripts/tm-search.sh 不可用，可改为直接使用 curl 调用已配置的 endpoint（参见下方斜杠命令严格区块中的 curl 备用方案）——仍须纯粹使用 HTTP，绝不进入容器 shell。
• 保留内置记忆：服务端记忆用于补充 Agent 的内置记忆，而非取代它
• 明确依赖项：Bash 封装命令需要 Bash/curl/jq；记忆写入／脱敏还需要 Python 3。原生 Python CLI 使用 httpx/Typer/Rich，无需 Bash/jq。参见 references/search-contract.md。
• 渐进式加载：首次设置时阅读 references/setup.md，之后日常使用只需阅读此文件
• 两条路径，不自动桥接：/ingest-memory/objects 写入 LanceDB（由 /search 提供服务）；/documents/text 和 /documents/upload 写入 RAG-Anything 知识图谱（由 /query 提供服务）。通过一条路径摄取的数据不会自动同步到另一条路径。如果同时需要 /search 摘录和 /query 综合结果，必须双写。参见 references/best-practices.md。

行为约定

以下是此技能期望 Agent 在读取或写入记忆时遵循的约定。这些约定有助于保护搜索召回效果，并防止凭据泄露。

1. 何时回忆

• 在会话开始时，如果接下来的工作显然依赖先前的决策。
• 当用户提到“之前／上次／以前／上次／之前／我们之前怎么做的”等词语时。
• 在回答任何涉及项目历史、先前决策或重复性标准操作流程的问题之前。

2. 何时记录

• 得出高价值结论后（决策、经验教训、标准操作流程、复盘、已解决问题的根本原因）。
• 完成一个 sprint、发布一项功能或处理完一个事件后。
• 绝不记录临时上下文——文件差异、调试跟踪信息、原始工具输出、临时 REPL 输出。

3. 标题 + 触发词模式

之后会回忆记忆的 Agent 使用的是模糊的自然语言短语，而非原始 ASCII ID。写入高价值记忆时，按以下结构组织：

1. 包含同义词的标题——至少包含 2–3 个未来搜索者可能输入的动词／名词，并混合英语和工作语言。
2. 一行 “何时回忆此记忆”，列出动词、实体以及可能的问题表述。
3. 双语标签——混合技术 ID（deploy、auth）和自然语言词语（部署、登录）。

完整模板参见 references/best-practices.<lang>.md §7；围绕一个模糊入口整合多条记忆的索引卡模式参见 §8。

明确的私有记忆政策

如果用户明确授权其私有跨设备记忆端点保留包含凭据在内的原始内容，则应为该端点逐字保留这些内容。不得擅自脱敏或修改。这项授权不适用于其他租户、无关端点或公开输出。对于封装命令会强制执行脱敏的情况，应直接使用 HTTP 摄取 API；graphify 支持 --private-verbatim。配置的 [privacy] preserve_sensitive = true 是端点所有者明确设定的本地政策。记录来源路径和版本，确保结果可追溯。在采用下方默认政策之前，先遵循用户的本地政策。

4. Credential redaction (auto)

The skill auto-redacts common secret patterns through the PostToolUse and Stop hooks via redact_secrets() in hooks/common.sh. If you ingest memories programmatically through another path (custom script, batch importer, manual curl), call redact_secrets() yourself or pass --redact to scripts/batch-ingest.py. Patterns covered:

• API keys: sk-..., xoxb-..., xoxp-..., ghp_..., gho_..., pk_live_..., sk_live_..., AKIA...
• Authorization: Bearer ... headers
• URL-embedded credentials: scheme://user:password@host
• PEM private-key blocks: -----BEGIN ... PRIVATE KEY-----
• JWT-like triple-segment tokens

Sample memory structure:

[Decision / 决策 · Release SOP · 部署 / launch — sprint port conflict]

When to recall me: deploy 部署 launch sprint port conflict docker compose
端口 冲突 -- what was the resolution?

Decision: ...
Tags: deploy, docker, port-conflict, 部署, 端口冲突

See references/best-practices.<lang>.md §9 for the full redaction checklist.

5. Tag-Driven Semantic Memory (采用人类可读的标签 tags 与标题，告别 Memory ID)

在记录记忆时，彻底摒弃人工设计或管理 Memory ID 的心智负担：

• 去 ID 化（No Manual Memory ID）：严禁向用户暴露或强求使用类似 mem-xxxx 的 Memory ID。底层系统会自动从标题、标签和正文中生成不可变的索引指针，调用方无需且不应显式指定 --id。
• 标签与标题是第一等公民（Tags & Titles First）：
  • 多维语义标签（--tags）：调用时必须提炼 3~5 个高区分度、人类完全可读的标签，格式涵盖 [系统/组件, 动作/事件, 主机/环境, 业务实体]。
  • 清晰标题（--title）：用一句话精炼概括决策、根因或操作结论，供人类审查与模糊检索对齐。
• 标准记录命令范式：

  bash scripts/tm-remember.sh "<详细背景、根因与决策正文>" \
    --title "Alishell 代理超时导致 Claude-Mem 观察停滞根因与修复" \
    --tags "claudemem,proxy,alishell,mihomo,newapi"
  

  系统将自动将记忆归档于当前主容器（默认为 main），无需关心内部 ID。

6. Multi-Node Resilience & Node Attribution (单服务/多服务节点自动适配与节点溯源)

为了适应多服务节点高可用部署与跨客户端节点分布式协同，技能全面支持弹性故障转移与节点感知：

• 单服务/多服务节点自动适配 (Single/Multi Server Nodes Auto-Adaptation)：
  • 零改动单节点兼容：沿用单端点配置（endpoint = "https://..."）时，系统保持纯粹的单端点请求，零冗余开销，100% 向后兼容。
  • 多服务节点与故障转移 (Failover)：当配置了多个端点（endpoints = ["https://ep1", "https://ep2"] 或环境变量 TM_ENDPOINTS="ep1,ep2"）时，HTTP 传输层在遇到连接失败（如 curl exit code 6/7/28）或服务端 5xx 故障时，自动故障转移至下一个候选服务节点重试，并即时完成请求。
  • 动态项目路由：自动检测并加载 ~/.transcendence-memory/project-route.sh 或 $TM_ROUTE_SCRIPT，支持根据当前工程目录动态覆盖目标端点与容器。
• 客户端节点感知与协同 (Client Node Attribution & Topology)：
  • 记忆写入时自动节点打标：tm-remember.sh 会自动推断当前环境的主机名，向记忆 tags 中注入 node:<hostname>（如 node:mac-m3），方便跨设备检索时定位知识产生来源；支持使用 --node <name> 显式指定，或使用 --no-node 禁用注入。
  • 动态容器检索与跨容器联合：tm-search.sh search 新增 -c|--container <name> 参数动态覆盖当前容器，并支持 --union / --no-union 参数控制是否联合检索相关联的辅助向量容器。
  • 拓扑与健康探测：tm-search.sh status 会自动遍历探测所有配置的服务节点健康状态并汇总；tm-search.sh node（别名 nodes, info）可一键查看本机客户端环境、活跃服务端点、多节点拓扑与默认容器。

AI 行为 — /tm 是斜杠命令，而非裸 Shell 二进制文件（严格）

/tm 是通过 SlashCommand 工具调用的 Claude Code 斜杠命令。 它不是 Shell 二进制文件，因此将斜杠形式传给 Shell 总会失败：

$ /tm search "..."         # ❌ no such file or directory ( /tm is a slash command )
$ tm-codex search "..."    # ❌ command not found ( no such binary )
$ tm search "..."          # ❌ command not found — UNLESS the user installed
                           #    `pipx install transcendence-memory-cli` (optional, not shipped here)

另有一个可选的 Shell CLI，名为 tm（通过 pipx install transcendence-memory-cli 安装，随服务端仓库的 cli-package/ 提供）。它与 /tm 斜杠命令是不同的东西，且不随此技能打包——只有用户自行安装后才存在。不要假设它存在，也绝不要混淆 /tm <cmd>（本节所述的斜杠命令）和已安装的 tm <cmd> 二进制文件。不存在 tm-codex 二进制文件。AI 必须仅使用以下路径之一（全部为纯 HTTP——绝不可通过 Shell 连接数据库）：

1. 首选 — 随附的包装脚本（适用于 Claude Code 内外的任何 Agent——Claude / Gemini / Codex）：

   bash scripts/tm-search.sh search <query> [-c container] [--union] # semantic recall over configured/specified container
   bash scripts/tm-search.sh query <q>                               # multimodal RAG query
   bash scripts/tm-search.sh status                                  # health probe across single or multi-server nodes
   bash scripts/tm-search.sh node                                    # inspect client environment, endpoints & topology
   bash scripts/tm-search.sh containers [pat]                        # list containers (name/objects/index state)
   bash scripts/tm-search.sh jobs <id>                               # one job's state in plain words
   bash scripts/tm-remember.sh "text" [--title t] [--tags a,b] [--node name|--no-node] # memory store with node attribution
   

   它会读取 ~/.transcendence-memory/config.toml，使用对 zsh 通配符安全的方式构建 JSON 请求体（jq + heredoc，绝不使用裸花括号），添加兼容 WAF 的 User-Agent，遵循 *_PROXY 配置并在必要时自动回退为直接连接，且会在首次调用时按需处理冷启动的后端——因此 Agent 无需安装可选的 tm CLI，也绝不需要（并不存在的）tm-codex 二进制文件。（无需单独的预热 SOP——脚本会自行处理预热。）

2. SlashCommand 工具（在 Claude Code 内运行时）：

   SlashCommand({ command: "/tm search <query>" })
   

3. 备用方案 — 内联 curl（仅在包装脚本不可用时）：

   ENDPOINT="$(grep '^endpoint' ~/.transcendence-memory/config.toml | cut -d'"' -f2)"
   API_KEY="$(grep '^api_key' ~/.transcendence-memory/config.toml | cut -d'"' -f2)"
   CONTAINER="$(grep '^container' ~/.transcendence-memory/config.toml | cut -d'"' -f2)"
   curl -sS -X POST "$ENDPOINT/search" \
     -H "X-API-KEY: $API_KEY" -H "Content-Type: application/json" \
     -d "{\"container\":\"$CONTAINER\",\"query\":\"<query>\",\"topk\":5}"
   

如果 AI 发现自己即将调用 Bash({command: "/tm ..."})（将斜杠命令形式传给 Shell），就立即停止并改用上述路径之一。长格式别名 /transcendence-memory <command> 也同样适用。（Bash({command: "tm ..."}) 仅在用户安装了可选的 transcendence-memory-cli 软件包时才有效——它不属于此技能，因此优先使用上述包装脚本或 SlashCommand。）

下方命令表中的 Example 列展示的是斜杠命令形式。 请通过 SlashCommand 工具调用。原始 HTTP 备用方案请参阅 references/api-reference.md。

AI 行为 — 异步摄取静默模式（v0.4.1+，严格）

任何从服务端 v0.15.0+ 的 KG 写入端点（/tm upload、原始 POST /documents/text、POST /documents/upload）返回整数 pid / job_id 的调用，都是发出后即忘。HTTP 响应已返回——任务已移交处理。AI 必须：

1. 绝不轮询 /jobs/{id} 来等待完成——此规则仅适用于上述 KG 构建任务（/documents/*、/tm upload）。这些任务不得使用 until 循环、休眠循环或阻塞等待。（/embed 异步任务是索引重建，不是 KG 构建任务，因此可以通过 GET /jobs/{id} 轮询——references/* 中的 until ... sleep 轮询模板仅适用于 /embed，不适用于这些 KG 构建任务。）
2. 将服务端响应通过管道写入账本，然后结束本轮对话：

   echo '<server-response-json>' | python3 <skill-path>/scripts/job-ledger.py add
   

3. 成功时保持静默。 下次会话启动时，SessionStart hook 会扫描账本；只有失败时才向用户显示一行警告。当用户在会话中再次提及此技能（或 memory / RAG / KG）时，静默运行 python3 <skill-path>/scripts/job-ledger.py sweep——绝不报告成功，只提示失败。
4. 用户主动检查：/tm jobs。

❌ 不要在加入队列后立即告诉用户“摄取成功，文档现在可以查询”——它只是已加入队列；KG 尚未构建。❌ 不要将加入队列后立即执行 /query 返回空结果视为失败——这是预期行为；该文档会在后续会话中变得可供检索。

按设计采用发出后即忘的方式。一切正常时，用户不会收到任何通知。

内置命令

可通过 /transcendence-memory <command> 调用这些命令，也可使用简写 /tm <command>。每条命令的完整 HTTP / curl / 参数架构见 references/commands.md——此表便于快速查阅，需要调用时请查看参考文档。

命令	用途	示例
connect <token>	导入连接令牌并写入本地配置	/tm connect eyJlbmRw...
connect --manual	手动输入 endpoint、api_key 和 container	/tm connect --manual
status	检查连接状态和服务健康状况（探测所有已配置的 endpoint）	/tm status
node	检查客户端环境、主机平台、活动 endpoint 和拓扑	/tm node
search <query>	对记忆执行语义搜索（-c <container>、--union/--no-union）	/tm search architecture decision from the last deployment
search --match <pattern> <query>	在名称与 <pattern> 模糊匹配的所有 container 中搜索	/tm search --match my-project docker compose
search --all <query>	一次搜索所有 container	/tm search --all release notes
remember <text>	快速存储一条记忆（--title t、--tags a,b、--node name/--no-node）	/tm remember Port conflicts caused the deployment failure
update <id> <text>	更新当前 container 中已有记忆的文本	/tm update mem-001 New corrected content
embed	重建当前 container 的索引	/tm embed
query <question>	执行多模态 RAG 查询并获取大模型生成的回答	/tm query What is the overall project architecture?
upload <file>	将文件上传到知识图谱	/tm upload ./design.pdf
containers [pattern]	列出 container，可选按模糊匹配模式筛选	/tm containers my-project
batch <file.jsonl>	批量导入记忆	/tm batch memories.jsonl
graphify [options]	将 LanceDB 记忆逐步聚类并导入 LightRAG 知识图谱（--container/-c、--dry-run、--status、--all）	python3 scripts/tm-incremental-graphify.py -c <container>
jobs	列出知识图谱后台构建任务（pending / failed / done）	/tm jobs
auto on	启用 git commit 时自动记忆	/tm auto on
auto off	禁用自动记忆	/tm auto off
auto status	显示自动记忆配置	/tm auto status
upgrade	从上游仓库拉取最新技能脚本	/tm upgrade

运维 / 管理 HTTP endpoint（服务 v0.18，无 /tm 简写）

这些 endpoint 没有对应的 /tm 命令——请直接通过 HTTP 调用（均需身份验证）。完整请求 / 响应架构见 references/api-reference.md 和 references/commands.md。

方法 + 路径	用途
GET /index-status · GET /containers/{name}/index-status	按 container 显示索引状态机（stale/indexing/ready/…）+ 对象数量 + embed 积压摘要——用于确认关联 container 是否已实际完成嵌入，再将其纳入 union
POST /embed-multimodal (multipart)	通过 Gemini 原生多模态嵌入，为单个媒体文件（图像/音频/视频）生成嵌入 → 一个 LanceDB 向量行，可通过 /search 检索。要求 container 路由到 gemini_native 配置
POST /containers/aliases · GET /containers/aliases · DELETE /containers/aliases/{alias}	管理 container 名称别名路由（alias → canonical）；仅限管理员
GET /admin/usage/{summary,endpoints,containers,timeseries} · POST /admin/usage/cleanup	请求使用情况分析（调用次数 / 延迟 / 按 container 统计 / 时间段统计）+ 保留数据清理
GET /admin/ui · POST /admin/ui/{login,logout} · GET /admin/ui/me	Cookie 会话管理仪表板 SPA（面向浏览器；Agent 很少直接调用）

治理 / 梦境 / 编排 Agent 端点（服务端 v0.20，无 /tm 快捷方式）

可自托管的自主记忆治理子系统。默认先进行 dry-run，且默认安全——全新部署不会自行修改数据。完整的请求/响应架构见 references/api-reference.md；命令速查见 references/commands.md；概览和安全模型见 references/governance.md。

方法 + 路径	用途
GET /admin/config · PUT /admin/config	运行时配置中心——枚举 / 批量写入已知配置键（热重载）。敏感键不会回显值（仅显示 configured）。这是切换工具 / 梦境计划 / Agent 限制的唯一入口
GET /admin/tools · POST /admin/tools/{tool}/invoke	治理工具箱：包含 6 个预设工具（SAFE / LLM / 可逆的破坏性操作）的矩阵 + 每个容器的启用映射；调用其中一个工具（默认 dry_run=true；SAFE 始终实际执行，LLM/破坏性操作需要 dry_run=false）
GET /admin/dreaming/status · POST /admin/dreaming/trigger	梦境子系统：后台 / 手动记忆整理周期。默认仅生成报告；实际删除还需要通过 config:dreaming:prune_apply 进行门控
POST /admin/agent/{name}/invoke · GET /admin/agent/runs	LLM 工具调用编排 Agent（通过 TM_AGENT_ORCHESTRATION_ENABLED 选择启用，默认关闭）。仅当 dry_run=false 且 allow_apply=true 时才应用可逆工具
GET /admin/agent/approvals · POST …/{id}/approve · POST …/{id}/reject	人工审批队列——/approve 是唯一会实际执行破坏性治理工具的入口；无人值守循环本身绝不会执行破坏性工具

运维：保留已批准的向量空间

• 模型别名及其维度不能标识向量空间。未经用户明确批准，绝不要更改嵌入模型 / 提供方 / 通道，也不要启用跨模型回退。成功的回退响应仍可能破坏检索，同时返回 HTTP 200。
• 要修复疑似污染，请检查服务端代码库，并将实际向量与已批准的通道进行比较。历史 embedding_model 标签可能描述的是主模型，即使生成向量时用的是回退模型。请先备份；在隔离工作区中重建，核验每一行源数据，然后再切换。
• bash scripts/tm-search.sh errors --category other 会显示除未经身份验证的 404 之外的错误。使用 --category all 获取原始记录集，或使用 authenticated 获取携带 API 凭据的请求。对未知 URL 的探测计数不能证明记忆发生故障。历史请求正文可能不可用；新条目会包含经过脱敏的详细信息和请求 ID。
• python3 scripts/tm-governance.py tools 可检查工具箱。invoke <tool> 默认执行 dry-run，并从配置中读取容器；--params-file 用于提供结构化参数。--apply 会明确执行；隔离还需要 --confirm-quarantine。配置工具的请求并不授权隔离真实记忆。
• 模型输入限制和聚合方式属于索引约定的一部分。服务端的 TM_EMBEDDING_MAX_INPUT_CHARS / TM_EMBEDDING_MAX_BATCH_SIZE 会在工作进程和检索中采用相同的完整内容拆分与池化方式；更改这些设置需要重新索引受影响的长输入。不要为了绕过上游 502 限制而悄悄截断记忆。

注意事项——最常踩的坑（写新代码前先扫一遍）

症状	真因	修复
Bash({command: "tm ..."}) 报 command not found	/tm 是 slash command，不是 shell binary	用 SlashCommand({command: "/tm ..."})，或本文 ## AI Behavior — /tm is a slash command 的 curl fallback
/documents/text 或 /upload 后立即 /query 返空	KG 构建异步 (server v0.15.0+)；HTTP 200 ≠ 完成	不要 polling；写 ledger 后结束本轮，下个 session 再 query。详 ## AI Behavior — async ingestion silent-mode
/tm remember 写入后 /query 找不到	/ingest-memory/objects 只写 LanceDB；/query 只看 KG	需要双轨召回时 dual-write，详 references/best-practices.md §1.2
/search 的 results[] 找不到入库时给的 id	服务端不回流 client id；引用 key 是 taskId + chunkId	按 taskId / chunkId / 文本前缀匹配；详 references/commands.md search §Response schema
自写 Python / Node 客户端调 endpoint 全部 403	Cloudflare 默认拦 python-urllib / node-fetch / Go net/http UA	显式 User-Agent: transcendence-memory-skill/0.4（任何非默认值都行）
update / delete 之后 /search 看不到改动	LanceDB index 没 rebuild	/tm embed 刷新（异步入队，duplicate calls 自动 coalesce）
/jobs/{pid} 取不到 .status 字段	顶层没有 status；字段是 running / exit_code	直接读 running / exit_code；或用 /tm jobs 走本地 ledger
明文 sk-... / ghp_... / xoxb-... 进了 memory	hooks 已自动 redact，但 batch / 自定义脚本绕过	调 redact_secrets()（hooks/common.sh）或 batch-ingest.py --redact
/tm upgrade 报 fatal: Not possible to fast-forward	本地有 cherry-pick shadow 或 divergence	保留当前文件与分支，检查 git status 和提交分叉；不要自动 reset。受管安装使用 scripts/install.py --update，检测到本地修改即停止
recall / search 查不到老知识但记得写过	标题用了 ASCII id 不是模糊自然语言	按本文 ## Behavior Conventions §3 的 Title + trigger-words 模板写；老记忆 retrofit 用索引卡补一层（references/best-practices.<lang>.md §8）
/health / /search 回 200 但服务其实没就绪	冷启动（切换/重启后）body 携带 degraded:true / per_container_status: timeout|not_initialized / initialized:false，200 ≠ 成功	解析 body，命中冷启动信号就把同一查询短间隔重发几次直到 ok（tm-search.sh 已自动做）。curl --retry 抓不到（200 在它眼里就是成功）
单容器查询无故 degraded:true	默认 union:false；但一旦走 union，存在却未 embed 的 sibling（如 *_openai）会把整次检索拖成 degraded	主容器结果其实正常——本次显式传 "union":false 跳过 sibling，或先给 sibling 跑一次 /embed 再 union（v0.18 起 server 会自动软跳过未 embed 的 sibling，见下条）
union 时仍看到 not_initialized sibling 噪音 / 整次检索失败	v0.18：从未 embed（无 chunks 表）的 sibling 在 union 解析阶段被软跳过，不再拖累主容器；旧行为是把它算进 per_container_status 致 degraded/error	让 sibling 先 /embed 一次即可下次自动恢复双轨；只要主容器出结果，本次就照常返回。判断某容器是否真就绪用 GET /containers/{name}/index-status（state 字段）
部分容器失败但本应有结果，却被当成整体失败	v0.18 优雅降级：只要任一容器（尤其主容器）有结果就 200 返回，body 标 is_degraded:true（= 旧 degraded，同值双写）+ fallback_source:"partial_containers"；全部失败才 status:"error"。部分成功 不再弹错误文案（message 为 null）	读 is_degraded / degraded（任选，同值）判断结果完整性，照常渲染 results；只有 status==="error" 才当真失败。详 references/troubleshooting.md 降级段
/search 返回空 results 但 blocked_low_score>0	v0.19.0 score-gate：服务端配了 similarity_threshold 或请求传了 score_threshold，向量距离大于上限的命中被丢弃	这是阈值过严，不是库空、不是冷启动——放宽/去掉 score_threshold 重查，或运维提高距离上限 similarity_threshold（dashboard 热重载）。默认不开 → 该字段恒 0
想给检索结果加"源文件第几行"定位却拿不到行号	v0.19.0 行号溯源：results[].lineStart/lineEnd + citations[] 才有；P4 前 ingest 的老 chunk 恒 null	读 lineStart/lineEnd（判 !=null 再用）；老记忆无行号是预期（零 re-embed 向后兼容），新 ingest 自动带
fallback_rendered 非 null / 答案像"模板话术"	v0.19.0 opt-in 兜底模板：score-gate 全拦或全容器降级、且运维配了 fallback_template 时渲染	别当高置信检索结果呈现；默认未配模板时此字段恒 null，无需关注
服务拒绝启动，日志打 FATAL: EMBEDDING_DIM=X disagrees with LanceDB schemas	启动期 dim 一致性闸（v0.18 已在 prod）：.env 的 EMBEDDING_DIM 与已落库容器的 vec 列维度不符——历史上曾静默错配致 /search 连续 14h 报 dim 错。守卫宁可不启动也不放行	把 EMBEDDING_DIM/EMBEDDING_MODEL 对齐已存维度，或用新 model 重建受影响容器；确在迁移途中才临时 TM_ALLOW_DIM_DRIFT=1 跳过。这是 server 端 env，不在本 skill 配置
有全局代理时直连超时 / 或反过来代理不通	endpoint 常被 Cloudflare fronting：某些机器上 env 代理才是快且可靠的路径（GFW 区直连可能 ~12s 超时），另一些机器反之	别预设"代理 = 问题"。tm-search.sh 默认走 *_PROXY、连接失败再自动回退直连；TM_NO_PROXY=1 强制直连
多端点 Failover 时某个节点 5xx / 网络超时	集群中某个服务节点宕机、冷启动或网络闪断	传输层已内建自适应 Failover，遇到连接失败或 5xx 自动按顺序切换至下一个备选服务节点重试；可通过 bash scripts/tm-search.sh status 统一排查各节点连通性

黄金法则：HTTP 200 ≠ 业务完成。所有写入路径（/embed / /documents/* / /upload）都是发后不管；只有 /search 是同步的。冷启动时，连读取路径的 200 响应也可能携带降级的响应正文——务必解析。

跨平台安装

将仓库检出目录与已安装的技能分开。从仓库运行 python3 scripts/install.py（PowerShell：scripts/install.ps1）。该脚本会安装完整的技能树和现有的原生 CLI；绝不会修改全局规则或网络设置。请参阅安装兼容性。

首次设置

首次使用时，请阅读 references/setup.md 完成配置。

核心流程只有两步：

1. 从服务获取连接令牌（通过 /export-connection-token 端点或向管理员获取）
2. 运行 /tm connect <token> 自动完成设置

也可以运行 /tm connect --manual，逐步输入各项值。

之后要验证连接状态，建议使用 bash scripts/tm-search.sh status（一个 Bash/curl/jq 健康检查脚本，可在任何 Agent 上运行——Claude / Gemini / Codex——并解析响应正文以检测冷启动信号，因此不会将降级的 200 误判为成功）。无需安装二进制文件即可使用此脚本；包装脚本本身就足够。可选的 tm CLI（transcendence-memory-cli）是单独提供的便捷工具，而且不存在 tm-codex 二进制文件。

配置完成后，无需再将 references/setup.md 加载到上下文中。

参考文档

主题	文件	加载时机
首次设置（令牌解码、config.toml、验证）	references/setup.md	仅首次使用时
完整 HTTP API（请求 / 响应 / 错误架构、字段别名表）	references/api-reference.md	需要准确字段类型时
逐命令 curl / 选项矩阵	references/commands.md	调用任何 /tm <command> 时——包含完整 HTTP 请求正文、选项和响应架构
治理框架（v0.20）——工具箱 / 梦境 / 编排 Agent + dry-run 优先的安全模型	references/governance.md	操作 /admin/config · /admin/tools · /admin/dreaming/* · /admin/agent/* 时
架构（双路径模型、容器隔离、多嵌入路由）	references/ARCHITECTURE.md	了解其内部工作原理时
故障排除（connect / 401 / 403 / 空搜索 / 空查询 / 冷启动 / union 降级 / WAF 403）	references/troubleshooting.md	遇到问题时
运维（批量导入、持久化队列、自动记忆、平台支持、多嵌入运维）	references/OPERATIONS.md	大规模运行时
最佳实践——英语 / 中文（双路径模型、专用容器、双轨嵌入）	references/best-practices.md · references/best-practices.zh-CN.md	设计记忆布局前
改造指南（为旧版 ASCII ID 记忆补建模糊索引卡片）	references/retrofit-playbook.md	迁移旧记忆以便检索时

认证方式：X-API-KEY: <api-key> 或 Authorization: Bearer <api-key>。

无法连接 / 401 / 403 / 空响应 → 先看本文的 ## Gotchas；完整的失败矩阵见 references/troubleshooting.md；大批量导入 / 持久化队列 / /jobs/{id} 轮询 / 自动记忆 / 平台支持见 references/OPERATIONS.md。

此技能中的文件

references/*.md 已列在上方的 参考文档 表格中。此技能中的非参考文件：

文件	用途	何时加载
references/templates/config.toml.template	配置文件模板	首次设置时
scripts/tm-search.sh	首选检索封装脚本：通过 HTTP 执行 search / query / status / containers / jobs（加载配置、兼容 zsh 通配符的 JSON、代理自动回退、惰性冷启动预热）	用于记忆召回、健康检查和只读管理查看的主要路径
scripts/tm-remember.sh	首选快速存储封装脚本：使用 jq 构建 JSON 调用 POST /ingest-memory/objects（杜绝手动转义导致的 422 错误）、自包含密钥脱敏、支持 --tags/--title/--no-embed/--json	用于 /tm remember 风格的单条记忆写入的主要路径
scripts/batch-ingest.py	批量摄取脚本（内置 --redact）	导入大量记忆时
scripts/tm-incremental-graphify.py	增量知识图谱构建器（语义聚类 + 账本跟踪 + 别名解析）	将 LanceDB 记忆转换为 LightRAG 知识图谱时
scripts/job-ledger.py	异步作业账本：为后台 KG 构建作业提供 add / sweep / list 操作	由 /tm jobs、/tm upload 和 SessionStart 钩子使用
scripts/sync-skill.sh	单向 canonical→installed 镜像（防止偏移）；编辑 canonical 技能后运行	仅用于维护

以下生命周期钩子位于插件/仓库根目录（在此技能目录的上一级 ../../hooks/），且仅在 Claude Code 插件安装中自动注册（单独安装技能时不会启用这些钩子——包括自动凭据脱敏；此时请使用 batch-ingest.py --redact）：

文件（位于 ../../hooks/）	用途	何时启用
hooks/common.sh	所有钩子共用的 bash 库（加载配置、API 调用、JSON 转义）	仅限插件安装——由钩子自动加载
hooks/session-start	SessionStart 钩子：健康检查 + 记忆召回注入	仅限插件安装——自动注册
hooks/prompt-inject	UserPromptSubmit 钩子：由召回关键词或长提示词触发的记忆注入	仅限插件安装——自动注册
hooks/post-commit-memory	PostToolUse 钩子：指示 Agent 存储 git 提交摘要	仅限插件安装——自动注册
hooks/session-stop	Stop 钩子：自动存储会话摘要记忆	仅限插件安装——自动注册

治理子系统 — 服务端环境开关（v0.20）

v0.20 治理工具箱 / 梦境 / 编排 Agent 在服务端配置——大多数参数位于运行时配置中心（config:dreaming:* / config:tools:* / config:agent:*，通过 PUT /admin/config 热重载；默认值完整列表见 references/governance.md §5）。编排 Agent 有一个主环境开关：

• TM_AGENT_ORCHESTRATION_ENABLED — 默认值为 0（关闭）。关闭时，POST /admin/agent/{name}/invoke 会返回 status:"disabled"，且绝不会将任务加入队列，因此默认部署不会运行自主循环。设置为 1（服务端 .env）以允许 Agent 运行。
• TM_AGENT_MAX_STEPS（默认值为 6）/ TM_AGENT_RUN_TIMEOUT_SEC（默认值为 300）/ TM_AGENT_DAILY_TOKEN_BUDGET（留空 = 无额外上限）用于限制每次运行；环境变量优先于对应的 config:agent:* 键。

这些属于服务端 .env 配置，而不是此技能的 config.toml——此技能只会调用这些端点。LLM 路由仍通过获准的网关（HR-9、LLM_*）；不会引入新的模型环境变量。

不适用场景

• 部署后端服务 -> 使用 transcendence-memory-server 仓库
• 管理 Docker、systemd 或 Nginx -> 使用 transcendence-memory-server 仓库
• 排查 5xx 错误、存储问题或日志等服务端问题 -> 使用 transcendence-memory-server 仓库
• 配置 Embedding、LLM 或 VLM 模型 -> 这是服务端的工作，无需由该技能处理