transcendence-memory

このスキルでできること

transcendence-memory-server バックエンドに接続し、AI エージェントにセルフホスト可能な長期メモリを提供します。

主な機能：

• 接続：接続トークンまたは手動設定を使用して、1 ステップで認証を完了します
• テキストメモリ：軽量な CRUD エンドポイントを通じて、構造化されたメモリを管理します
• マルチモーダル RAG：ドキュメント（PDF、画像、Markdown）または生テキストを RAG-Anything パイプラインにアップロードし、自然言語で質問して、LLM が生成した回答を取得します
• コンテナ管理：コンテナの一覧表示と削除を行います
• ガバナンス（サーバー v0.20）：ランタイム設定センター、6 ツールのガバナンスツールボックス（SAFE／LLM／破壊的だが元に戻せる操作）、夢想サブシステム（バックグラウンドまたは手動でのメモリ整理）、人間の承認を伴うオプトイン方式の LLM ツール使用オーケストレーションエージェントを提供します。すべてドライランを優先し、デフォルトでは無効です。詳細は 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> を使ってプラグインのインストール先を解決するため、必ず指定してください。

または GUI を使用します。/plugin を実行してプラグインマネージャーを開き、Discover タブで「transcendence-memory」を検索して Install を選択します。

インストール後、Claude Code を再起動してください。 /reload-plugins を実行するとフックとスキル本文はコンテキストに読み込まれますが、スラッシュコマンドパーサーは再構築されません（既知の問題：anthropics/claude-code#37862）。そのため、/tm ／ /transcendence-memory スラッシュコマンドは完全に再起動した後にのみ登録されます。4 つのライフサイクルフック（SessionStart ／ UserPromptSubmit ／ PostToolUse ／ Stop）は、次回起動時にすぐ有効になります。

後で更新する場合：/plugin update transcendence-memory@transcendence-memory（Claude Code がキャッシュを管理します）。 または、同梱の /tm upgrade コマンドを使用すると、管理対象のインストールマニフェストを使って別のソースチェックアウトを更新できます（インストール互換性を参照）。

その他のエージェント（Cursor ／ Codex ／手動での git clone）

Claude Code 互換のプラグインマネージャーを持たないエージェントの場合：

# 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/ です。正規のパスについては、お使いのエージェントのドキュメントを確認してください。管理対象のインストールでは、/tm upgrade が ~/.transcendence-memory/install.json からチェックアウトパスを読み取ります。

原則

• 取得経路は常に1つだけです。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 が使用できない場合は、設定済みの endpoint に対してインラインの curl を使ってください（以下のスラッシュコマンドの厳守ブロックにある curl の代替手順を参照）。あくまで HTTP のみとし、コンテナーのシェルは使いません。
• 組み込みメモリを維持する：サーバー側のメモリは、エージェントの組み込みメモリを置き換えるのではなく、補完します。
• 依存関係を明示する：Bash ラッパーには Bash／curl／jq が必要です。記憶の保存／秘匿情報の削除には、さらに Python 3 が必要です。ネイティブ Python CLI は httpx／Typer／Rich を使用し、Bash／jq は不要です。references/search-contract.md を参照してください。
• 段階的に読み込む：初回セットアップ時に references/setup.md を読み、その後の日常的な使用にはこのファイルだけで十分です。
• 経路は2つあり、自動連携はありません：/ingest-memory/objects は LanceDB に書き込み（/search で提供）、/documents/text と /documents/upload は RAG-Anything のナレッジグラフに書き込みます（/query で提供）。一方の経路で取り込んだデータが、もう一方に自動で反映されることはありません。/search のスニペットと /query の合成結果の両方が必要な場合は、両方に書き込む必要があります。references/best-practices.md を参照してください。

動作規約

以下は、記憶を読み書きするときにエージェントが従うべき規約です。検索時の再現率を保ち、認証情報の漏えいを防ぎます。

1. 呼び出すタイミング

• セッション開始時に、これから行う作業が過去の決定事項に明らかに依存する場合。
• ユーザーが「before／last time／previously／上次／之前／我们之前怎么做的」のような表現に言及したとき。
• プロジェクトの履歴、過去の決定事項、繰り返し使う SOP に関する質問に答える前。

2. 記憶するタイミング

• 価値の高い結論（決定事項、教訓、SOP、事後分析、解決したバグの根本原因）に至った後。
• スプリントの完了、機能のリリース、インシデントの収束後。
• 一時的なコンテキストは決して記憶しません。ファイルの差分、デバッグトレース、生のツール出力、一時的な REPL 出力などが該当します。

3. タイトル＋トリガーワードのパターン

後で記憶を呼び出すエージェントは、元の ASCII ID ではなく、自然言語の曖昧な表現を使います。価値の高い記憶を書くときは、次のように構成してください。

1. 類義語を含むタイトル — 将来の検索者が入力しそうな動詞／名詞を2～3個以上含め、英語と作業言語を混在させます。
2. 「When to recall me」の行 — 動詞＋エンティティ＋想定される質問の表現を列挙します。
3. バイリンガルのタグ — 技術的な ID（deploy、auth）と自然言語の用語（部署、登录）を組み合わせます。

完全なテンプレートは references/best-practices.<lang>.md §7 を参照してください。曖昧な1つのエントリーポイントを軸に複数の記憶をまとめるインデックスカードのパターンについては、§8 を参照してください。

プライベートメモリに関する明示的なポリシー

ユーザーが、認証情報を含む元の内容を保持するために、自身のプライベートなデバイス間メモリエンドポイントを明示的に許可した場合、そのエンドポイント向けには内容を一字一句そのまま保持してください。黙って秘匿情報を削除したり、内容を変更したりしてはいけません。この許可は、他のテナント、無関係なエンドポイント、公開出力には適用されません。ラッパーによって秘匿情報の削除が強制される場合は、HTTP 取り込み API を直接使用してください。graphify は --private-verbatim に対応しています。設定済みの [privacy] preserve_sensitive = true は、エンドポイント所有者が明示的に定めたローカルポリシーです。結果の追跡可能性を保つため、ソースのパスとバージョンを記録してください。以下のデフォルトを適用する前に、ユーザーのローカルポリシーに従ってください。

4. 認証情報の自動マスキング

このスキルは、hooks/common.sh の redact_secrets() を介して、PostToolUse フックと Stop フックにより一般的なシークレットパターンを自動でマスキングします。別の方法（カスタムスクリプト、バッチインポーター、手動の curl）でプログラムからメモリを取り込む場合は、自分で redact_secrets() を呼び出すか、scripts/batch-ingest.py に --redact を渡してください。対象となるパターンは次のとおりです。

• API キー：sk-...、xoxb-...、xoxp-...、ghp_...、gho_...、 pk_live_...、sk_live_...、AKIA...
• Authorization: Bearer ... ヘッダー
• URL に埋め込まれた認証情報：scheme://user:password@host
• PEM 秘密鍵ブロック：-----BEGIN ... PRIVATE KEY-----
• JWT 形式の3セグメントトークン

メモリ構造のサンプル：

[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, 部署, 端口冲突

マスキングチェックリストの全容については、references/best-practices.<lang>.md §9 を参照してください。

5. タグ主導のセマンティックメモリ（人間が読みやすいタグとタイトルを採用し、Memory ID を不要にします）

メモリを記録する際は、Memory ID を手動で設計・管理する負担を完全になくしてください：

• ID の廃止（手動での 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. マルチノードの耐障害性とノードの帰属（単一／複数サービスノードへの自動対応とノードのトレース）

複数のサービスノードによる高可用性デプロイと、クライアント間でのノード分散協調に対応するため、このスキルは柔軟なフェイルオーバーとノード認識を全面的にサポートします：

• 単一／複数サービスノードへの自動対応（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 はスラッシュコマンドであり、単体のシェルバイナリではありません（厳守）

/tm は、SlashCommand ツールを介して実行する Claude Code のスラッシュコマンドです。 シェルバイナリではないため、スラッシュ付きの形式をシェルに渡すと必ず失敗します。

$ /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)

別途、オプションのシェル CLI である tm もあります（pipx install transcendence-memory-cli。サーバーリポジトリの cli-package/ から提供されます）。これは /tm スラッシュコマンドとは別のものであり、このスキルには同梱されていません。ユーザーが自分でインストールした場合にのみ存在します。存在すると決めつけてはいけません。また、/tm <cmd>（このセクションで説明するスラッシュコマンド）と、インストール済みの tm <cmd> バイナリを混同してはいけません。tm-codex バイナリはありません。AI は次のいずれかの方法のみを使用する必要があります（すべて純粋な HTTP 通信です。DB へのシェル接続は使用しません）。

1. 推奨 — 同梱のラッパースクリプト（Claude Code の内外を問わず、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 とヒアドキュメントを使用し、波括弧を単独で記述しません）。WAF に対応した User-Agent を追加し、*_PROXY を尊重して、失敗時は直接接続に自動でフォールバックします。また、初回呼び出し時に起動直後のバックエンドを遅延的に起動します。そのため、エージェントはオプションの tm CLI をインストールする必要がなく、（存在しない）tm-codex バイナリも必要ありません。（個別のウォームアップ手順は不要です。ウォームアップはスクリプト内で処理されます。）

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}"
   

Bash({command: "/tm ..."})（スラッシュコマンド形式をシェルに渡す）を実行しそうになったら、そこで停止し、上記のいずれかの方法に切り替えてください。長形式のエイリアスである /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、raw 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 フックが台帳を処理し、失敗時のみ警告を 1 行ユーザーに表示します。セッション中にユーザーがこのスキル（または 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	エンドポイント、api_key、コンテナーを手動で入力します	/tm connect --manual
status	接続状態とサーバーの稼働状況を確認します（設定済みのすべてのエンドポイントをプローブします）	/tm status
node	クライアント環境、ホストプラットフォーム、アクティブなエンドポイント、トポロジーを確認します	/tm node
search <query>	メモリをセマンティック検索します（-c <container>、--union／--no-union）	/tm search architecture decision from the last deployment
search --match <pattern> <query>	名前が <pattern> にあいまい一致するすべてのコンテナーを対象に検索します	/tm search --match my-project docker compose
search --all <query>	すべてのコンテナーを一度に検索します	/tm search --all release notes
remember <text>	メモリを1件すばやく保存します（--title t、--tags a,b、--node name／--no-node）	/tm remember Port conflicts caused the deployment failure
update <id> <text>	現在のコンテナーにある既存メモリのテキストを更新します	/tm update mem-001 New corrected content
embed	現在のコンテナーのインデックスを再構築します	/tm embed
query <question>	マルチモーダル RAG クエリを実行し、LLM が生成した回答を取得します	/tm query What is the overall project architecture?
upload <file>	ナレッジグラフにファイルをアップロードします	/tm upload ./design.pdf
containers [pattern]	コンテナーを一覧表示します。あいまいパターンで絞り込むこともできます	/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	バックグラウンドのナレッジグラフ構築ジョブを一覧表示します（保留中／失敗／完了）	/tm jobs
auto on	Git のコミット時にメモリを自動作成する機能を有効にします	/tm auto on
auto off	メモリの自動作成を無効にします	/tm auto off
auto status	メモリ自動作成の設定を表示します	/tm auto status
upgrade	上流リポジトリから最新のスキルスクリプトを取得します	/tm upgrade

運用／管理用 HTTP エンドポイント（サーバー v0.18、/tm の短縮形なし）

これらには /tm コマンドがありません — HTTP 経由で直接呼び出してください（すべて認証が必要です）。完全なリクエスト／レスポンススキーマは references/api-reference.md および references/commands.md にあります。

メソッド + パス	用途
GET /index-status · GET /containers/{name}/index-status	コンテナーごとのインデックス状態マシン（stale／indexing／ready／…）＋オブジェクト数＋埋め込み待ちの概要 — 統合する前に、関連コンテナーの埋め込みが実際に完了しているか確認できます
POST /embed-multimodal (multipart)	Gemini ネイティブのマルチモーダル埋め込みを使ってメディアファイル1件（画像／音声／動画）を埋め込みます → LanceDB のベクトル行1件となり、/search で検索できます。コンテナーのルーティング先が gemini_native プロファイルである必要があります
POST /containers/aliases · GET /containers/aliases · DELETE /containers/aliases/{alias}	コンテナー名のエイリアスルーティング（エイリアス → 正規名）を管理します。管理者のみ
GET /admin/usage/{summary,endpoints,containers,timeseries} · POST /admin/usage/cleanup	リクエスト使用状況の分析（呼び出し回数／レイテンシ／コンテナーごと／時間区分）＋保持データのクリーンアップ
GET /admin/ui · POST /admin/ui/{login,logout} · GET /admin/ui/me	Cookie セッション方式の管理ダッシュボード SPA（ブラウザー向け。エージェントが直接呼び出すことはほとんどありません）

ガバナンス／ドリーミング／オーケストレーションエージェントのエンドポイント（サーバー v0.20、/tm ショートカットなし）

セルフホスト可能な自律型メモリーガバナンスサブシステムです。すべてドライランを優先し、デフォルトで安全です。新規デプロイでデータが自動的に変更されることはありません。完全なリクエスト／レスポンススキーマは references/api-reference.md、コマンドのクイックリファレンスは references/commands.md、概要と安全性モデルは references/governance.md を参照してください。

メソッド＋パス	目的
GET /admin/config · PUT /admin/config	実行時設定センター — 既知の設定キーを列挙／一括書き込みします（ホットリロード）。機密キーの値は返されず、configured のみが返されます。ツール／ドリーミングのスケジュール／エージェントの制限を切り替える唯一の場所です
GET /admin/tools · POST /admin/tools/{tool}/invoke	ガバナンスツールボックス：6 つのプリセットツール（SAFE／LLM／破壊的・可逆）の一覧とコンテナごとの有効化マップです。ツールを 1 つ実行します（デフォルトは 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 のツール使用を調整するエージェント（TM_AGENT_ORCHESTRATION_ENABLED によるオプトイン方式で、デフォルトは OFF）。可逆ツールが適用されるのは、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 を、API 認証情報を含むリクエストには authenticated を使用してください。不明な URL へのプローブ数は、メモリー障害の証拠にはなりません。過去のリクエスト本文は取得できない場合があります。新しい記録には、詳細を秘匿した情報とリクエスト ID が含まれます。
• python3 scripts/tm-governance.py tools でツールボックスを調べられます。invoke <tool> はデフォルトでドライランを実行し、設定からコンテナを読み込みます。構造化パラメーターは --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）は fire-and-forget です。同期処理されるのは /search だけです。コールドスタート時には、読み取りパスの 200 であっても degraded body が含まれる可能性があります。必ず解析してください。

クロスプラットフォームでのインストール

リポジトリのチェックアウトとインストール済みスキルは分けてください。リポジトリで python3 scripts/install.py を実行します（PowerShell の場合は scripts/install.ps1）。完全なスキルツリーと既存のネイティブ CLI をインストールします。グローバルルールやネットワーク設定は編集しません。インストールの互換性を参照してください。

初回セットアップ

初回使用時は、references/setup.md を読み、設定を完了してください。

基本的な手順は 2 つだけです。

1. サーバーから接続トークンを取得します（/export-connection-token エンドポイント経由、または管理者から取得します）
2. /tm connect <token> を実行して、セットアップを自動的に完了します

または、/tm connect --manual を実行して、値を順に入力します。

接続を確認するには、bash scripts/tm-search.sh status を優先して使用してください（Claude / Gemini / Codex のいずれのエージェントでも実行できる Bash/curl/jq ヘルスチェックです。コールドスタートの兆候を検出するためにレスポンス本文を解析するので、degraded な 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） — ツールボックス／ドリーミング／オーケストレーションエージェント + dry-run を最初に行う安全モデル	references/governance.md	/admin/config · /admin/tools · /admin/dreaming/* · /admin/agent/* を操作するとき
アーキテクチャ（デュアルパスモデル、コンテナ分離、マルチ埋め込みルーティング）	references/ARCHITECTURE.md	内部での動作を理解するとき
トラブルシューティング（接続／401／403／検索結果なし／空のクエリ／コールドスタート／union degraded／WAF 403）	references/troubleshooting.md	問題が発生したとき
運用（一括取り込み、永続キュー、自動メモリ、プラットフォームサポート、マルチ埋め込みの運用）	references/OPERATIONS.md	大規模運用時
ベストプラクティス — 英語／中国語（2 パスモデル、専用コンテナ、デュアルトラック埋め込み）	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 にあります。一括 ingest／persistent queue／/jobs/{id} のポーリング／automatic memory／プラットフォームサポートについては 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	一方向の正規版→インストール先のミラー（ドリフト防止）。正規版のスキルを編集した後に実行	メンテナンス専用

以下のライフサイクルフックはプラグイン／リポジトリのルート（このスキルディレクトリの 1 つ上の階層にある ../../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 フック：git コミットの要約を保存するようエージェントに指示	プラグインのインストール時のみ — 自動登録されます
hooks/session-stop	Stop フック：セッションの要約メモリを自動保存	プラグインのインストール時のみ — 自動登録されます

ガバナンスサブシステム — サーバー側の環境変数スイッチ（v0.20）

v0.20 のガバナンスツールボックス／ドリーミング／オーケストレーションエージェントはサーバー側で設定します。大半の設定値はランタイム設定センター（config:dreaming:* / config:tools:* / config:agent:*）にあり、PUT /admin/config 経由でホットリロードされます。デフォルト値を含む一覧は references/governance.md §5 を参照してください。オーケストレーションエージェントには、マスター環境変数ゲートが 1 つあります。

• TM_AGENT_ORCHESTRATION_ENABLED — デフォルトは 0（OFF）です。OFF の場合、POST /admin/agent/{name}/invoke は status:"disabled" を返し、ジョブを登録しません。そのため、デフォルトのデプロイでは自律ループは実行されません。エージェントの実行を許可するには 1（サーバーの .env）を設定してください。
• 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 モデルを設定する場合 → これはサーバー側の対応事項であり、スキルで扱う必要はありません