エージェントメモリ

AIはコードや会話を読むのは得意ですが、セッションが終わると「このワークベンチで何ができるか」を忘れます。 そのため、一度成功させた作業（デプロイ・ビルド・DB接続）を、次のセッションでは「資格情報がないからできない」と再び誤判断してしまいます。

エージェントメモリは、AIが検証した事実を完全一致のドロワーに保存し、次のセッションで自動的に取り出して使えるようにします。RAG（意味的な近似検索）と競合せず、役割を分担します — 事実の判断はドロワー、近似的な探索はライブラリ。

なぜ必要か — 実際の事故から出発する

BlyckのデプロイはこのPCで直接実行可能でした（aws CLI が構成済み、直接デプロイした履歴あり）し、手順もドキュメント化されていました。それにもかかわらず、エージェントは毎セッション「資格情報がないからデプロイできない」と繰り返し誤判断しました。原因は、コードのコメントだけを見て「別ステップが必要 = 自分にはできない」と推論したことです。

診断してみると、弱い環は想起ではなく保存でした。

段階	状態	根拠
想起（recall）	正常	保存されてさえいれば、確実に読み出されていたはず
保存（capture）	失敗	「このPCでデプロイ可能」が一度も永続保存されたことがない

つまり、記憶できないのではなく、記憶すべき項目そのものを作っていなかったのです。行動（s3 cp 1回）は揮発的に見えますが、それが証明する能力（「デプロイ可能」）は永続・再利用可能な事実です。この区別の失敗が盲点でした。

核心原則

メモリはRAGのスープに入れない。 事実・能力の記憶は、意味的な近似検索ではなく完全一致で取り出します。
保存は自覚に依存しない。 成功した行動を自動的に能力候補へ昇格させます（ただし承認ゲートあり）。
想起は自動注入する。 関連する記憶は、呼び出しなしでコンテキストに入ります。
できないと断定する前に検証。 「できない」と言う前に、メモリ照会＋安価なプローブで確認します。

たとえ — ライブラリと机の引き出し

📚 ライブラリ検索（RAG）: コード・会話・ログをすべて溜め込んで「似たものを探す」。量が多く近似なのでガベージが混ざります。→「以前似たコードがどこにあったか?」用。
🗂️ 机の上のメモ引き出し（メモリ）: 検証済みの核心的な事実をいくつかだけ整然と。正確で、常に見えています。→「このPCでデプロイ可能」「PROD DB に触れるな」用。

RAGとメモリは競合ではなく分担です。事実の判断はドロワー（第一優先）、近似的な探索はライブラリ（補助）。

型付き完全一致ドロワー

記憶は workspace.sqlite の専用テーブルに型付きレコードとして保存されます。

フィールド	説明
`type`	`capability` · `decision` · `rule` · `procedure` · `fact`
`scope`	`workspace`（デフォルト） · `global`
`key`	完全一致の識別子（例: `deploy:blyck`）
`body`	人が読む事実の本文
`confidence`	0〜1（検証済み=1.0）
`proof`	根拠（例: 「aws sts 通過; s3 cp 成功」）
`status`	`active` · `stale` · `retired`

保存（capture） — 弱い環を三重に

方式	トリガー	ガベージ遮断
明示的	`memory_write(key, body, type, scope)` MCPツール	意図的な呼び出しのみ
自動昇格	成功イベント（デプロイ・ビルド・認証・DB接続）をアクティビティログから検知 → 候補生成	承認ゲート
リフレクションパス	チャット終了/マイルストーン時にセッション要約 →「学んだ永続的な事実?」候補抽出	承認ゲート

3つの経路すべて、承認後にのみドロワーへ入るため、RAG式の自動吸引ノイズがありません。

自動昇格分類器が能力候補へ上げる成功イベントの例:

外部認証/デプロイ成功（aws … 成功、gh auth、deploy/publish） → capability
ビルド/パッケージング成功（npm run dist、テスト通過） → capability/procedure
DB/SSH接続成功（資格情報の検証） → capability
ユーザーが命令形で与えたルール（「PROD に触るな」） → rule
あまりに些細または一回限り（単純なファイル読み取りなど）は除外 — 承認疲れを防止

想起（recall） — 自動注入

毎ターン、コンテキストを組み立てる際にメモリ回収ステップが割り込みます。

現在のクエリ・アクティブパネル・プロジェクトで key 完全一致＋軽い意味的マッチング。
上位 k 件の active な記憶をシステムプロンプトに自動注入（別途の呼び出し不要）。
recency・importance 加重＋decay → 長く使われない記憶は stale→retired。

AIツール（MCP）

ツール	権限	役割
`memory_write(key, body, type, scope)`	確認	事実をドロワーに明示保存（同じ key を上書き）
`memory_read(key?/query?)`	読み取り（自動）	key 完全一致または軽い意味的マッチングで記憶を照会

ほとんどの想起は自動注入で処理されるため、memory_read を逐一呼び出す必要はありません。自動注入が取りこぼした項目を補強照会するときに使います。

decay と整理

ドロワーが肥大化しないよう、last_seen を基準に長く使われない記憶を整理します。

capability · rule · procedure は自動消滅を免除 — 上記§の事故再発防止が目的です。一度検証された能力は、使われなくても消えません。
decision · fact のみ 90日→stale、180日→retired。
明示照会時に stale→active へ復活。

全体の流れ — 本日の事例

[保存] 初回デプロイ成功 → アクティビティログ "s3 cp blyck-releases 成功"
   → 昇格分類器が検知 → 候補 {capability, key:"deploy:blyck",
      body:"このPCで直接デプロイ可能: npm run dist → s3 cp → cloudfront invalidate",
      proof:"aws sts 通過; s3 cp 成功"} → [承認] → ドロワーに刻まれる

[想起] 次のセッション "デプロイして" → コンテキスト組立が "deploy:blyck" を自動注入
   → "資格情報なし" という推論自体が不可能 → 事故再発 0

Claude のファイルメモリとの関係

この機能は、Claude Code のファイルメモリ（MEMORY.md + *.md、毎セッション自動ロード）の正確・自動想起をそのまま借用しつつ、その弱点を補完します。

項目	Claude ファイルメモリ	Blyck 定着ドロワー
保存場所	マークダウンファイル	workspace.sqlite テーブル
保存トリガー	エージェントの判断（手動）	手動 + 行動の自動昇格 + リフレクションパス
自動保存	✗	✓（成功イベント昇格）
ガベージ	少ない	ほぼ0（UNIQUE key + 承認）
重複防止	人がインデックス管理	`UNIQUE(scope, key)` 自動
decay/整理	手動	`last_seen` ベースの stale/retire
ドメイン認識	汎用	Blyck アクティビティ（デプロイ・DB・SSH）特化

決定的な違いは自動保存です。 上記の事故は、Claude のファイルメモリが有効な状態で起きました — 想起は正常で、弱い環は「保存が判断依存」という点でした。Blyck にはアクティビティログという行動の記録があるため、成功イベントを能力候補へ自動昇格でき、これがファイルメモリだけでは構造的に不可能な部分です。

セキュリティ

クロスチャットの記憶は既定で scope=workspace + 機微情報フィルタにより、グローバルセッションの非移転・読み取り専用原則と衝突しません。
シークレットはメモリ本文に保存しません（OS暗号化ストレージ + 自動マスキングは別経路）。

FAQ

Q. RAGがあるのに、なぜメモリがさらに必要なのですか? → RAGは意味的近似なので、事実の判断にガベージが混ざります。「このPCでデプロイ可能」のような検証済みの事実は、完全一致のドロワーから 1:1 で取り出してこそ安全です。両者は分担します。

Q. 私が逐一「覚えて」と言わなければなりませんか? → いいえ。memory_write で明示保存もできますが、成功イベントは自動昇格候補として浮上し、承認するだけで済みます。チャット終了時にはリフレクションパスがルールも自動抽出します。

Q. 誤って保存された記憶がずっと付きまといませんか? → 同じ key は上書きされ、decision/fact は decay で整理されます。誤った能力記憶は memory_write で更新するか retire すればよいです。

Q. 検証された能力が使われずに消えたら、また事故が起きませんか? → そのため capability・rule・procedure は自動消滅を免除しています。一度検証された能力は、使われなくてもドロワーに残ります。