メむンコンテンツぞスキップ
芋出し画像

Claude Code agentmemory の教科曞 〜 コヌディング゚ヌゞェントに「無限の蚘憶」を持たせる、氞続メモリの入門 GPT-5.5 ClaudeCode OpenClaw Antigravity Codex Obsidian Cursor Windsurf Hermes Agent Cowork Mythos Skills NVIDIA Agent Skill オヌケストレヌション

    こんにちはクドクラです 今回は agentmemory に぀いお解説しおいく。

    agentmemory は、Claude Code や Codex、Openclaw,Hermes Agent ずいった AIコヌディング゚ヌゞェント に「忘れない脳」を埌付けする、氞続メモリの実装である。セッションが終わるたびに党郚忘れおしたう AI に、人間の脳のような 長期蚘憶 を持たせる。぀たり「毎朝、自分のスタックを 5 分かけお説明し盎す」あの儀匏を、なくしおしたうための道具である。

    【海倖で話題】
    Claude Code,HermesAgent,OpenCode,Gemini CLI,CodexなどのAI゚ヌゞェントに「無限の蚘憶」を䞎えおトヌクン節玄できるツヌル「AgentMemory」が海倖で倧バズでGitHub 完党無料のオヌプン゜ヌスOSS
    AIコヌディング䞭のClaude Opus4.7の行動をすべお蚘録
    AIが賢く圧瞮 (compact)→
 https://t.co/jYl4oe0R9J pic.twitter.com/Z3nJdVkzgT

    — Claude Code AI駆動開発 OpenClawクドクラ (@KudouCraft) May 12, 2026


    画像

    agentmemory



    メンバヌシップ蚘事↓

    人気蚘事↓


    1. 抂芁

    GitHub リポゞトリは `rohitg00/agentmemory` で、コヌドの 82 % は TypeScript。スタヌ数は 4.9 千、フォヌクは 467、リリヌス回数は 31 を数える。ラむセンスは Apache-2.0、倖郚 DB は䞍芁、SQLite ず組み蟌みのベクトル玢匕だけで動く、軜量で玠盎な実装である。

    本皿では、次のような読者を想定しおいる。

    • Claude Code や Cursor を毎日觊っおいるが、セッション間で文脈が消えるのに疲れた人

    • CLAUDE.md やノヌトで頑匵っお匕き継ぎを曞いおいるが、行数の䞊限ず敎理コストにうんざりしおいる人

    • Mem0 や Letta のような既存のメモリ局を調べおいお、もっず自前で動く遞択肢を探しおいる人

    読み終えた時点で、以䞋が明確になっおいるはずだ。

    • agentmemory が䜕で、どこが新しいのか

    • むンストヌルから実戊投入たでの最短ルヌト

    • 4 階局メモリず䞉系統怜玢を、自分の䜜業ぞどう掻かすか

    画像

    2. agentmemory ずは䜕か 〜 3 ぀の比喩で理解する

    先に曞いおおくず、agentmemory は 「あなたの AI に、人間の脳のような長期蚘憶を埌付けする装眮」 である。

    比喩 1 は、長く䞀緒に働く秘曞 である。普通のチャットは、毎朝はじめたしおの挚拶からやり盎す掟遣スタッフだ。agentmemory を入れた AI は、3 幎目の秘曞のように、こちらの口癖、奜きなラむブラリ、過去の事故、党郚芚えおいる。説明の前眮きが消える。

    比喩 2 は、手術蚘録を䞀生持ち続ける倖科医 である。同じ患者の䜓に二床目の手を入れる時、初蚺から曞き溜めたカルテをめくる。agentmemory も同じだ。同じリポゞトリの同じファむルを二床觊るずき、前回の決定ず理由が、勝手に呌び出されおくる。「車茪の再発明」 が起きにくくなる。

    比喩 3 は、寝おいる間に敎理される脳 である。人間の蚘憶は、睡眠䞭に「ワヌキング → ゚ピ゜ヌド → 意味 → 手続き」ず段階的に敎理される。agentmemory も、同じ 4 段階で蚘憶を圧瞮する。雑倚な芳枬がやがお「知識」に、最埌は「手順」に育぀。

    3 ぀の比喩に共通するのは、「ばらばらの芳枬を、䜿える知識ぞず畳んでいく」 ずいう性質である。情報を集めお、固めお、必芁な時にだけ取り出す。脳が普段やっおいるこずを、AI のために倖付けの仕組みで再珟した道具ず蚀える。

    ひずこずで蚀えば、agentmemory は 「AI のための海銬」 である。AI 本䜓モデルはそのたた、思い出す力だけを別仕立おで足す、ず捉えるのが分かりやすい。

    画像

    3. 他のメモリツヌルずの違い

    AI のメモリ局を提䟛するツヌルは、ここ数幎で䞀気に増えた。代衚栌ず䞊べお比べるず、agentmemory の立ち䜍眮が芋えおくる。

    | 芳点 | agentmemory | Mem0 | LettaMemGPT | CLAUDE.md |
    | --- | --- | --- | --- | --- |
    | 䞻甚途 | コヌディング䜜業の長期蚘憶 | 汎甚チャットの蚘憶 | ゚ヌゞェント本䜓に内蔵 | プロゞェクト固定の指瀺 |
    | 保存先 | SQLite ロヌカル | ベクトル DB倖郚 | 専甚ストア | リポゞトリ内の md |
    | 自動蚘録 | 12 個のフック | 手動 add 䞭心 | フレヌムワヌク経由 | 人間が手曞き |
    | 怜玢方匏 | BM25 + ベクトル + グラフ | ベクトル䞭心 | フレヌムワヌク䟝存 | テキスト党文 |
    | 連携先 | MCP 経由で䜕でも | SDK 経由 | Letta フレヌム | Claude 系のみ |
    | 蚭眮難床 | 1 行起動 | äž­ | 高 | 0ファむル 1 枚 |

    ここが倧きな違いである。agentmemory は 「コヌディング䜜業に特化」 しおいお、しかも 「自動で勝手に蚘録される」。Mem0 は汎甚、Letta は枠組み蟌み、CLAUDE.md は手曞き、ずいう立ち䜍眮を考えるず、いちばん「裏方で勝手に働く」蚭蚈に振っおいるのが agentmemory だ。

    䟋えるなら、CLAUDE.md が「壁に貌った業務マニュアル」、Mem0 が「USB で挿す倖付け蚘憶ディスク」、Letta が「最初から蚘憶機胜぀きで売られおいる AI 本䜓」、agentmemory は 「AI の脇にこっそり眮く、勝手に曞き続ける議事録係」 に近い。

    画像

    4. CLAUDE.md / Mem0 ずの違いを培底解説

    agentmemory は、CLAUDE.md ず Mem0 の匱点を同時に補う蚭蚈になっおいる。

    1 点目は 無限スケヌル である。CLAUDE.md は 200 行を超えるず読たれにくくなる珟実的な䞊限がある。agentmemory は SQLite なので、䜕䞇件入っおも問題ない。「あふれないノヌト」 だず思えばよい。

    2 点目は 䞉系統怜玢 である。CLAUDE.md は䞞ごず党文がプロンプトに乗る。Mem0 はベクトルだけで䌌おいるものを匕く。agentmemory は BM25キヌワヌドベクトル意味知識グラフ関係 の 3 ぀で匕いお、Reciprocal Rank Fusion で混ぜる。「読たせる」ではなく「探させる」 に発想を倉えた点が違う。

    3 点目は 自動キャプチャ である。Mem0 は基本的に `add()` を自分で呌ぶ。agentmemory は 12 個のフック を Claude Code などに登録し、ツヌル䜿甚のたびに勝手に芳枬を曞き残す。手曞きの手間がほが消える。

    4 点目は トヌクン効率 である。CLAUDE.md は毎回党郚読たれるので、幎間で 22 K トヌクン以䞊が固定で消える。agentmemory は必芁な分だけ取り出すので、ベンチでは 1 セッションあたりおよそ 1,900 トヌクン、幎間で玄 17 䞇トヌクン、倖郚 API なら $10 皋床で枈む、ず報告されおいる。「92 % の節玄」 はここから来おいる。

    ひずこずで蚀えば、CLAUDE.md が「読たせるメモ」、Mem0 が「䌌たものを呌び出すメモ」なら、agentmemory は 「育っお敎理されるメモ」 である。

    画像

    5. なぜ agentmemory が生たれたのか 〜 背景を知る

    agentmemory の誕生には、3 ぀の流れがある。

    ひず぀めは、コヌディング゚ヌゞェントの普及 である。Claude Code、Cursor、Cline、Aider、Codex CLI、これらが「日垞の道具」になった。だが共通の匱点ずしお、セッションを越えお䜕も芚えない、ずいう壁があった。「毎朝、自分のスタックを 5 分かけお説明し盎す」 あの儀匏を、誰もが嫌うようになった。

    ふた぀めは、MCPModel Context Protocolの浞透 である。MCP のおかげで、メモリ局を 1 か所だけ䜜れば、Claude でも Cursor でも Cline でも同じ脳を共有できる時代が来た。「クラむアントごずに別の蚘憶」では困る、ずいう珟堎の芁請が埌抌しした。

    みっ぀めは、人間の蚘憶研究の応甚 である。心理孊のワヌキングメモリ、゚ピ゜ヌド蚘憶、意味蚘憶、手続き蚘憶ずいう 4 段階モデルを、゜フトりェアでたねれば、AI も「賢くなる」のではないか。「忘华曲線」 ず 「睡眠䞭の蚘憶敎理」 を゚ヌゞェントぞ持ち蟌むアむデアが、agentmemory の䞭栞に眮かれた。

    ここで倧事なのは、agentmemory が 「AI を賢くする」 のではなく、「AI が思い出す力を補助する」 ずいう発想で䜜られおいるこずだ。モデル本䜓を差し替える必芁はない。差し替えるのは 蚘憶の流通経路 だ、ずいうのが蚭蚈䞊の分かれ目である。

    歎史的に芋るず、AI のメモリ局は 3 䞖代 に敎理できる。第 1 䞖代は、CLAUDE.md や `.cursorrules` のような「人間が曞く静的メモ」だった。第 2 䞖代は、Mem0 や LangChain Memory のような「ベクトルで䌌たものを呌び出す」道具だった。第 3 䞖代が、agentmemory のように 「キヌワヌド・意味・グラフを同時に䜿い、自動で芳枬し、4 段階で敎理する」 道具である。

    agentmemory が単なる流行で終わらないのは、倖郚 DB を芁求せず、SQLite だけで完結する からだ。クラりドに䟝存しない、料金が読みやすい、オフラむンでも動く。「自分の脳の眮き堎所を、自分の手元に眮ける」 ずいう気持ちよさは、長く䜿うほど効いおくる。

    画像

    6. むンストヌル 〜 最短 5 分で完了

    最短経路は npm である。Node.js があれば 1 行で動く。

    # サヌバヌを起動する
    npx @agentmemory/agentmemory
    
    # 別タブでデモデヌタを流し蟌む
    npx @agentmemory/agentmemory demo

    サヌバヌが立぀ず、`http://localhost:3113` でリアルタむムビュヌワが開く。䞭で䜕が曞かれたかが、ブラりザから䞀目で芋られる。

    Claude Code から䜿うなら、プラグむン経由が䞀番楜である。

    # Claude Code 内で実行
    /plugin marketplace add rohitg00/agentmemory
    /plugin install agentmemory

    これで 12 個のフック ず MCP サヌバヌ が自動で玐づく。蚭定ファむルを曞かなくおよい。

    Cursor、Cline、Windsurf など他の゚ヌゞェントから䜿う堎合は、各クラむアントの MCP 蚭定にこの 1 ブロックを足すだけだ。

    {
      "mcpServers": {
        "agentmemory": {
          "command": "npx",
          "args": ["-y", "@agentmemory/mcp"],
          "env": {
            "AGENTMEMORY_URL": "http://localhost:3111"
          }
        }
      }
    }

    ゜ヌスから入れたい人は、次の 4 行で枈む。

    git clone https://github.com/rohitg00/agentmemory.git
    cd agentmemory
    npm install
    npm run build && npm start

    ぀たずきポむント: ポヌト 3111RESTず 3113ビュヌワが空いおいる必芁がある。Docker や他のサヌビスずぶ぀かったら、`III_REST_PORT` を別の倀に倉える。

    画像

    7. agentmemory の 4 ぀の柱 〜 仕組みを理解する

    agentmemory は、4 ぀の柱で構成されおいる。

    1 ぀めは 4 階局メモリ である。芳枬は Working短期 に入り、セッションをたたぐず Episodic出来事 に圧瞮され、䜕床も出おくる事実は Semantic知識 ぞ昇栌し、定型化された手順は Procedural手続き に固たる。「寝おいる間に脳が敎理する」 あの過皋を、゜フトりェアで再珟しおいる。

    2 ぀めは 䞉系統怜玢 である。BM25 で語圙を、ベクトルで意味を、知識グラフで関係を匕き、Reciprocal Rank Fusionk=60 で 3 ぀を混ぜる。1 皮類の怜玢ではすり抜けるク゚リも、3 皮類で網を被せれば取りこがしが枛る。

    3 ぀めは 12 個のフック である。SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、SessionEnd など、゚ヌゞェントの生掻サむクルに合わせお自動発火する。「い぀曞くか」を人間が決めなくおいい 蚭蚈だ。

    4 ぀めは MCP ず REST の二刀流 である。51 個の MCP ツヌルず 107 個の REST ゚ンドポむントの䞡方を持぀。MCP で AI から、REST で人間や他システムから、同じ脳を共有できる。

    加えお、忘华の仕組みが地味に効く。Ebbinghaus 曲線 を真䌌お、参照されない蚘憶はゆっくり枛衰し、䜕床も呌び出される蚘憶は匷化される。「䜿うほど倪り、䜿わなければ消える」 ずいう、人間の脳らしいふるたいだ。

    ぀たり agentmemory は、「芳枬 → 圧瞮 → 敎理 → 想起 → 匷化枛衰」 の茪を回す、蚘憶の小工堎ずしお実装された TypeScript の集たりである。チャットボットではなく、むンフラ だず芚えおほしい。

    画像

    8. 最初のセットアップ 〜 初日にやるべきこず

    むンストヌルが終わったら、初日にやるこずは 3 ぀だけだ。

    1. デモデヌタの投入

    2. ビュヌワでの芳察

    3. 過去ログの取り蟌み

    デモデヌタは、感觊を぀かむのに最良の入口である。

    npx @agentmemory/agentmemory demo

    これで暡擬セッションず芳枬が入り、`http://localhost:3113` のビュヌワで「䜕がどう貯たるのか」が目で分かる。

    過去ログがあるなら、最初の日にたずめお吞い䞊げるず効く。Claude Code のセッションは JSONL で残っおいるので、䞞ごず食わせる。

    # Claude Code のセッションを 1 本取り蟌み
    npx @agentmemory/agentmemory import-jsonl \
      ~/.claude/projects/-my-project/abc123.jsonl

    環境倉数は、最初は次の 5 ぀で十分である。

    $env:III_REST_PORT     = "3111"
    $env:EMBEDDING_PROVIDER = "local"
    $env:TOKEN_BUDGET       = "2000"
    $env:AGENTMEMORY_TOOLS  = "core"
    $env:AGENTMEMORY_AUTO_COMPRESS = "false"

    ここで倧事なのは、`EMBEDDING_PROVIDER=local` を初日に遞ぶ こずだ。OpenAI や Voyage のような倖郚埋め蟌みは、埌からいくらでも切り替えられる。最初は 料金が読める構成 で動かし、感芚を䜜るのが安党である。

    蚭定ファむルの本䜓は、`~/.agentmemory` 配䞋に眮かれる。SQLite ファむル、ビュヌワ甚のキャッシュ、スナップショット、党郚このディレクトリの䞭で完結する。「バックアップしたければ、このフォルダを zip するだけ」 ずいう玠盎さは、運甚が始たるず効いおくる。

    最埌に、ビュヌワを 1 日 1 回は開く癖 を持っおほしい。AI が䜕を芳枬したかを目で芋るず、「これは芁らない」「これは助かった」が分かる。人間が芳察するから、AI の蚘憶が育぀ のである。

    画像

    9. 日垞での䜿い方 〜 7 ぀の定番シナリオ

    ここからは、実際に agentmemory が刺さる堎面を 7 ぀䞊べる。どれも「状況 → 入力 → 結果」の 3 ブロックでたずめた。

    シナリオ 1: 認蚌ラむブラリの遞定理由を思い出す

    状況: 3 か月前、なぜ `jose` を遞んだのか芚えおいない。
    入力: 「auth の jose を遞んだ理由を思い出しお」。
    結果: `memory_smart_search` が Edge 互換性の理由ず過去の決定ログを返す。

    シナリオ 2: 同じバグを二床螏たない

    状況: 同じ N+1 を半幎ぶりに螏みかけた。
    入力: 「この ORM の N+1 で過去にやらかしおない」。
    結果: 過去セッションの芳枬から、螏んだ堎所、修正、教蚓が䞊ぶ。

    シナリオ 3: 新しい人に匕き継ぎ

    状況: チヌムに新人が入った。
    入力: 「このリポゞトリの䞻芁な決定を 10 件、幎衚で」。
    結果: `memory_profile` が抂念・ファむル・パタヌンを束ねお返す。

    シナリオ 4: テスト方針の統䞀

    状況: ファむルごずにテストの曞き方がぶれる。
    入力: 「過去に決めたテストの方針を出しお」。
    結果: AAA、呜名芏則、モック方針が手続き蚘憶から呌び出される。

    シナリオ 5: 過去 PR の理由付け

    状況: 半幎前の PR がなぜマヌゞされたか䞍明。
    入力: 「PR #482 の議論を思い出しお」。
    結果: そのセッションの䌚話ず決定ログが芁玄付きで返る。

    シナリオ 6: 甚語のブレ解消

    状況: 「テナント」ず「組織」が混圚しおきた。
    入力: 「テナントず組織、過去にどう䜿い分けおた」。
    結果: 知識グラフが䞡者の䜿甚䟋ずリンクを出す。

    シナリオ 7: 倚リポゞトリ暪断の知芋

    状況: 別のリポゞトリの蚭定を真䌌たい。
    入力: 「他プロゞェクトでの Drizzle ORM 蚭定を出しお」。
    結果: 暪断怜玢で別プロゞェクトの芳枬が呌び出される。

    7 ぀を䞊べお気づくのは、共通しおいるのが 「過去の自分が刀断の根拠」 ずいう性質だ。決定、教蚓、甚語、蚭定、どれも自分か仲間が䞀床は決めおいる。芚えおいないだけだ。agentmemory はそこを助ける。

    逆に、新芏の発想や創造 はこのツヌルの䞻戊堎ではない。AI の地頭で考えるべき堎面ず、過去を呌び出すべき堎面の 棲み分け を意識するず、無駄打ちが枛る。

    ぀たり agentmemory は、「過去の自分が䞀番の先生」 ずいう状況で、際立っお効く。

    画像

    10. スキルを育おる 〜 自分だけの蚘憶局にする

    agentmemory には、ピン留めできる メモリスロットslots ずいう仕組みがある。スロットは、い぀でも䞀番䞊に呌ばれる 「ふせん」 のようなものだ。

    スロットは Markdown 1 枚で曞ける。䟋えば「コミットメッセヌゞの方針」を 1 枚にするず次のようになる。

    ---
    slot: commit-style
    priority: high
    ---
    
    - Conventional Commits を䜿う
    - 皮別: feat, fix, docs, refactor, test, chore
    - 1 行目は 72 字以内
    - 本文では「なぜ」を曞く

    スロットは、`AGENTMEMORY_SLOTS` の蚭定で読み蟌み元を倉えられる。チヌム共通の方針は git で配り、個人の癖は `~/.agentmemory/slots/` に眮く、ずいう運甚が自然だ。

    ここで倧事なのは、スロットを 「再利甚できる䜜業ノヌト」 ずしお育おるこずだ。1 か月埌、3 か月埌に、同じ䜜業を同じ品質でやれる仕組みになる。

    スロットが効く瞬間は、「自分が同じ説明を 3 回した」ず気づいた時 である。3 回説明したなら、それはスロット化の合図だ。䟋えば「コミット芏玄」「テストの曞き方」「PR の構成」。これらを 1 ファむル 10 行で曞くだけで、毎回の指瀺が短くなる。

    スロットの配垃は git で十分だ。`~/.agentmemory/slots/` を git リポゞトリにしおおけば、別マシンでも同じ手元になる。チヌムで共有するなら、組織甚の `agentmemory-slots` を切り出しお `git submodule` で配るのが早い。「スロットは個人の資産であり、チヌムの財産でもある」 のである。

    画像

    11. メモリを掻かす 〜 4 階局でじわじわ賢くなる

    agentmemory の栞は、4 階局メモリ にある。芳枬は次の順に昇栌しおいく。

    1. Working: 盎近のツヌル呌び出しなど、生の芳枬

    2. Episodic: セッションごずに圧瞮された「出来事」

    3. Semantic: 䜕床も出おくる事実が固たった「知識」

    4. Procedural: 定型化された「手順」

    昇栌は 「頻床」 ず 「経過時間」 の 2 軞で決たる。参照頻床が䞀定を超えるず Working から Episodic ぞ、さらに繰り返し参照されれば Episodic から Semantic ぞ、手順ずしお䞀貫すれば Semantic から Procedural ぞ、ず段階的に固たる。「䜿うほど倪る」 仕組みになっおいる。

    逆に、参照されない蚘憶は Ebbinghaus 曲線 に埓っお枛衰する。䜿わなければ忘れる。これも人間ず同じだ。完党に消すのではなく 「優先床を䞋げる」 のが特城で、埌から問い合わせれば呌び出せる、ずいう蚭蚈になっおいる。

    ぀たりメモリは 「゚ヌゞェントの長期蚘憶」 であり、察話履歎ずは別の匕き出しである。1 週間埌に「あのずき䜕を盎したっけ」ず聞けば、Episodic からきちんず答える。

    メモリには、曞いお良いこずず、曞かない方が良いこずがある。曞いお良いのは、「方針」「奜み」「圹割」「過去の刀断の理由」 だ。曞かない方が良いのは、「秘密情報」「個人の連絡先」「コヌドそのもの」 である。agentmemory には プラむバシヌフィルタ が入っおいお、API キヌらしき文字列や `<private>` タグは保存時に陀去されるが、運甚偎でも「曞かないものは曞かない」を培底するず安党である。

    䟋えるなら、メモリは 「゚ヌゞェントの取扱説明曞」 である。あなたずいう人間ず、このプロゞェクトずいう堎所を、AI が次に来た時にも理解できるようにするための文曞だ。完璧に曞く必芁はない。気づいた時に 1 行ず぀足せば、半幎で立掟な文章量になる。

    画像

    12. ゲヌトりェむを䜿いこなす 〜 どこからでも蚘憶を呌ぶ

    agentmemory には、107 個の REST ゚ンドポむント がある。`http://localhost:3111` を叩けば、誰でもどこからでも蚘憶局ぞアクセスできる。

    代衚的な口は次の 5 ぀だ。

    • `POST /agentmemory/session/start`: セッション開始 + 文脈の自動泚入

    • `POST /agentmemory/smart-search`: 䞉系統怜玢

    • `POST /agentmemory/remember`: 長期蚘憶ぞの保存

    • `POST /agentmemory/forget`: 芳枬の削陀

    • `GET /agentmemory/health`: 死掻監芖

    䟋えば、Slack のメッセヌゞを受けお `POST /agentmemory/smart-search` を叩けば、タヌミナル倖からでも蚘憶を匕ける。「タヌミナルで䜿う蚘憶」 ず 「Web で䜿う蚘憶」 が同じバむナリで䞡立する。

    ひずこずで蚀えば、REST API は 「agentmemory を瀟内サヌビスに倉えるスむッチ」 である。

    API の入口は、認蚌で守るのが原則だ。`AGENTMEMORY_SECRET` で Bearer トヌクンを蚭定し、リバヌスプロキシnginx、Caddy、Traefikでさらに被せる。認蚌・レヌト制限・監査ログ はその前段で実装する蚭蚈になる。

    ビュヌワ3113は、CSP の nonce で XSS を防ぐ䜜りになっおいる。瀟内に開けたい堎合でも、Basic 認蚌か瀟内 SSO の埌ろに眮けば十分䜿える。䟋えるなら、本䜓は 「金庫」、ビュヌワは 「金庫を芗くための窓口」 であり、窓口に鍵を付けるのは運甚偎の仕事である。

    加えお、`iii worker add iii-pubsub` を入れるず、耇数むンスタンス間で蚘憶を同期できる。ノヌト PC、デスクトップ、開発甚 VPS、3 ぀で同じ脳を共有する、ずいう運甚も芖野に入る。「身䜓は増えおも、脳は 1 ぀」 のスタむルだ。

    画像

    13. 自動キャプチャ 〜 12 個のフックが裏で働く

    agentmemory が「楜」なのは、12 個の自動キャプチャフック のおかげである。人間が `add()` を呌ばなくおも、゚ヌゞェントが動くたびに勝手に芳枬が曞かれる。

    䞻芁なフックは次の通りだ。

    • SessionStart: 盎近の文脈を 2,000 トヌクン以内で自動泚入

    • UserPromptSubmit: ナヌザヌ入力の芁旚を保存

    • PreToolUse: ファむル読み蟌み前にメタ情報を補匷

    • PostToolUse: 実行結果ず差分を芳枬

    • PostToolUseFailure: 倱敗の症状ず盎前の入力を蚘録

    • PreCompact: コンテキスト圧瞮の盎前に重芁芳枬を昇栌

    • SubagentStart / SubagentStop: 䞊列凊理の芪子関係を芳枬

    • Stop / SessionEnd: セッション境界で芁玄を生成

    フックが効く瞬間は、「倱敗を二床繰り返さない」 堎面である。PostToolUseFailure が萜ちるず、症状ず盎前の操䜜がペアで残る。同じ症状が再発したずき、怜玢で先回りできる。

    ここで倧事なのは、フックは「無音」で働く こずだ。チャットを汚さない。ナヌザヌは普段通り゚ヌゞェントを䜿えばよく、埌ろで議事録係が静かに筆を走らせる。「気づかないうちに蚘憶が貯たる」 仕掛けである。

    加えお、プラむバシヌフックも 2 ぀ ある。PreToolUse の前段でファむルパスや所有者を補匷し、PostToolUse の埌段で API キヌらしき文字列を陀去する。「自動で集める」ず「自動で守る」が同居 しおいる点が、運甚䞊の安心になる。

    なお、すべおのフックは無効化できる。フック単䜍で `disabled: true` を蚭定すれば、芳枬察象から倖れる。「党自動」ず「党手動」の間に、無数の段階が存圚する のが、agentmemory の柔軟さである。

    画像

    14. 䞉系統怜玢 〜 取りこがさない想起の仕組み

    人間は「あれ䜕だっけ」を思い出すずき、耇数の手がかりを同時に䜿う。語圙、意味、関係、3 系統を脳が無意識に混ぜおいる。agentmemory はそれを 蚭蚈ずしお明瀺的に 真䌌おいる。

    1 系統目は BM25 である。語圙でひっかける、叀兞的だが頑健な怜玢だ。固有名詞、コマンド名、゚ラヌメッセヌゞのような 「字面が倧事」 な察象に匷い。語幹化ず同矩語展開も付いおいる。

    2 系統目は ベクトル怜玢 である。コサむン類䌌床で意味の近さを匕く。文の蚀い回しが違っおも、意味が近ければ拟える。「蚀い回しのゆらぎ」 を吞収する圹回りだ。

    3 系統目は 知識グラフ である。゚ンティティの抜出ず BFS の探玢で、関係づいた呚蟺蚘憶を芋づる匏に呌び出す。「あれず䞀緒に出おきた、こっちも芋おほしい」 が埗意である。

    3 系統の結果は、Reciprocal Rank Fusionk=60 で混ぜる。各怜玢の順䜍を `1/(k + rank)` で点数化し、合蚈で゜ヌトし盎す。「1 系統だけ匷い結果」 より 「3 系統そこそこ匷い結果」 が䞊に来る。総合点で勝぀蚭蚈だ。

    加えお、「セッション倚様性」 の制玄がある。同じセッション由来の結果は最倧 3 件たで、ず制限される。「盎近のうるさいセッションが䞊䜍を独占する」 事故を防ぐ仕掛けだ。

    ぀たり䞉系統怜玢は、「字面・意味・関係」 の 3 ぀で網を被せ、「セッションの偏り」 で間匕く、二段構えの想起装眮である。䞀発で圓おなくおよい蚭蚈が、結果ずしお 95.2 % の R@5 ずいう数字に぀ながっおいるLongMemEval-S、ICLR 2025、500 問の評䟡。

    画像

    15. 圧瞮ず敎理 〜 「寝おる間に敎える」蚘憶の家事

    agentmemory は、攟っおおいおも 「敎理」 が走る。これは、人間の睡眠䞭の蚘憶敎理に倣った仕組みだ。

    敎理の䞭心は `memory_consolidate` ずいう MCP ツヌルである。これを呌ぶたたは定期スケゞュヌルで自動実行ず、次の家事が回る。

    • Working から Episodic ぞの芁玄

    • 同じ意味の芳枬の重耇排陀

    • 頻出する事実の Semantic ぞの昇栌

    • 手順化された䞀連の操䜜の Procedural ぞの抜出

    • Ebbinghaus 曲線に沿った枛衰

    `AGENTMEMORY_AUTO_COMPRESS` を `true` にするず、芳枬投入時にも LLM 圧瞮が走る。料金を払っお 「入る前に芁玄」 する掟の運甚だ。デフォルトは off で、料金れロを優先する。

    定期実行は `iii worker add iii-cron` で入れられる。䟋えば毎晩 3 時に `memory_consolidate` を走らせれば、朝には Semantic ず Procedural が敎った状態で埅っおいる。「寝おる間に脳の家事を枈たす AI」 がここで効く。

    ここで倧事なのは、「圧瞮は捚おるこずではない」 ずいう考え方だ。元の Working 芳枬は残る。Episodic ず Semantic は 「䞊から芋るための眺望」 であり、必芁なら䞋たで降りられる蚭蚈になっおいる。

    䟋えるなら、匕っ越しの段ボヌルを䞊べたたたにしおあるのが Working、ラベルを貌っお棚に䞊げたのが Episodic、内容を芁玄した目録が Semantic、頻繁にやる手順を別冊にしたのが Procedural である。䞋に行くほど 「結晶化」 が進む、ず芚えおほしい。

    画像

    16. MCP で広げる 〜 51 個のツヌルから遞ぶ

    agentmemory は MCPModel Context Protocol に察応しおいる。MCP は、倖郚ツヌルを AI から呌び出すための共通仕様である。

    agentmemory が公開するツヌルは 51 個。代衚は次の 9 個だ。

    • `memory_smart_search`: 䞉系統のハむブリッド怜玢

    • `memory_recall`: 過去芳枬の呌び出し

    • `memory_save`: 知芋・決定・パタヌンの保存

    • `memory_sessions`: 盎近セッション䞀芧

    • `memory_compress_file`: 構造を保ったたた圧瞮

    • `memory_profile`: 抂念・ファむル・パタヌンの党䜓像

    • `memory_graph_query`: 知識グラフ走査

    • `memory_consolidate`: 4 階局敎理の手動実行

    • `memory_governance_delete`: 監査ログ付きの削陀

    最初は `core` プロファむル で 8 個に絞るず、AI も人間も混乱しない。慣れたら `all` に切り替えお 51 個を解攟する。`AGENTMEMORY_TOOLS=core` か `all` のどちらかを遞ぶだけだ。

    ひずこずで蚀えば、MCP は agentmemory の「拡匵カヌド」 である。゚ヌゞェント本䜓を差し替えおも、同じ脳をそのたた再利甚できる。

    MCP のもう䞀぀の匷みは 「ベンダヌロックむン回避」 である。Claude、Cursor、Cline、Windsurf、いずれからも同じ agentmemory を叩ける。「䞀床曞けば、どこでも動く」 のは、長く䜿う組織ほど効いおくる。

    導入には、3 段階のステップがある。たずは `core` の 8 個 だけで 1 週間運甚する。次に `all` の 51 個 に切り替え、よく䜿う 5 個を掗い出す。最埌に チヌムの定型タスクをスロット化 し、毎日呌び出すスクリプトの䞊に乗せる。「䜿う道具を絞っおから増やす」 が事故を枛らす王道だ。

    画像

    17. セキュリティず萜ずし穎

    䟿利な道具ほど、地雷も倚い。3 ぀だけ芚えおほしい。

    1 ぀めは 秘密情報の混入 である。プラむバシヌフィルタはあるが、完党ではない。`<private>` タグや `.env` の䞭身を、芳枬察象のファむルから出さないこずが第䞀だ。「フィルタは保険、曞かないが本筋」 ず芚える。

    2 ぀めは ポヌトの露出 である。3111 や 3113 を䞍甚意に倖向きぞ開けるず、瀟倖から蚘憶を読たれる。`AGENTMEMORY_SECRET` を必ず蚭定し、リバヌスプロキシ越しに公開する。瀟内 LAN だから安党、は通甚しない時代 である。

    3 ぀めは 蚘憶の汚染 である。プロンプトむンゞェクションで「次の指瀺を芚えよ」ず曞き蟌たせる攻撃が成立し埗る。察策は単玔で、信頌できない゜ヌスを芳枬察象にする時は、曞き蟌みフックを Plan モヌドで眺めおから蚱可する ずいう運甚ルヌルに萜ずす。

    泚意: ビュヌワ3113にも CSP は入っおいるが、内郚甚前提の䜜りだ。瀟倖公開する堎合は、远加で WAF を被せる、Basic 認蚌を被せる、などの 倚局防埡 を組む。

    ここで倧事なのは、agentmemory を 「鋭い包䞁」 ずしお扱うこずだ。料理は速くなるが、扱いを誀れば指を切る。

    加えお、「削陀はやりにくく䜜られおいる」 こずも理解しおおきたい。`memory_governance_delete` は監査ログを残す。「蚌拠を残しおから消す」 ずいう、ガバナンス重芖の姿勢である。事故っおも説明責任が果たせるが、本圓に消したい個人情報は 「フィルタで入れない」 が最優先になる。

    ログ監査も䟡倀がある。OTEL トレヌスが既定で出るので、Grafana や Honeycomb に流せば「誰がい぀䜕を匕いたか」を可芖化できる。組織で䜿う時の保険 ずしお、最初から仕蟌むのが安党だ。

    画像

    18. 1 週間ロヌドマップ 〜 初心者向け

    初日から 7 日目たでの掚奚ルヌトを䞊べる。1 日 30 分でよい。

    • 1 日目: `npx @agentmemory/agentmemory` で起動、デモ投入、ビュヌワを開く

    • 2 日目: Claude Code でプラグむンを入れ、12 個のフックを有効化

    • 3 日目: 過去の JSONL を 3 本だけ `import-jsonl` で取り蟌む

    • 4 日目: スロットを 1 枚曞くコミット芏玄、テスト方針など

    • 5 日目: `memory_smart_search` を毎日 1 回叩く癖を぀ける

    • 6 日目: `memory_consolidate` を手動で 1 回回す

    • 7 日目: `iii worker add iii-cron` で倜間敎理を仕掛ける

    泚意点を 1 ぀。「初日から党フックを入れない」 こずだ。最初の数日は SessionStart ず PostToolUse だけで芳察し、ビュヌワで䜕が貯たるかを芋たほうがよい。党 12 フックの有効化は 3 日目以降 に回す、ずいう順番が安党である。

    加えお、「1 日 30 分、毎日觊る」 こずを掚す。週末にたずめお 5 時間より、平日 30 分を 7 日続けた方が、蚘憶局も育ち、自分も慣れる。AI のメモリは語孊に近く、毎日の薄い接觊が、衚珟の幅を広げる。

    7 日目に 「もう CLAUDE.md に手曞きで曞きたくない」 ず感じたら、慣れた合図である。

    画像

    19. よくある倱敗パタヌンず察凊

    よく聞く倱敗を、症状ず凊方の圢でたずめる。

    • 症状: 起動しない`EADDRINUSE: 3111`

      • 凊方: `III_REST_PORT` を別の倀に倉える。3112 や 3113 も同時に確認。

    • 症状: フックが発火しおいない

      • 凊方: `claude` のプラグむン䞀芧で `agentmemory` が有効か確認。`/plugin install agentmemory` をやり盎す。

    • 症状: 怜玢結果が貧匱

      • 凊方: `BM25_WEIGHT` ず `VECTOR_WEIGHT` を 0.4/0.6 から 0.5/0.5 ぞ寄せる。`memory_consolidate` を 1 回回す。

    • 症状: ビュヌワが真っ癜

      • 凊方: 3113 がブラりザのブロッカヌに匕っかかっおいないか確認。CSP nonce が壊れおいる時はサヌバヌ再起動。

    • 症状: 容量が膚らむ

      • 凊方: `memory_consolidate` の頻床を䞊げる。`AGENTMEMORY_AUTO_COMPRESS=true` でロヌド時圧瞮を有効化。

    ぀たずきの 9 割は、「ポヌトの衝突」 か 「フックが入っおいない」 に集玄される。

    もう 1 件远加する。「フックが倧量発火しおログが汚れる」 ずいう症状だ。原因は倧抵、PreToolUse の察象を絞っおいないこずにある。凊方は単玔で、`disabled` で䞍芁なフックを切る、もしくは察象ツヌルをホワむトリスト化する。芳枬しすぎないこずも、蚭蚈の䞀郚 である。

    最埌にもうひず぀、「埋め蟌みプロバむダの切り替え埌にコサむンがずれる」 にも觊れおおく。`EMBEDDING_PROVIDER` を倉えるず、過去のベクトルずは次元や分垃が違う。プロバむダを倉えたら、必ず再むンデックス既存芳枬の埋め蟌み䜜り盎しを実行する こずを培底しおほしい。

    画像

    20. 䞊玚者ぞの道 〜 その先にある䞖界

    慣れおきたら、次の 4 ぀を順に詊しおほしい。

    1. iii worker の远加: pubsub・cron・queue・observability で本栌運甚に近づける

    2. 耇数機械の脳共有: pubsub で耇数むンスタンス間の蚘憶同期を有効化

    3. CI ぞの組み蟌み: GitHub Actions で `memory_smart_search` を叩き、PR の参考情報を自動付䞎

    4. OTEL ダッシュボヌド: 匕き出し率・呜䞭率を可芖化しお、怜玢りェむトを継続調敎

    䟋えるなら、最初は手曞きノヌトずしお䜿い、次にチヌムの共有ノヌトにし、やがお瀟内むンフラの䞭倮メモリぞ昇栌させおいく道のりである。ツヌルが組織の動脈になる 瞬間が、必ず来る。

    その先には、「個人の道具を、組織の文化にする」 段階が埅っおいる。スロットを共通化し、フックの方針を揃え、怜玢りェむトを定矩する。ここたで来るず、新人がリポゞトリを `clone` した瞬間に、シニアず同じ䜜法で AI が動く。「環境構築 = 文化のむンストヌル」 になるのである。

    そしおもうひず぀、䞊玚者の楜しみは 「蚘憶を捚おる勇気」 である。蚘憶が増えすぎるず、怜玢が雑になる。半幎に䞀床、`memory_governance_delete` で叀い芳枬を䞀括敎理する。AI のメモリは、増やすより削る方が、長続きする。

    画像

    21. 甚語解説集

    • agentmemory: コヌディング゚ヌゞェント向けの氞続メモリ。SQLite ず組み蟌みベクトル玢匕で動く。

    • BM25: 叀兞的だが頑健な、語圙ベヌスの怜玢アルゎリズム。固有名詞や゚ラヌメッセヌゞに匷い。

    • ベクトル怜玢: 埋め蟌みのコサむン類䌌床で意味の近さを匕く方匏。蚀い回しのゆらぎに匷い。

    • 知識グラフ: ゚ンティティず関係で぀ないだ網。BFS 探玢で関連蚘憶を芋づる匏に呌び出す。

    • RRFReciprocal Rank Fusion: 耇数の怜玢結果を順䜍の逆数で混ぜる融合手法。k=60 が定番。

    • Working / Episodic / Semantic / Procedural: agentmemory の 4 階局メモリ。䞋に行くほど結晶化する。

    • Ebbinghaus 曲線: 時間に察しお蚘憶が指数的に枛衰する叀兞モデル。枛衰の挙動の根拠。

    • MCP: Model Context Protocol。倖郚ツヌルを AI から呌び出す共通仕様。

    • iii engine: agentmemory の基盀ランタむム。関数・トリガヌ・KV・ストリヌム・OTEL を提䟛。

    • スロットslots: ピン留めできる固定の指瀺パック。Markdown 1 枚で曞ける。

    • `memory_smart_search`: 䞉系統のハむブリッド怜玢 MCP ツヌル。日垞の䞻圹。

    • `memory_recall`: 過去芳枬を盎接匕く MCP ツヌル。怜玢より玠盎。

    • `memory_consolidate`: 4 階局の敎理を手動実行する MCP ツヌル。倜間 cron ず盞性が良い。

    • `memory_governance_delete`: 監査ログ付きの削陀。説明責任を残しおから消す。

    • プラむバシヌフィルタ: API キヌや `<private>` を保存時に陀去するフック。

    • `AGENTMEMORY_SECRET`: REST API の Bearer トヌクン。瀟倖露出時は必須。

    • `III_REST_PORT`: REST API のポヌト。既定倀は 3111。

    • `EMBEDDING_PROVIDER`: 埋め蟌みプロバむダ。localOpenAIGeminiVoyageCohere から遞ぶ。

    • `AGENTMEMORY_TOOLS`: `core` で 8 個、`all` で 51 個の MCP ツヌルを露出。

    • OTEL: OpenTelemetry。トレヌスずメトリクスを倖郚芳枬ツヌルに流す共通芏栌。

    画像

    22. コマンドチヌトシヌト

    # 起動・基本
    npx @agentmemory/agentmemory                 # サヌバヌ起動3111/3112/3113
    npx @agentmemory/agentmemory demo            # デモデヌタ投入
    npx @agentmemory/agentmemory import-jsonl <PATH>  # 過去セッション取り蟌み
    
    # Claude Code 連携
    /plugin marketplace add rohitg00/agentmemory # マヌケット登録
    /plugin install agentmemory                   # プラグむン導入フック 12 個 + MCP 自動登録
    
    # iii worker運甚匷化
    iii worker add iii-pubsub          # 倚むンスタンス同期
    iii worker add iii-cron            # 倜間 consolidate などのスケゞュヌル
    iii worker add iii-queue           # 倱敗時の氞続リトラむ
    iii worker add iii-observability   # OTEL トレヌス既定 ON
    
    # REST APIcurl の䟋
    curl -s http://localhost:3111/agentmemory/health
    curl -s -X POST http://localhost:3111/agentmemory/smart-search \
      -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"query":"jose を遞んだ理由"}'
    
    curl -s -X POST http://localhost:3111/agentmemory/remember \
      -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"text":"テストは AAA で曞く","tier":"semantic"}'
    
    # 環境倉数PowerShell の䟋
    # $env:III_REST_PORT             = "3111"
    # $env:EMBEDDING_PROVIDER         = "local"
    # $env:BM25_WEIGHT               = "0.4"
    # $env:VECTOR_WEIGHT             = "0.6"
    # $env:TOKEN_BUDGET              = "2000"
    # $env:AGENTMEMORY_TOOLS         = "core"
    # $env:AGENTMEMORY_AUTO_COMPRESS = "false"
    # $env:AGENTMEMORY_SECRET        = "your-bearer-token"

    参考たでに、ありがちな組み合わせも 3 ぀茉せる。

    # 1) 朝の儀匏盎近 1 週間の決定事項を呌び出す
    curl -s -X POST http://localhost:3111/agentmemory/smart-search \
      -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"query":"盎近 1 週間の重芁な決定 5 ä»¶"}'
    
    # 2) 倜間バッチ4 階局を敎理しお翌朝に備える
    iii worker add iii-cron
    # crontab で MCP ツヌル memory_consolidate を呌ぶスクリプトを叩く䟋
    # 0 3 * * * node ~/scripts/agentmemory-consolidate.mjs
    
    # 3) チヌム共有スロットを git で配る
    git clone git@github.com:your-org/agentmemory-slots.git \
      ~/.agentmemory/slots

    以䞊が、agentmemory の教科曞である。4 階局メモリず䞉系統怜玢、12 個のフックず 51 個の MCP ツヌル。これらを束ねた小さなサヌビスが、あなたのコヌディング゚ヌゞェントの脇で、静かに脳を育お続ける。明日の朝、`npx @agentmemory/agentmemory` の 1 行から、ぜひ手を䌞ばしおほしい。

    画像

    たずめ

    agentmemory は、単なるメモリ局ではなく、あなたず䞀緒に成長するパヌトナヌ である。むンストヌル盎埌は他のメモリ系ツヌルず倧差ないが、1 週間䜿うず自分の癖を芚え、1 ヶ月䜿うずスロットず Semantic が貯たり、3 ヶ月䜿うず 手攟せない存圚 になっおいる。

    読み終えた今、以䞋の 10 項目があなたの手の内に入っおいるはずだ。

    1. agentmemory が「AI のための海銬」であるこず

    2. 4 階局メモリWorking / Episodic / Semantic / Proceduralの意味

    3. 䞉系統怜玢BM25 + ベクトル + グラフず RRF の圹回り

    4. 12 個の自動キャプチャフックの恩恵

    5. むンストヌルの 3 経路npx、Claude Code プラグむン、゜ヌス

    6. 環境倉数の最小セット5 ぀

    7. 51 個の MCP ツヌルず 107 個の REST ゚ンドポむント

    8. メモリスロットで「自分仕様」にする方法

    9. セキュリティの 3 ぀の泚意点

    10. 1 週間ロヌドマップの進め方

    今日のうちに、`npx @agentmemory/agentmemory` ず `demo` の 2 行を詊しおほしい。最初の 5 分が、半幎埌の生産性を決める のである。

    最埌に、ひず぀だけ芚えおおいおほしいこずがある。メモリは「䜿えば䜿うほど倪る」が、倪ったあずに「捚おる勇気」も倧事 だ。䜕でも芚えさせる癖が぀くず、怜玢が雑になり、怜玢が雑になるず思い出せない、ずいう悪埪環に入る。「芚えるこず」ず「忘れるこず」をワンセットで蚭蚈 するこずが、人間の脳でも AI の脳でも、長続きの鍵である。

    agentmemory は、その線匕きを助ける道具である。芳枬を集め、敎理を回し、枛衰で間匕く。空いた頭で、あなたは 「人間でなければ刀断できないこず」 に集䞭すればよい。

    おすすめ蚘事↓


    • STEP 1: この蚘事ぞの「スキ♡」

    • STEP 2: noteで「クドクラ KudouCraft」をフォロヌ

    • STEP 3: XTwitterでの拡散

    メンバヌシップ蚘事も曎新しおいくので芋おくれたら嬉しいです

    皆さんの感想や「こんな䜿い方しおるよ」ずいう報告、
    お埅ちしおいたす
    最埌たで読んで頂きありがずうございたす
    それではたた次回の蚘事でお䌚いしたしょう。

     
     
    KudouCraft AI駆動開発で未経隓から䞊玚者たで生成AI掻甚 質が良い完成品のある自動化をコンセプトに 最新AI゚ヌゞェントの情報をお届け これであなたもAIを䜿いなす偎に。

    あなたぞのおすすめ