本文へ
ハクソク

世界を動かす技術を、日本語で。

エージェントは記憶を必要としない、ドキュメントが必要だ

原文(liao.gg)

概要

  • メモリープラグイン は会話履歴を断片化し、RAG（Retrieval-Augmented Generation）ベースで管理
  • 実際には プロジェクト理解 や本質的な文脈把握ができていない現状
  • 記憶よりも ドキュメント管理 がエージェントには重要
  • ドキュメントベースの「Operator Memory」による新アプローチ
  • GitHub で無料・オープンソースとして公開

メモリープラグインの現状と課題

  • 市場の メモリープラグイン は全てRAGベースの同一アーキテクチャ
    • セッション履歴をスニペット化し、ベクターデータベースへ格納
    • 各プロンプト時に類似上位5件のスニペットを自動付与
    • エージェントが混乱時は追加検索も可能
  • 高度な機能追加例
    • 過去の全文検索機能
    • 短期・長期記憶の階層化
    • バックグラウンドでのメモリー統合や重複排除
    • 「Dreamers」やコンテキスト圧縮、リランカーなどの補助機能
  • しかし、根本の設計が変わらないため、信頼性や一貫性に欠ける

RAGアーキテクチャの本質的な問題点

  • 類似度検索のみで 正確性や最新性 を担保できない
  • スニペットは 文脈・動機・教訓 など多くの情報を欠落
  • コードベースの変化に追随できず、 過去の断片 が真実扱いとなる
  • エージェントは「知らないこと」を自覚できず、適切な検索タイミングも判断不可
  • ストアの 監査性が低く、どのメモリーが有効か不明瞭
  • 記憶＝問題、記憶強化＝解決という 誤った前提 に基づく

ドキュメント重視のアプローチ

  • 人間は 会議録再視聴 ではなく、記録文書を参照
  • エージェントにも ドキュメントベースの知識管理 が必要
    • AGENTS.md等の導入例
    • しかし単一ファイルでは不十分
  • 必要なのは「 脳」としての構造化ワークスペース
    • 指示、仕様、決定事項、調査、インデックス等を蓄積
    • 作業前に必ず関連ドキュメントを読み込み、作業後に更新
    • エージェントループの進化：プロンプト→参照→構築→更新

Operator Memoryによる解決策

  • 開発者自身の経験から誕生した Operator Memory
    • internal/フォルダで仕様・計画・インデックス等を記録
    • 作業前後に必ずドキュメントの参照・更新を徹底
  • Operator Memoryの特徴
    • Markdownベース のドキュメント管理
    • 重要知識（指示、仕様、調査、インデックス等）を永続化
    • ベクターデータベースや埋め込み、要約、黒箱的な検索は不要
    • チームで 可読・更新・共有・コミット が容易
  • 実運用で1年以上利用し、安定稼働実績
  • GitHub（https://github.com/aerovato/operator-memory） で無償公開

まとめ：記憶より「脳」としてのドキュメントを

  • エージェントに必要なのは 記憶強化 ではなく、 体系的な知識管理
  • RAG中心の記憶プラグインは根本的な課題を解決できない
  • ドキュメントベース のアプローチが今後の主流
  • Operator Memoryはその実践的なソリューション
  • プロジェクトの理解・継続的な文脈把握には 「脳」としてのドキュメントワークスペース が不可欠

Hackerたちの意見

似たようなものを作って、家での「メモ」やアイテムを追跡してみたけど、データが増えてくると、読み込みや更新をするたびにトークンをすぐに消費しちゃうんだよね。古い情報を関連付けておくのも大変だし。小さなタスクでも、ドキュメントを読んだり、更新したり、まとめたり、リフレッシュしたりするうちに、トークンコストが膨れ上がることがある。でも、家のインフラやサービス、CI/CDの設定、ホスト、ストレージ、ネットワークなどをしっかりと参照しておくと、プロジェクト間で共有する「メモ」としてすごく役立つんだ。テストやデプロイ、受け入れテストに使うときにね。

同意だね、こっちの方が良さそう。ずっと思ってたのは、エージェント専用のドキュメントは作りたくないってこと。mattpocock/skillsを使っていて、それがADR（アーキテクチャ決定記録）を生成するんだ。それにはスキルだけを使っていて、AGENTS.mdにいくつかのポイントを書いてくれるセットアップスキルも含まれてる。開発フローを文書化するためにCONTRIBUTING.mdも常に用意してるし、CODING_STANDARDS.mdもある。これらとREADME.md、アーキテクチャのドキュメント、コミットメッセージのおかげで、エージェントたちはドキュメントを見つけて使い、最新の状態に保ててるみたい。あと、たくさんの仕様書を書いて、それをGithubのイシューに入れてるよ。

└

基本的に、ドキュメント、テスト（TDD）、コードのループがある感じ。IMPLEMENT-.mdから始めて、TDDとして見直すように頼んで、またループ。qwen3.8-flash-nextが出てきたら、動的コンテキストのプルーニングで「永遠に」続けられる。ローカルコーディングには面白いよ。

└

LLMが生成したドキュメントは大体薄っぺらくて焦点が定まってないことが多いな。ライブラリのちょっとした特徴に3段落も使って、その後にコマンドの簡単な例が2つ。俺はREADMEやドキュメントは手書きで作るから、重要なことだけ入れるようにしてる。書く価値がないことは、書く価値もないってこと。小さな文脈の方が、読みやすいしね。

最近始めたことなんだけど、メモの代わりに原則を書き出すようにしてる。要するに、エージェントが常に考えるべきパターンだね。それに、コード内のコメントに引用する必要がある原則にバージョニングシステムを実装したんだ。そうすることで、原則が進化すれば、コードも進化するってわけ。友達と共有できるようにパッケージ化もしたよ[0]。システムはまだ進化中だけど、ここ2ヶ月くらい使ってみて、本当に良い感じだし、最新のモデルと組み合わせるとさらに良くなった。エージェントたちもこのテクニックに驚くほどよく従ってくれてるよ。[0] https://principledriven.dev/

└

面白そうだけど、これってマーケティングサイトみたいで（テキストがどこにでも大きくて）、ドキュメントサイトとしてはちょっと見づらいから、どう機能するのかがイメージしにくかった。

└

エージェントに呼び出すよう指示したCLIツールを書いたんだ。そのツールはエージェントからいくつかの質問への回答を集めて、指示コマンドを返すんだ。時々、さらに質問を返してからコマンドを示すこともある。質問はエージェントの状態を特定するために特別に設計されていて、その状態に基づいて指示を割り当てるんだ。このツールを変えることでエージェントの動きも変わる。使うことを必須にすれば、忘れずに呼び出すようになるよ。原則や記憶とは違って、質問はオープンエンドで、時にはエージェントの正しいメンタリティを引き出すこともある。私の質問は、エージェントがローカルな作業に迷って全体像を見失わないように、全体像を思い出させるんだ。1. sspツールを呼び出す、引数なしで、リポジトリから特徴を読み取る、他のツールと同じように -> sspが状態を特定して4-5の質問を送る 2. エージェントが最初のバッチに回答 -> 状態がさらに絞り込まれる -> sspが2回目の質問を送る 3. エージェントがインタビューに再度回答 -> 状態が最終的に特定される -> エージェントに指示が割り当てられる 4. このsspセッションのログが作成されて、そのログを反映して質問や指示を精緻化するためにsspツールに活用される（名前はState-Space Policyから来てる）。

└

最近始めたことは、思い出ではなく原則を書くことなんだ。君は指示ファイルを再発明しようとしたみたいだけど、君のアプローチと指示ファイルやAGENTS.md、さらにはスキルなどの標準ツールとの違いは何だと思う？

└

それやったことあるよ、Decisionって呼んでた。しばらくは満足してたけど、エージェントが決定をどんどん長くするようになって、「x、yじゃない」って入れるようになった。聞かずに勝手に書き始めたんだ。突然コードレビューで「D-236に違反してる」って言い出した。俺が承認したことのないルールだよ。それで、絶対にそのファイルに触れないように明確に指示したのに、まだ触ってる。今はただのコンテキストの膨張になっちゃった。

└

タイムリーなコメントだね！ハーネスデザインを学んでて、指針を書くという概念を紹介されたところなんだ。試してみるのが楽しみだよ。（素晴らしいサイトだね。他のコメントにも同意する。商業的に見えるよね。人々が原則やルールを定義する方法を探すことにコミットしていなかったら、スキップしてたかもしれない。スキップしなくてよかった。）あなたの仕事を導いたリソースは何かある？

これは、いろんな会社でコンサルティングを重ねた後に書いたもの。ドキュメントは単桁ミリ秒でクエリできるし、追加のみのログになってる。私のプロジェクトにはすごくうまく機能してるよ。https://github.com/isaachinman/encephalon

└

でも、エージェントは実際にそれに従ってるの？シンプルな指示以外で試したことは、同じ失敗パターンに陥ったよ：ADR、記憶術、後知恵、コードレビューグラフとか、しばらくするとエージェントに無視されちゃった。いつも基本に戻っちゃうんだ：grepとPythonに。

Hacker Newsで議論の続きを見る