leekkk2 What This Skill Does
Provides self-hosted long-term memory for AI agents by connecting to the transcendence-memory-server backend.
Core capabilities:
- Connect: complete authentication in one step with a connection token or manual configuration
- Text memory: manage structured memories through lightweight CRUD endpoints
- Multimodal RAG: upload documents (PDF, image, or Markdown) or raw text into the RAG-Anything pipeline, then ask natural-language questions and get LLM-generated answers
- Container management: list and delete containers
- Governance (server v0.20): runtime config center, a 6-tool governance toolbox (SAFE / LLM / destructive-reversible), a dreaming subsystem (background/manual memory tidy-up), and an opt-in LLM tool-use orchestration agent with human approval — all dry-run-first and off by default. See
references/governance.md. - Troubleshooting: diagnose connection and retrieval issues
Install
Claude Code (recommended)
Inside a Claude Code session:
/plugin marketplace add leekkk2/transcendence-memory
/plugin install transcendence-memory@transcendence-memory
The
@transcendence-memorysuffix names the marketplace (set by.claude-plugin/marketplace.json.name). Always include it — Claude Code resolves plugin installs by<plugin>@<marketplace>per the official docs.
Or use the GUI: run /plugin to open the plugin manager → Discover tab → search "transcendence-memory" → Install.
After install, restart Claude Code. /reload-plugins loads hooks + skill body into context but does not rebuild the slash-command parser (known issue anthropics/claude-code#37862) — /tm / /transcendence-memory slash commands will only register after a full restart. The four lifecycle hooks (SessionStart / UserPromptSubmit / PostToolUse / Stop) are active immediately on next launch.
Updating later:
/plugin update transcendence-memory@transcendence-memory(Claude Code manages the cache). Or use the bundled/tm upgradecommand, which uses the managed install manifest to update the separate source checkout (see installation compatibility).
Other agents (Cursor / Codex / manual git clone)
For agents without a Claude Code-compatible plugin manager:
# Community installer (3rd-party — wraps a git clone into a stable layout)
npx skills add https://github.com/leekkk2/transcendence-memory --skill transcendence-memory
Keep the source checkout separate from the installed skill:
git clone https://github.com/leekkk2/transcendence-memory.git ~/src/transcendence-memory
cd ~/src/transcendence-memory
python3 scripts/install.py --agents codex gemini
Cursor's directory is
~/.cursor/skills/; consult your agent's docs for the canonical path. For managed installs,/tm upgradereads the checkout path from~/.transcendence-memory/install.json.
Principles
- Retrieval has exactly one correct path — HTTP only (STRICT). Recalling / searching memory goes only through this skill's backend over HTTP: the configured
endpoint's/searchor/query(preferred wrapper:bash scripts/tm-search.sh search <query>). Neverdocker execinto any local database to look for memories — notsupabase_db_*, not aclaude-mempostgres, notmemory-app/memory-copilot, not any app's localsupabase/psql. Those are other projects' private stores with no relationship to this skill's backend; querying them is both wrong (no data there) and a cross-project contamination violation. Ifscripts/tm-search.shis unavailable, fall back to inlinecurlagainst the configuredendpoint(see the curl escape hatch in the slash-command STRICT block below) — still pure HTTP, never a container shell. - Keep builtin memory: server-side memory augments the agent's builtin memory instead of replacing it
- Explicit dependencies: Bash wrappers require Bash/curl/jq; remember/redaction additionally require Python 3. Native Python CLI uses httpx/Typer/Rich and needs no Bash/jq. See
references/search-contract.md. - Progressive loading: read
references/setup.mdduring first-time setup, then this file is enough for day-to-day use - Two paths, no auto-bridge:
/ingest-memory/objectswrites to LanceDB (served by/search);/documents/textand/documents/uploadwrite to the RAG-Anything knowledge graph (served by/query). Data ingested through one path is not auto-promoted to the other. When you need both/searchsnippets and/querysynthesis, you must dual-write. Seereferences/best-practices.md.
Behavior Conventions
These are the conventions the skill expects agents to follow when reading or writing memories. They protect search recall and prevent credential leaks.
1. When to recall
- At session start, when the upcoming work obviously depends on prior decisions.
- When the user mentions verbs like "before / last time / previously / 上次 / 之前 / 我们之前怎么做的".
- Before answering any question that references project history, prior decisions, or recurring SOPs.
2. When to remember
- After a high-value conclusion is reached (decision, lesson, SOP, postmortem, resolved bug root cause).
- After completing a sprint, shipping a feature, or closing an incident.
- Never for transient context — file diffs, debug traces, raw tool output, ephemeral REPL output.
3. Title + trigger-words pattern
Agents that recall memory later use fuzzy natural-language phrases, not the original ASCII id. When writing a high-value memory, structure it as:
- Title with synonyms — at least 2-3 of the verbs / nouns a future searcher might type, mixing English and the working language.
- A "When to recall me" line listing verbs + entities + likely question phrasings.
- Bilingual tags — mix technical ids (
deploy,auth) and natural- language terms (部署,登录).
See references/best-practices.<lang>.md §7 for the full template, and §8 for
the index-card pattern that consolidates many memories around one fuzzy entry
point.
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。
AI Behavior — /tm is a slash command, not a bare shell binary (STRICT)
/tm is a Claude Code slash command invoked through the SlashCommand tool.
It is NOT a shell binary, so passing the slashed form to a shell always fails:
$ /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)
A separate, optional shell CLI named tm does exist (pipx install transcendence-memory-cli, shipped from the server repo's cli-package/). It is a different thing from the /tm slash command and is not bundled with this skill — only present if the user installed it themselves. Do not assume it exists, and never conflate /tm <cmd> (the slash command, this section) with the installed tm <cmd> binary. There is no tm-codex binary. The AI MUST use one of these paths only (all pure HTTP — never a shell into a DB):
Preferred — bundled wrapper script (works on any agent — Claude / Gemini / Codex — in or out of Claude Code):
bash scripts/tm-search.sh search <query> # semantic recall over the configured container bash scripts/tm-search.sh query <q> # multimodal RAG query bash scripts/tm-search.sh status # one-line health probe 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] # quick memory store (jq-built JSON + secret redaction)It reads
~/.transcendence-memory/config.toml, builds the JSON body zsh-glob-safely (jq + heredoc, never bare braces), adds a WAF-compatible User-Agent, honors*_PROXYwith auto-fallback to direct, and lazily absorbs a cold-start backend on first call — so agents don't need the optionaltmCLI installed, and never need a (nonexistent)tm-codexbinary. (No separate warm-up SOP — warm-up is handled inside the script.)SlashCommandtool (when running inside Claude Code):SlashCommand({ command: "/tm search <query>" })Escape hatch — inline curl (only when the wrapper is unavailable):
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}"
If the AI catches itself about to invoke Bash({command: "/tm ..."}) (slash-command
form passed to a shell), STOP and switch to one of the paths above. The same applies
to the long-form alias /transcendence-memory <command>. (Bash({command: "tm ..."})
only works if the user installed the optional transcendence-memory-cli package — it
is not part of this skill, so prefer the wrapper script or SlashCommand above.)
The
Examplecolumn in the command table below shows the slash-command form. Invoke via theSlashCommandtool. For raw HTTP fallback, seereferences/api-reference.md.
AI Behavior — async ingestion silent-mode (v0.4.1+, STRICT)
Any call that returns an integer pid / job_id from a server v0.15.0+ KG-write endpoint (/tm upload, raw POST /documents/text, POST /documents/upload) is fire-and-forget. HTTP already returned — the task is handed off. The AI MUST:
- Never poll
/jobs/{id}to wait for completion — this rule scopes ONLY to the KG-build jobs above (/documents/*,/tm upload). Nountilloops, no sleep-loops, no blocking waits for those. (/embedasync jobs are an index rebuild, not a KG-build job, and MAY be polled viaGET /jobs/{id}— theuntil ... sleeppolling templates inreferences/*are scoped to/embed, not to these KG-build jobs.) - Pipe the server response to the ledger and end the turn:
echo '<server-response-json>' | python3 <skill-path>/scripts/job-ledger.py add - Stay silent on success. The SessionStart hook sweeps the ledger next session; only failures surface one warning line to the user. When the user mentions this skill (or memory / RAG / KG) again mid-session, silently run
python3 <skill-path>/scripts/job-ledger.py sweep— never report success, only surface failures. - User-initiated inspection:
/tm jobs.
❌ Don't tell the user "ingestion succeeded, doc is queryable now" right after enqueue — only enqueued; KG isn't built yet. ❌ Don't treat empty /query immediately after enqueue as failure — expected; the doc becomes recallable in a later session.
Fire-and-forget by design. If everything is fine, the user never hears about it.
Built-in Commands
These commands can be invoked through /transcendence-memory <command> or the short form /tm <command>. Full HTTP / curl / argument schemas for every command live in references/commands.md — keep this table for at-a-glance discovery, jump to the reference when you need to call one.
| Command | Purpose | Example |
|---|---|---|
connect <token> |
Import a connection token and write local config | /tm connect eyJlbmRw... |
connect --manual |
Enter endpoint, api_key, and container manually | /tm connect --manual |
status |
Check connection status and server health | /tm status |
search <query> |
Run semantic search over memories | /tm search architecture decision from the last deployment |
search --match <pattern> <query> |
Search across all containers whose name fuzzy-matches <pattern> |
/tm search --match my-project docker compose |
search --all <query> |
Search across every container at once | /tm search --all release notes |
remember <text> |
Store one memory quickly (preferred wrapper: bash scripts/tm-remember.sh "<text>" — jq-built JSON, no hand-escaping 422s, built-in secret redaction) |
/tm remember Port conflicts caused the deployment failure |
update <id> <text> |
Update an existing memory's text in the current container | /tm update mem-001 New corrected content |
embed |
Rebuild the index for the current container | /tm embed |
query <question> |
Run a multimodal RAG query and get an LLM-generated answer | /tm query What is the overall project architecture? |
upload <file> |
Upload a file into the knowledge graph | /tm upload ./design.pdf |
containers [pattern] |
List containers, optionally filtered by a fuzzy pattern | /tm containers my-project |
batch <file.jsonl> |
Bulk import memories | /tm batch memories.jsonl |
jobs |
List background knowledge-graph build jobs (pending / failed / done) | /tm jobs |
auto on |
Enable automatic memory on git commits | /tm auto on |
auto off |
Disable automatic memory | /tm auto off |
auto status |
Show auto-memory configuration | /tm auto status |
upgrade |
Pull latest skill scripts from the upstream repo | /tm upgrade |
Operational / admin HTTP endpoints (server v0.18, no /tm shortcut)
These have no /tm command — call them directly over HTTP (all need auth). Full request / response schemas in references/api-reference.md and references/commands.md.
| Method + path | Purpose |
|---|---|
GET /index-status · GET /containers/{name}/index-status |
Per-container index state machine (stale/indexing/ready/…) + object counts + embed backlog summary — tells you whether a sibling is actually embedded before you union it |
POST /embed-multimodal (multipart) |
Embed one media file (image/audio/video) via Gemini-native multimodal embedding → one LanceDB vector row, recallable by /search. Requires the container to route to a gemini_native profile |
POST /containers/aliases · GET /containers/aliases · DELETE /containers/aliases/{alias} |
Manage container-name alias routing (alias → canonical); admin only |
GET /admin/usage/{summary,endpoints,containers,timeseries} · POST /admin/usage/cleanup |
Request-usage analytics (call counts / latency / per-container / time buckets) + retention cleanup |
GET /admin/ui · POST /admin/ui/{login,logout} · GET /admin/ui/me |
Cookie-session admin dashboard SPA (browser-facing; agents rarely call directly) |
Governance / dreaming / orchestration-agent endpoints (server v0.20, no /tm shortcut)
Self-hosted autonomous memory-governance subsystem. All dry-run-first and safe by default — a fresh deploy never mutates data on its own. Full request/response schemas in references/api-reference.md;命令速查 in references/commands.md; overview + safety model in references/governance.md.
| Method + path | Purpose |
|---|---|
GET /admin/config · PUT /admin/config |
Runtime config center — enumerate / batch-write known config keys (hot-reload). Sensitive keys never echo a value (only configured). The single place to toggle tools / dreaming schedule / agent limits |
GET /admin/tools · POST /admin/tools/{tool}/invoke |
Governance toolbox: matrix of 6 preset tools (SAFE / LLM / destructive-reversible) + per-container enable map; invoke one (dry_run=true default; SAFE always real, LLM/destructive need dry_run=false) |
GET /admin/dreaming/status · POST /admin/dreaming/trigger |
Dreaming subsystem: background/manual memory tidy-up cycle. Trigger is report-only by default; real deletes additionally gated by config:dreaming:prune_apply |
POST /admin/agent/{name}/invoke · GET /admin/agent/runs |
LLM tool-use orchestration agent (opt-in behind TM_AGENT_ORCHESTRATION_ENABLED, default OFF). Reversible tools apply only when dry_run=false AND allow_apply=true |
GET /admin/agent/approvals · POST …/{id}/approve · POST …/{id}/reject |
Human approval queue — /approve is the only place a destructive governance tool runs for real; the unattended loop never executes destructive tools itself |
Operations: preserve the approved vector space
- A model alias and its dimensions do not identify a vector space. Never change an embedding model/provider/channel or enable cross-model fallback without explicit user approval. A successful fallback response can corrupt retrieval while still reporting HTTP 200.
- To repair suspected contamination, inspect the server repository and compare actual vectors with the approved channel. Historical
embedding_modellabels can describe the primary even when a fallback generated the vector. Back up first; rebuild in an isolated workspace, verify every source row, then switch. bash scripts/tm-search.sh errors --category othershows errors excluding unauthenticated 404s. Use--category allfor the raw record set orauthenticatedfor requests carrying API credentials. Counts of probes to unknown URLs are not evidence of memory failures. Historical bodies may be unavailable; new entries include redacted details and a request ID.python3 scripts/tm-governance.py toolsinspects the toolbox.invoke <tool>defaults to a dry run and reads the container from config;--params-filesupplies structured parameters.--applyexecutes explicitly; quarantine additionally requires--confirm-quarantine. A request to configure tools does not authorize quarantining real memories.- Model input bounds and aggregation are part of the index contract. Server
TM_EMBEDDING_MAX_INPUT_CHARS/TM_EMBEDDING_MAX_BATCH_SIZEapply the same full-content splitting and pooling in worker and retrieval; changing these requires reindexing affected long inputs. Do not silently truncate a memory to work around upstream 502 limits.
Gotchas — 最常踩的坑（写新代码前先扫一遍）
| 症状 | 真因 | 修复 |
|---|---|---|
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 强制直连 |
黄金法则：HTTP 200 ≠ 业务完成。所有写路径（
/embed//documents/*//upload）都是 fire-and-forget；只有/search同步。冷启动时连读路径的 200 都可能携带 degraded body——务必解析。
Cross-platform installation
Keep the repository checkout separate from the installed skill. Run python3 scripts/install.py from the repo (PowerShell: scripts/install.ps1). It installs the complete skill tree and existing native CLI; never edits global rules or network settings. See installation compatibility.
First-Time Setup
On first use, read references/setup.md to complete configuration.
The core flow has only two steps:
- Get a connection token from the server (through the
/export-connection-tokenendpoint or from an administrator) - Run
/tm connect <token>to finish setup automatically
Or run /tm connect --manual and enter the values step by step.
To verify connectivity afterwards, prefer bash scripts/tm-search.sh status (a Bash/curl/jq health probe that runs on any agent — Claude / Gemini / Codex — and parses the body for cold-start signals, so a degraded 200 is not mistaken for success). No binary needs to be installed for this — the wrapper script is enough; the optional tm CLI (transcendence-memory-cli) is a separate convenience, and there is no tm-codex binary.
After configuration is complete,
references/setup.mdno longer needs to be loaded into context.
Reference Documents
| Topic | File | When to load |
|---|---|---|
| First-time setup (token decode, config.toml, verify) | references/setup.md |
First use only |
| Full HTTP API (request / response / error schemas, field-alias table) | references/api-reference.md |
When you need exact field types |
| Per-command curl / options matrix | references/commands.md |
When invoking any /tm <command> — full HTTP body, options, response schema |
| Governance framework (v0.20) — toolbox / dreaming / orchestration agent + dry-run-first safety model | references/governance.md |
When driving /admin/config · /admin/tools · /admin/dreaming/* · /admin/agent/* |
| Architecture (dual-path model, container isolation, multi-embedding routing) | references/ARCHITECTURE.md |
When understanding how it works internally |
| Troubleshooting (connect / 401 / 403 / empty search / empty query / cold-start / union degraded / WAF 403) | references/troubleshooting.md |
When something doesn't work |
| Operations (bulk ingest, persistent queue, automatic memory, platform support, multi-embedding ops) | references/OPERATIONS.md |
When operating at scale |
| Best practices — English / 中文 (two-path model, dedicated containers, dual-track embeddings) | references/best-practices.md · references/best-practices.zh-CN.md |
Before designing memory layout |
| Retrofit playbook (back-filling fuzzy index cards onto legacy ASCII-id memories) | references/retrofit-playbook.md |
When migrating old memories for recall |
Auth methods: X-API-KEY: <api-key> or Authorization: Bearer <api-key>.
Cannot connect / 401 / 403 / 空响应 → 先看本文
## Gotchas；展开的失败矩阵在references/troubleshooting.md；大批量 ingest / persistent queue //jobs/{id}polling / automatic memory / 平台支持在references/OPERATIONS.md。
Files in This Skill
references/*.mdare listed in the Reference Documents table above. The non-reference files in this skill:
| File | Purpose | When to load |
|---|---|---|
references/templates/config.toml.template |
Config file template | During first-time setup |
scripts/tm-search.sh |
Preferred retrieval wrapper: search / query / status / containers / jobs over HTTP (config load, zsh-glob-safe JSON, proxy auto-fallback, lazy cold-start warm-up) |
Primary path for recall + health probe + read-only admin peeks |
scripts/tm-remember.sh |
Preferred quick-store wrapper: POST /ingest-memory/objects with jq-built JSON (kills the hand-escaping 422 class), self-contained secret redaction, --tags/--title/--no-embed/--json |
Primary path for /tm remember-style single-memory writes |
scripts/batch-ingest.py |
Bulk ingest script (built-in --redact) |
For large memory imports |
scripts/job-ledger.py |
Async job ledger: add / sweep / list for background KG build jobs |
Used by /tm jobs, /tm upload, and the SessionStart hook |
scripts/sync-skill.sh |
One-way canonical→installed mirror (anti-drift); run after editing the canonical skill | Maintenance only |
The lifecycle hooks below live at the plugin/repo root (../../hooks/, one level up from this skill dir) and are auto-registered only in the Claude Code plugin install (a bare skill install has none of them — including auto credential redaction; use batch-ingest.py --redact there):
File (at ../../hooks/) |
Purpose | When active |
|---|---|---|
hooks/common.sh |
Shared bash library for all hooks (config loading, API calls, JSON escaping) | Plugin install only — auto-loaded by hooks |
hooks/session-start |
SessionStart hook: health check + memory recall injection | Plugin install only — auto-registered |
hooks/prompt-inject |
UserPromptSubmit hook: recall-keyword / long-prompt triggered memory injection | Plugin install only — auto-registered |
hooks/post-commit-memory |
PostToolUse hook: instruct agent to store git commit summary | Plugin install only — auto-registered |
hooks/session-stop |
Stop hook: auto-store session summary memory | Plugin install only — auto-registered |
Governance subsystem — server-side env switches (v0.20)
The v0.20 governance toolbox / dreaming / orchestration agent are configured server-side — most knobs live in the runtime config center (config:dreaming:* / config:tools:* / config:agent:*, hot-reloaded via PUT /admin/config; full list with defaults in references/governance.md §5). The orchestration agent has one master env gate:
TM_AGENT_ORCHESTRATION_ENABLED— default0(OFF). When off,POST /admin/agent/{name}/invokereturnsstatus:"disabled"and never enqueues, so a default deploy runs no autonomous loop. Set1(server.env) to allow agent runs.TM_AGENT_MAX_STEPS(default 6) /TM_AGENT_RUN_TIMEOUT_SEC(default 300) /TM_AGENT_DAILY_TOKEN_BUDGET(blank = no extra cap) bound each run; env wins over the matchingconfig:agent:*key.
These are server .env concerns, not this skill's config.toml — the skill only calls the endpoints. LLM routing stays on the sanctioned gateway (HR-9, LLM_*); no new model env is introduced.
When NOT to Use
- Deploying the backend service -> use the
transcendence-memory-serverrepository - Managing Docker, systemd, or Nginx -> use the
transcendence-memory-serverrepository - Troubleshooting server-side problems such as 5xx errors, storage issues, or logs -> use the
transcendence-memory-serverrepository - Configuring Embedding, LLM, or VLM models -> this is a server-side concern and does not need to be handled by the skill