agent-recall

英語 · 中文

AgentRecall

エージェントを一度修正すれば、次のセッションでも覚えています——そして、本当に同じ間違いをしなくなったかを測定します。

AI エージェント向けのローカルファーストなメモリです。修正履歴と監査可能な計算を中心に構築されています。MCP · SDK · CLI · スキル。

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

On session start                  → call session_start (before you act)
When the human corrects you       → call remember with type "correction" — saying "noted" is not saving
Before publish/push/deploy/delete → call check with action_description; obey verdict "blocked"
When past context would help      → call recall
On "save" / "remember" / exit     → call session_end

目次

• 問題点 · できること · セッションループ · MCP ツール
• 記憶の性質 — 5 層 · 記憶が蓄積される仕組み · 数学的な裏付け
• 公約ではなく、実測値 · 他の記憶ツールとの比較
• インストール · オプションの追加機能 · アーキテクチャ · プラットフォーム · コミュニティ · リンク

問題点

エージェントに「確認せずにバージョンを上げないで」と伝えます。エージェントは謝罪して修正し、セッションは終了します。翌週、新しいセッションでまた同じことをします。修正内容は、誰も読まないチャットログの中に埋もれてしまったのです。

AgentRecall は、その一言を構造化された永続ルールに変換し、次のエージェントが行動を起こす前に提示し、同じミスが再発したかどうかを記録します。

── session 3 ─────────────────────────────────────────────
you   › no — never bump the version without asking me first
agent › remember(type: "correction")
        ✓ saved · severity p0 · applies_when: [release, npm]

── session 9 · new agent, no chat history ───────────────
session_start › project "my-app" · 1 critical correction
                watch_for: version bump → ask the owner first
you   › ship the fix
agent › Fix is merged. Want me to bump to 1.4.1, or leave the version?
        outcome recorded: heeded

_{イメージ例のトランスクリプトです。}

できること

AgentRecall は、次の 2 つの機能を備えています。

1. 管理された修正履歴です。 すべての修正（「そのバージョンではありません」「このセクションを先頭にしてください」「決めつける前に確認してください」）が、重要度、証拠、applies_when、撤回、結果を含む構造化レコードになり、セッション、プロジェクト、エージェントの再起動をまたいで保持されます。エクスポート形式は corrections-export/v1 で、外部へ出す際に機密情報を除去します。
2. 測定ツールです。 各修正の retrieved_count が蓄積され、エージェントが同じ状況に遭遇するたびに、結果が heeded（修正が反映された）または recurred（再発した）として記録されます。この段階を測定する公開ベンチマークはありません。私たちはまず測定用の仕組みを構築し、芳しくない数値も含め、得られた結果を公開しています。

セッションループ

flowchart LR
    A([session start]) --> B["/arstart · session_start<br/>load rules + context"]
    B --> C{work}
    C -->|need past knowledge| D["/arrecall · recall"]
    D --> C
    C -->|corrected| R["remember<br/>type: correction"]
    R --> L[(corrections<br/>ledger)]
    C -->|risky action| K["check"]
    L -.-> K
    C --> E["/arsave · session_end<br/>journal + compound"]
    E --> F([session end])
    L -. watch_for .-> B
    F -. every K sessions .-> G["/arreflect<br/>consolidate"]
    G -.-> A

/arstart を実行しないと、新しいエージェントは何の状況把握もできません。/arsave を実行しないと、何も蓄積されません。

MCP ツール

デフォルトで5つのツールが提供されます。各ツールの説明はエージェント向けに書かれており、呼び出すタイミングを示しています。

重要

自動性の法則 — デフォルトが5つだけの理由。 記憶が積み重なるのは、求められなくても呼び出される場合だけです。44のプロジェクトで何週間も実際に使った結果、取得ツール（recall、memory_query）が自発的に呼び出されたことは一度もありません。それらを構築したエージェントからも同様でした。動作を変えるのは、プッシュ型のチャネル（session_start、session_end、修正フック）です。デフォルトのツールを1つ増やすごとに、見返りなく毎回のセッションで定義トークンを消費します。_{（所有者のストアでの自己計測、2026-06-12。）}

そのため、Claude Codeではフックを設定してください。そうすれば、エージェントが規律を保たなくても一連の処理が動作します。

ar hook-start        SessionStart      コンテキストを読み込み、watch_for 警告を表示
ar hook-correction   UserPromptSubmit  修正事項を黙って取り込む
ar hook-ambient      UserPromptSubmit  関連する記憶を注入（2語以上の重なりを最低条件とする）
ar hook-save         UserPromptSubmit  「save」／「retain」→ session_end を促す
ar hook-pretool      PreToolUse        npm publish、git push、rm -rf、deploy、DROP TABLE に警告
ar hook-end          SessionEnd        その日にまだ保存していない場合、ジャーナルを自動保存
ar health            —                 最近のフックの失敗（失敗を明示）

記憶の性質 — 5つのレイヤー

認知心理学の分類を、通常のファイルに対応付けています。人間の記憶と同様に、各レイヤーは異なる速さで忘れます。

~/.agent-recall/
├── projects/<slug>/
│   ├── journal/            episodic — one entry per session
│   ├── corrections/        behavioral rules + outcome ledger
│   └── palace/
│       ├── rooms/          semantic
│       ├── skills/         procedural
│       ├── pipeline/       narrative
│       ├── identity.md
│       └── awareness       cross-project insights
├── dreams/                 nightly consolidation reports
├── dashboard.html          human-readable
└── dashboard.json          agent-readable snapshot

すべてのレイヤーで共通の命名規則を使うため、エージェントは意図に応じて取得パスを組み立てられます。古いファイルも legacy_path ビューを通じて引き続き使用でき、移行は不要です。

記憶が積み重なる仕組み

flowchart LR
    C["correction<br/>(remember / hook)"] --> L[(ledger)]
    L --> S["session_start<br/>ranked by severity,<br/>proof, recency"]
    S --> O{"same situation<br/>again?"}
    O -->|heeded| P["proof_count +1<br/>stability × 1.3"]
    O -->|recurred| X["phantom<br/>→ /arreflect<br/>rewrites the rule"]
    P --> A["≥ 3 confirmations<br/>→ awareness<br/>(cross-project)"]
    X --> L

修正は確認されるたびに強化され、役に立たないと評価されると弱まり、異なる（日時、プロジェクト）の組み合わせで3回確認されると、すべてのプロジェクトに適用されます。保存したルールがあるのに、間違いが再発した場合、それはファントムです。書き込みコストをかけたにもかかわらず動作が変わっていないため、単に再保存するのではなく、書き直します。

数学的な仕組み

多くの製品は「AI メモリー」をブラックボックスとして提供しています。AgentRecall の各メカニズムは、ソースコード内に定数が記され、誠実なラベルが付いた、読み解ける数式です。

1 · 順位融合 — Reciprocal Rank Fusion 🟢

Palace、journal、insight、corrections はそれぞれ独自の候補を順位付けします。リストは生スコアではなく、順位に基づいて統合されます。生スコアは比較できない尺度だからです（Cormack、Clarke、Büttcher 2009 — Elasticsearch が採用しているものと同じ $k$）。

\mathrm{RRF}(d) \;=\; \sum_{\ell \,\in\, \text{lists}} \frac{w_\ell}{k + \mathrm{rank}_\ell(d)}, \qquad k = 60,\;\; w_\ell = 1

オプションのセマンティック検索も、$w = 1.0$ のリストをもう1つ追加するだけです。この重みは推測ではなく測定された値です。1.1 と 1.3 では上位5件が埋め尽くされました。

メモ

数式によってバグが見つかりました。 隣接する RRF 順位の差はわずか $\frac{1/(60+r)}{1/(61+r)} \approx 1.6\%$ なので、融合後の乗数が約1.02を超えると、話題に沿わない項目が話題に沿う項目すべてを追い越します。以前の ×3 / ×2 / ×1.3 の「最近の項目ブースト」は、まさにそれを引き起こし、上位5件が直近72時間の日記行で埋まりました。これを削除した結果、ゴールデンセットの上位5件ヒット率は 55.0% → 75.0% になりました（ツインクローンの対照実験、2026-09-12）。

2 · 忘却 — ソースごとのエビングハウス曲線 🟢 形式 · 🟡 定数

R(t) = e^{-t/S}, \qquad S_{\text{journal}} = 2,\;\; S_{\text{knowledge}} = 180,\;\; S_{\text{palace}} = 9999 \text{ days}

3 · 間隔を空けた強化 — FSRS-lite 🟢 形式 · 🟡 定数

FSRS-6 / SuperMemo を、安定性と検索可能性の2要素に簡略化したものです。レビューセッションは実行しないため、難易度項はありません。

R = e^{-\Delta t / S}, \qquad S_0 = 7\text{ d}, \qquad \underbrace{S' = 1.3\,S}_{\text{confirmed}}, \qquad \underbrace{S' = \max(1,\; 0.5\,S)}_{\text{marked wrong}}

バケット：$R \ge 0.85$ は高温 · $\ge 0.6$ は温 · $\ge 0.3$ は低温 · それ以外はアーカイブ候補です。ダッシュボードに表示されますが、自動削除はされません。

4 · 重要度 — パレスの部屋の価値 🟡

\text{salience} = 0.30\,\text{recency} + 0.25\,\text{access} + 0.20\,\text{connections} + 0.15\,\text{urgency} + 0.10\,\text{importance}

ここで $\text{recency} = \max(0.05,\; \rho_c^{\,\text{days}})$ です。減衰率はカテゴリによって異なります。目標 $\rho = 0.99$ · アーキテクチャ $0.98$ · 決定／教訓 $0.97$ · 観察 $0.95$ · 阻害要因 $0.90$。自己申告の重要度は、意図的に最も弱い項にしています。人は重要度を誤って見積もるためです。実際の利用状況のほうが、より強いシグナルです。

5 · フィードバックから学習 — Beta–Bernoulli 🟢

recall の各結果は、有用／有用でないと評価できます。項目のスコアには、ラプラス平滑化した事後平均の2倍が乗算されます（中立の場合は ×1.0。デフォルトの経路で、融合後のスコアが変化する唯一の処理です）。

\mathbb{E}[\theta] = \frac{\text{pos}+1}{\text{pos}+\text{neg}+2}, \qquad \text{multiplier} = 2\,\mathbb{E}[\theta] \in (0, 2)

6 · 関連付け — ACT-R の活性化 🟡（オプトイン AGENT_RECALL_ACTIVATION=1）

同時に引用された記憶は、互いにリンクされます。ACT-R の宣言的記憶方程式における連想項です（Anderson と Lebiere）。

A_i = B_i + \sum_j W_j\, S_{ji}, \qquad S_{ji} = w_{ji}\, e^{-\Delta d / 30}, \qquad W_j = \tfrac{1}{|\text{context}|}

再順位付け：$\text{score}' = \text{score}\cdot\bigl(1 + 0.2\,\tfrac{x}{x+1}\bigr)$ — $\tfrac{x}{x+1}$ による圧縮で、互いに整合しない尺度が合算されるのを防ぎ、根拠がない場合には厳密に何も変更しません。

7 · 言い換えの照合 — 集合コサイン 🟡 指標 · 🟢 閾値

\cos(A,B) = \frac{|A \cap B|}{\sqrt{|A|\,|B|}}, \qquad \text{sim} = \max\bigl(\cos_{\text{concepts}},\; \cos_{\text{char-trigrams}}\bigr) \ge 0.20

語幹と13個の手作業で選定した同義語グループを対象にします（「publish / ship / release」は1つの概念にまとめられます）。これは曖昧な語彙照合であり、意味の照合ではありません。0.20 の閾値は、leave-one-out（predict-loo）で調整したもので、**誤検出率0%**を維持できる中で再現率が最も高い点です。

8 · 昇格 — まず受け入れ、その後に投票 🟢

夜間の統合では、以前は $\tfrac{\text{obs}}{7}\times\text{recency} \ge 0.8$ を条件としていました。午前2時の時点で最も新しいジャーナルは前日のものなので、再現性は $\le 0.85$ となり、「7日間に3件の観測」は $\tfrac{3}{7}\times 0.85 = 0.36$ と評価され、稼働状況の監視が正常を示す一方で、22夜連続で何も記録されずに破棄されていました。新しい方式では、受け入れと昇格を分離しています。

\text{promote} \iff \#\{(\text{day},\,\text{project}) \text{ confirmations}\} \ge 3

また、毎晩 yield レコードが書き込まれるようになりました。これにより、出力がゼロの夜も健全に見えるのではなく、empty-corpus · filtered · already-known · errored のいずれかに分類されます。

9 · 行動変化の測定 — 傾聴率 + ウィルソン区間 🟢

\text{heed} = \frac{\text{heeded}}{\text{heeded} + \text{recurred}}, \qquad
\text{CI}_{95} = \frac{\hat p + \frac{z^2}{2n} \;\pm\; z\sqrt{\frac{\hat p(1-\hat p)}{n} + \frac{z^2}{4n^2}}}{1+\frac{z^2}{n}}, \quad z = 1.96

$n$ が小さい場合は、自信に満ちた単一の推定値ではなく、誠実に幅広い区間を示します。イベントは証拠に応じて段階分けされ（heeded_verified · heeded_checkaction · heeded_default · recurred_verified · recurred_selfreport）、すべての KPI 表示で両方の段階を範囲として示します。証拠がないことを「傾聴した」と評価することはありません。

10 · 校正された信頼度 🟡

\text{conf} = \frac{\text{score}}{0.12}\;(\text{local RRF}) \;\;\big|\;\; \frac{\text{score}}{0.049}\;(\text{Supabase RRF}) \;\;\big|\;\; \cos\;(\text{vectors}) \;\;\longrightarrow\;\; \text{high} \ge .66,\; \text{med} \ge .40,\; \text{low} \ge .20

\xi^{\text{new}} = X^{\top}\operatorname{softmax}(\beta X \xi), \qquad E = -\tfrac{1}{\beta}\log\sum_i e^{\beta\langle x_i,\xi\rangle} + \tfrac12\lVert\xi\rVert^2

未解決の問題 🔴 — 冗長性によって意図を再構成できるか？

現在、蓄積された修正はクラスタリング + 減衰 + 集合コサイン類似度であり、事後分布ではなく単なる集計です。これを「意図の再構成」と呼ぶのは誇張になります。この表現に値するモデルでは、各修正を潜在的な選好 $\theta$ のノイズを含むサンプルとして扱い、$x_i = \theta + \varepsilon_i,\; \varepsilon_i \sim \mathcal N(0, \sigma^2 I)$、事前分布を $\theta \sim \mathcal N(\mu_0, \tau^2 I)$ とします。

\operatorname{Var}[\theta \mid x_{1..N}] = \Bigl(\frac{1}{\tau^2} + \frac{N}{\sigma^2}\Bigr)^{-1} = O\!\left(\frac{\sigma^2}{N}\right),
\qquad \mathrm{SNR}_N = \frac{\lVert \mu_N \rVert^2}{\operatorname{tr}\operatorname{Var}[\theta \mid x_{1..N}]}

反証可能な主張：一貫した修正が続く場合、$\mathrm{SNR}_N$ は単調に上昇し、修正が相反する場合は停滞します。一緒に作ってみませんか？ これはリポジトリで最も重要な未解決の問題です。

_{完全な導出、入力値、および各定数の由来については、packages/core/src/MATH.md を参照してください。}

約束ではなく、実測値

エージェントメモリのベンチマークでは、検索性能をテストします。修正によって、新しいエージェントの振る舞いが変わるかどうかをテストするものはありません。こちらが、都合の悪い部分も含めた、独自の計測結果です。

_{🔁 このリポジトリから再生成可能 · 🔒 所有者のプライベートストアでの自己計測値であり、ここでは再現できません。角括弧内は 95% 区間です。埋め込みの 80.8% はオプトインモデルを使ってローカルで計測しています（CI はこのモデルをダウンロードしないため、成果物はコミットされていません）。実行時間はマシンに依存します。CI ではスキーマと決定性をゲートし、実行時間の値はゲートしません。}

他のメモリツールとの比較

_{競合製品の数値は各社が公開しているものであり、同一条件での実測値ではありません。概要については、docs/research/agent-memory-landscape-2026-07.md を参照してください。}

インストール

MCP サーバー — エージェント向け

# Claude Code
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

# Codex
codex mcp add agent-recall -- npx -y agent-recall-mcp

// Cursor — .cursor/mcp.json   ·   Windsurf — ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

// VS Code — .vscode/mcp.json
{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

スキル — Claude Code

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall-X/main/SKILL.md

SDK — JS/TS アプリ向け

import { AgentRecall } from "agent-recall-sdk";

const memory = new AgentRecall({ project: "my-app" });
await memory.capture("What stack?", "Next.js + Postgres");
const ctx = await memory.recall("rate limiting");

各インスタンスには独立したルート（AsyncLocalStorage）が割り当てられるため、同時に実行されるインスタンス間で状態が共有されることはありません。

CLI — ターミナル、CI、フック向け

npx agent-recall-cli recall "rate limiting"
ar bootstrap            # scan git repos, Claude AutoMemory, CLAUDE.md files (read-only, secrets untouched)
ar bootstrap --import   # import what it found

オプション機能

ar embeddings setup     # one-time: local runtime (~380 MB) + model (~145 MB), cached
ar embeddings rebuild   # incremental — only new/changed content embeds
export AGENT_RECALL_EMBEDDINGS=1
ar embeddings status

アーキテクチャ

packages/
├── core/         storage, retrieval, math, tool logic     agent-recall-core
├── mcp-server/   thin MCP wrappers                        agent-recall-mcp
├── sdk/          programmatic API                         agent-recall-sdk
└── cli/          the `ar` command + hooks                 agent-recall-cli

flowchart LR
    Q[query] --> T[tokenize · stem<br/>synonyms · IDF]
    T --> P[palace<br/>0.9 key + 0.1 salience]
    T --> J[journal<br/>0.5 recency + 0.5 exact]
    T --> I[insights<br/>relevance · exact · confirm]
    T --> K[corrections<br/>exact · severity · proof]
    Q -. opt-in .-> V[local embeddings<br/>cosine top-8]
    P & J & I & K & V --> F["RRF  Σ w/(60+rank)"]
    F --> B["× Beta feedback"]
    B --> C[calibrated confidence]
    C --> R[results + alsoLinked]

すべてのメモリはローカルの Markdown です。オプションの Supabase ミラーを追加すると、同じ RRF 融合による pgvector 検索を利用できます。デフォルトでは、すべてローカルで処理されます。書き込みには、進行状況を考慮したファイルロックと NTFS 対応のロック解放を使用します。アラインメントとフィードバックのログは追記専用の NDJSON です。

プラットフォーム

CI では ubuntu-latest と windows-latest 上でビルド、回帰テスト、テストを実行します。

コミュニティ

• 💬 Telegram — 質問、フィードバック、リクエスト
• 🗣️ GitHub Discussions — 現場からの報告、ベンチマーク結果、アダプター、中文区
• 🐛 GitHub Issues — バグや機能の要望
• 📦 npm: agent-recall-mcp · agent-recall-sdk · agent-recall-cli

ヒント

最も役立つ、15分でできる貢献。 この分野では、ベンダーが選んだ良好な結果はありますが、動作の変化を測る外部ベースラインはありません。AgentRecallを1週間使ってから、次を実行してください。

git clone https://github.com/Goldentrii/AgentRecall-X.git && cd AgentRecall-X
npm ci && npm run bench    # ローカルの ~/.agent-recall コーパスを読み込みます

結果をDiscussions → Benchmark Numbersに投稿してください。スコアが低くても、有効な結果です。詳しくはCONTRIBUTORS-WANTED.mdをご覧ください。

貢献者

Windowsへの移植作業と、3.5.xに反映された修正を行ってくださった@buer5、@lonelyhty、雷昊に感謝します。

リンク

• README.full.md — SDK API、CLI、すべてのツールパラメーターを網羅した完全なリファレンス
• packages/core/src/MATH.md — すべての数式、定数、ラベル
• docs/eval/REPRODUCE.md — 🔁の数値をすべて再生成する方法
• CHANGELOG.md · UPDATE-LOG.md — 変更内容とその理由
• Correction-transfer benchmark spec · Agent-memory landscape 2026
• SKILL.md — Claude Codeのスキル · AGENTS.md — このリポジトリで作業するエージェント向け
• 以前のREADME：docs/archive/README-2026-10-13.md

貢献

プルリクエストを歓迎します。重要な変更を行う場合は、まずIssueを作成してください。このプロジェクトの設計は明確な方針に基づき、公開された研究を土台としています。変更についても同じように、数式、ラベル、測定結果に裏付けられたものを求めています。

ライセンス

MIT — LICENSEをご覧ください。