agent-memory

agent-memory

AI コーディングエージェント向けのローカルな、Git ネイティブなプロジェクトメモリです。MCP 呼び出しを 1 回行うと、構造化されたメモリ更新が返されます。現在のタスクの状態、決定事項、規約、落とし穴、モジュールごとの情報を記録できます。ブランチを認識します。シークレットを安全に扱います。バイト列を保持します。クラウドもベクトル DB も不要です。Markdown が信頼できる情報源であり、同期には Git を使います。3 つの MCP ツールと、フル機能の CLI を備えています。

他との違いは、メモリがリポジトリにコミットされたプレーンな Markdownであり、読み取ったり git diff で差分を確認したりできることです。永続的な変更は黙って反映されず、ステージして人がレビューします（review --diff → apply）。また、書き込む前にシークレットや個人情報（PII）をスキャンして除外します。今後の方向性（システムレベル／複数リポジトリのメモリ）については、ROADMAP.md をご覧ください。

デモ

エージェントが永続的な決定事項を記録してステージし、あなたが正確な差分を確認して適用すると、後の fetch でその内容が表示されます。ローカルで、Git ネイティブで、レビュー可能で、シークレットを安全に扱います。この動画は再現可能です。実行可能な手順は docs/demo/demo.sh にあり、docs/demo/demo.tape で vhs を使って GIF を生成できます。docs/demo/ をご覧ください。

比較

機能	AGENTS.md / CLAUDE.md	ベンダーのメモリ（例：Claude）	ベクトル／DB メモリ（mem0、Zep）	agent-memory
プレーンテキストで、Git でバージョン管理された信頼できる情報源	✓ フラットファイル	✗ ベンダー管理	✗ DB／クラウド	✓ リポジトリ内の Markdown
構造化されたセクション単位の更新	✗	✗	~	✓
人によるレビューゲート（先に差分を確認）	✗ 自由に編集	✗	✗	✓ ステージ → review --diff → 適用
ベンダーに依存しない（MCP — あらゆるエージェントに対応）	~ 広く使われる規約	✗ 1 つのベンダー	~ さまざま	✓ Claude · Cursor · Codex · Gemini
書き込み時のシークレット／個人情報（PII）スキャン	✗	✗	~ さまざま	✓
同時編集時のチームでのマージ	✗ テキストの競合	✗	✗	✓ セクションマージドライバー
完全にローカルで動作（クラウド不要）	✓	✗	~ さまざま	✓
Verifiable Task Protocol（VTP-1）と Machine Receipts	✗	✗	✗	✓ 5 フェーズの暗号ライフサイクル + Clause B の分離された席

これらは一般的な特徴を示したものであり、ツールは急速に進化しています。誤りを見つけた場合は、イシューを作成してください。該当箇所を修正します。agent-memory は、AGENTS.md／CLAUDE.md のような指示ファイルを補完するものです（指示ファイルのインストール機能もあります）。指示ファイルがどのように振る舞うかを定めるのに対し、agent-memory はその背後にある、永続的で、検索可能で、レビュー済みの知識を扱います。

ステータス

Release 0.6.1 — Swarm Audit Hardening & Metamorphic Rebase リリースです。 永続的なメモリと検証可能な自律実行を結び付け、フェイルクローズの厳格なセキュリティ不変条件を適用します。

• Astra Pro Audit Hardening (AM-001..AM-008) — カテゴリに基づく承認ルーティング（DecideRoutingWithCategory）、 ファイル全体の変更前状態 CAS（proposal.PreHashes）、Jaccard 重複排除における極性／否定修飾語の保持（criticalQualifiers）、 冪等な純粋読み取り専用の fetch_context、および正規の3ウェイマージ削除セマンティクスです。
• Metamorphic Rebase & Drift Detection (internal/memory/rebase.go) — リベース中にファイル全体の変更前ハッシュのドリフトを検出し、 隣接セクションが並行して編集された際の暗黙の上書きを防ぎます。メタモルフィックな合成テストで検証されています。
• Control-Plane Manifest Isolation — .agent-memory/meta/manifest.yaml に対する直接変更、シンボリックリンクによる回避、パストラバーサル攻撃をフェイルクローズで防止します。
• RFC 8785 (JCS) Determinism (internal/vtp) — 厳密な JSON Canonicalization Scheme への準拠。 RFC 8785 Appendix B の公式テストベクトル26件すべてに合格し、ECMAScript の浮動小数点数フォーマット（1e+21）、 単独サロゲートの拒否、再帰的な UTF-8 検証に対応しています。
• Fail-Closed Cross-Process SQLite NonceStore (internal/memory/nonce.go) — withDB パターンを使用した永続的な リポジトリスコープのストアにより、Windows のファイル記述子ロックを解消し、 ドリフトのないアトミックな検証と期限切れ nonce の自動掃除を実現します。
• Two-Phase Staging & Compound Rollback (internal/memory/staging.go) — 厳格なパストラバーサルのサニタイズ （ValidateStagingID、agentfs.ValidateMemoryPath）、シンボリックリンクの封じ込め、複数ファイルのアトミックなロールバックを実装し、 一部失敗時には RollbackIncomplete の複合エラーを報告します。
• VTP-1 Strict Assertion Identification & Dual-Oracle Settlement (internal/vtp) — 宣言されたアサーション ID と一致する識別可能な AssertionResults の必須化、検証者キーのバインディング検証、Workpool/0 Clause B における異なる席の適用です。

0.6.0（装飾的でない SAR-008 のグラウンディング nonce、SAR-007 のバイト保持）、0.5.4（VTP-1 初期プロトコルエンジン）、 0.5.0（フェデレーション、参照されるランドスケープストア）、0.4（セクションマージドライバー）を基盤としています。

変更点の全一覧は CHANGELOG.md をご覧ください。

ドキュメント	目的
ROADMAP.md	プロジェクトの今後の方向性、原則、対象外の事項です。
CHANGELOG.md	リリースごとの機能一覧と既知の制限事項です。
Design Doc v0.4.1	このバイナリが実装する正式な設計です。
Implementation Plan	MVP の過去のビルド記録（M0–M8）です。今後の予定は ROADMAP をご覧ください。
Retrieval eval	fetch のオフライン再現率／MRR／nDCG ベンチマーク（手法と数値）です。
Patterns	サブシステムごとに文書化された再利用可能な設計パターンです。
Spikes	M1 前のスパイクの成果（バイト保持エンジン、MCP SDK、flock、FTS5）です。

クイックスタート

インストール — ビルド済みバイナリをダウンロード（推奨）：お使いの OS／アーキテクチャ向けのアーカイブを最新リリースからダウンロードして展開し、agent-memory を PATH に追加します。ツールチェーンは不要です。

# npx (no Go, no manual download): fetches the verified release binary on
# first run and caches it — also usable straight from an MCP client config.
npx -y @xchucx/agent-memory --help

# Go toolchain alternative (Go 1.25+)
go install github.com/xChuCx/agent-memory/cmd/agent-memory@latest

# from source
go build -o agent-memory ./cmd/agent-memory

Homebrew、Scoop、winget のパッケージは今後提供予定です。agent-memory はMCP Registryにも掲載されています。

メモリを持たせたいリポジトリ内で、次の操作を行います。

# Scaffold .agent-memory/ in a repo
agent-memory init --name my-project

# Install the Claude Code skill + register the project MCP server
# (writes .claude/skills/agent-memory/SKILL.md and merges .mcp.json)
agent-memory install claude

# Verify (prints the release tag, the go-install version, or dev+vcs locally)
agent-memory version

# Read context
agent-memory fetch                # bootstrap pack
agent-memory fetch "auth"         # FTS query

# Start MCP server (your agent spawns this automatically once configured)
agent-memory mcp

install claude は MCP サーバーを登録します。リポジトリのルートに、agent-memory mcp --root ${CLAUDE_PROJECT_DIR:-.} を実行するプロジェクトスコープの .mcp.json をマージします。Claude Code は起動時に CLAUDE_PROJECT_DIR をリポジトリのパスに展開するため、サーバーは常にこのリポジトリを対象とします。設定はクローン間で共有でき、Claude Code のスコープ優先順位（ローカル > プロジェクト > ユーザー）に従って、誤ったユーザースコープのサーバーがあっても上書きされます。チームで共有できるよう、.mcp.json をコミットしてください。

⚠️ ユーザースコープで、ルートをハードコードした単一のサーバーを登録しないでください（claude mcp add -s user agent-memory -- agent-memory mcp --root /some/repo）： すべてのプロジェクトがその1つのリポジトリを対象にするため、プロジェクト B で書き込んだメモリが、気づかないうちにプロジェクト A に保存されます。プロジェクトごとの登録（install が書き込む方法）が正しい運用です。agent-memory doctor は、誤ったルートを指す登録に警告を出します。

サーバーは --root、次に $CLAUDE_PROJECT_DIR、最後に作業ディレクトリの順にリポジトリを解決します。その他のランタイム（Cursor、Gemini CLI、AGENTS.md を読み取るものなど）でも同じサーバーを使用できます。各ランタイムのアダプターをインストールしてください（以下を参照）。

既存プロジェクトに導入する

init は空のメモリを作成します。実際のコードベースからメモリを作成するには、コーディングエージェントに分析させます。それがこの仕組みの目的です。init と install <adapter> を実行し、（上記のとおり）MCP サーバーを登録したら、memory.* ツールを読み込ませるためにエージェントを再起動し、以下のプロンプトを貼り付けます。

処理の流れ：エージェントがリポジトリを読み込み、memory.propose_update を呼び出します。作業メモと注意点は直ちに反映されます。永続カテゴリ（規約、決定事項、モジュール）はレビュー用にステージングされます。各項目を agent-memory review --diff で確認し、agent-memory apply（または reject）で反映してください。承認なしに永続データが書き込まれることはありません。

You now have agent-memory MCP tools (memory.fetch_context,
memory.propose_update, memory.status) backed by this repository's
.agent-memory/ store. Bootstrap the project's memory from the codebase.

1. Call memory.fetch_context with an empty query to see the current
   (mostly empty) state and the conventions/decisions/pitfalls/modules
   layout.

2. Analyze THIS repository — read the build files, CI config, entry
   points, and the main packages/modules. Identify:
   - build / test / run / lint commands and the toolchain;
   - conventions: code style, branching, commit rules, review practices;
   - architecture: the major modules/components and what each is for;
   - durable decisions: notable choices and WHY (only ones that are real
     and stable — not speculation);
   - pitfalls: footguns, sharp edges, "don't do X because Y" you can infer
     from the code, tests, or docs.

3. Persist what you found via memory.propose_update, choosing the intent
   per kind:
   - update_conventions  → conventions.md (build/test/style/workflow)
   - refresh_module      → modules/<name>.md (one per major component)
   - record_decision     → decisions.md (Date / Status / Confidence +
                           sources; type ∈ file|test|user, NOT external)
   - add_pitfall         → pitfalls.md
   - update_shared       → local/current.shared.md (a short "current
                           state / where things stand" summary)

Rules:
- Cite provenance: pass sources as file references you actually read
  (e.g. {"type":"file","ref":"internal/auth/session.go"}). Use
  confidence=confirmed for facts from code, inferred for deductions.
- Every section needs a unique "" anchor; keep entries
  concise — this is working knowledge, not a wiki. Decisions need
  **Date**, **Status** (active|superseded|deprecated|proposed), and
  **Confidence** fields.
- NEVER put secrets, tokens, or credentials in memory (the server will
  reject them anyway).
- Work in a few focused passes (conventions + architecture first, then
  modules, then decisions/pitfalls). Report what you proposed and what
  staged for review.

MCP サーバーを利用できませんか？エージェント（またはユーザー自身）が CLI を使うこともできます。検証、シークレットスキャン、ルーティングのパイプラインは同じです。

agent-memory propose --intent update_conventions --op append_section \
  --path conventions.md --heading "Build & test" --heading-level 2 \
  --source file:Makefile --confidence confirmed \
  --content-file - <<'MD'
## Build & test

Run `go build ./...` and `go test ./...`. ...
MD
# add --apply to land it immediately (you are the reviewer);
# or omit it and review the staged proposal with `review --diff` + `apply`.

ビルド

Go 1.25 以降が必要です（MCP SDK が依存関係を通じて必要とします）。

go build -o agent-memory ./cmd/agent-memory   # binary
go test ./...                                  # unit + integration tests
go test -tags=e2e ./internal/e2e/...           # end-to-end smoke (linux/macos)
go test -race ./internal/...                   # race detector

make のターゲットは上記の go コマンドと同等です。この形式を使いたい場合は Makefile を参照してください。

CLI

agent-memory init [--root DIR] [--name NAME] [--force]
        # Create the .agent-memory/ scaffold.

agent-memory status [--root DIR] [--json]
        # Project state: version, file counts per category, lock metadata.

agent-memory doctor [--root DIR]
        # Diagnostic layout checks. Advisory; exits 0 even with findings.

agent-memory digest [--root DIR] [--verify SHA256] [--json]
        # Compute or verify deterministic SHA-256 Merkle root of active memory.
        # CRLF-normalized; cryptographic receipt for VTP-1 or swarm audit.

agent-memory fetch [QUERY] [--scope X,Y] [--budget N]
                   [--exclude-archive] [--json] [--root DIR]
        # Return a budgeted Markdown context pack.

agent-memory mcp [--root DIR]
        # Start the MCP server (stdio). Exposes memory.fetch_context and
        # memory.propose_update.

agent-memory propose --intent INTENT --op OP --path PATH [op flags...]
                     [--content STR | --content-file FILE|-] [--source type:ref]
                     [--confidence C] [--apply] [--from-json FILE|-] [--json]
        # Create a proposal WITHOUT an MCP server, through the same
        # validate / secret-scan / route pipeline. --from-json takes a full
        # multi-op ProposeRequest; --apply immediately lands a result that
        # would otherwise stage (you are the reviewer).

agent-memory review [STAGING_ID] [--diff] [--show] [--json] [--root DIR]
        # List staged proposals or inspect one. --diff shows a unified diff
        # of each staged file vs the current on-disk version.

agent-memory apply STAGING_ID [--json] [--root DIR]
        # Re-validate drift and apply a staged proposal.

agent-memory reject STAGING_ID [--json] [--root DIR]
        # Discard a staged proposal.

agent-memory rebase STAGING_ID [--force] [--json] [--root DIR]
        # Re-plan a staged proposal against the current disk state
        # after target_drift. --force is required for soft drifts
        # (acknowledges accepting the new base as planning input).

# review / apply / reject / rebase accept a full STAGING_ID, any unique
# prefix (Git-style), or --latest for the most recently staged proposal:
#   agent-memory apply 20260527       # unique prefix
#   agent-memory apply --latest       # newest staged proposal

agent-memory install <adapter> [--user-global] [--force] [--json]
        # Materialise agent-runtime adapter assets.
        # Supported: claude, cursor, agents, gemini.

agent-memory merge-driver --install [--root DIR]
        # Register the section-aware git merge driver so a team's concurrent
        # edits to .agent-memory/ files union by @id instead of conflicting.
        # Run once per clone. (git invokes the bare `merge-driver %O %A %B %P`
        # form itself during a merge.)

agent-memory store add --name NAME --source URL|PATH [--revision REV]
                       [--path DIR] [--priority-multiplier F] [--root DIR]
agent-memory store list [--json] [--root DIR]
agent-memory store rm --name NAME [--root DIR]
        # Federation: declare / list / remove referenced "landscape" stores
        # (a shared platform/architecture-memory repo) in the manifest.

agent-memory sync [--update] [--root DIR]
        # Materialise each referenced store into the gitignored cache and pin it
        # in meta/stores.lock (committed). --update moves a pin forward.

agent-memory rebuild-index [--root DIR] [--clobber] [--no-assign-ids] [--json]
        # Recreate the FTS5 shadow index from canonical Markdown files.
        # Use for SQLite corruption, schema changes, or after manual .md edits.

agent-memory sweep [--root DIR] [--ttl DURATION] [--dry-run] [--json]
        # Remove staged proposals past the manifest's staging.ttl_seconds.
        # Each removal also writes a ttl_expired entry to meta/rejection-log.jsonl.

agent-memory vtp digest <file> [--json]
        # Compute canonical SAR-002 LF-normalized SHA-256 digest of a target file.

agent-memory vtp verify --receipt FILE [--spec FILE] [--stdout FILE]
                        [--diff FILE] [--exit-code N] [--verifier ID]
                        [--disjoint] [--json]
        # Verify a TaskReceipt execution proof against stdout/diff digests, exit code,
        # and enforce Workpool/0 Clause B (disjoint seat isolation).

agent-memory vtp settle --verify FILE [--spec FILE] --payer ID --payee ID
                        --seq N [--json]
        # Emit a canonical TaskSettle artifact from a passed verification, enforcing
        # that Clause B disjoint verification was satisfied.

agent-memory version
        # Print binary version and exit.

MCP ツール

agent-memory mcp が stdio JSON-RPC 経由で公開します。

ツール	用途
memory.fetch_context	予算内に収まる Markdown コンテキストパックを読み込みます。
memory.propose_update	構造化された編集内容を送信します（即時反映またはステージング）。
memory.status	メモリの状態を報告します：ファイル数、ステージング中の提案（差分を含む）、セキュリティ／Git／ロックの状態。

フェデレーションメモリ（ランドスケープストア）

リポジトリの .agent-memory/ が把握するのは、そのリポジトリだけです。フェデレーションを使うと、共有の読み取り専用「ランドスケープ」ストアを参照でき、アーキテクチャのナレッジベース、プラットフォームスキーマ、ピアサービスのメモリを、エージェントのアクティブな推論ループに直接つなげられます。

これは、静的な Wiki を取り込むこととは根本的に異なります：

• 無駄のないエンジニアリング（ピアの解決策の発見）： エージェントが複雑な分散メカニズム（トランザクショナルアウトボックス、分散レート制限、2PC／Saga など）を一から作り直す代わりに、フェデレーションされたストアを検索して、ピアサービスがすでにどのように解決したかを、根拠（decisions.md）や既知の本番環境での落とし穴（pitfalls.md）とともに確認できます。
• 公開 API を超えたコンテキスト： API（OpenAPI、gRPC）で構造上の構文は定義されますが、運用上の性質、つまりデータベースの分離レベル、ロック競合のパターン、重複排除のウィンドウ、バックプレッシャーの挙動は見えません。フェデレーションメモリは、こうした隠れた運用上の境界を明らかにします。
• サービスをまたぐ安全な PR： エージェントが上流または隣接するサービスを変更する必要がある場合、フェデレーションメモリによって、安全で後方互換性のある変更を提案するために必要なローカル規約と不変条件を得られます。

arch-wiki を使ったクイックスタート

公開されている正規の Architecture Wiki を接続します（https://github.com/xChuCx/arch-wiki — 4 層の分類体系 L1–L4 にわたる、本番環境レベルの技術記事 165 件）：

# 1. Declare the landscape store (edits .agent-memory/meta/manifest.yaml)
agent-memory store add --name arch-wiki --source https://github.com/xChuCx/arch-wiki

# 2. Fetch, sandbox-validate, scan for secrets/PII, and pin commit into meta/stores.lock
agent-memory sync

# 3. Rebuild local shadow index with federated content
agent-memory rebuild-index

# 4. Fetch budgeted, high-density context pack with exact full-article pointers
agent-memory fetch "Debezium Transactional Outbox"

返されるパックは二層検索を実装しています。トークン数の少ない不変条件パックから、必要に応じて全 50 ページの詳細記事を参照できます：

## АНТИ-ПАТТЕРН: Это гарантированно сломается
**Executive Summary:** TL;DR: Change Data Capture (CDC) — это единственный надежный способ превратить базу данных (State) в поток событий (Stream)...
- **Full Article Access:** [L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md](file:///.../4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md)
- **Repository Path:** `4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md`

主な保証：

• ストアごとの公平性とピン留め。 各ストアからそれぞれ上位候補が提供されます。ブレンドされるのは、コミットにピン留めされ、ロックファイルに記録されたストアのみです。同点の場合はローカルがランドスケープより優先されます（priority_multiplier のデフォルトは 0.8）。
• 出典情報と信頼境界。 すべてのランドスケープチャンクにストアとコミットがラベル付けされ、明示的な 「指示ではなく、証拠」 の境界で囲まれます。
• オプトイン。 ストアが宣言されていない場合、動作は単一リポジトリの経路とバイト単位で同一です。

フェデレーション名前空間のガバナンスと並行処理バリア（SAR-010 & SAR-010.1）

異なるリポジトリや異種ファイルシステム（Windows の NTFS、macOS の APFS、Linux の ext4）にまたがるナレッジを統合する際、単純な識別子の照合は、気づかないままの上書きやキャッシュ汚染を引き起こします。agent-memory は、正式な暗号学的バリアを適用します。

1. Unicode 正規化契約（SAR-010）： 識別子と検索キーは、Unicode の完全なケースフォールディング（FullCasefold(NFC(Trim(s)))）を使用して正規化されます。agent-memory doctor はメモリキーを自動的に検査し、デプロイ前にプラットフォーム間で発生する可能性のある大文字・小文字の衝突を警告します。
2. ローカル解決オーバーレイ（meta/store_overrides.yaml）： 上流で衝突やスキーマの相違が発生した場合、ローカルの所有者は上流ソースを変更せずに、ルーティングのオーバーライド（local_alias、exclude）を明示的に定義します。

   version: 1
   overrides:
     - store: "arch-wiki"
       upstream_commit: "9dda4b6f2544"
       key: "STRASSE"
       local_alias: "strasse-arch"
       approved_by: "steward-artemy"
       assigned_steward: "agent-stanislavsky"
       escalation_deadline: "2026-10-01T00:00:00Z"
   

3. 読み戻し整合性とガバナンスの承認ゲート： オーバーレイは、結果整合性ストア（readback_consistency: eventual）を対象とする場合、承認を厳格に拒否されます。古いロック状態を検証に使うことを防ぐため、ネットワークやディスクに副作用が生じる前に、承認はフェイルクローズで失敗します。さらに、責任の所在が曖昧になるのを防ぐため、incident_id、assigned_steward、有効な RFC3339 形式の escalation_deadline が必須です。
4. TOCTOU 対策の二重並行処理バリア（協調プロセスモデル）：
   • カーネルレベルの OS アドバイザリロック（internal/lock）： プロセス間の排他ファイルロックにより、書き込み操作（agent-memory sync、apply）を直列化します。同時に、読み取り側（agent-memory fetch）は、ストアの解決とコンテキストパックの組み立てを通じて、共有 OS 読み取りロック（AcquireShared）を保持し、ディレクトリの切り替え（SwapDir）中の不完全な読み取りや操作の割り込みを防ぎます。
   • 無条件のロックファイル CAS ダイジェスト検証（VerifyStoresLockCAS）： 検証時に meta/stores.lock の SHA-256 ダイジェストを取得し、書き込みの直前に（ファイルが最初から存在しない場合も含めて）検証することで、協調する参加者間での検査・使用間の競合や、作成操作の割り込みを防ぎます。
   • 契約の境界： この二重バリアは、ロックプロトコルに参加するすべての協調プロセスに対して、厳密な直列化可能性を保証します。保持されたアドバイザリロックが実行区間を直列化し、ダイジェスト検証が検証後の変更を検出します。ただし、OS アドバイザリロックを回避する非協調の外部書き込みは明示的に対象外です。
5. 読み取りセットの書き込みスキュー検証（ReadSections CAS）： ステージングされた提案は、提案の合成中に読み取ったすべてのセクションのハッシュ（proposal.ReadSections）を記録します。agent-memory rebase と agent-memory apply はどちらも、変更を適用する前に読み取りセットのセクションが変化していないことを検証し、並行セッションが相互依存するメモリセクションを更新した際の、気づかない書き込みスキュー異常を防ぎます。
6. 型付きガバナンスインシデントレシート（ProvenanceAlert）： 隔離された衝突や古くなった差分について、incident_id、assigned_steward、escalation_deadline、上流コミットの SHA を追跡する、機械可読なレシートを出力し、責任の所在が曖昧になるのを防ぎます。

パターン：federation-stores.md、multi-store-fetch.md、sar-010-unicode-canonicalization-contract.md。

検証可能タスクプロトコル（VTP-1）とスウォームコンセンサス

マルチエージェントのスウォームで稼働したり、経済タスクを実行したりする自律型 AI エージェントは、「バグを修正しました」「テストに合格しました」といった検証されていない自然言語の主張に頼ることはできません。オープンネットワークでは、会話上の主張はコンパクションによる記憶喪失、お世辞の応酬、敵対的な印象操作の影響を受けます。

**VTP-1（検証可能タスクプロトコル）**は、タスク実行をエンドツーエンドで機械検証可能な5段階の暗号ライフサイクルに変換します。

警告

VTP-1 のステータス：実験的／セキュリティ強化を進行中 決定論的なダイジェスト検証、アサーションチェック、タスク間の決済バインディングは暗号学的に強制されますが、現在、Clause B の分離シート検証は ID 文字列の不一致（worker != verifier != creator）に依存しています。外部 PKI や証明済みハードウェア ID のないオープンな分散型または経済環境では、これはまだ敵対的な信頼境界として使用すべきではありません。暗号学的なアカウント証明は現在開発中です。

[TASK-SPEC] ──> [TASK-CLAIM] ──> [TASK-RECEIPT] ──> [TASK-VERIFY] ──> [TASK-SETTLE]
 Creator         Worker           Worker             Independent      Dual-Oracle
 Bounty/Oracle   TTL/IdemKey      Stdout/Diff SHA    Disjoint Seat    Payout / Mint

フェーズ	構造	役割と機械的な不変条件
フェーズ 1：SPEC	TaskSpec	宣言型要件、オラクルの種類（execution@1、rule_kb@1）、対象リポジトリ／コミット、および報奨金を指定します。
フェーズ 2：CLAIM	TaskClaim	ワーカーは、同時実行による競合状態を防止するため、べき等キーとシーケンスベースの TTL を担保として差し入れます。
フェーズ 3：RECEIPT	TaskReceipt	stdout、差分ハンク、プロセスの終了コードの CRLF 正規化（SAR-002）済み SHA-256 ダイジェストを取得する、決定論的な実行証明です。
フェーズ 4：VERIFY	TaskVerify	Workpool/0 Clause B（is_disjoint_seat == true）を強制する独立評価です。検証は、隔離されたマシン／シート（例：キーのないサンドボックスと、シークレットを持つホストの間）で必ず実行しなければなりません。
フェーズ 5：SETTLE	TaskSettle	検証済みレシート参照に紐付けられた決定論的な決済ペイロードで、台帳へのミント（例：Grain コンセンサス）またはエスクローの解放に使用します。

クロスプラットフォームの改行コード整合性（SAR-002）

Windows（CRLF）と Linux／macOS（LF）で Git チェックアウトを行うと、同一のテキストコンテンツでもハッシュが異なる場合があります。VTP-1 エンジンは、stdout、パッチハンク、メモリの Merkle リーフの SHA-256 ダイジェストを計算する前に、正規の LF 正規化（NormalizeLF）を適用し、異種プラットフォーム間でバイトレベルのコンセンサスを確保します。

自律型エージェント向け CLI ワークフロー

# 1. Compute canonical normalized digest for an output log or diff patch
agent-memory vtp digest ./artifacts/stdout.log --json

# 2. Verify a worker's TaskReceipt against live execution output
agent-memory vtp verify --receipt receipt.json --spec spec.json \
                        --stdout stdout.log --diff patch.diff \
                        --verifier @orca-agent --disjoint --json > verify.json

# 3. Settle verified task into a settlement artifact (fails closed if Clause B violated)
agent-memory vtp settle --verify verify.json --spec spec.json \
                        --payer @creator --payee @worker --seq 14500 --json > settle.json

エビデンス（測定済み）

対象範囲を正直に示す3つの層です — 検索 → 継続性 → 振る舞い。 最初の2つは決定論的で、LLM を使わず、リグレッションガードを設けて CI で実行されます。コーパス、ラベル、手法はリポジトリ内で監査できます。

1 · 検索品質。 fetch は正しいセクションを返しますか？ラベル付きの28クエリ／28セクションのベンチマークでは、リリース済みの match-any 検索により、クエリの 98% で関連セクションが上位5件に入り、従来の match-all の動作と比べて再現率が0.91向上しました。

設定	recall@5	hit@1	MRR
match-all (AND) — 以前	0.07	0.07	0.07
match-any (OR) — リリース済み	0.98	0.96	0.97

→ 手法と注意事項：docs/eval/retrieval.md · go test -run TestRetrievalEval -v ./internal/eval/

2 · セッションをまたぐ継続性。 あるセッションで記録した教訓は、次のセッションにも引き継がれますか？実際の記録 → 永続化 → 取得のループでは、次のセッションのコンテキストに教訓が含まれたのは、agent-memory を使用した場合は 5 / 5 のシナリオ、使用しなかった場合（記憶喪失のベースライン）は 0 / 5 でした。

→ docs/eval/continuity.md · go test -run TestMemoryContinuity -v ./internal/eval/

3 · 振る舞い（タスク成功率）。 エージェントはそれに基づいて行動し、同じ間違いを繰り返さなくなりますか？これにはループ内に LLM が必要なため、独自のモデルで実行する A/B ハーネス（「groundhog-day」、メモリあり／なし）として提供しています：eval/behavioural/。ここでは数値を公表していません — メモリなし側を適切に切り分けるのは簡単ではありません（標準の Claude Code 自身の自動メモリが実行間で漏れます。ハーネスの README を参照してください）。設計上、CI には含めていません。

エージェント実行環境アダプター

agent-memory install <adapter> を実行すると、各実行環境が読み込む場所に、記入済みの手順ファイルが配置されます。

アダプター	対象ファイル	備考
claude	.claude/skills/agent-memory/SKILL.md	Claude Code のスキル形式です。--user-global を指定すると ~/.claude/skills/ に書き込みます。
cursor	.cursor/rules/agent-memory.mdc	説明ベースのマッチングを使う Cursor MDC ルールです。--user-global を指定すると ~/.cursor/rules/ に書き込みます。
agents	AGENTS.md（リポジトリのルート）	業界全般で広く使われている規約です。OpenAI Codex CLI、Cursor のエージェントモード、Sourcegraph Cody などが読み込みます。プロジェクト内のみで使用します。
gemini	GEMINI.md（リポジトリのルート）	Gemini CLI のプロジェクト向け長期コンテキストです。プロジェクト内のみで使用します。

各ファイルでは、memory.fetch_context と memory.propose_update を呼び出すタイミング、インテントの語彙、来歴ルール、デバッグ時の却下理由について、実行環境に指示します。4つすべてで同じ振る舞いのモデルを使い、各アダプターはそれを実行環境固有の形式でラップするだけです。

アーキテクチャ（概要）

.agent-memory/
├── meta/
│   ├── manifest.yaml      operational settings (budgets, approval, security)
│   ├── schema.yaml        per-category file/glob, section schema, provenance
│   ├── index.sqlite       FTS5 shadow index (regenerable)
│   ├── lock               OS-level advisory lock (flock)
│   └── lock.info          informational metadata sidecar
├── conventions.md         project conventions
├── decisions.md           durable architectural decisions
├── pitfalls.md            known footguns
├── index.md               server-managed memory index summary
├── modules/<name>.md      per-module facts
├── archive/<date>-*.md    write-once archived entries
├── local/
│   ├── current.shared.md  cross-branch working notes
│   └── current.<branch>.md branch-scoped working notes
├── sessions/<YYYY-MM-DD>.md per-day session logs
└── staging/<id>/          pending human-review proposals
    ├── proposal.json
    ├── target-checksums.json
    └── files/<rel-path>

ディレクトリ構成

cmd/agent-memory/                       CLI and MCP binary entry point
internal/
  adapters/                             agent runtime adapters (Claude, Cursor, Codex, Gemini)
  bench/                                retrieval & FTS5 benchmark harness
  cli/                                  cobra subcommands (init, fetch, propose, digest, vtp, etc.)
  config/ schema/                       YAML loaders (manifest.yaml + schema.yaml)
  e2e/                                  release smoke test suite (-tags=e2e)
  eval/                                 offline retrieval and continuity benchmarks
  fs/                                   atomic file swap and path sanitization
  git/                                  branch resolution and repo inspection
  index/                                FTS5 incremental shadow index
  lock/                                 flock-based cross-process advisory lock
  logging/                              structured slog logging with level filtering
  markdown/                             byte-preserving section-level Markdown engine
  mcp/                                  stdio JSON-RPC 2.0 Model Context Protocol server
  memory/                               operations, staging pipeline, security scanner, Merkle tree
  vtp/                                  Verifiable Task Protocol (VTP-1) engine & Clause B verifier
spikes/                                 pre-M1 architectural spikes (S1-S4)
docs/
  patterns/                             reusable architecture patterns (SAR, Merkle, federation)
  eval/                                 retrieval and continuity benchmark methods and logs
  spikes/                               spike outcome write-ups
.github/workflows/                      CI & CD release workflows (goreleaser)
agent-memory-design-doc-v0.4.1.md       canonical design specification
agent-memory-implementation-plan.md     MVP and federation build log
CHANGELOG.md                            per-release feature list and upgrade notes

リリース

goreleaser を使ったタグ駆動方式です。v* タグをプッシュすると .github/workflows/release.yml が起動し、バイナリのマトリックスをビルドして、アーカイブを添付した GitHub Release を公開します。

リリースごとのマトリックス：

• linux_amd64、linux_arm64
• darwin_amd64、darwin_arm64
• windows_amd64、windows_arm64

各アーカイブには、agent-memory バイナリ、README.md、CHANGELOG.md が含まれます。同じ場所にある agent-memory_<version>_checksums.txt には SHA-256 ハッシュが記載されています。

# Verify a downloaded archive
sha256sum -c agent-memory_0.2.0_checksums.txt

リリースパイプラインをローカルでドライランする場合（goreleaser のインストールが必要です）：

goreleaser check                       # parse + validate .goreleaser.yml
goreleaser release --snapshot --clean  # full build with no upload

ソースからビルドした場合は、常に dev と識別されます。

$ go build -o agent-memory ./cmd/agent-memory
$ ./agent-memory version
dev

goreleaser によるリリースビルドでは、-ldflags='-X .../cli.ProgramVersion=v0.X.Y' を通じて実際のタグが設定されます。

ライセンス

Apache License 2.0。このソフトウェアはライセンスの条件に従って使用、変更、配布できます。また、明示的な特許許諾が含まれています。貢献も同じライセンスの下で受け付けています（CONTRIBUTING.md を参照）。