設定のアップグレード

Engram は CLI と Entry Web UI で 1 つのアップグレードインベントリエンジンを共有します。設定されたワークスペースとグローバルのスコープをスキャンし、Engram 管理下のアーティファクトを分類して決定的なプランを作成し、ハッシュとフィンガープリントで古い内容による書き込みを防ぎます。

engram upgrade --latest --plan
engram upgrade --latest --review
engram upgrade --latest
engram upgrade --latest --yes
engram upgrade --help

--plan は読み取り専用です。人間向けの出力は、アーティファクトの種類ごとに Config、Instructions、Memories、Skillsets、Hooks、Plugins の順でグループ化されます。--plan --json は同じグループ化されたプラン、そのフィンガープリント、レビュー状態、pendingReviewCount を出力します。UI の種類タブは、All、Config、Instructions、Memories、Skillsets、Hooks、Plugins という正確なラベルを使用します。

Engram が検出するもの

インベントリは、既知の Engram の場所または登録済みの接続済みエージェントのインストールにある memory、instruction、skillset、config、hook、plugin のアーティファクトを対象とします。ワークスペースとグローバルのルートは個別にスキャンされ、Engram は任意のホームディレクトリツリーを再帰的にクロールしません。

Engram はまず明示的なスキーマ/バージョンのメタデータと登録済みインストールのメタデータを信頼します。マーカーのない従来のファイルは、既知の管理構造と期待される内容に基づいて判定されます。各項目は current、outdated、conflict、invalid のいずれかに分類されます。

型を考慮した置換とマージ

競合はレビューが必要という意味であり、永久にブロックされるわけではありません。Engram は、ユーザーが置換/マージの判断を確認するまでユーザーの編集内容を保持します。

• Instructions: Engram は Engram のマーカーの外側にあるユーザーのテキストを保持して、最新の管理ブロックを提案します。Engram が所有するファイル全体の instruction ファイルは置換できます。
• Skillsets: Engram は Engram 管理下の最新コンテンツを提案します。ユーザーが所有すると明示されたセクションは、形式が対応している場合に保持されます。
• Config: Engram は設定を解析してマージ済みの移行を提案します。既知の Engram キーはアップグレードされ、必要に応じて新しい既定値が追加され、関係のないユーザーのキーと値は保持されます。
• Memories: Engram はテンプレートの置換ではなく、スキーマ移行を実行します。
• Hooks/plugins: 生成されたアーティファクトは、所有権を証明できる場合に限って置換されます。所有者が曖昧なユーザーコードはレビューのみとなり、Keep current として確定できます。

Entry Web UI での競合レビュー

Updates ページはコンパクトなダッシュボードを使用します。ステータスバナーが設定が最新であるか、更新が必要か、競合レビューが必要かを示し、Workspace、Global、Conflicts のサマリーカードが重要な件数を一目で示します。プレビュー後、対応可能なすべての項目が、Artifact、Scope、Agent(s)、Status、Review、Actions の列を持つ 1 つの対応可能アーティファクトテーブルに表示されます。テーブルは狭い画面でも構造が崩れず、行ごとのスクロールバーの代わりに 1 つの共有された横スクロールのコンテナーを使用します。

engram entry を開き、Settings → Updates を選択します。サイドバーのコマンドのコピー操作では、画面を遷移することなく engram upgrade --latest --plan をコピーできます。プレビューには All と、対応可能な種類のタブだけ（Config、Instructions、Memories、Skillsets、Hooks、Plugins）があります。

すべての競合に Review アクションがあります。モーダルには Current、Proposed、Diff のビューがあります。Current は読み取り専用です。Proposed は置換可能な Config/Instruction/Skillset の項目で編集でき、Engram の型を考慮したマージ/置換結果から始まります。Diff は既定で Inline で、Parallel に切り替えられます。Inline では削除された行を赤い背景で -、追加された行を緑の背景で + として示し、Parallel では Current と Proposed の行を揃え、同じ赤/緑のハイライトを適用します。Use latest、Reset proposed、Keep current、または Engram が所有権を証明できる場合は Force upgrade を使用し、その後、Confirm change を選択します。

Open in editor は、サーバーが解決した正確な現在のアーティファクトを、$VISUAL、次に $EDITOR、それでもなければプラットフォームのフォールバックで開きます。ブラウザーがファイルシステムのパスを渡すことはありません。Instructions では、Proposed には管理対象の <!-- engram:start --> ブロックだけが含まれ、グローバル skillset の全体は付属の .agents/engram.md ガイドに残ります。外部での編集によってファイルが変更されると、プレビュー/ソースのハッシュが古くなり、確定する前にレビューを更新する必要があります。

置換可能でレビュー待ちの対象の競合には選択用のチェックボックスがあります。Select all visible は、アクティブな種類タブ内の対象行を選択し、選択状態はタブを切り替えても維持されます。Confirm selected changes はチェックした行に対して Use latest を承認し、Confirm all changes はプレビュー全体の対象となるすべてのレビュー待ち競合に対して Use latest を承認します。置換できない行、古くなった行、すでにレビュー済みの行は選択できません。サーバーは、バッチ全体をプレビューのフィンガープリント、現在のソースハッシュ、レビュー状態、生成された提案に照らして検証してから、レビューストアへ 1 回のアトミックな書き込みを行います。選択した項目のいずれかが検証に失敗すると、バッチの決定は 1 件も保存されません。

Entry はアップグレードのレビュー全体で同じカスタムチェックボックスを使用し、チェック済み、キーボードフォーカス、無効の各状態をはっきり区別できるようにしています。結果のトーストは、成功時に緑の枠とグロー、エラー時に赤の枠とグローを使用します。

ページにはレビューの進捗が表示されます。最終の Upgrade アクションは、すべての競合が、最新の承認、編集済みの提案、Force upgrade、Keep current のいずれかとして明示的に解決されるまで無効のままです。最終確認では、自動更新、承認された提案、編集された提案、強制置換、現状維持としたファイル、バックアップが要約されます。

所有権を考慮した Force upgrade

Engram は接続済みエージェントのアップグレードインベントリを物理ファイル単位で正規化するため、.agents/engram.md のような共有ガイドは、Codex、Claude、Gemini、または他の登録済みホストが指していても 1 つだけ表現されます。ホストの一覧はメタデータとして引き続き表示されますが、物理ファイル 1 つにつきレンダラーの正規出力と書き込みトランザクションはそれぞれ 1 つだけです。

Force upgrade は意図的に Use latest よりも限定的です。Engram が所有権の境界を証明できる場合に限って表示されます。

• 管理対象の領域: Engram はマーカー付きの Engram ブロックだけを置換し、その外側にあるユーザーが記述したすべてのバイトを、ファイルの CRLF/LF という改行スタイルも含めて保持します。
• 生成ファイル: Engram は、登録済み/生成された Engram ファイル全体を、その Engram 所有のファイル内の手動編集も含めて置換することがあります。
• 所有権不明: Force upgrade のアクションは表示されません。Keep current を使うか、先に所有権の曖昧さを解消してください。

一括操作では強制は行いません。Confirm selected changes と Confirm all changes は、安全な Use latest の判断のみに限定されます。強制の判断は 1 項目ずつレビューされ、プレビュー後にソースハッシュ、所有権の証拠、または強制モードが変更された場合は拒否されます。

書き込みが完了すると、Engram はアップグレードされた物理アーティファクトを再スキャンします。更新が期待される項目は current に収束しなければならず、トランザクションの失敗またはロールバック、あるいは outdated/conflict のまま残る項目がある場合、適用全体が成功のトーストではなくエラーとして報告されます。明示的な Keep current の項目は、この収束の要件から除外されます。

CLI での競合レビュー

次を実行します。

engram upgrade --latest --review

対話型のレビュアーは、未解決の競合を 1 件ずつ処理します。

[V] View diff
[E] Edit proposed content
[L] Accept latest proposal
[K] Keep current
[Q] Save and quit

E は、$VISUAL、次に $EDITOR、それでもなければプラットフォームのフォールバックを使って一時的な提案ファイルを開きます。Engram は編集された提案を受け入れる前に検証します。決定内容はプランのフィンガープリントごとに Engram の状態領域へ保存されるため、Q でセッションを中断しても、後で --review を実行すると保存済みの決定から再開されます。

自動化の場合は次のとおりです。

engram upgrade --latest --yes

--yes は競合の判断を勝手に作成することはありません。未解決または古くなった競合が 1 件でも残っている場合、Engram はゼロ以外の終了コードで終了し、engram upgrade --latest --review の実行を促します。

古いレビューの保護

レビューした各項目は、そのソースハッシュ（source hash）を記録します。適用する前に、Engram は現在のソースハッシュとレビュー時のソースハッシュを比較します。レビュー後にファイルが変更された場合、その判断は古い/レビュー待ちになり、再度レビューする必要があります。プランのフィンガープリントにより、レビューしたものとは異なるインベントリを適用することも防げます。

トランザクショングループ、バックアップ、ロールバック

承認された置換とマージは、安全な自動アップグレードと同じトランザクション経路を使用します。Engram は元のバイトとパーミッションを取得し、必要に応じてバックアップを作成し、提案内容を検証し、一時ファイル経由で書き込み、アトミックにリネームして所定の位置へ配置します。永続的な変換に失敗した場合は、そのトランザクショングループがロールバックされます。Keep current は書き込みを一切行いません。

ベクトルインデックスはフェイルオープン

ベクトル検索はオプションの高速化レイヤーです。Engram は sqlite-vec の memory_vectors のプライマリキーを、整数互換の BigInt 値でバインドします。ベクトルの再構築に失敗した場合、Engram は不完全なベクトルのサイドカー/WAL/SHM を削除し、縮退警告を報告して、永続的な字句/グラフのアップグレードを継続します。ベクトルだけの失敗が、それ以外は有効な設定アップグレードを中断させることはありません。

パッケージバージョンと設定状態の違い

新しい npm パッケージと古いローカル設定は別々のシグナルです。推奨されるリリースの手順は次のとおりです。

npm install -g @the-long-ride/engram@latest
engram upgrade --latest --plan
engram upgrade --latest --review
engram upgrade --latest

アップグレードの再実行は、最新のアーティファクトに対して冕等です。レビュー済みの Keep current ファイルは、状態が変わって新たなレビューが必要にならない限り、そのまま維持されます。