compound-memory

compound-memory

English | 简体中文

複数の AI エージェントで共有する、ローカルファーストのメモリです。通常の Markdown ファイルで構成され、使うほど価値が積み重なります。メモリはフロントマター付きの Markdown としてディスク上に保存され、確認された使用のたびに強化されます。使われなくなると、復元可能なアーカイブへと移行し、書き込みのたびにローカルの Git 履歴へ自動コミットされます。

なぜ使うのか

エージェントのセッションは毎回ゼロから始まります。設定を何度も尋ねられ、プロジェクトの規約を再発見し、同じ落とし穴に何度も遭遇します。compound-memory を使えば、すべてのエージェントに共通のストアを用意できます。

• ローカルファースト — データがマシンの外に出ることはありません。メモリは、内容の見えないデータベースの行ではなく、人が読める Markdown ファイルとして保存されます。
• MCP ネイティブ — 読み書きの境界となるツールは 5 つ（memory_write / memory_search / memory_get / memory_link / memory_feedback）のみです。あらゆる MCP ホスト（Claude Code、ZCode、WorkBuddy、…）で動作し、操作用の完全な CLI も備えています。
• 蓄積 — 使用が確認されると信頼度が上がり、関連するメモリが近傍情報として呼び出されます。別の ホストからの検証は独立した証拠として扱われ、蒸留によって複数の生メモリを、より少数で密度の高いメモリに統合できます。
• マルチエージェントを前提とした設計 — 全員が読み取れる _shared 名前空間と、各ホストが管理する agent-* のプライベート名前空間を備えています。ホストをまたぐ検証は、ホストごとに追跡されます。
• セマンティック検索は任意 — sqlite-vec と BGE 埋め込みを使ったベクトル検索を利用でき、利用できない場合は純粋な語彙検索へ自動的に切り替わります。モデルは COMPOUND_MEMORY_EMBEDDING_MODEL（デフォルトは Xenova/bge-small-zh-v1.5）と COMPOUND_MEMORY_EMBEDDING_DIM（デフォルトは 512）で変更できます。どちらかを変更する場合は運用上の操作となるため、明示的に rebuild-index を実行する必要があります。

クイックスタート

AI エージェントの場合

この 1 行をコーディングエージェント（Claude Code、Cursor、ZCode、…）に貼り付け、残りを任せてください。

Set up compound-memory (https://github.com/chinwe/compound-memory) — a local-first multi-agent shared memory (MCP server + CLI) — on this machine. Do not clone the repo for a normal install. Initialize the store with `uvx --from compound-memory compound-memory init` (defaults to ~/.agents/memory). Register its stdio MCP server in this host's MCP config: command `uvx`, args `--from compound-memory compound-memory-server`, env `COMPOUND_MEMORY_ROOT=$HOME/.agents/memory` and `COMPOUND_MEMORY_AGENT_ID=agent-<your-host-id>`. Verify by calling `memory_search` and expecting a `{"hits": [...]}` response; if the host needs a restart to load MCP servers, tell me. Use `uv run --directory <repo>` only when developing against a local checkout. Short English setup and the search → feedback → write loop: docs/agent-integration.en.md. Full per-host configs: docs/agent-integration.md.

人間の場合

1. インストール

Python ≥ 3.11 が必要です。デフォルトではリポジトリをクローンしません。

# Default: PyPI. Hosts launch the MCP server with
#   uvx --from compound-memory compound-memory-server
# Optional CLI on PATH:
uv tool install compound-memory   # or: pip install compound-memory

# Developer / local checkout only — not the default host launch
git clone https://github.com/chinwe/compound-memory.git
cd compound-memory && uv sync --extra dev

2. ストアを初期化する

デフォルトの保存先は ~/.agents/memory です。COMPOUND_MEMORY_ROOT 環境変数で変更できます。先頭の ~ または $HOME は展開されます。空白のみの値を指定した場合は、デフォルトに戻ります。

uvx --from compound-memory compound-memory init
# after `uv tool install`: compound-memory init

3. MCP ホストに接続する（推奨）

これにより、普段使っているエージェントが共有ストアを自動的に読み書きできるようになります。リポジトリのパスは不要です。

{
  "mcpServers": {
    "compound-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "compound-memory", "compound-memory-server"],
      "env": {
        "COMPOUND_MEMORY_ROOT": "$HOME/.agents/memory",
        "COMPOUND_MEMORY_AGENT_ID": "agent-<your-host-id>"
      }
    }
  }
}

uvx にはパッケージ名を指定します。サーバーのコンソールスクリプトは compound-memory-server なので、--from が必要です。uvx が PATH にない場合は、command に絶対パス ~/.local/bin/uvx を指定してください。COMPOUND_MEMORY_AGENT_ID は、マルチエージェントストアでは必須です。モデルが申告した内容よりもプロセスの ID が優先されるため、偽装された source によって別のホストの名前空間に書き込んだり、ホスト間検証の評価を水増ししたりすることはできません。未設定または空白の場合、共有 _shared の使用は失敗します。stats と doctor は終了コード 1 を返します（診断結果は引き続き表示されます）。MCP ツールは動作を続け、サーバーは起動時に同じ警告をログに記録します。ID がない場合、ID は自己申告となり、偽装される可能性があります。

ローカルチェックアウトは開発者向けの手順であり、2 つ目のデフォルトではありません。uv sync --extra dev の実行後、command に uv を、args に ["run", "--directory", "<absolute-repo-path>", "compound-memory-server"] を指定してください。

確認方法：エージェントに memory_search（任意のキーワード）を呼び出すよう依頼します。{"hits": [...]} が返れば接続されています。または、uvx --from compound-memory compound-memory doctor を実行します（COMPOUND_MEMORY_AGENT_ID が設定され、ストアへの書き込みが可能な場合は終了コード 0、未設定または空白の場合は終了コード 1）。

Claude Code プラグイン

Claude Code と uv（PATH 上の uvx）が必要です。このリポジトリはセルフホスト型マーケットプレイスを提供します。プラグインを Anthropic の公式ディレクトリに登録することは対象外です。

claude plugin marketplace add chinwe/compound-memory
claude plugin install compound-memory@compound-memory

これにより integrations/claude がインストールされ、COMPOUND_MEMORY_AGENT_ID=agent-claude を設定して uvx --from compound-memory compound-memory-server が起動します（別の ID が必要な場合は、ホスト側でこの環境変数を上書きしてください）。SessionStart フックは新しいセッションで短いリマインダーを追加します。確認と無効化の手順はプラグインの README に記載されています。これらのマーケットプレイス関連ファイルとプラグインファイルは PyPI の sdist または wheel には含まれません。MANIFEST.in で除外し、scripts/wheel_smoke.sh でビルド済みアーティファクトをチェックします。

WorkBuddy / CodeBuddy プラグイン

WorkBuddy または CodeBuddy と uv（PATH 上の uvx）が必要です。このリポジトリは .codebuddy-plugin/marketplace.json にセルフホスト型マーケットプレイスを提供します。

/plugin marketplace add chinwe/compound-memory
/plugin install compound-memory@compound-memory

これにより integrations/workbuddy がインストールされ、COMPOUND_MEMORY_AGENT_ID=agent-workbuddy を設定して同じ PyPI サーバーが起動します。SessionStart フックは新しいセッションで短い厳格ルールのリマインダーを表示し、ストアは読み取りません。Claude のマーケットプレイスファイルは変更されません。

ZCode プラグイン

ZCode デスクトップアプリと uv（PATH 上の uvx）が必要です。ZCode はこのリポジトリの .claude-plugin/marketplace.json をマーケットプレイスのカタログとして読み込むため、別のマーケットプレイスファイルは必要ありません。

リポジトリをクローンしてから、ZCode で Plugin Marketplace → Add → Add Plugin Marketplace を選択し、クローンしたパス（.claude-plugin/ を含むディレクトリ）を貼り付けて、Personal → compound-memory の下にある Compound Memory (ZCode) をインストールします。これにより integrations/zcode がインストールされ、COMPOUND_MEMORY_AGENT_ID=agent-zcode を設定して同じ PyPI サーバーが起動します。さらに、SessionStart の厳格ルールのリマインダーと短いスキルも含まれます。プラグインの MCP サーバー名は compound-memory です。~/.zcode/cli/config.json に同じ名前のサーバーがすでに登録されている場合（docs/agent-integration.md の §3 にある手動設定の方法）、どちらか一方だけを残してください。

4. 次のステップ

skills/compound-memory/SKILL.md の使用プロトコル（検索 → フィードバック → 書き込みのループ）をホストに組み込みます。短い英語版は docs/agent-integration.en.md に、プロトコルの全文は docs/agent-integration.md §6 に記載されています。

デモ

一連のループ全体：write → search → feedback（ホスト間の初回検証ボーナス付き）→ ストアの健全性。v0.4.0 の実際の出力です。長いペイロードは省略しています：

uv run compound-memory init

{ "ok": true, "root": "~/.agents/memory" }

異なる2つのホストが、それぞれ安定した事実を1つ書き込みます（新しいメモリは confidence 0.5、uses 0 で開始します）：

uv run compound-memory write \
  "Deploy serverless functions on this platform times out at 10s — keep handlers under that budget" \
  fact agent-claude --key vercel-timeout

{
  "id": "20261007_86adf1",
  "ns": "_shared",
  "type": "fact",
  "source": "agent-claude",
  "content": "Deploy serverless functions on this platform times out at 10s — keep handlers under that budget",
  "confidence": 0.5,
  "uses": 0,
  "key": "vercel-timeout",
  "validated_by": []
  ...
}

uv run compound-memory write \
  "User prefers concise replies with tables and code examples" \
  fact agent-zcode --key user-style

検索結果はスコア順に並びます（--explain を付けると、デバッグ用に各ヒットのランキング構成要素が含まれます）：

uv run compound-memory search "serverless timeout"

[
  {
    "id": "20261007_86adf1", "score": 1.0292, "similarity": 1.0,
    "type": "fact", "source": "agent-claude",
    "content": "Deploy serverless functions on this platform times out at 10s — keep handlers under that budget",
    "neighbors": []
  },
  {
    "id": "20261007_6a0c0c", "score": 0.5211, "similarity": 0.4919,
    "type": "fact", "source": "agent-zcode",
    "content": "User prefers concise replies with tables and code examples",
    "neighbors": []
  }
]

別のホストがこのメモリを使用し、既定の success 結果で報告しました。uses は +1、conf は +0.1 です。また、報告者の agent-workbuddy はソースの agent-claude とは異なるため、ホスト間の初回検証でさらに +0.15 が加算されます：

uv run compound-memory feedback 20261007_86adf1 agent-workbuddy

{
  "id": "20261007_86adf1",
  "confidence": 0.75,
  "uses": 1,
  "last_used": "2026-10-07",
  "validated_by": ["agent-workbuddy"],
  "evidence": {
    "success_count": 1, "failure_count": 0, "contradiction_count": 0,
    "last_verified": "2026-10-07",
    "recent": [{ "date": "2026-10-07", "agent": "agent-workbuddy", "outcome": "success" }]
  }
  ...
}

ストアの健全性をひと目で確認できます（固定バケットのヒストグラム、稼働状況、蒸留の収率）：

uv run compound-memory stats

{
  "total": 2, "archived": 0, "active": 2,
  "avg_confidence": 0.625,
  "by_type": { "fact": 2 },
  "by_ns": { "_shared": 2 },
  "review_queue_entries": 0,
  "uses_histogram": { "0": 1, "1-2": 1, "3-5": 0, "6-9": 0, "10+": 0 },
  "confidence_histogram": { "<0.3": 0, "0.3-0.6": 1, "0.6-0.8": 1, "0.8-1.0": 0 },
  "recent_feedback_7d": 1, "cross_validated": 0,
  "distilled_total": 0, "distilled_recent_7d": 0
}

現在の stats には、retrieval（mode：vector または lexical。ベクトルチャネルがオフの場合は reason も含む）、attestation（attested。COMPOUND_MEMORY_AGENT_ID が未設定の場合は warning も含む）、expired_active（valid_until を過ぎたアクティブ領域のメモリ。このスナップショットでは 0）も含まれます。cross_validated は、validated_by に2つ以上の異なるエージェントが記載されているメモリの数です。上記のホスト間検証は1回だけなので、正しく 0 のままです。memory_search にも同じ retrieval オブジェクトが含まれます。CLI の search は引き続き配列のみを返します。COMPOUND_MEMORY_AGENT_ID が未設定または空白の場合、CLI の stats は 1 で終了します。doctor は、attestation、retrieval、書き込みロック、git を1ページで確認できるコマンドで、同じ規則に加えて、ルート／ロック／git の失敗も確認します。MCP ツールはエージェント ID がなくても停止しません。

注目すべき点は3つです：

• 新しいメモリは confidence 0.5 で開始し、エビデンスに基づいて変化します。feedback は結果を伝えます。success は値を上げ、failure は値を下げ（下限 0.05）、contradiction は値を固定してレビューキューに入れ、obsolete はすぐにアーカイブします。同一ホストによる success の基本加算分は evidence.host_bumps に記録され、そのホストについて上限は 0.3 です（単一ホストでは最大 0.8。ADR-0012）。
• 別のホストからの初回検証には独立したボーナスが加算されます（メモリごとにホストあたり1回）。その履歴は validated_by / evidence に残ります。confidence は正しさのエビデンスであり、人気を示すものではありません。
• ヒットには1ホップ先の隣接メモリが自動で埋め込まれます（ここでは空です。リンクはまだありません。memory_link で双方向リンクを作成すると、無料で呼び出されます）。

複利的な効果の仕組み

価値の源泉	仕組み
① 使用による強化	memory_feedback のたびに uses と last_used が更新されます。confidence は結果に応じて変化します。既定の success：+0.1。ホストごとの基本加算分は evidence.host_bumps に保存され、上限は 0.3 です（単一ホストでは最大 0.8。ADR-0012）。failure：−0.2（下限 0.05。同じ結果が繰り返されると累積）。contradiction：confidence を固定し、レビューキューに行を追加します。obsolete：すぐにアーカイブします。unknown：イベントを記録し、confidence は変化しません
② リンクの価値	memory_link で双方向リンクを作成します。memory_get は1ホップ先の隣接メモリを取得します。search のヒットには、最大3件の簡潔な隣接メモリが埋め込まれます（アクティブなメモリのみ。無効にするには --no-neighbors を指定）
③ 蒸留	distill-plan（CLI。決定論的な候補と suggested_action：merge / promote / review を提示）→ エージェントが成果物を書き込み → distill-apply でアトミックにコミット（成果物はソースにリンクし、ソースは再有効化可能な状態でアーカイブされます）
④ エージェント間検証	success の場合に限り、source 以外のホストからの初回フィードバックで +0.15 が加算されます（メモリごとにホストあたり1回。validated_by に記録され、同一ホストの host_bumps 上限には影響しません）

スコアリング（重みは src/compound_memory/scoring.py 内の W_* 定数です）：0.70·類似度 + 0.15·confidence + 0.10·新しさ(0.5+0.5·e^(−Δt/τ)) + 0.05·タイプの重み。ベクトルチャネルが有効な場合、ランキングは ε=0.04 の事前タイブレークを使った RRF 融合に切り替わります（仕様の「キャッシュとしてのインデックス」を参照）。

5 つの MCP ツール

ツール	目的	主なポイント
memory_write	メモリを書き込む	type：episode/fact/insight/skill/decision；source：エージェント ID；fact/insight/decision には安定した key を指定します；任意の valid_from/valid_until（ISO 日付）、project スコープ、lesson_role（lesson または avoid。通常のメモリの場合は省略）を指定できます。262144 文字を超える content は拒否され、何も書き込まれません
memory_search	取得する	スコア順に並んだ {"hits": [...], "count", "retrieval"} を返します（デフォルトの top_k=5）；最大 3 件のトリミング済み 1 ホップ隣接メモリを埋め込みます；デフォルトではデュアルチャネル（_shared と呼び出し元自身のプライベート名前空間）を使用します；任意の project（フェイルクローズ）と explain を指定できます。CLI の search は引き続き配列のみを返します
memory_get	ID で取得する	常に found キーを含みます；件数制限なしで 1 ホップ隣接メモリを取得し、アーカイブ済みの隣接メモリも保持します（search は最大 3 件に制限し、内容を 80 文字にトリミングし、アーカイブ済みの隣接メモリを除外します）。期限切れの隣接メモリはどちらの方法でも除外されます。プライベート名前空間の対象には reader が必要です
memory_link	2 つのメモリをリンクする	双方向です；両方のメモリは同じ名前空間になければなりません；プライベート名前空間のリンクには所有者の ID が必要です
memory_feedback	メモリが実際にどのように機能したかを報告する	どの結果でも uses と last_used が更新されます。デフォルトの outcome=success：conf+0.1、同一ホストのベース値は host_bumps により最大 0.3（単一ホストでは最大 0.8；ADR-0012）、初回のクロスホスト検証は +0.15（この上限の対象外）。failure は −0.2（下限 0.05）；contradiction は信頼度を固定し、レビューキューに追加；obsolete は直ちにアーカイブ；unknown はイベントを記録し、信頼度は変更しません。ヒットを採用した後は必ず実行してください — これがストアを積み重ねて成長させるループです

ツールの説明にはプロトコルのルール自体が埋め込まれているため、ホスト側からルールを注入しなくても、エージェントはループを維持できます。英語版の短いループについては docs/agent-integration.en.md をご覧ください。パラメーターの完全なリファレンス：docs/agent-integration.md。

CLI

以下のコマンドはチェックアウトしたリポジトリ内で実行します（クローン内で uv run）。リポジトリをクローンしていないホストでは、代わりに uvx --from compound-memory compound-memory … を使用します。

uv sync --extra dev              # first clone: build .venv (later `uv run` reuses it)

uv run compound-memory init               # initialize an empty store
uv run compound-memory write "Vercel Serverless has a 10s timeout" episode agent-workbuddy
uv run compound-memory search "Vercel timeout"   # default top_k=5; hits embed one-hop neighbors (limit 3, --no-neighbors to disable)
uv run compound-memory feedback <id> agent-claude
uv run compound-memory decay          # run from cron
uv run compound-memory revive <id>    # revive an archived memory
uv run compound-memory distill-plan   # distillation candidates: suggested_action is merge / promote / review; also report-only negative_salience and contradiction_pairs
uv run compound-memory dream --ns _shared   # read-only report: distill-plan section (including the negative sections) + decay_signals + equal stats snapshots (no writes, no LLM)
uv run compound-memory maintain            # one ops pass: read-only dream → optional decay → health-snapshot. Decay is off unless --with-decay or RUN_DECAY=1 (DECAY=1). No --propose, no dream-apply
uv run compound-memory dream --ns _shared --propose  # system proposes: qualifying clusters go to <root>/distill/dream-proposals.json; a human runs dream-apply. Default off; empty pack is []
uv run compound-memory dream-apply --proposals apply.json --source agent-workbuddy --dry-run  # gated apply preview; drop --dry-run to run distill-apply on admitted rows
uv run compound-memory distill-apply "the merged insight" insight agent-workbuddy --sources <id1>,<id2>  # atomic: product (links, origin=distillation) + source archival, one commit
uv run compound-memory doctor           # one-page health check; exit 1 if AGENT_ID is unset, root is missing, the lock is broken, or git is unusable
uv run compound-memory stats            # health: uses/confidence buckets + liveness + distillation yield; exit 1 if AGENT_ID is unset
uv run compound-memory rebuild-index  # rebuild the search cache anytime
uv run compound-memory review-queue   # conflict queue (CLI-only entry)
uv run compound-memory git-log        # audit trail

その他の操作：explain <id>（1 件のメモリの信頼度の構成要素と証拠の詳細）、forget <id> --agent <id>（完全な削除、ADR-0009）、review-resolve（競合の裁定）、extract <transcript|dir>（決定論的なセッション文字起こしのマイニング）。

アーキテクチャ

Agent (MCP client / CLI)
  └─ memory_write | memory_search | memory_get | memory_link | memory_feedback
       └─ MemoryStore (~/.agents/memory)
            ├─ namespaces/_shared/{episode,fact,insight,skill,decision}/*.md   shared area
            ├─ namespaces/agent-*/...                                          private areas
            ├─ archive/...                                                     decayed archive (revivable)
            ├─ index/tokens.json                                               rebuildable lexical cache
            ├─ index/vectors.db                                                rebuildable vector cache (optional)
            ├─ review-queue.md                                                 fact/insight/decision conflict queue
            └─ .git/                                                           auto-commit on every write

定期的な蒸留の準備（launchd / cron / systemd）

ADR 0001 に従い、決定論的な準備処理はスケジュールに沿って実行し、判断（要約／統合）は呼び出し元のエージェントに委ねます。毎日 09:00 に dream が <root>/distill/last-plan.json へ読み取り専用レポートを書き込みます（distill オブジェクトは候補リストです；アーカイブも削除も行われません）。スケジューラーは dream の呼び出しを続けます；dream-apply は明示的に呼び出し元が指定する適用処理で、タイマーには含まれません。スケジューラーは 1 つ選んでください — launchd（macOS 標準、スリープ後に追いついて実行）、systemd user timer（Persistent=true、同様に追いついて実行）、または cron（最も移植性が高く、追いついて実行する機能はありません） — いずれもプラットフォームに依存しない同じ scripts/distill-prepare.sh を実行します。すぐに使えるテンプレート：scripts/com.compound-memory.distill-prepare.plist.tmpl（launchd）、scripts/compound-memory-distill-prepare.{service,timer}.example（systemd）、scripts/compound-memory-distill-prepare.cron.example（cron）。値を埋めた launchd / systemd / cron コマンドは中国語の README に記載されています。スクリプトは set -eu を実行します：失敗すると終了コードが 0 以外で終了します（launchctl list / systemctl --user list-timers / cron メールで確認できます。ログは distill/prepare.log）。distill/ は実行時成果物用のディレクトリ（自動的に gitignore に追加）で、コミットにノイズが生じることはありません。エージェントの判断後に distill-apply を実行した場合のみ、単一のアトミックなコミットが作成されます。

毎日のメンテナンス（タイマー1つ）

compound-memory maintain は毎日実行する単一のジョブです。読み取り専用の dream（<root>/distill/last-plan.json に書き込み、dream と同じレポートを生成し、--propose は決して指定しません）→ 任意の decay → health-snapshot の順に実行します。スナップショットは decay の後に実行されるため、decay が実行された場合は、その後のストアの状態を記録します。デフォルトは dream と health-snapshot です。 --with-decay を渡すか、RUN_DECAY=1（DECAY=1 はエイリアス）を設定しない限り、decay は無効です。いずれかのステップが失敗すると、ゼロ以外の終了コードを返し、stderr にそのステップ名を出力します。後続のステップは実行されません。

scripts/distill-prepare.sh は引き続き dream のみを準備する経路として使用します。タイマーの実行先を dream --propose、dream-apply、distill-apply にしないでください（ADR-0001 / #72 / #97）。提案とマージは、引き続き人間またはエージェントが明示的に行うステップです。scripts/daily-maintain.sh は、launchd/cron 用の薄いラッパーです（PATH 上の uv を解決してから、compound-memory maintain を実行します）。各ステップのオーケストレーションは行いません。

チェックアウトからは、cron の行を1つ設定するだけで十分です（decay は無効です）。

0 9 * * * COMPOUND_MEMORY_ROOT=$HOME/.agents/memory $HOME/.local/bin/uv run --project <repo> compound-memory maintain >> $HOME/.agents/memory/distill/daily-maintain.log 2>&1

decay を有効にするには、同じジョブの先頭に RUN_DECAY=1 を付けます。launchd の ProgramArguments 配列には、同じ uv、run、--project、<repo>、compound-memory、maintain を指定できます（COMPOUND_MEMORY_ROOT と、decay を有効にする場合に限り RUN_DECAY を EnvironmentVariables に設定します）。薄いラッパーを使う方法なら、PATH に依存しません。UV_BIN を設定して /bin/sh <repo>/scripts/daily-maintain.sh を実行してください。タイマーで dream レポートのみを更新する場合は、引き続き distill-prepare.sh を使用してください。

ドキュメント

• CHANGELOG.md — リリースノート（0.5.x の Windows サポート以降）
• docs/specs/0001-compound-memory-spec.md — 設計仕様書
• docs/agent-integration.en.md — 英語による簡潔なセットアップ（uvx、必須のエージェント ID、5つのツール、検索 → フィードバック → 書き込み）
• docs/agent-integration.md — ホストごとの MCP 設定と統一された使用プロトコル（中国語、完全ガイド）
• docs/eval/README.md — 「実行できる」ことと「メモリによって同じタスクの結果が変わった」ことを記録する方法。チェックリストと少数の固定プロンプトセットであり、効果を測定した主張ではありません
• docs/adr/ — アーキテクチャ決定記録
• CONTEXT.md — 用語集（中国語）
• skills/compound-memory/SKILL.md — ホスト向けの使用ルール（中国語）

開発

uv run pytest tests/ -q     # full suite (MCP tool boundary + distillation + lifecycle/index/CLI + input defense)
uv run mypy src/compound_memory/   # whole package, non-strict except the modules below

storage.validation、storage.paths、server は、pyproject.toml にあるモジュールごとの厳格なフラグでチェックされます（CI が Ubuntu / Python 3.13 で実行するものと同じ mypy 呼び出しです）。その他のモジュールには、より緩いグローバル設定が適用されます。[[tool.mypy.overrides]] ブロック内で strict = true を設定しないでください。mypy はこのキーをグローバルオプションに適用するため、パッケージ全体が厳格にチェックされてしまいます。

テストの分離境界：インプロセスの mcp.Client(server) による MCP ツール境界のテスト（サブプロセスなし）と、コアモジュール（スコアリング／インデックス／ストア操作）のユニットテストです。CI は Linux と Windows 上で、Python 3.11／3.12／3.13 を対象に、テスト、型チェック、純粋な wheel インストールのスモークテストを実行します。

プラットフォームのサポート

macOS、Linux、Windows で動作する Python ≥ 3.11。

	macOS / Linux	Windows
インストール	pip / uv のホイール、またはクローン	同じです。CI では純粋なホイールをインストールし、init / write / search / サーバーのエントリーポイントを実行します
書き込みロック	flock。ロックが解放されるまで待機します	msvcrt のバイト範囲ロックを使用し、最大 30 秒ポーリングします。待機がタイムアウトすると書き込みは失敗し（WriteLockError）、ロックなしで続行することはありません
ロックファイルを作成できない場合	警告を出し、ロックなしで書き込みを続行します	同じです。これはロック競合ではなく、ファイルシステムの破損です
ファイルのアクセス権	アトミックな置換時に POSIX モードビットを保持します	POSIX のアクセス権はありません。アクセス権を合わせる手順はスキップされます
ベクトル検索	オプションの vec エクストラとローカル BGE モデル	同じコードパスです。Windows CI では vec エクストラをインストールしません。これがない場合は語彙検索となり、stats.retrieval で報告されます
定期的な蒸留準備	launchd、systemd のユーザータイマー、または cron（distill-prepare.sh、dream のみ）	ファーストパーティのタスクスケジューラーテンプレートはありません。scripts/distill-prepare.sh を cron またはタスクスケジューラーに自分で設定してください
毎日のメンテナンス	1 つの cron/launchd ジョブ：compound-memory maintain（または scripts/daily-maintain.sh）	同じコマンドです。減衰処理は --with-decay または RUN_DECAY=1 を指定した場合のみ実行されます
Git 履歴	PATH にある git	同じです

リリース

PyPI のバージョンは変更できません。タグは pyproject.toml の version と一致する必要があります（リリースワークフローで確認され、不一致の場合は明確なエラーを出して失敗します）。リリースは GitHub Actions と PyPI Trusted Publisher（OIDC、トークン不要）を通じて行われます。v0.1.0 のようなタグをプッシュすると、release.yml が自動的にビルドして公開します。

---

MCP Registry 名：mcp-name: io.github.chinwe/compound-memory

server.json には PyPI パッケージ compound-memory（stdio）が記録されています。リポジトリのパスは指定されていません。パッケージ名とサーバーのコンソールスクリプト名が異なるため、ホストの設定では引き続き uvx --from compound-memory compound-memory-server を使用します。