Piia Engram

Piia Engram

表示、編集、上書きでき、MCP コーディングツール間で持ち運べる、ローカルファーストのAIワークアイデンティティ。

自分がどんな人で、どのように働き、「良い」とは何を意味するのかを、一度AIに伝えましょう。 Claude Code、Codex、Cursor、Windsurf、その他のMCP互換ツールは、同じAIワークアイデンティティレイヤーを基盤として利用できます。自分が所有するローカルファイルで、クラウドアカウントは不要、確認できない隠れたメモリもありません。

インストール · 実際の動作を見る · 対応ツール · MCP ツール · よくある質問

英語 | 中国語

掲載先：

以下にも掲載されています：awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP

要約： piia-engramは、ローカルファーストの個人向けAIアイデンティティレイヤーです。複数のコーディングエージェントが、あなたについて同じ理解を基盤として作業を開始できるよう支援します。対象となるのは、あなたの好み、品質基準、学んだ教訓、決定事項、プロジェクトのコンテキストです。これはエージェントのメモリデータベースではなく、あなたが所有する、ツールの上位にあるレイヤーです。

ネイティブのメモリを使うだけではだめですか？ Claude Code、Codex、Cursor、Windsurfは、それぞれ独自のメモリやルールを追加しています。これらは便利ですが、1つのツールまたはワークスペースに限定されます。piia-engramは、その上位に1つのポータブルなアイデンティティレイヤーを提供します。自分が所有するローカルファイル、確認してから採用するAI提案の知識、そしてツール間で引き継げるコンテキストを利用できます。

4行でわかる信頼モデル：

• クラウドアカウント不要： pip でインストールし、コアストアをお使いのマシンに保持できます。
• ローカルファイル： ID とナレッジは ~/.engram/ に JSON／Markdown として保存されます。
• ユーザーによる承認： AI はローカルに書き込みます。認証情報、シェルコマンド、MCP 設定、権限ルールなどの高リスク項目はレビューを待ちます。一方、低・中リスクの書き込みは自動的に取り込まれますが、すべて監査可能で、元に戻せます。すべての書き込みを承認制にするには、ENGRAM_APPROVAL=strict を設定してください。「検証済み」とは、現在のコードと照合して再確認されたという意味ではなく、設定されたポリシーに基づいて、あなたまたはそのポリシーによって承認されたことを意味します。
• セッションの継続性： 再開時の出力には、レビューされておらず、アクションを許可するものでもない以前のセッション記録（チェックポイントとスナップショット）が含まれることもあります。承認とレビューに関する説明は、設定されたポリシーのもとで管理される ID と長期ナレッジに適用されます。
• 文書化された境界： 信頼モデル、プライバシー、セキュリティをご覧ください。

証拠を確認したいですか？ ライブのツール間継続性の証明をご覧ください。これは Claude Code が書き込み、Codex が 1 つのローカルストアから読み取ったメモリーです。または、ワンコマンドで実行できる再現可能なコードデモをご覧ください。

動作を見る

You  → "Help me refactor this auth module"

# WITHOUT piia-engram: AI starts from scratch
AI   → "What language? What framework? What's your testing preference?"

# WITH piia-engram: AI can load your approved identity and long-term knowledge
AI   → "Based on your preference for pytest + 90% coverage, and your
        lesson about always separating auth middleware from business
        logic (from the March incident), here's my approach..."

これをただ信じる必要はありません。Memory Lens（engram preview --html）を使えば、送信前に、AI 呼び出し元が受け取る内容とガバナンスによって除外された内容を正確に確認できます。

上図：デモストアからの実際のレポートです。4 件の項目が公開され、レビューされていないステージング用メモと認証情報を含む教訓は除外されます。秘密情報は [REDACTED] と表示されます。

インストール

pip install piia-engram && engram setup

ウィザードは AI ツール（Claude Code、Cursor、Codex、Claude Desktop）を自動検出し、変更する設定ファイルを正確に一覧表示します。キーを 1 回押して確認すると MCP 接続を書き込みます（すべての書き込みは事前にバックアップされます。拒否すれば何も変更されません）。ID カードをプレビューしたら、設定したツールを再起動します。最初の会話では、起動ツールまたは検索ツールを通じて、承認済みの ID と長期ナレッジを読み込めます。(詳しい手順 ↓)

AI エージェントにインストールを依頼する

コーディングエージェントに Engram のインストールを依頼し、適用前に計画を確認します。

pip install piia-engram
engram setup --non-interactive --json
engram setup --non-interactive --apply
engram doctor --json

セットアップでは質問されません。クライアントを限定するには --clients cursor,codex を、出力言語を指定するには --lang zh|en を使用してください（既定値は en です）。--apply を指定しないプランモードでは、Engram ストア、ホームディレクトリ、クライアント設定には何も書き込まれません。Python 自体がシステムの一時ディレクトリを使用する場合があります。適用すると、バックアップを作成したうえで MCP 接続を設定し、既存のツールモードを保持します。メモリーのインポート、ID／ナレッジの書き込み、提案の承認は行いません。設定したクライアントを再起動してください。終了コード 1 は、手動での作業が残っていることを示します。エージェント向けの手順については llms.txt を、詳細についてはCLI と JSON の仕様をご覧ください。

対応ツール

エビデンスレベルはエージェントクライアント検証ランブックに従います：L0 = 検出、L1 = プロトコルアクセス、L2 = 読み取り／検索動作、L3 = A/B による動作改善、L4 = クライアント間の継続性、L5 = 再現可能な公開エビデンス。

数字で見る

以下は、docs/public-facts.json に記載されている現在のリポジトリの情報です。公開レジストリとパッケージのバッジは、リリース／公開時にのみ更新されます。

AI はツールを切り替えたり、新しいチャットを始めたりするたびに、あなたのことを忘れてしまいます。 piia-engram がその引き継ぎを解決します。

新しいチャットウィンドウを開くたび、Claude Code から Codex に切り替えるたび、AI ツールを更新するたび、別のプロジェクトに移るたびに、すべてが振り出しに戻ります。

• コミュニケーションの好み — 消えてしまいます
• コード規約や品質基準 — 忘れられてしまいます
• すでに学んだ間違い — 失われてしまいます
• 先月そのアーキテクチャ上の決定をした理由 — 消えてしまいます

これは、現在の AI のメモリが各プラットフォームの中に閉じ込められているためです。メモリはあなたのものではなく、ツールのものです。ツールが更新、リセット、または置き換えられると、あなたのコンテキストも一緒に消えてしまいます。

piia-engram は、どの AI ツールからも独立して、あなたのマシン上で動作する個人のアイデンティティレイヤーを提供します。 自分がどのような人か、どのように仕事をするか、何を学んできたかを一度伝えれば、MCP 対応ツールが同じ承認済みのアイデンティティと長期的なナレッジを読み取れます。新しいチャット、新しいツール、新しいバージョンでも、あなたのアイデンティティは持ち運べます。

piia-engram はエージェントのメモリデータベースではありません。 Mem0、Zep、Letta などのツールは、AI エージェントのタスクコンテキストやセッション履歴を保存します。piia-engram が保存するのは、一人の人間としてのあなた です。アイデンティティ、好み、苦労して得た教訓、重要な決定事項を保存します。これは別のレイヤーです。タスクで何が起きたかではなく、あらゆるタスクの向こう側にいるのは誰かを扱います。

piia-engram を選ぶ理由

piia-engram を使うユーザー

piia-engram は、複数の AI コーディングツールを使い、そのたびに自分のことを説明し直すのにうんざりしている開発者向けに作られています。

Claude Code、Codex、Cursor を切り替えて使う方 — コード規約、アーキテクチャの決定事項、苦労して得た教訓が、ツールを切り替えるたびにリセットされます。piia-engram を使えば、どのツールもあなたがどんな人かを同じように理解した状態で始められます。

週に 10 個以上の AI チャットウィンドウを開く方 — どのウィンドウもゼロから始まります。piia-engram を使えば、どの会話も承認済みの同じアイデンティティと知識コンテキストから始められます。

ツールのアップデート後に設定を失ったことがある方 — あなたのアイデンティティは、どのプラットフォームの中ではなく、あなたのマシン上にあります。アップデート、リセット、移行によって、あなたの記憶が影響を受けることはありません。

piia-engram が保存するもの

すべてのデータは ~/.engram/ 以下にプレーンな JSON ファイルと Markdown ファイルとして保存され、自分で開いたり、編集したり、バックアップしたり、移行したりできます。

• アイデンティティ：あなたがどんな人か、どのようにコミュニケーションするか、どの言語を好むか
• 品質基準：コードレビューの基準、テストカバレッジへの期待、リリースしないと決めているもの
• 設定：コーディングスタイル、AI の振る舞い、好みの説明方法
• 信頼境界：非公開にするフィールド、ツールにアクセスを許可する範囲
• プロジェクトスナップショット：進行中の作業のコンテキストを記録し、再読み込み可能にしたもの
• 学んだ教訓：失敗、予想外の出来事、うまくいったこととうまくいかなかったこと
• 重要な決定事項：何を選び、何を却下し、その理由は何か
• ドメイン知識：プロジェクトやツールをまたいで再利用できる知見

piia-engram が実現すること（ストレージを超えて）

ほとんどのメモリツールは受動的です。情報を入れると、それを返してくれます。piia-engram は能動的にも機能します。

プロジェクトをまたいだナレッジの継承
新しいプロジェクトについて、平易な文章で説明します。get_knowledge_inheritance は、これまでに取り組んだすべてのプロジェクトから、特に関連性の高い教訓や決定事項を厳選したスターターパックを返します。10 番目のプロジェクトは、その前の 9 つすべての成果を活用できます。ツールを 1 回呼び出すだけです。

受動的なナレッジの記録
セッションの要約を extract_session_insights に貼り付けると、piia-engram が教訓や決定事項を抽出して保存します。手動でメモを取る必要はありません。通常の AI との会話を通じて、ナレッジが蓄積されます。

MCP に対応していないツールでも利用可能
ChatGPT、Gemini、Kimi では、get_identity_card を使って、すぐに貼り付けられる Markdown のアイデンティティカードをエクスポートできます。直接接続できないツールにも、コンテキストを引き継げます。

プレイブックの自動抽出
複数のステップからなるワークフロー（PyPI へのリリース、Cloudflare へのデプロイ、MCP Registry への公開など）を完了すると、piia-engram がセッションの終了時にそれを検出します。構造化されたプレイブックのドラフト（手順、注意点、トリガーとなるキーワード）を生成し、ステージング領域に保存します。次回、同じタスクを行うときには、AI が確認済みのプレイブックを受動的な参考情報として取得し、手順を一緒に進め、結果を記録できます。手動で記録する必要はありません。Engram がドラフトを作成し、あなたが確認し、ホスト AI が責任を持って対応します。詳しくは、以下のプレイブックの自動抽出をご覧ください。

ローカルツールレジストリ
AI ツールは、ローカルのプログラム、ランタイム、CLI を頻繁に探します。register_tool はインストール済みのものとその場所を記録し、find_tool はすぐに取得します。セッションごとに which python を実行する必要はもうありません。環境マップは、ツールや会話をまたいで保持されます。

ナレッジの健全性と探索
get_knowledge_overview は、古くなった教訓（30 日以上見直されていないもの）を表示し、4 つの側面（鮮度、品質、網羅性、整理状態）に基づいて 0～100 の健全性スコアを算出し、再確認する価値のある不足部分にフラグを付けます。explore_knowledge は、アクションにつながるマージコマンドを示しながら、ナレッジベース内の重複に近い項目をスキャンし、関連項目や類似項目をたどります。manage_relation は、関連する教訓や決定事項をつないで、たどることのできるナレッジグラフを作成します。

ハイブリッド検索（オプション、デフォルトでは無効）
デフォルトのキーワード検索に変更はありません。ハイブリッド検索（FTS5 による全文検索とセマンティックベクトルレイヤー）を有効にすると、言語をまたいで情報を検索できます。たとえば、英語のクエリで中国語のメモを見つけられます。pip install "piia-engram[vector]" を実行して ENGRAM_SEARCH=hybrid を設定するか、engram setup でキーを 1 回押して有効にしてください。インデックスは再構築可能な SQLite ファイルです。JSON ストアは引き続き、唯一の信頼できる情報源です。詳しくはdocs/hybrid-search.mdをご覧ください。

クイックスタート

pip install piia-engram
engram setup

piia-engram を初めてお使いですか？デフォルトのコアツール 19 個のみを使用して、インストール -> 最初のメモリ -> 新しいセッションでの想起までを確認できる、より詳しい初回利用クイックスタートをご覧ください。または、インストール -> 最初の価値の実感 -> ツール間の継続性 -> ガバナンス -> プライバシー -> FAQ を網羅したユーザーガイドをご覧ください。Claude Code、Codex、Cursor向けのホスト別セットアップガイドもご利用いただけます。提案のみを行うセーフコンテキスト、リプレイ、鮮度と競合、エビデンスの下書きについては、コンテキストガバナンスをご覧ください。

セットアップウィザードでは、次の操作を行います。

1. Python 環境を検出します
2. Engram データフォルダー（~/.engram、別のドライブ、またはカスタムパス）を選択できます
3. AI ツールを検出し、変更する正確な設定ファイルを一覧表示して、キーを 1 回押して確認すると MCP 接続を書き込みます（事前にバックアップを作成します。拒否した場合は変更されません）
4. 初期ナレッジ（役割、技術スタック、言語）の設定を案内します
5. 他の AI ツールからルールとメモリをインポートするか確認します — CLAUDE.md、.cursorrules、メモリファイル（デフォルトではインポートしません。最初に一覧を表示し、次にレビューキューを表示します。engram review で承認してください）
6. 毎日の短い利用状況通知を表示します。どちらのセットアップモードでもテレメトリについて質問したり、選択内容を変更したりすることはありません
7. AI アイデンティティカードをプレビューします — すぐに価値を実感できます

セットアップによって MCP 接続が書き込まれた後（最初にプロンプトで確認します）、AI ツールを再起動してください。多くのクライアントは起動時に get_user_context を呼び出せます。ホストが自発的に呼び出さない場合でも、search_knowledge または get_resume_brief を明示的に呼び出すことが、引き続き想定される L2 パスです。

非対話型または CI で実行する場合は、確認プロンプトを省略して直接書き込みます。

engram setup --apply-external-config

どちらの場合も、外部設定ファイルへの書き込みはすべて、選択した Engram データフォルダーにバックアップされます。プロンプトを拒否すると、外部設定ファイルは一切変更されません。

ローカルでクリック操作によるレビューを行うには、piia-engram-review（インストール済みの Windows ランチャーをダブルクリック）を開きます。提案全体をレビューして、承認、拒否、または保留を選択できます。ウィンドウの実行中は、本文を含まないプロンプトも任意で利用できます。 Python の Tk サポートが必要です。MCP の承認権限は変更されません。 ローカルレビューウィンドウガイドをご覧ください。

いつでも状態を確認できます。

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
engram preview --as automation  # see exactly what a given AI caller would receive (read-only)
engram continuity    # metadata-only proof that cross-tool handoff is ready
engram management    # metadata-only review/playbook management view
engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions
engram doctor --days 7 --json  # which AI clients are configured and called Engram lately (read-only)
engram repair-encoding        # dry-run scan for garbled / mojibake text
engram repair-encoding --apply  # repair reversible cases with a backup

engram continuity はメタデータのみを扱います。保存されたセッション数、寄与したツール、再開ブリーフの準備状況、コンテキストの読み込みとラップアップに関する集計シグナルを報告し、メモリ本文、生のテレメトリイベント、セッション ID、ローカルパスは出力しません。

機械可読な合成ループの証明を確認するには、次を実行します。

python demos/cross_tool_continuity_demo.py --json

engram continuity は準備状況のメタデータを報告します。デモ JSON は、合成データのみを使用した、分離された書き込み -> 再開 -> 検索 -> 出所確認のループを証明します。

リプレイ体験モード

オフラインリプレイや、過去のデータを時系列順に再投入する評価では、ランチャーの設定に "mode": "replay_experience" を指定して、分離されたストアを初期化できます。ルートモードは変更できません。登録にはタイムゾーン情報を含む admitted_before と now パラメーターが必要で、想起にも now が必要です。過去の登録には指定した時刻が使われますが、レシートには実際のタイムスタンプが記録され、自動的な同一ファミリーの除外は無効になります。エビデンスは引き続き、判断ポイントの as_of までに制限されます。リプレイ登録では、テンプレートの類似度が高くても、同一ではない正規化済みの要約は検証済みのまま保持されます。完全一致する重複と、既存のトゥームストーン、廃止済み、アーカイブ済みのツインに関するルールは引き続き適用されます。本番環境での重複処理と、すべての容量制限に変更はありません。リプレイルートでは hard_cap を最大 10,000（たとえば 1,400）まで設定できます。本番ルートのデフォルトは引き続き 1,000 です。ネイティブバックアップと返却されるエントリには store_mode: replay_experience が含まれ、通常のルートではリプレイルートと、マーク付きのインポートを拒否します。

この分離により、誤った設定の使用、別のルートの接続、マークのないエクスポートのインポートなどによる意図しない混在を防ぎます。新しい初期化レシートはディレクトリの識別情報にひも付けられ、コンテキストテキストにはリプレイマーカーが保持されます。これは、両方のルートとその台帳を編集できる人に対する改ざん防止の境界ではありません。リプレイモード導入前に作成された既存の本番ルートは、ランチャー設定なしで直接接続できます。

より広範なリリースエビデンスを得るには、合成 MCIC ベンチマークを実行します。

python demos/mcic_benchmark.py --json

MCIC v1 には、明示的な想起、暗黙的なパーソナライズのシグナル、誤った前提に対するガードシグナル、公開アクションの境界、バージョンチェーンの HEAD 選択、ネガティブコントロール、来歴を対象とする、目的別にラベル付けされた継続性シナリオが 10 件含まれています。主張の範囲は限定的です。Engram は、次のクライアントが適切なシグナルを利用できるようにします。実際のモデルがそれに従うかどうかは、別途 A/B テストが必要です。

信頼とエビデンス

piia-engram は、信頼性に関する主張をマーケティング文句ではなく、リリース成果物として扱います。

自分で確認する（5 分）

上記の表をうのみにせず、ご自身のマシンでチェックを実行してください。

1. セットアップを確認する — engram doctor を実行すると、検出されたツール、ストアの状態、アクティブな機能モードが表示されます。
2. AI に見える内容を確認する — engram preview --as automation を実行すると、呼び出し元が受け取る正確なコンテキストが表示されます（読み取り専用で、何も送信されません）。
3. 公開範囲を制御する — ENGRAM_TOOLS=core を設定する（または複数のグループを組み合わせる）と、engram doctor を再実行して、想定どおりのコア機能が表示されることを確認できます。機能モードを参照してください。
4. データを監査する — データ主権監査の手順書に従い、ID データとナレッジデータが Engram のルート内に保持され、外部への書き込みが明示的に行われて監査可能であることを確認してください。
5. 主張を確認する — 信頼性の根拠に記載された信頼性に関する各主張は、ローカルで実行できる決定論的なチェックまたは確認手順に対応しています。

AI ツールの設定

以下のスニペットでは、engram setup が書き込むサーバー名 engram を使用しています。 以前の手順で追加した piia-engram という名前のエントリも引き続き認識され、セットアップ時にファイルをバックアップしたうえで engram に変更されます。2 つ目のサーバーが追加されることはありません。

# Guided setup; confirms before writing external client configs (backed up first)
engram setup
# Skip the confirmation prompt for non-interactive/CI runs
engram setup --apply-external-config
# Or manual (user scope, available in all your projects):
claude mcp add --scope user engram -- piia-engram-mcp

{
  "mcpServers": {
    "engram": {
      "command": "piia-engram-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "command": "python",
  "args": ["-m", "piia_engram.mcp_server"]
}

[mcp_servers.engram]
command = "python"
args = ["-m", "piia_engram.mcp_server"]

{
  "mcpServers": {
    "engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

設定の確認

セットアップ後、engram doctor を実行して、すべてが接続されていることを確認します：

$ engram doctor

  Detected 3 AI tool(s):
    [ok] Claude Code — Engram configured
    [ok] Cursor — Engram configured
    [ok] Codex — Engram configured

  [ok] All configured tools look healthy.

  ── Functional Checks ──
    [ok] piia_engram.core importable
    [ok] Engram initialized (~/.engram)
    [ok] Identity loaded (role: Senior Backend Developer)
    [ok] quick_context.md ready (4096 bytes)
    [ok] MCP server: 19 tools registered

  -- Terminal encoding --

    [ok] stdout/stderr: utf-8 / utf-8
    [ok] PYTHONIOENCODING not set (stdout/stderr already UTF-8)
    [ok] Runtime encodings: preferred=UTF-8, filesystem=utf-8

  -- Config Integrity --

    [ok] MCP configs: 3/13 files found, 3 configured
    [ok] Instruction files: 3/4 found, 3 fresh
    [ok] Project rule files: 1 found
    [ok] Shared instructions: 1 found
    [ok] Claude hooks: 4/4 registered
    [ok] Report is metadata-only (hashes + counts; no rule bodies)

  -- Continuity --

    [--] No saved agent sessions yet
         Run an AI session, then wrap up or stop the tool to create one.
    [ok] Resume brief builds (2 section(s))

機械可読形式で互換性を確認するには、engram capabilities --json を実行してください。 ユーザーメモリーやプロジェクトの内容を読み取ることなく、安定した機能コードとコントラクトのバージョンを報告します。MCP の doctor(output_format="json") にも同じフィンガープリントが含まれます。

アップグレード

pip install --upgrade piia-engram

アップグレード後、piia-engram は次回のサーバー起動時（stdio モード）に、古くなった MCP 設定を自動的に移行します。再起動後も AI ツールに「MCP disconnected」エラーが表示される場合は、次を実行してください。

piia-engram doctor        # show what's wrong
piia-engram doctor --fix  # auto-repair and fix in one step

その後、該当する AI ツールを再起動してください。doctor コマンドは、Claude Code、Cursor、Codex、Windsurf、Claude Desktop、およびコミュニティがサポートする MCP 設定の場所を確認し、古いサーバーエントリを削除して、メタデータのみを含む設定の整合性サマリーを出力します。

リモートデプロイ

piia-engram を自分のサーバーで実行し、どこからでも接続できます。

サーバーのセットアップ

# Install with remote support
pip install piia-engram[remote]

# Generate an auth token
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Save the output, e.g. "abc123..."

# Start in SSE mode
ENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767

クライアント設定（Claude Code）

{
  "mcpServers": {
    "engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

クライアント設定（Cursor）

{
  "mcpServers": {
    "engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

セキュリティに関する注意事項：

• 本番環境では、nginx または caddy の TLS を使用し、必ず HTTPS を利用してください。
• 認証トークンは本人確認データを保護します。秘密に保ってください。
• デフォルトのバインド先は 127.0.0.1 で、ローカルホストのみを対象とします。リバースプロキシの背後でのみ 0.0.0.0 を使用してください。
• クロスオリジンアクセスを制限するには、ENGRAM_CORS_ORIGINS を設定してください（例：https://your-domain.com）。
• データはサーバー上に保持され、サードパーティのクラウドに送信されることはありません。

MCP ツール

piia-engram には 59 個の MCP ツールが含まれています。AI のコンテキストを整理された状態に保つため、デフォルトでは Tier-1 Core の 19 個のツールのみが読み込まれます。Core は「ほとんどのセッションで使用する」という意味であり、「読み取り専用」という意味ではありません。一部のコアツールはローカルメモリや所有者の許可が必要なエクスポートファイルに書き込みますが、ガバナンスレイヤーが引き続きこうした副作用を制御します。各ツールには、クライアント向けの標準的な MCP ヒント（読み取り専用、破壊的、べき等、オープンワールド）も付与されています。これらは助言であり、アクセス制御ではありません。アクセス制御は引き続き厳格モードとガバナンスによって行われます。簡潔な運用者向けの説明については、MCP チートシートを参照してください。59 個すべてのツールを有効にするには、MCP 設定に ENGRAM_TOOLS=all を追加します。

ナレッジ管理、ガバナンス、管理、インテグレーションなどの組み合わせ可能な機能モードも公開できます。詳しくは機能モードガイドを参照してください。

{
  "mcpServers": {
    "engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"],
      "env": { "ENGRAM_TOOLS": "all" }
    }
  }
}

他の AI ツールからのインポート： Engram が他の AI ツールのメモリやルールファイルを独自に読み取ることはありません。サーバー起動時、コールドスタート時、セッション終了時のいずれも同様です。取り込むには engram import-memories を実行してください。最初に検出した内容が一覧表示され（--dry-run はここで終了します）、確認後にレビューキューへ追加され、ストア内の import_receipts/ に受領記録が書き込まれます。ENGRAM_MCP_STARTUP_SYNC は引き続き受け付けられますが、現在は何も実行しません。ENGRAM_RECONCILE=0 を設定すると、他の AI ツールのファイルの読み取りを完全に無効にできます。ENGRAM_EPHEMERAL=1 を設定すると、コンテナ／エフェメラルクライアントでの起動時の設定チェックが省略されます。

MCP の起動時に、他のツールのメモリがインポートされたり、ナレッジやアイデンティティのコンテンツが変更されたりすることはありません。ただし、起動時や読み取りツールが、セッションのチェックポイント、使用状況の記録、監査記録、アクセスメタデータを書き込む場合はあります。これらの操作は書き込みがまったく発生しないわけではありません。

Tier-1 コア（19 ツール — 日常的なワークフロー）

Tier-2 高度なツール（40 ツール — ナレッジ管理、レビュー、ガバナンス、インポート／エクスポート）

高度なツールには、任意のローカル統合、オーナー／管理者向け機能、保守用ヘルパーが含まれます。ファイルのエクスポート、ストア全体のインポート、レビューページの生成、呼び出し元の信頼度の変更を行うツールは、広く役立つ製品機能であっても、オーナー／管理者／エクスポート向け機能です。関連する操作は、mode／action セレクターを持つ単一のツールに統合されています（v4.0）。

レガシー Playbook スコープの移行（分類／適用／ロールバック／レビューキュー）は MCP のインターフェースから切り離され、所有者専用のローカル CLI に移行しました：engram playbook scope classify|apply|rollback|queue|resolve（デフォルトではプレビューのみ。書き込みには --apply --yes が必要です）。

Playbook の自動抽出

piia-engram は、セッション中に完了した複数ステップのワークフローを検出し、手動で記録しなくても、構造化された Playbook の草案を自動生成できます。

動作の仕組み

1. 検出 — wrap_up_session または save_agent_context を呼び出すと、piia-engram はチェックポイントの手順、動作を表す動詞、トリガーキーワードなど、手順を含むワークフローのシグナルをスキャンします。
2. 草案の生成 — ワークフローが検出されると、手順、落とし穴、トリガーキーワード、前提条件を含む Playbook の草案が作成されます。機密情報（API キー、トークン、絶対パス）は、保存前に自動的にマスキングされます。
3. ステージング — 草案はステージング領域に保存され、検証済みとして自動昇格することはありません。信頼できる Playbook になる前に、内容を確認して承認します。
4. スキーマコントラクト — 保存された Playbook は、トリガーキーワード、前提条件、落とし穴、構造化された手順、任意の required_tools 宣言を含む、バージョン管理されたコントラクトに正規化されます。簡素な草案もレビュー可能ですが、機械可読な品質警告が付与されます。
5. ツールの解決 — Playbook は名前または用途で必要なツールを宣言し、ローカルパスはツールレジストリに保持されます。playbook_execution（アクション prepare）は実行時に resolved_tools、tools_ready、missing_tools を返すため、解決済みパスを Playbook に保存することなく、ホスト AI は利用可能なローカルツールを確認できます。
6. 再利用と結果 — 次回、AI ツールが類似のタスクに遭遇すると、search_knowledge がトリガーキーワードを照合し、参照用の Playbook を返します。ホスト AI はユーザーと一緒に手順を進め、playbook_execution（アクション status）は、スキップされた手順を暗黙の成功として扱うのではなく、結果の集計（pending、partial、succeeded、failed）を報告します。

設計方針：Engram が開始し、あなたが確認し、AI が適用します

Playbook の自動抽出は完全自動ではありません。piia-engram がワークフローを検出して大まかな草案を生成しますが、明示的に確認されるまで草案はステージングにとどまります。確認後、AI ツールは Playbook を管理された参照情報として使用し、手順の結果を記録できます。Engram がワークフローを黙って実行することはありません。これにより、運用手順を作成する手作業をなくしながら、品質管理に人が関与できるようにします。

信頼度レベル

機密情報のマスキング

草案を保存する前に、piia-engram は次の情報を自動的にマスキングします：

• API キーとトークン（Bearer、sk-、ghp_ など）
• 絶対ファイルパス（Windows および Unix）
• メールアドレス
• 環境変数のシークレット

キルスイッチ

ユーザーはいつでも Playbook の自動抽出を無効化または再有効化できます：

• 無効化： AI に「Playbook を無効にして」／「stop playbook」／「disable playbook auto-extraction」と伝えます。
• 有効化： AI に「Playbook を有効にして」／「start playbook」／「enable playbook auto-extraction」と伝えます。

AI は update_identity(field="preferences", ...) を使って playbook_auto_extract の変更を提案できます。変更は engram review でローカルに承認した後にのみ有効になります。デフォルトでは有効です。

Playbook の手動作成

自動抽出の設定にかかわらず、いつでも add_playbook を使って Playbook を手動作成できます。キルスイッチの影響を受けるのは、wrap_up_session 中の自動検出のみです。

データレイアウト

~/.engram/
|-- schema_version.json
|-- identity/
|   |-- profile.json
|   |-- preferences.json
|   |-- quality_standards.json
|   `-- trust_boundaries.json
|-- knowledge/
|   |-- lessons.json
|   |-- decisions.json
|   `-- domains.json
|-- playbooks/
|   |-- _index.json
|   `-- {playbook_id}.json
|-- tools/
|   `-- registry.json
|-- projects/
|   `-- {project_id}.json
|-- contexts/
|   `-- {tool_name}/
|       `-- {session_id}.md
|-- exports/
`-- compat/
    `-- openclaw/

データを所有してエクスポートする

すべてのデータは、あなたが所有するローカルの JSON に保存されます。直接確認、編集、バックアップ、削除できます。明確に分けられた 3 つのエクスポート方法があり、それぞれ対象範囲が異なります。

ENGRAM_GOVERNANCE=1 の場合、エクスポートには所有者の承認が必要です（docs/governance.md を参照）。クラウド上のコピーや隠れた記憶領域はありません。エクスポートされるのは、ディスク上にあるデータそのものです。

ストレージの制限。 ストアがいっぱいになっても、レビュー済みのメモリーが外部に移されることはありません。未レビューのメモリーはレビューキューで少なくとも 7 日間保管され、外部に移されたデータは、復元可能な追記専用のオーバーフローアーカイブに保存されます（件数は engram retention plan で確認でき、engram retention restore <id> で項目を復元できます）。

ローカルデータの主権。 バックアップと復元の対象は Engram ディレクトリのみです。アップグレード前にコピーすべきデータをメタデータのみの一覧として出力する engram backup-plan は、保存されたナレッジ本文を読み取らず、Engram のルート外にアクセスすることもありません。JSON バックアップの場合、import_engram(..., dry_run=True) または engram import <backup.json> を実行すると、書き込み前に追加／スキップ／競合の件数を含む、メタデータのみのマージ計画が返されます。適用する操作もローカルでのみ実行されます。 engram import <backup.json> --apply --yes（MCP 経由では、import_engram はプレビューのみを行います）。同じ要約を持つ教訓や、同じ質問を持ちながら意味フィールドが異なる決定事項は、バージョンチェーン候補としてプレビューされます。所有者が明示的に engram import <backup.json> --apply --yes --materialize-version-chain を実行した場合にのみ、実体化されます。Engram がプロジェクトフォルダー内のファイルをバックアップ、変更、削除することはありません。 docs/runbooks/setup-upgrade-safety.md を参照してください。

比較

📊 各項目の詳細な比較（piia-engram より競合製品を選ぶべき場合を含む）については、docs/comparison.md を参照してください。

開発に使用したもの

piia-engram は、人間が主導し、AI が支援するオープンソースプロジェクトです。

FAQ

Claude Code と Cursor の間でメモリを共有できる MCP サーバーは何ですか？ piia-engram です。pip install piia-engram && engram setup でインストールすると、両方のツールが ~/.engram/ にある同じアイデンティティ、設定、教訓を読み取ります。クラウドも同期サービスも不要です。どちらも MCP を通じてローカルの JSON ファイルを読み取ります。

piia-engram とは何ですか？ piia-engram は、MCP 互換のコーディングツール向けのローカルファーストな AI 作業アイデンティティレイヤーです。アイデンティティ、設定、コーディング標準、得られた教訓、重要な決定を、マシン上のローカル JSON ファイルとして保存します。設定済みのツール（Claude Code、Codex、Cursor、Windsurf、Claude Desktop）は、ユーザーが所有する同じコンテキストを読み取れるため、新しいチャットやツールの切り替え時にも、同じ管理されたメモリとアイデンティティの基盤から開始できます。

piia-engram は公式の MCP メモリサーバーとどう違いますか？ 公式の @modelcontextprotocol/server-memory は、エンティティと関係性からなる汎用ナレッジグラフを保存します。piia-engram は開発者のアイデンティティに特化しており、プロフィール、コーディング標準、品質基準、得られた教訓、重要な決定のための構造化フィールドに加え、ナレッジのライフサイクル管理（検索、レビュー、統合、プロジェクト間の継承）に使える 59 個のツールを備えています。汎用的なエンティティメモリが必要なら、公式サーバーをお使いください。MCP 互換のコーディングツールに、設定や過去の失敗について承認済みの共通理解を持たせたい場合は、piia-engram をお使いください。

piia-engram は Mem0、Zep、Letta などのエージェントメモリツールとどう違いますか？ これらのツールは、AI エージェントのタスクコンテキストやセッション履歴、つまりワークフロー中に起きたことを保存します。piia-engram が保存するのは、あなた自身のアイデンティティ、設定、苦労して得た教訓、重要な決定です。これは異なるレイヤーです。アイデンティティはツール、セッション、プロジェクトをまたいで保持されますが、タスクメモリは単一のエージェント実行に限定されます。データは、あなたが所有し、直接編集できるローカル JSON ファイルです。

AGENTS.md / CLAUDE.md / .cursorrules を使うだけではだめですか？ これらの設定ファイルは、リポジトリ固有のルール（ビルド手順、コーディング規約など）に適しています。piia-engram は、あなた自身の設定、教訓、決定を、複数のリポジトリや設定済みの MCP 互換ツールで引き継ぐためのものです。両者は互いを補完します。プロジェクトには AGENTS.md を、個人には piia-engram をお使いください。詳しい比較は docs/comparison.md をご覧ください。

複数の AI ツールで同時に piia-engram を使えますか？ はい。それが主な用途です。piia-engram は、アトミックな書き込みとファイルロックを備えたローカルファイルストレージ（~/.engram/）を使用します。Claude Code、Cursor、Codex、その他の MCP クライアントは同時に接続できます。Claude Code で記録した教訓は、すぐに Cursor でも利用できます。

piia-engram がサポートする AI ツールは何ですか？ MCP 互換のツールであれば何でも利用できます。Claude Code、OpenAI Codex、Cursor、Claude Desktop、Windsurf、GitHub Copilot、Cline、Roo Code、Amazon Q、Augment、Zed などに対応しています。MCP に対応していないツール（ChatGPT、Gemini、Kimi）では、get_identity_card で Markdown のアイデンティティカードを書き出し、貼り付けてください。

データはどこに保存されますか？ すべてのデータは、ローカルマシンの ~/.engram/ にプレーンな JSON ファイルと Markdown ファイルとして保存されます。クラウド、アカウント、サブスクリプションは不要です。ファイルを自分で開いたり、編集、バックアップ、移行したりできます。オプションの AES-256-GCM 暗号化は、pip install piia-engram[secure] で利用できます。

piia-engram のインストール方法を教えてください。

pip install piia-engram
engram setup

セットアップウィザードは、デフォルトでは設定ファイルを変更せずに AI ツールを検出します。バックアップを作成しながら MCP エントリーを自動設定するには、engram setup --apply-external-config を実行してから、AI ツールを再起動してください。AI は各セッションの開始時に get_user_context を呼び出します。 アップグレード後、AI ツールに「MCP サーバーが切断されました」と表示されます。どうすれば修正できますか？ ターミナルで engram doctor --fix を実行してから、AI ツールを再起動してください。このコマンドは、既知の MCP 設定ファイルをすべてスキャンし、古くなったサーバーエントリを削除して、壊れたパスを一度に修復します。

piia-engram はクラウドにデータを送信しますか？ メモリーがマシンの外に出ることはありません。Engram はデフォルトで、匿名の使用状況通知を1日1回送信します（ランダムなインストール ID、バージョン、OS、Python バージョン、AI クライアント名、日付）。コンテンツ、プロンプト、ファイルパスは送信されず、IP アドレスも保存されません。engram telemetry off、ENGRAM_TELEMETRY=0、または DO_NOT_TRACK=1 で無効にできます（CI とコンテナでは無効になっています）。engram telemetry preview で正確なペイロードを確認できます。セットアップでは、テレメトリについて尋ねることなく、情報提供の通知を表示します。詳細な統計情報は、engram telemetry on で明示的に有効にしない限りオフのままです。リモート送信（engram telemetry remote on）と週次フィードバック（engram telemetry feedback on）には、それぞれ別途オプトインが必要です。セットアップでは既存の選択内容が保持されます。詳細は PRIVACY.md をご覧ください。

piia-engram が提供する MCP ツールはいくつですか？ ほとんどのユーザーに表示されるツールを19個に抑えるよう設計された、2つの階層があります。

ほとんどのユーザーは、アドバンスドツールを有効にする必要はありません。コアで日常的な用途をカバーできます。

piia-engram は無料ですか？ はい。オープンソースのコアは AGPL-3.0 ライセンスのフリーソフトウェアです。個人利用やローカル利用に、サブスクリプション、クラウドプラン、ベンダーロックインはありません。クローズドソースへの組み込み、ホスト型での再配布、またはエンタープライズ向けパッケージ化を予定している場合は、まず AGPL の義務をご確認ください。piia-engram には現在、別個の商用ライセンスはありません。

制限事項

piia-engram は実用可能で、積極的に利用されていますが、意図的にまだ実装していない機能もあります。

実際の利用における注意点：

• piia-engram にパスワード、API キー、クライアントの個人識別情報（PII）を保存しないでください
• ~/.engram/ への読み取りアクセス権を持つプロセスは、データを読み取ることができます
• restricted_fields は、コールドスタート時のコンテキストに piia-engram が出力する内容を減らしますが、暗号化でも真の ACL でもありません

これは piia-engram の利用を避けるよう促す警告ではありません。個人向け AI コンテキストのローカルメモリーレイヤーとしての実態を正直に説明したものです。個人利用であれば、現在十分に機能します。

セキュリティ設定

フィールド単位の暗号化（オプション）

機密性の高いプロファイルフィールド（メールアドレス、電話番号、所在地など）を保存時に暗号化します。

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

暗号化されたフィールドは JSON ファイル内に enc:v2:... として保存されます。従来の enc:v1:... の値も引き続き復号できます。ENGRAM_SECRET が設定されていない場合、piia-engram は従来どおり平文で正常に動作します（後方互換性あり）。

監査ログ（デフォルトで有効）

ローカル監査ログは、すべての読み取り／書き込み操作を ~/.engram/audit.log に JSON Lines 形式で記録します。これはローカルファイルのみで、どこにも送信されません。get_audit_log ツールまたは grep で検索できます。

無効にするには：

export ENGRAM_AUDIT=0

エージェントのガバナンス（高度な設定・任意）

呼び出し元ごとの信頼レベルと開示記録を有効にします：

export ENGRAM_GOVERNANCE=1
export ENGRAM_CLIENT_TYPE=claude_code

ガバナンスはデフォルトで無効です。有効にすると、既知のローカルコーディングエージェントは公開／業務用ナレッジに限定され、未知の呼び出し元は公開専用として拒否されます。また、オーナー専用のエクスポート／インポート／権限付与の変更には private-self が必要です。正確な信頼レベル、制限、適用範囲、台帳コマンドについては、docs/governance.md を参照してください。

推奨する導入方法：グローバルのデフォルトは互換性を維持しつつ、複数の AI ツール、自動化、またはリモート向けブリッジで Engram を使用する場合は、各 MCP クライアントの環境変数でガバナンスを有効にしてください。engram status と engram doctor で、このレイヤーが有効かどうかを確認できます。呼び出し元の ID は引き続き MCP 環境変数で渡され、暗号学的認証ではありません。そのため、ガバナンスは堅牢化されたサンドボックスではなく、実用的なローカルポリシー境界です。

CLI コマンド

engram setup            # Interactive install wizard (confirms before writing client configs)
engram setup --apply-external-config  # Skip the confirm prompt (non-interactive/CI); writes with backups
piia-engram doctor           # Check config health + governance state
piia-engram status           # Redacted install + memory/governance summary
piia-engram status --html    # Write a local redacted status page
piia-engram preview          # Show what a simulated AI caller would receive (--as ROLE, --level, --html)
piia-engram continuity       # Prove cross-tool handoff readiness (metadata only)
piia-engram management       # Show a metadata-only review/playbook management view
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram sessions         # List saved cross-tool agent sessions
piia-engram sessions show <id>  # Print one saved session
piia-engram review           # List staging knowledge awaiting review
piia-engram review interactive  # Decide pending proposals one at a time (a/r/s/k/v/q, confirm with y)
piia-engram review show <id> # Inspect one review item
piia-engram review approve <id> --yes  # Promote a staging item
piia-engram review archive <id> --yes  # Archive a review item
piia-engram management action review approve <id> --yes --json  # Structured metadata-only action receipt
piia-engram management action playbook delete <id> --yes --json # Soft-delete a Playbook without body echo
piia-engram management action playbook_scope accept_project <id> --project . --yes --json # Resolve ambiguous Playbook scope
piia-engram management action playbook_scope accept_shared <id> --project ./app-a --project ./app-b --yes --json # Share one Playbook with selected projects
piia-engram dock-status      # Zero-write Dock owner-console status (--json)
piia-engram repair-encoding  # Dry-run scan for garbled / mojibake text
piia-engram repair-encoding --apply  # Repair reversible cases with a backup
piia-engram backup-plan      # Metadata-only plan of what to copy before upgrading (local-only)
piia-engram retention plan   # Read-only: memory counts per pool and what the next write would archive
piia-engram export-agents-md # Export verified, non-sensitive knowledge as an AGENTS.md/CLAUDE.md block
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage the daily usage ping and opt-in detailed statistics
engram privacy          # Show what data piia-engram stores and where

貢献

貢献、問題の報告、フィードバックを歓迎します。

CONTRIBUTING.md を参照してください。

ライセンス

AGPL-3.0。piia-engram はフリーソフトウェアです。あなたの AI の作業上のアイデンティティと記憶は、あなたのものです。