メモリとナレッジ

メモリの役割

メモリがなければ、エージェントとの会話は毎回ゼロから始まります。同じ規約をまた説明し直し、同じ意思決定をまた議論し、同じ行き止まりをまた探索することになります。メモリは実行をまたいで生き残るワークスペース単位のストアであり、あるエージェントが生み出したナレッジを、後から別のエージェントが見つけられるようにするために存在します。

メモリには 3 つの層があり、それぞれ異なる問いに答えます。

事実 — 何が真か（規約、結果、意思決定）。
ポリシー — それに対してエージェントが何をすべきか（規範的なルール）。
ワーキングメモリ — あるエージェントが何の途中だったか。

この区別が重要なのは、それぞれが異なる経路でエージェントに届くからです。事実は検索されます。ポリシーはプッシュされます。ワーキングメモリは非公開です。

事実

MemoryFact は、ワークスペースとドメインにスコープされたナレッジの単位です。

属性	内容
`domain`	ナレッジのドメイン（“conventions”、“decisions”、“codebase”）
`topic`	短いトピックラベル
`content`	ナレッジの本文
`confidence`	0.0～1.0。来歴から初期化され、再言及によって上がる
`memoryType`	事実の種類。時間減衰の曲線を左右する
`veracity`	どう知られるに至ったか。confidence を初期化し、再言及ごとの上昇幅を決める
`sourceObservationIds`	どの観測がその事実を導いたか
`supersededBy`	それを置き換えた新しい事実（存在する場合）
`validUntil`、`recallCount`、`mentionCount`	リコール時に使われる有効期限と利用のシグナル

最後の 2 行は見落とされがちですが、_どの_事実が表に出るかを決めるのはこの 2 行です。memoryType は型ごとの Weibull 減衰パラメーターを持ち、期限付きのコミットメントは素早く薄れる一方、安定したプロファイルの事実は薄れません。veracity は来歴を記録します。人間が述べたもの（重み 1.0）、エージェントが推論したもの（0.7）、ツールが生成したもの（0.5）、インポートされたもの（0.6）で、その重みが事実の初期 confidence を決めます。

事実は矛盾したときでもその場で編集されることはありません。事実を書き込むと、同一ドメイン・同一トピックの事実に対して競合検出が実行され、敗れた側を置き換えて競合の行を記録します。狙いは監査証跡です。以前に何が信じられていたか、そして何がそれを置き換えたかを、いつでも確認できます。

ポリシー

MemoryPolicy は事実から導かれる規範的なルールで、ワークスペースとドメインにスコープされ、アクティブフラグと任意の requiredRole を持ちます。

ワークスペース内のすべてのアクティブなポリシーが、あらゆるディスパッチにフィルタリングなしで注入されます。ドメイン、ロール、タスク、スペースによる絞り込みはありません。20 個目のポリシーを書く前にこれを知っておく価値があります。ポリシーはタスクと同じコンテキストウィンドウを奪い合うからです。ポリシーの requiredRole が助言的な意味しか持たないのも同じ理由です。それはそのルールが誰に向けられたかを示すだけで、ルールがほかの全員に届くのを止めるものではありません。

ドメイン

MemoryDomain はワークスペース内で事実とポリシーをまとめます。ドメインはナレッジに組織的な構造を与え、アクセスグラントを書く対象となる単位です。ただし、ドメインを機密性の境界として扱う前に、以下の注意を参照してください。

ドメインはワークスペース全体（architecture）か、1 つのリポジトリ（repo:<slug>/architecture）のどちらかにスコープされます。両方のスコープで同じ名前を使っても、それは 2 つの独立したストアです。あるコードベースについて真である事実が、ワークスペース全体のものを上書きすることはありません。エージェントがそのリポジトリで作業しているとき、search_memory とディスパッチのプリアンブルはリポジトリスコープのメモリを優先して順位付けしますが、残りを除外するわけではありません。そのスコープに書き込む、あるいはブーストするには、propose_fact / propose_policy / search_memory に repo を渡します。

アクセス制御は読み取りについてフェイルオープン

MemoryAccessGrant は、エージェントのロールとドメインを 3 つの権限レベルのいずれかに対応付けます。

権限	意味
`none`	アクセスなし
`read`	事実を検索して取得できる
`write`	`propose_policy` で必要。事実の書き込み（`propose_fact`、`supersede_fact`）はグラントの制限を受けない

(role, domain) のペアに対するグラントの行が存在しない場合、実効権限は read になります。読み取りは設計上フェイルオープンです。例外を投げる唯一の書き込みは、write 権限なしの propose_policy です（InsufficientMemoryPermission）。機密性の高い内容をメモリドメインに置いても、それを見るべきでないすべてのロールに対して明示的に none グラントを書かない限り、誰が読めるかは制限されません。

また、現時点で製品のどこにもグラント用の UI はありません。メモリ画面には事実、ポリシー、ナレッジグラフのタブしかなく、グラントに到達できるのは memory_access_grant.* の RPC オペレーション経由だけです。

この非対称性（読み取りには緩く、ポリシーの書き込みには厳しい）は意図的なトレードオフです。メモリは循環してこそ最も役立ち、読み取りの拒否は、問題を報告するエージェントではなく、黙って知っていることが減ったエージェントを生みます。対照的に、ポリシー書き込みの拒否は目立って気づけるので、強制はそちらに置かれています。新しく作成されたドメインはすべてのロールに write をシードします。後からそれを厳しくするのは RPC 経由の編集だけです。グラントの UI が存在しないからです。

ワーキングメモリ

各エージェントは AgentWorkingMemory を持ちます。ワークスペースとエージェントをキーとする自由記述のスクラッチパッドです。これは実行をまたいで永続し、そのエージェントだけのもので、ディスパッチのたびにプロンプトへ注入されます。「認証のリファクタリングの途中だった」という状態が住む場所であり、次の実行へ持ち越す価値はあるものの、永続的な事実へ昇格させる価値はない状態です。

実際にエージェントのプロンプトに届くもの

ディスパッチ時に、メモリのプリアンブルはちょうど 3 つから組み立てられます。

ワークスペースのアクティブなポリシーすべて。- [domain] rule 行として。
エージェント自身のワーキングメモリ。逐語的に。
このタスクにキーワードでマッチした事実の候補リスト。最大 5 件で、約 1,200 文字の予算内、かつタスクの説明が 20 文字以上の場合に限られます。それより短いタスクには事実がまったく与えられません。

候補リストは FTS／キーワードのみで、上限は意図的です。クエリの埋め込みは遅く、ディスパッチ経路はレイテンシが即座に見える唯一の場所なので、遅いセマンティック経路は意図的にそこから外されています。プリアンブルは、重要な項目を search_memory で検証するようエージェントに伝えて締めくくられます。完全なリコールモデルはそこにあります。

この経路ではアクセスグラントは参照されません。候補リストが見つけたものだけが、エージェントの目に入ります。

リコール: 1 つのクエリ、4 つの声

エージェント向けの search_memory ツールには 3 つのモードがあり、それらは本当に異なる検索です。

keyword — FTS5 のみ。
semantic — BM25 とベクトルの結果を相互ランク融合で統合。
hybrid（既定） — ポリフォニックリコール。4 つの順位付きの声を統合し、その後で多様化します。

4 つの声とは、字句（FTS）、セマンティック（ベクトル KNN）、時間（最近のアクティブな事実）、グラフです。グラフは、最も強い字句とセマンティックのシードから、エピソードエッジをたどる 2 ホップの探索です。グラフの声こそがエピソードエッジの存在理由です。あなたのどの言葉にもマッチせずに、あなたの答えに_つながっている_事実を表に出します。それぞれの声は分類されたクエリ意図によって重み付けされ（既定ではセマンティックが最も重く、次にグラフと字句、その次に新しさ）、各候補のスコアは Weibull 減衰でスケーリングされ、結果セットは MMR で多様化されるため、1 つの事実の 5 通りの言い換えが 4 つの異なる事実を押しのけることはありません。

デスクトップとウェブのメモリ検索は、別のより単純な経路です。memory_fact.search の RPC オペレーションは FTS5 のみです。シンクライアントはクエリの埋め込みを送れず、ハイブリッド経路はホスト内に留まるからです。したがって、メモリブラウザーで目にする順位は、エージェントが search_memory から得る順位とは異なります。これは想定どおりでバグではありませんが、UI で「検索したが見つからなかった」ことは、エージェントも見つけられない証拠にはならない、ということは意味します。

メモリがどこにあり、誰が書くのか

メモリブラウザーは 設定 → ワークスペース → メモリ（/workspaces/<id>/settings/memory）にあり、事実、ポリシー、ナレッジグラフのタブがあります。

そこには人を驚かせる非対称性があります。メモリは編集も削除もできますが、作成はできません。 事実タブにもポリシータブにも追加の手段はありません。作成はエージェント側で、propose_fact と propose_policy を通じて行います（置き換えには supersede_fact / supersede_policy）。remember はセッションに閉じたホット層の項目を書き込み、それを consolidate_memory が後から事実へ昇格させることがあります。record_observation と update_my_notes は、ディスパッチ時に注入される非公開のスクラッチパッドを書きます。ブラウザーはレビューと修正のサーフェスであり、作成のサーフェスではありません。ですから、メモリに事実を入れたいなら、それを入れる方法はエージェントに伝えることです。

2 つのメンテナンス操作も同様に、スケジュールではなくエージェントが呼び出します。consolidate_memory は蓄積された事実をマージして刈り込み、harmonize_memory はエージェント間で食い違った信念を調停します。list_memory_conflicts は競合検出がすでに記録した内容を表示します。これらをタイマーで実行してくれるものはありません。ミーティングの決定は、ミーティングの永続化ステップがそれらを記録するときに decisions ドメインへ取り込まれます。それは完了したエージェント実行に対するタイマーではありません。