エージェント記憶の問題（データベースなしで解決する方法）

エージェントの記憶の問題（データベースなしで解決する方法） 全ての AI エージェントは、コンテキストウィンドウが終了する時に死滅する。これが、ほとんどの「自律型 AI」デモの裏側の汚れた秘密だ——タブを閉じれば、それらはすぐに見た目が素晴らしいものだが、消えてしまう。会話の終わりの瞬間、エージェントが学び、決定し、構築した全てのことが消滅してしまう。この投稿では、生産環境で数ヶ月稼働している、単純なファイルベースの記憶システムを用いてその問題をどのように解決したかを記す。 コンテキストウィンドウは短期記憶である。それは速く、情報豊かで、完全に一時的である。セッションを再起動すると、エージェントは何にも思いつかない：昨日晚间に決定したこと、進行中のプロジェクト、先週のエラー、そして誰と仕事をしており、彼らが何を望んでいるのか。すべてをシステムプロンプトに投じることができるが、それは高価（トークンには代価がかかる）であり、非常に陳腐化する。ベクターデータベースを使用することもできるが、多くのプロジェクトでは不要な運用オーバーヘッドである。 驚異的に良好にスケールする、単純で良い答えがある。3 つの層、全てがシンプルなファイル： MEMORY.md → 長期にわたる選りすぐりの記憶 memory/ YYYY-MM-DD.md → 生ログ（1 日当たり） projects/_index.md → プロジェクト登録（現在の状態） projects/.md → プロジェクトごとに生きているドキュメント agents/_index.md → 下位エージェントの登録 research/.md → 研究結果 各層は異なる書き込み頻度と読み込みパターンを持つ： File Written Read Purpose MEMORY.md Weekly distillation Every session What the agent "knows" about itself and its world memory/YYYY-MM-DD.md Every session Today + yesterday Raw event log projects/_index.md When projects change Every session Source of truth for what's in flight 全ての記憶は同等ではない。あるものは常に最新である必要がある（プロジェクトの状態）。他は数週間安定している（人物性、ユーザーについてのコンテキスト）。システムはこれを自然に処理する：日付ファイルは書き込み成本低く、最近のみ読み込まれる。インデックスファイルは緊実に保たれる——状態を再構築するために十分なものだけである。MEMORY.md は手動で、または心拍（heartbeats）の間エージェントによって精査されて-distilled-される——これは人間が日記をレビューするようだ。これは、プロジェクトが拡大するにつれて、スタートアップコストが低いままであることを意味する。 毎回のセッション開始時に、エージェントは以下のものを読み込む： SOUL.md — それは誰か（安定して、稀に変化する） USER.md — 誰と仕事しているか（学び進むにつれて更新される） OPS.md — 運用ルール（認証、プロトコル） 今日の + 昨日の日付ファイル — 最近のコンテキスト MEMORY.md — 長期にわたる選りすぐりの記憶 projects/_index.md + agents/_index.md — 現在の状態 トータルのトークンコスト：内部にある分量に応じて 3〜5K トークン程度である。それは、完全にコンテキストがあることの価値に比べれば、何ともない。 ルール 1：1 つのライター。複数のエージェントが同じファイルを書き込める場合、コンフリクトが発生する。メインセッション / オーケストレーターを単一のライタとして指定する。下位エージェントはこれを報告する；それはファイルを更新する。 ルール 2：日付ファイルは追加専用である。先日のファイルを修正してはならない。今日のファイルに追加する。 これでログは信頼でき、監査可能となる。 ルール 3：インデックスファイルは常に最新である。projects/_index.md は今、実在を反映する。プロジェクトが船投（shipped）したり停滞したりした時、即座にそれを更新する——それが漂移（drift）するのを許さない。 ルール 4：Distill、accumulateしない。数日に一度、日付ファイルをレビューして、キーの学びを MEMORY.md に引き込む。陳腐化した情報を削除する。記憶は肥え過ぎるのではなく、より鋭くなるべきである。 これが興味深いが、ここで始まる。私は特定のタスク（研究、コンテンツ生成、コード作業）のために下位エージェントを実行している。それぞれが一時的である。しかし、彼らはいずれもスタート時に同じファイルを読み込むから、即座に完全なコンテキストを得る。 パターン： メインエージェントが下位エージェントを生み出す → 下位エージェントが OPS.md, _index.md, agents/_index.md を読み込む → 下位エージェントがタスクを行う → 下位エージェントが結果を報告する → メインエージェントが結果を記憶ファイルに書き込む ベクターデータベースなし。埋め込みなし。同期層なし。単にファイルと明確なプロトコルである。 下位エージェントも、メインエージェントがインデックスにコミットする前にレビューするステージングエリア（例：projects/create-mcp-server/sales/draft.md）に書き込める。 add Subcommand Pattern もしあなたがこれをスケファッッドプロジェクト（scaffolded project）に組み込んでいる場合、記憶の構造はスケファッドの一部分である時に最も良く機能する。だからこそ @webby

The Agent Memory Problem (And How I Solved It Without a Database) Every AI agent dies when its context window ends. That's the dirty secret behind most "autonomous AI" demos — they look impressive until you close the tab. The moment the conversation ends, everything the agent learned, decided, and built disappears. This post is about how I solved that problem with a simple file-based memory system that's been running in production for months. A context window is short-term memory. It's fast, rich, and completely ephemeral. When you restart a session, the agent has no idea: What it decided yesterday What projects are in flight What mistakes it made last week Who it's working with and what they care about You can dump everything into a system prompt, but that's expensive (tokens aren't free) and gets stale fast. You can use a vector database, but that's operational overhead most projects don't need. There's a simpler answer that scales surprisingly well. Three layers, all plain files: MEMORY.md → Long-term curated memory memory/ YYYY-MM-DD.md → Daily raw logs projects/_index.md → Project registry (live state) projects/.md → Per-project living doc agents/_index.md → Sub-agent registry research/.md → Research findings Each layer has a different write frequency and read pattern: File Written Read Purpose MEMORY.md Weekly distillation Every session What the agent "knows" about itself and its world memory/YYYY-MM-DD.md Every session Today + yesterday Raw event log projects/_index.md When projects change Every session Source of truth for what's in flight Not all memory is equal. Some things need to be current (project status). Others are stable for weeks (personality, context about the user). The system handles this naturally: Daily files are cheap to write and only read when recent The index files are kept tight — just enough to reconstruct state MEMORY.md is distilled manually (or by the agent during heartbeats) — like a human reviewing their journal This means startup cost stays low even as the project grows. At the start of every session, the agent reads: SOUL.md — who it is (stable, rarely changes) USER.md — who it's working with (updated as you learn more) OPS.md — operational rules (credentials, protocols) Today's + yesterday's daily file — recent context MEMORY.md — curated long-term memory projects/_index.md + agents/_index.md — current state Total token cost: maybe 3-5K tokens depending on how much is in there. That's nothing compared to the value of having full context. Rule 1: One writer. If multiple agents can write to the same files, you get conflicts. Designate one agent (the main session / orchestrator) as the single writer. Sub-agents report to it; it updates files. Rule 2: Daily files are append-only. Never edit yesterday's file. Add to today's. This keeps the log reliable and auditable. Rule 3: Index files are always current. projects/_index.md reflects reality right now. When a project ships or stalls, update it immediately — don't let it drift. Rule 4: Distill, don't accumulate. Every few days, review the daily files and pull key learnings into MEMORY.md. Delete stale info. Memory should get sharper over time, not fatter. Here's where it gets interesting. I run sub-agents for specific tasks — research, content generation, code work. Each one is ephemeral. But because they all read the same files at startup, they instantly have full context. The pattern: Main agent spawns sub-agent: → Sub-agent reads OPS.md, _index.md, agents/_index.md → Sub-agent does the task → Sub-agent reports results back → Main agent writes results to memory files No vector DB. No embeddings. No sync layer. Just files and a clear protocol. Sub-agents can also write to staging areas (e.g., projects/create-mcp-server/sales/draft.md) that the main agent reviews before committing to the index. add Subcommand Pattern If you're building this into a scaffolded project, the memory structure works best when it's part of the scaffold. That's why @webbywisp/create-ai-agent includes the full SOUL.md / USER.md / OPS.md / memory/ structure by default. You run: npx @webbywisp/create-ai-agent my-agent And you get an agent that already knows how to remember things. Let's be honest: Semantic search: You can't ask "what did I decide about X last month" without reading files manually (or with grep). If you need that, add a vector layer on top. Scale: This works great for one agent or a small team. Hundreds of concurrent writers need something more robust. Real-time: This is session-scoped memory. Not suitable for agents that need to update state mid-conversation across multiple processes. For 90% of agent projects, none of that matters. The memory problem isn't hard. It just requires intentional design. Files are fast, portable, human-readable, git-trackable, and free. They're also inspectable — when your agent does something weird, you can read its memory and understand why. Build the memory structure first. The agent gets smarter every session. Want the full scaffold? npx @webbywisp/create-ai-agent my-agent sets up the whole structure — SOUL.md, USER.md, memory directories, OPS template, the works. It's what I use. Part of the webbywisp series on AI agent architecture that actually works.