# メモリモデル 統合方法を選ぶ前に、永続的な事実、決定事項、引き継ぎ、出所の帰属について理解します。 - Canonical: https://docs.xmemo.dev/ja/docs/concepts/memory-model - Locale: ja-JP - Content-Locale: ja-JP - Canonical-Content-Digest: 9ffe2da573b664ce4e37254715ed959c138dfd6b89262c6d0a1bda8dd473291a - Edition-Digest: 31f167dd0d17693519237b751056805109284d76b4401f5b6edc40242271d207 - Source-Revision: sha256:310bf66a9ffcf2384ebc6400fad1b1da9d01fa0cdadc9d129c9084e880334e73 ## XMemoが保存するもの XMemoは、現在のチャットやタスクが終わった後も役立つ永続的なコンテキストを保持します。プロジェクトの事実、決定事項、設定、修正、引き継ぎメモなどが対象です。一時的な会話のノイズ、一度きりの回答、未加工のツール出力はメモリに保存しません。 - semantic — セッションをまたいで有効な、永続的な事実と決定事項。 - episodic — タスクまたはセッション内の特定の時点に結び付いた出来事。 - procedural — このプロジェクトでタスクを実行する方法。 - working — 現在進行中のタスクのアクティブな状態。 - identity — 所有者またはエージェント自体に関する安定した情報。 ## 永続的なメモリを書き込む 永続的な書き込みには、content、プロジェクトまたはnamespaceに結び付ける論理的なpath、そしてmemory typeが必要です。後続のrecallはpathでフィルタリングされます。 ```ts remember({ content: "Use OAuth for hosted ChatGPT connections.", path: "projects/memory-os/decisions" }) ``` ## SDKで使うmemory type MemoryCandidate.memory_typeはTypeScript SDKでも同じ値の集合を受け取るため、正規化されたagent eventには保存すべきtypeが引き継がれます。 ```ts import { normalizeAgentEvent, toMemoryCandidate } from '@xmemo/client'; const event = normalizeAgentEvent( { type: 'command_completed', command: 'pytest', exit_code: 0, output: '12 passed' }, { source: 'shell', defaultAgentId: 'codex' }, ); console.log(toMemoryCandidate(event).memory_type); // episodic ``` ## インタラクティブな出所とライフサイクルのウォークスルー（合成デモ） メモリの作成、クライアント間検索、バージョン置き換え（v1 -> v2）を伴うリアルタイムユーザー修正、トークン予算の保護、ソフト削除廃棄記録、および分離された合成破棄を示すステップバイステップの検証可能なライフサイクルデモ。すべてのステップは、実際のユーザーメモリを一切公開しない使い捨てランタイム証拠によって裏付けられています: - ステップ 1 [STATE_1_CREATED_ACTIVE_V1]: Agent A (Claude Desktop) が tools.py::remember を介して不変の作成者、インスタンスハッシュ、デバイスメタデータを含む初期設定を書き込み — レシート: Status 200 OK, demo_mem_lifecycle_001@v1, active — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 - ステップ 2 [STATE_2_ACCESSED_ATTRIBUTED]: 同じ認可スコープ内の Agent B (Codex CLI) が tools.py::recall を介して引用レシート付きで即座にメモリを取得し、クライアント間ドリフトはゼロ — レシート: Status 200 OK, 引用 demo_mem_lifecycle_001@v1 — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 - ステップ 3 [STATE_3_CORRECTED_SUPERSEDED_V2]: ユーザーが tools.py::update_memory を介して会議室と時間を修正。VersionController は status='superseded' で v1 の不変スナップショットを作成し、アクティブレコードを v2 にバンプ — レシート: Status 200 OK, v2, 親 v1, 差分: Room Orion -> Room Polaris — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 - ステップ 4 [STATE_4_RETRIEVAL_FILTERED]: その後の recall クエリはアクティブな v2 のみを選択し、廃止された v1 は LLM コンテキストウィンドウから厳格に除外されて幻覚を防止しトークン予算を節約 — レシート: Status 200 OK, v2選択, 置き換えられたv1除外 — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 - ステップ 5 [STATE_5_TOMBSTONE_DELETED]: オーナーが tools.py::forget を介して事実を削除済みとしてマーク。リコール候補クエリから即座に除外され、復元アクション付きのごみ箱ビューに移動 — レシート: Status 200 OK, status: deleted, 候補数: 0 — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 - ステップ 6 [STATE_6_RESET_PURGED]: 分離された使い捨て破棄（reset_synthetic_state）により、デモスコープのレコードがディスク上で正確に0件の残存行にパージされる。個人アカウントのハードリセット（POST /api/v1/me/memories/reset）は厳格に除外 — レシート: teardown_status: SUCCESS_PURGED, residual_rows: 0, account_hard_reset_called: FALSE — 状態: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 境界: [DEMO_DATA: SYNTHETIC]。 ```text +------------------------------------------------------------------------------------------------------------------------+ | [PROVENANCE & LIFECYCLE 6-STATE STATE MACHINE: DISPOSABLE HARNESS WALKTHROUGH] | | | | Agent A (Claude Desktop) XMemo FastMCP & Engine Agent B (Codex CLI) Demo Owner (Supervising) | | [04f9b8c2 / MacBook] [VersionController / Scope] [e81d7a31 / Workstation] [user:demo_owner] | | | | | | | | (1) remember(sync in Orion) | | | | | -------------------------------------> | | | | | | [STATE 1: Created Active v1] | | | | <------------------------------------- | | | | | Receipt: mem-001@v1 | | | | | | | (2) recall(sync) | | | | | | <--------------------------- | | | | | | [STATE 2: Cited @v1] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v1 | | | | | | | (3) update_memory(Polaris) | | | | | <---------------------------------------------------------- | | | | | [STATE 3: Bump v2, Supersede v1] | | | | | ----------------------------------------------------------> | | | | | Receipt: mem-001@v2 (parent: v1) | | | | | | | | | | | (4) recall(Polaris) | | | | | | <--------------------------- | | | | | | [STATE 4: Select v2, | | | | | | Filter superseded v1] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v2 only | | | | | | | (5) forget(mem-001) | | | | | <---------------------------------------------------------- | | | | | [STATE 5: Tombstone / Trash View] | | | | | ----------------------------------------------------------> | | | | | Receipt: status=deleted | | | | | | | | | | | (6) reset_synthetic_state() | | | | | <---------------------------------------------------------- | | | | | [STATE 6: Teardown Purge] | | | | | Scope purged: 0 residual rows (account reset excluded) | | | | | ----------------------------------------------------------> | | | | | Teardown Status: SUCCESS_PURGED | | +------------------------------------------------------------------------------------------------------------------------+ ``` ## ChatGPT ユーザー bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。 ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。 合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。 OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。 ## Copilot / Codex 開発者 リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。 利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。 コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。 呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。 ## チーム / エンタープライズ pilot owner アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。 保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。 pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。 メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。 ## 自律エージェント operator headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。 /api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。 XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。 attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。