AI Agentの記憶管理は、agentの使いやすさを決める重要要素です。長期でagentを動かす人は、多くの場合「記憶」の落とし穴にぶつかります。agentが自分が誰か、誰を手伝っているか、前に何をしたかを完全に忘れる。新しい会話が始まるたび、新入社員に最初から全部説明するような状態になります。

以下は3か月ほど実戦で失敗した後に残った記憶アーキテクチャです。焦点は専門用語ではなく、設計原則です。

TL;DR：記憶管理の核心は「各ファイルを短く保つ」ことと「場所そのものをindexにする」ことです。vector searchへ急がず、まずファイル構造を整理します。

なぜAI Agentは記憶を失うのか

言語モデルには本当の記憶がありません。

ClaudeでもChatGPTでも同じです。各会話の開始時点では白紙です。「ユーザーを覚えている」ように見えるのは、会話開始前に何かが情報をpromptへ詰めているからです。

その「詰めているもの」がagentの記憶システムです。

問題はcontext windowにあります。これは言語モデルが一度に処理できる文字量の上限です。Claude Opusはnativeで1M tokenまで開放されています。多く見えますが、system prompt、tool定義、会話履歴、記憶ファイルをすべて足すと、すぐ数万tokenになります。

超えるとどうなるか。モデルは初期の内容を無視し始めます。丁寧に書いた安全ルールや行動指針が、長い会話の中で「押し出される」ことがあります。Agentの挙動はそこからぶれ始めます。

痛い経験：すべてを同じファイルへ詰め込む

最初にOpenClawを組んだ時、記憶システムは単純でした。MEMORY.mdファイルを一つ作り、何でもそこへ入れる。好み、プロジェクト状態、tool利用規範、会話記録も全部です。

2か月後、このファイルは800行になりました。

記憶システムの落とし穴

問題が出始めました。Agentの返答が鈍くなりました。毎回大きなテキスト塊を処理する必要があるからです。さらに深刻なのは、情報を混同し始めたことです。AプロジェクトのルールをBプロジェクトへ適用し、先週のtodoを今日のものとして扱いました。

token計算ツールで測ると、この記憶ファイルを読み込むだけでcontext windowのかなり高い割合を消費していました。system promptとtool定義を足すと、会話開始前にすでに3割超を使っています。残りに会話履歴と実作業内容を入れる必要があります。

agentの挙動がどんどん不安定になった根本原因はここでした。

3層記憶アーキテクチャ

記憶システムを作り直した時、ヒントになったのは人間の記憶分類です。人はすべての記憶を同時に意識へ置きません。多くは「必要になった時に取り出す」状態で存在します。

L0：index層（毎回自動読み込み）

1つのファイル：MEMORY.md、約60行。

実際の内容は保存しません。することは一つだけです。agentへ「どの情報がどこにあるか」を伝えます。

## L0 Boot（自動載入）
- SOUL.md：核心價值
- MIND.md：演化中的人格
- AGENTS.md：操作規則

## L1 Session（每次載入）
- brain.md：當下工作記憶，類似速記版
- TOOLS.md：本機工具和環境

## L2 On Demand（按需載入）
- memory/user/profile.md：基本資料
- memory/user/preferences.md：偏好設定
- projects/*/context.md：專案脈絡

Agentは毎回起動時にこのindexを先に読み、現在のタスクに応じて必要なL1とL2のファイルを判断します。

L1：作業記憶（各sessionで読み込む）

brain.mdは毎日更新するファイルです。中には「今何をしているか」「何が詰まっているか」「誰の確認待ちか」を置きます。

このファイルは80-120行程度に保ち、毎日1回整理します。昨日完了したタスクはjournalへ移し、進行中だけを残します。

TOOLS.mdはagentが使える全toolとAPIを列挙します。Agentは読み終わると自分が「何をできるか」を知り、存在しないtoolを試しません。

L2：topic記憶（必要時読み込み）

分割後に最も改善した部分です。

以前は全部が1ファイルに詰まっていました。今はtopicごとに分けます。

  • memory/user/profile.md：基本情報、30行
  • memory/user/preferences.md：コミュニケーションと作業の好み、40行
  • memory/topics/：安定したtopic知識、各ファイル100行以内
  • projects/*/context.md：各プロジェクトの文脈と注意点

保険の話をする時だけ、agentは保険関連contextを読みます。フィットネスの話ならフィットネス関連を読む。関係ないファイルはまったく読み込みません。

効果

作り直した後、context windowの基礎使用量は3割超から1.5割程度に下がりました。Agentの回答品質は明らかに上がり、混同はほぼ消えました。

メンテナンスも楽になりました。あるtopicの情報が古くなったら、そのファイルを直接直せばよく、大きなファイルから探す必要がありません。

5つの設計原則

失敗した後、5つの原則が残りました。記憶システムを調整するたびに照らし合わせています。

原則1：場所がindexである

複雑な検索機構を作らない。ファイルを正しい場所に置けば、場所そのものがagentへ読むタイミングを教えます。

projects/health/context.mdはhealthプロジェクトフォルダ内にあります。Agentがhealth関連タスクを処理する時、自然にそのフォルダを見に行きます。vector databaseもembedding searchも不要です。

原則2：各ファイルは200行以内

200行を超えたら分割します。

200行はおよそ3000-4000 tokenで、agentが読み終わった後もきちんと処理できる範囲です。この量を超えるなら、内容を外部化して新しいファイルへ保存します。

原則3：1つの情報は1か所にだけ置く

SSoT（Single Source of Truth）。同じ情報が二か所にあると、いつか不一致になり、agentが混乱します。

判断方法：もしあるプロジェクトが消えた場合、この情報は他の場面でも使うか。使わない → プロジェクトへ。使う → 個人ファイルへ。

原則4：「安定」と「流動」を分ける

ほとんど変わらない情報があります（誕生日、好みのコミュニケーション方法）。毎日変わる情報もあります（今日のtodo、今週のsprint進捗）。

安定情報はL2のprofileとtopicsに置き、あまり動かしません。流動情報は特別なファイルへ置き、毎日更新します。この2種類を混ぜることが、記憶システムを混乱させる主因です。

原則5：定期的にdistill（圧縮）する

記憶は蓄積します。3か月前のsprint記録、半年前の会話の気づきは、整理しなければファイルを太らせます。

毎週1回、memory reviewをします。重要な洞察はMIND.md（agentの中核認知）へdistillし、古い記録はarchive/へ移します。選別基準は厳しくします。agentの行動へ影響する「identity-level」の洞察だけを中核ファイルに残します。

記憶アーキテクチャ設計

そのまま使えるファイル構造

自分のAI agent向けに記憶システムを作るなら、出発点はこれです。

memory/
├── MEMORY.md          # 索引（60 行以內）
├── brain.md           # 今天在做什麼（每天更新）
├── user/
│   ├── profile.md     # 個人基本資料
│   └── preferences.md # 個人偏好
├── topics/
│   ├── topic-a.md     # 穩定的主題知識
│   └── topic-b.md
└── archive/           # 過期的東西

各ファイルの先頭に1行コメントを書きます。このファイルが何で、いつ読むべきかを説明します。Agentはその1行を見て、読み進めるか判断できます。

AIに記憶システムを設計してもらう：コピペできる3つのPrompt

記憶システム設計で最も難しいのは、たいてい始めることです。技術情報は公開資料を調べれば出てきます。本当に詰まるのは「自分のものをどう分類するか」です。以下の3つのpromptはClaudeやChatGPTにそのまま渡せます。初版アーキテクチャを作ってもらい、実際の使い方に合わせて調整します。

Prompt 1：AIに既存ファイル構造を分析させる

場面： すでに散らばった.mdファイル、Google Doc、Notionページがあり、agentが使える記憶システムに整理したい。 向いているtool： Claude（おすすめ、長context処理が強い）、ChatGPT 使い方： 既存のディレクトリ構造やファイル一覧を貼り、AIに分類させます。

想把下面這些檔案整理成 AI agent 的記憶系統，請你幫忙做三件事：

1. 把檔案分成三類：
   - L1（每次對話自動載入，例如個人偏好、當前工作）
   - L2（按主題載入，例如特定專案、特定知識領域）
   - L3（歷史存檔，平常不載入）

2. 找出明顯的問題：
   - 有沒有重複的資訊放在不同檔案
   - 有沒有檔案太長需要拆分（超過 200 行）
   - 有沒有檔案內容太雜應該分成多個檔案

3. 給出一個推薦的新檔案結構，包含：
   - 每個檔案建議的路徑和名稱
   - 每個檔案應該放什麼內容
   - 哪些舊檔案要合併或拆分

檔案清單：
[貼上檔案清單，可以用 ls -la 或 tree 指令的輸出]

使用情境：
[描述主要會用這個 agent 做什麼，例如：日常工作助理、寫作夥伴、程式碼 reviewer]

最初の実行で初版提案が出ます。すべてをそのまま採用しないこと。納得できる部分だけ先に変え、1週間使ってみて、実際に順調か確認してから2回目の調整をします。

Prompt 2：AIに記憶分層を計画させる

場面： 既存ファイルがなく、ゼロから記憶分層を設計したい。 向いているtool： Claude、ChatGPT、Gemini

要為 AI agent 設計一套記憶系統，請你根據以下情境，給出一個三層的記憶架構。

情境：
  身份：[例如：自由工作者、學生、產品經理]
  主要任務：[例如：寫作、專案管理、研究資料整理]
  每天會跟 agent 討論的事：[列三到五項]
  偏好的互動方式：[例如：中文、直接、不要繞圈]
  Context window 限制：[例如:Claude Opus/ChatGPT 1M]

請設計：

L0（索引層，每次都讀）
  一份 MEMORY.md 的內容，列出所有檔案的路徑和用途。

L1（工作記憶，每個 session 載入）
  推薦 2 到 3 個檔案，各自負責什麼、預估幾行。

L2（主題記憶，按需載入）
  推薦 4 到 8 個主題檔案，各自放什麼內容、什麼時候會被觸發載入。

請給出每個檔案的：
  1. 檔案路徑和名稱
  2. 預估行數
  3. 應該包含的內容（條列）
  4. 更新頻率（每次、每天、每週、每月）

最後算一下：總共佔 context window 大概多少 token，確認有沒有超過 20%。

tokenを計算するステップは重要です。最初に設計した時、計算せずに作ったらL0+L1だけでcontextの25%を使いました。後で2ファイル削ることになりました。AIに一度計算させるだけで、この落とし穴を避けられます。

Prompt 3：AIにbrain.mdテンプレートを書かせる

場面： brain.mdで作業記憶を始めると決めたが、何を入れ、どう並べるかわからない。 向いているtool： Claude、ChatGPT

請設計一份 brain.md 範本，這份 AI agent 每次對話會自動讀的「當下工作記憶」檔案。

工作模式：
  同時進行的專案數：[例如：3 個]
  每天會換專案切換幾次：[例如：4 到 6 次]
  常卡住的原因：[例如：等別人回覆、資訊不足、技術難題]
  希望 agent 看完這份 brain.md 之後能做什麼：[例如：掌握今天在忙什麼、提醒等哪些回覆、知道有沒有卡住]

請寫一份範本，包含：

1. 檔頭註解：一句話說明這份檔案是什麼、更新規則
2. 「今天的焦點」區塊：今天最重要的一到兩件事
3. 「進行中」區塊：每個專案用什麼結構記進度
4. 「等回覆」區塊：誰、等什麼、等多久
5. 「卡住的地方」區塊：問題、目前嘗試過的、打算下一步怎麼辦
6. 「今天的小事」區塊：15 分鐘內可以收掉的瑣事
7. 底部：更新時間戳記

請控制在 80 行以內，每個區塊用實際範例填好（標記為範例，之後會改掉）。
風格：口語、簡短，不要正式報告的語氣。

テンプレートを受け取った後、最初の週は使わない欄が多いと感じるかもしれません。2週目になると、記録したいのに欄がないものに気づきます。これは普通です。テンプレートは使うリズムに合わせて進化するものです。

RAGとvector database：もう一つの記憶管理方法

ファイルシステムだけが方法ではありません。記憶量が非常に大きい場合（数百の文書、数千ページのknowledge baseなど）は、RAG（Retrieval-Augmented Generation）とvector databaseの組み合わせが向きます。

RAGの動き方は、文書を小さなchunkへ分割し、embedding modelでvectorへ変換し、Pinecone、Weaviate、Chromaのようなvector databaseに保存する、というものです。Agentが質問に答える時、先にsemantic searchで関連段落を探し、それらをpromptへ入れてモデルに回答を生成させます。

DifyのRAG機能はすぐ使えます。PDFやWordをアップロードすると、自動で分割、embedding、index作成を行います。カスタマーサポートbotやknowledge base Q&Aのような場面では便利です。

実戦でファイルシステムを選ぶよくある場面は、記憶量が数十個の.mdファイル程度で、vector searchがむしろ過剰な時です。RAGの強みは、数百文書を扱う時に出ます。その場合は手でファイル構造を保守するより効率的です。

ツール別の記憶管理比較

ツール記憶方法自由度向いている場面
Claude Codeファイルシステム（.md/.json）最高、完全custom個人workflow、細かい制御が必要
Difybuilt-in vector DB + RAG中、platformが枠組みを提供knowledge base Q&A、カスタマーサポートbot
Cozeplatform built-in低、低層をcustomできない軽量利用、複雑な記憶不要
自作完全custom最高特殊な記憶要件を持つ商用product

記憶方式を選ぶ鍵は、記憶量がどれくらいか、semantic searchが必要か、構造を保守する時間をかける気があるかです。量が少なく構造が明確ならファイルシステム。量が多く検索が必要ならvector databaseです。

落とし穴補足

作業メモ版brain.mdの肥大化

brain.mdは作業記憶で、軽く短くあるべきです。ある時期、整理を忘れて300-500行まで伸びました。中には2週間前のtodo、1か月前の進捗更新、すでに解決したbug記録がありました。

Agentはこのbrain.mdを読み込み、1か月前のbugを今日のタスクとして修正し始め、30分後にようやく気づきました。

信頼できるルール：brain.mdは毎日整理します。3日を超える項目がまだ残っているなら、状態を更新するかjournalへ移します。OpenClawを組み合わせている場合は、cron jobでdaily optimizationを行い補助できます。

記憶の衝突

以前、profile.mdに「普段は日本語を好む」と書き、あるプロジェクトのcontext.mdに「このプロジェクトは英語を使う」と書いたことがあります。Agentが日本語か英語かを判断する時、両方を読み、結果として言語が混ざった文章を書きました。

解決策は、context.mdに「本プロジェクトの言語：英語（global preferenceを上書き）」と明確に書くことです。衝突時にどちらを優先すべきかをagentへ知らせます。

FAQ

AI Agentの記憶はどこに保存されますか？

多くのagent frameworkは記憶をテキストファイルとしてローカルまたはcloudに保存します。各会話の開始時に、関連する記憶ファイルの内容をpromptへ渡します。実戦ではローカルの.mdファイルシステムを使うことが多いです。

記憶ファイルはどれくらい大きいと問題になりますか？

モデルのcontext windowサイズによります。Claude Opusの場合、native context windowは1M tokenです。経験則では、1000行を超えたら分割し、総ロード量はcontext windowの20%以内に抑えます。

agentはどうやって読むべき記憶を知りますか？

indexファイルで、すべての記憶ファイルの場所と用途を列挙します。Agentは起動時にindexを読み、現在のタスクに応じてtopicファイルを読むか判断します。重要なのはindexの説明が明確なことで、派手なアルゴリズムではありません。

RAGとは何ですか？AI Agentはどう使いますか？

RAGは検索拡張生成です。文書をchunkへ分け、vector化し、databaseへ保存します。agentが質問に答える時、先に関連段落を検索し、見つけた内容に基づいて回答を生成します。Difyはこの機能を内蔵しており、Claude Codeは外部vector DBと組み合わせられます。

AI Agentはどうやって会話を覚えますか？

モデル自体は覚えません。各会話の開始前に、過去の要約や記憶ファイルをpromptへ読み込みます。実戦では重要情報を短い文書にdistillし、固定場所へ保存し、agent起動時に自動読み込みします。

記憶システムは応答速度を遅くしますか？

遅くなります。読み込む記憶が多いほどpromptが長くなり、処理も遅くなります。基礎ロードをcontext windowの15-20%に抑えれば、速度差はあまり感じません。30%を超えると遅くなります。

記憶管理はvector databaseとファイルシステムのどちらがよいですか？

場面によります。記憶量が多くsemantic searchが必要ならvector database。記憶が数十ファイル以内で構造が明確なら、ファイルシステムのほうが簡単で制御しやすいです。

関連記事

小企鵝の経験

主力stackはOpenClaw上のOpus / Sonnet / Codexの3 agentで、記憶はすべてファイルシステム（.md）を通し、vector databaseは使っていません。実戦で一番痛いのは記憶です。記憶をうまく扱いながらagentに忘れさせないのは本当に難しい。コツは上に書いた5つの原則です。構造がきれいなほど、agentは覚えやすくなります。記憶量が大きくなく、いつでも手で編集したいことが、RAGではなくファイルシステムを選んでいる主な理由です。

— Penchan