Audrey

エージェントはチャットだけでなく、作業そのものを覚えているべきです

月曜日にデプロイコマンドを修正したとします。木曜日には、新しいセッションが壊れたバージョンを再び試します。

このリポジトリは生成されたファイルを決してコミットしないと説明したとします。次のエージェントは親切にもそれをコミットします。

微妙なマイグレーションルールを発見し、どこかに書き留めたとしても、新しい会話のたびにそれを貼り付けるのを覚えていなければなりません。

それが、Audrey が埋めるギャップです。

Audrey はエージェントのそばに寄り添い、作業に自動的に参加します。セッションの開始時には、関連性の高い小さな記憶パケットを呼び戻します。プロンプトを送信すると、プロジェクトの事実、好み、手順、最近のリスクを思い出します。副作用を伴うツールが実行される前に、Audrey は提案されたアクションを過去の証拠と照合して確認します。その後、結果をその直前の確認と正確に結び付けます。

モデルは記憶ツールが存在することを覚えておく必要はありません。そこが要点です。

Audrey Autopilot の紹介

Audrey を一度インストールし、フックを一度確認すれば、あとは Codex や Claude Code を通常どおり使うだけです。

npm install -g audrey
audrey install --host auto

Node.js 22.16 以上（22.x）または 24 以上が必要です。SQLite は Node に組み込まれているため、新規インストールや npx での起動は、依存関係スクリプトを承認しなくても動作します。npm 11.17 以上では依存関係スクリプトに関する警告が出る場合があり、npm 12 ではブロックしたと報告される場合がありますが、これらのスクリプトは Audrey の CPU 埋め込みランタイムには必要ありません。

auto は、インストールされているサポート対象の CLI を構成します。明示的に 1 つを選ぶこともできます。

audrey install --host codex
audrey install --host claude-code

インストール後はホストを再起動してください。Codex は /hooks を通じて一度だけ非管理フックを信頼するよう求めます。Claude Code もプロジェクトまたはプラグインのコンポーネントの承認を求める場合があります。この明示的なインストールと信頼のステップの後は Audrey は自動的に動作します—決してこっそりインストールされることはありません。

その後、Autopilot がループを閉じます。

タイミング	Audrey が行うこと
セッション開始	エージェント単位に絞られた簡潔な記憶ブリーフィングを注入します
プロンプトを送信	関連する証拠を思い出します。「remember that…」や「I prefer…」といった明示的に永続化されるフレーズは記憶になることがあります
Bash/edit/write が提案される	過去の正確な失敗、信頼されたルール、手順、矛盾、記憶の健全性を確認します
ツールが完了する	tool_use_id を Guard のレシートに関連付け、秘匿化された結果を記録します
ツールの失敗が報告される	次の試行のために、永続的でサニタイズされた失敗記憶を形成します
ターンが停止するかコンテキストが圧縮される	会話を開いたままにせず、軽量で期限が来たものだけの統合を実行します

各フックイベントには、ホストが宣言したタイムアウトが伴います（PreToolUse の Guard チェックでは 30 秒）。Audrey は自身の内部埋め込み/LLM タイムアウトをその期限より数秒早く競わせることで、ホストによる強制終了との競争に負けるのではなく、クリーンに終了できるようにします。インフラ障害はデフォルトでフェイルオープンです。Audrey 自体がエラーになったり時間切れになったりした場合、セッションをフリーズさせるのではなく、ツール呼び出しはガードなしで続行されます。このように PreToolUse チェックが失敗したときに代わりにアクションを拒否するには、AUDREY_HOOK_FAIL_CLOSED=1 を設定します。その他のライフサイクルフック（セッション開始、プロンプトの想起、ツール後の記録）にはフォールバックする「拒否」がなく、この設定に関係なく常にオープンに劣化します。

失敗したデプロイについての小さな物語

最初の試みは失敗します:

$ npm run deploy
Error: deployment target is missing

Audrey は秘匿化されたトレースと、その正確なアクションのフィンガープリントを保持します。問題が修正される前に別のセッションが同じアクションを提案すると、Guard は証拠とともに拒否を返します。コマンドを変更するか対象を修正すれば、Audrey は作業の続行を許可します。その正確なアクションが一度成功すれば、古い失敗はもはやそれをブロックしません。

これは「ベクトル検索が漠然と似たエラーを見つけた」よりも有用です。Audrey はアクションの前にレシートを作成し、その後に何が起きたかを記録し、両者の間の系譜を保持します。

API キーやネットワーク呼び出しなしで、完全なループを試してみてください:

audrey demo --scenario repeated-failure

見ることは行うことではない

失敗したデプロイと再試行の間、エージェントは何も変更できない多くのコマンドを実行します: エラーを探す grep、git status、設定ファイルに対する cat、存在しないことが判明するディレクトリに対する ls。それらすべてをリスクとして扱ったり、grep が何も見つけられなかったことを「失敗」として記憶したりする記憶システムは、トーストを焼くときに鳴り出す煙警報器になります。人々は耳を傾けるのをやめ、そしてトースターが燃えている日にそれは何の価値も持ちません。

Audrey はエンジニアが読むようにコマンドを読み取ります。そのすべての部分が読み取り専用であると積極的に認識されるコマンド(grep、git log、npm view、docker ps、sed -n '1,40p'、およびそれらに類するもので、コマンド置換がなく、/dev/null 以外へのリダイレクトがなく、sudo や xargs がなく、動詞が何に解決されるかを変えうる環境変数代入がないもの)は、Guard にまったく到達しません。その終了コードは記録されますが、教訓として数えられることはありません。それ以外のすべては以前とまったく同じようにガードされ、Audrey が積極的に認識できないものはすべて行うこととして扱われます。

$ grep -rn "prisma" src/          Guard: silent
$ git status --short              Guard: silent
$ cat prisma/schema.prisma        Guard: silent
$ npm run deploy
Audrey Guard: BLOCKED
- recent_failure (high): This exact Bash action failed before: Prisma client was not generated. Run npm run db:generate before deploy.
- must_follow (high): Before running npm run deploy, run npm run db:generate because Prisma client must be generated first.

これは audrey demo --scenario repeated-failure の出力であり、API キーもネットワークもなしでシーケンス全体を実行します。

Guard が実際に発言するとき、それはどの記憶から話しているのかを明示し、記憶された失敗は、2 つの文字列が埋め込みに対してどれほど似て見えるかではなく、何を実行するか(npm run deploy と npm run deploy)によって提案されたコマンドと照合されます。

実行可能なオプションやライフサイクルスクリプトを持つコマンドはガードされます。これには git ls-remote --upload-pack=...、npm pack --dry-run、ss -K が含まれます。分類器は通常の検査コマンドのための便宜であり、オペレーティングシステムのサンドボックスではありません。リポジトリの設定、シェルの展開、およびリーダーが呼び出すプログラムは、コマンドの動作を変える可能性があります。強制が必要な場合は、ホストの権限またはサンドボックスを使用してください。

Audrey が記憶するもの

Audrey は記憶を単なるテキストチャンクの山以上のものとして扱います。

• エピソードは起きた出来事です: ユーザーの決定、ツールの結果、プロジェクトの事実、好み。
• 意味記憶は、蓄積された証拠に裏付けられた原則です。
• 手続き記憶は行動の仕方です: 再試行、検証、回避、回復の方法。
• 矛盾は黙って上書きされるのではなく、可視のまま残ります。
• 信頼度は、情報源の品質、証拠、経過時間、検索、干渉、コンテキスト、フィードバックによって変化します。
• 価値の低い記憶は減衰し、繰り返された証拠はより長寿命の知識に統合されることがあります。

すべてのコンテキストパケットには、記憶 ID、信頼度、利用可能な場合は出所、および含める理由が含まれます。不確実または争いのある記憶はそのようにラベル付けされます。取得されたコンテンツは、シンプルなルールでラップされます: 記憶は証拠であり、権威ではありません。現在のシステムとユーザーの指示が常に優先されます。

メモリが真実でなくなる瞬間

メモリがおかしくなるのは、時間の経過だけが原因ではありません。「npm run deploy:prod でデプロイする」というメモは、ごく最近のもので出典も確かでありながら、そのスクリプトが削除された日には完全に間違ったものになります。さらに悪いことに、想起のたびにそのメモリは強化されます。検索されたという事実が、そのメモリが有用である証拠とみなされるからです。自信を持って述べられ、十分な裏付けのある誤った指示は、メモリがまったくない状態よりも有害です。

そこで Audrey は確認を行います。メモリが書き込まれるとき、プロジェクトに対して検証可能な主張 — リポジトリ相対のパスやパッケージスクリプト名 — をその中から記録し、その時点で解決できるものだけを保持します。この最後の部分が、このシグナルに価値をもたらします。一度も解決しなかった主張はタイプミスに関する推測にすぎませんが、かつて解決し、今は解決しなくなった主張は、それを依然として主張し続けるメモリの足元で世界が動いたことを意味します。

audrey ground

[audrey] Grounding memories against /home/you/project
[audrey] Checked 14: 12 still true, 2 broken, 0 repaired.
[audrey]   01K8ZQ... references a missing npm_script: deploy:prod
[audrey]   01K8ZR... references a missing path: scripts/release.mjs

壊れたメモリは削除されません。内容は保持したまま、それが今なお参照しているものを明確に示し、信頼度のペナルティを受けることで、デフォルトで先導することはなくなりつつも、引き続き読むことができ、修復も可能です。また、パケットの必ず従うべきセクションの対象からも外れます。これは Guard ブロックを強制できるセクションであり、もはや存在しないファイルを名指しするルールは誰も従えないルールだからです。

修復は対称的です。ファイルやスクリプトを復元すれば、次のチェックでフラグが解除されます。移動したチェックアウトは、壊れているではなく不明として報告されます。このマシンが現在見ることのできないプロジェクトを記述しているという理由だけで、メモリの信頼を損なうべきではないからです。

検証可能な主張を持たないメモリには、ラベルが付与されません。沈黙は健全なお墨付きではなく、それをそうであるかのように提示することは、逆方向を向いた同じ過ちです。

できることのすべてと、実際に使う場面

このほとんどは、Autopilot をインストールすれば自動で動作します。recall を呼び出す必要も、Guard を呼び出す必要もありません。この表は、あえて自分で使いたい部分のためにあり、自動で動く部分が魔法ではなく読み取れる形になっています。

何を	いつ使いたいか	なぜ役立つか	どうやって
Autopilot	常に、一度インストールした後は	これが本質です。エージェントが行動する前に記憶が届き、何かおかしくなったと気づいた後ではありません。	audrey install --host auto、ホストを再起動し、フックを一度承認します
Guard	自動で、副作用があり得るあらゆる編集、書き込み、シェルコマンドの前	正確なアクションのフィンガープリントを過去の失敗と照合します。「こんな感じのことが一度壊れた」ではなく、まさにこのコマンドが、まだ壊れているということです。読み取り専用コマンド（grep、ls、git status）はガードされず、その非ゼロ終了は失敗として記憶されません。	PreToolUse で実行されます。手動の場合: audrey guard --tool Bash --strict
Grounding	記憶が言及している可能性のあるものを削除または名前変更した後	信頼度は、その記憶が確かな出典に基づいていることを教えてくれます。Grounding は、それがまだ真であることを教えてくれます。削除したスクリプトに関するメモは、信頼度が高く、そして間違っています。	audrey ground、またはメンテナンススイープに任せます
Session briefing	セッション開始時に自動で	毎回コンテキストを貼り付ける代わりに、小さくスコープされたパケットです。変更されていない記憶はセッションごとに一度だけ注入され、内容や位置づけの変更は再度送信されます。	SessionStart フック。audrey greeting でプレビューできます
Explicit capture	「remember that…」や「I prefer…」と言ったとき	意図的な記憶は推論されたものより価値があり、そのように言うだけで十分です。	ただ入力するだけです。Autopilot がそうした文の形を拾います
Consolidation	アイドル時に自動で、長い休憩の前に手動で	繰り返されたエピソードが 1 つの原則になります。そうでなければ、ストアはほぼ重複したものの山になり、recall がノイズだらけになります。	audrey dream
Contradictions	2 つの記憶が矛盾するとき	どちらかが黙って勝つことはありません。何かが解決するまで、両方とも可視化されラベル付けされたままになります。	パケットで表面化します。1 つを解決するには memory_resolve_truth
Decay	自動で	価値の低い記憶は薄れていきます。強化されたものは残ります。Consolidation と同じスイープで実行されます。	audrey dream の一部です
Promote	パターンがリポジトリのルールになるべきとき	学習した習慣を記憶から、チームが読んでレビューできるファイルへ移します。	まず audrey promote --dry-run
Impact	これらが機能しているかどうかを知りたいとき	どの記憶が使われ、役立ったかどうかを示します。「これは元が取れているか」に答えます。	audrey impact --window 30
Snapshot	バックアップ、または新しいマシンへの移行	ストア全体を 1 つの JSON ファイルに。インポートはそれを信頼できないものとして扱います。取り込む際に秘匿化され、信頼マーカーが除去されます。	AUDREY_ENABLE_ADMIN_TOOLS=1、その後 memory_export / memory_import
Doctor	パケットが届かなくなったとき	実際の 2 つの原因は、ずれたフックのエントリポイントと、枯渇した consolidation です。Doctor はどちらかを特定します。	audrey doctor
Demo	これを信頼する前に	API キーもネットワークもなしで、ループ全体を実行します。動作を確認するのに設定するものは何もありません。	audrey demo --scenario repeated-failure
REST sidecar	Codex や Claude Code ではないカスタムエージェント	同じメモリランタイム、同じエビデンス契約を、HTTP 経由で。Python と JS のクライアントが含まれています。	AUDREY_API_KEY を設定して audrey serve

Audrey が意図的に行わないこと

Audrey は、デフォルトであなたのメモリをホスト型サービスにアップロードしません。すべての文を永続的な真実として扱うこともありません。任意のツール出力に含まれる指示を信頼されたポリシーへ昇格させることもありません。小規模なローカルベンチマークが最先端のメモリ品質を証明するなどと主張することもありません。

生のプロンプトイベントとツールの本体は、デフォルトでは保持されません。Audrey が保存するのは、ハッシュ、範囲を限定した要約、フィンガープリント、および秘匿化メタデータです。明示的なユーザーメモリの記述は意図的に永続化されますが、ツール障害のメモリはまずサニタイズされます。管理用のエクスポート／インポート／忘れさせる／昇格させる機能は、AUDREY_ENABLE_ADMIN_TOOLS=1 でない限り無効化されています。

保存時の暗号化、ID に紐づくテナント認可、レート制限、および規制対象の保持は、現時点ではデプロイ側の責任のままです。それらは「本番環境対応」というバッジの裏に隠されているわけではありません。

チームが実際にこれを求める理由

繰り返されるミスの削減

Guard は、被害が生じた後ではなく、アクションを変えうる時点でメモリを検査します。正確な障害フィンガープリントにより、「1 つの Bash コマンドが失敗したから、すべての Bash コマンドが疑わしい」というノイズの多い挙動を避けられます。

エージェントセッションをまたぐ継続性

Audrey は特定のモデルベンダーに縛られません。Codex と Claude Code は同じメモリランタイムと同じエビデンス契約を使用します。MCP、REST、JavaScript、Python のクライアントにより、カスタムエージェントでもコアを利用できます。

人間が検査できるエビデンス

許可、警告、ブロックの判断には、レシートとエビデンス ID が付随します。結果レコードはそれらのレシートに結びつきます。チームは「エージェントは何を覚えていたか」だけでなく、「どのメモリがこのアクションを変え、それが役に立ったのか」も問うことができます。

ローカルでの制御

デフォルトのストアは SQLite、FTS5、および sqlite-vec です。ローカル埋め込みがデフォルトです。クラウドの埋め込みまたは LLM プロバイダーを利用するには、明示的な設定が必要です。

より安全な共有ストア

エージェント単位のリコールは、検証、矛盾検出、干渉、感情、障害検索、カプセル、挨拶、Guard、および REST リクエストルーティングを通じて継続します。リコールは、返された結果に対する検索の記帳（意味記憶および手続き記憶の使用回数と最終強化タイムスタンプ）を更新します。カプセルと Guard のフィルタリングにより、それらの結果がさらに絞り込まれる場合があります。明示的な検証フィードバック（memory_validate / /v1/validate）は、単にリコールされたかどうかではなく、メモリが実際にどのように機能したかに基づいて、別途重要度を調整します。

ベクトル候補は、最近傍ランキングの前にエージェントごとに分割されるため、あるビジーなエージェントが別のエージェントを有限の検索から締め出すことはありません。厳密なテナント境界が必要な場合は、テナントまたはセキュリティドメインごとに別個の AUDREY_DATA_DIR を使用してください。

何もインストールする前に試す

npm exec --yes --package=audrey -- audrey demo --scenario repeated-failure

このコマンドは npm キャッシュから実行され、SQLite を基盤とする Guard ループ全体を動作させ、ホストの設定を変更せずに終わります。

私たちが目指す方向

その野心は、エージェントのための時間的エビデンスグラフです。不変の観測、明示的な有効期間、ソースの信頼性、進化する主張、スコープ付きの手続き、および結果で調整されたポリシーです。擁護できる部分は、より多くのテキストを保存することではありません。何が、なぜ、どのコンテキストで、どのくらいの期間信じられていたのか、そしてそれに基づいて行動することが役立ったのかを把握することです。

近期的な作業には、耐久性のあるバックグラウンド認知ジョブ、資格情報に紐づくテナント名前空間、メモリの隔離と汚染伝播、公開された長期的評価、暗号化バックアップの選択肢、およびフックごとのモデル起動を完全に排除する永続的なローカルデーモンが含まれます。

もしそれがあなたの構築したい種類のエージェントインフラであるなら、issue を開くか、デモから始めてください。Audrey は MIT ライセンスであり、製品の境界は意図的に検査可能になっています。

---

技術リファレンス

以下はすべてその仕組みです。上記の短い説明が製品です。

要件とパッケージ

• Node.js 22.16+（22.x）または 24+。Node 20 および 23 はサポート対象外になりました
• npm パッケージ: audrey
• Python クライアント: audrey-memory
• デフォルトのストレージ: ローカル SQLite + FTS5 + sqlite-vec
• デフォルトの埋め込み: ローカルの 384 次元モデル

npm install audrey
pip install audrey-memory

Audrey は node:sqlite を使用します。sqlite-vec はプラットフォーム別パッケージで拡張機能を提供します。ローカル埋め込みランタイムには CPU バイナリも含まれているため、npm install --ignore-scripts audrey が機能します。オプションの依存関係は有効のままにしてください。これらには sqlite-vec と sharp のプラットフォームファイルが含まれています。GPU アクセラレーションには、お使いのプラットフォーム向けの追加の ONNX Runtime ライブラリが必要になる場合があります。サポート対象の Node リリースの一部では、起動時に実験的な SQLite 警告が出力されますが、動作には支障ありません。

Autopilot では、グローバルまたはその他の安定したインストールを推奨します。フックと MCP の設定は実際の Node 実行ファイルと Audrey のエントリポイントを固定します。一時的な npx キャッシュは、耐久性のある本番ランタイムではありません。

ホストの設定

ライフサイクルフックを個別にプレビューまたは適用します:

audrey hook-config claude-code
audrey hook-config claude-code --apply --scope local
audrey hook-config claude-code --apply --scope project
audrey hook-config claude-code --apply --scope user

audrey hook-config codex
audrey hook-config codex --apply --scope project
audrey hook-config codex --apply --scope user

Claude Code のスコープの対応はホストの用語に従います:

• local → .claude/settings.local.json
• project → .claude/settings.json
• user → ~/.claude/settings.json

Codex はプロジェクトの .codex/hooks.json とユーザーの ~/.codex/hooks.json をサポートしますが、ローカルフックスコープはありません。Audrey は無関係なフックを保持し、古い Audrey 所有のハンドラーを置き換え、タイムスタンプ付きのプライベートなバックアップを作成し、繰り返しのインストールに対して冪等です。プロジェクト隣接のバックアップ名は *.audrey-*.bak に一致します。ホスト設定には無関係な認証情報が含まれる可能性があるため、このパターンを無視対象にしてください。

Audrey は CLAUDE_CONFIG_DIR と CODEX_HOME を尊重します。生成されるフックは、インストール時に使用された安定した Node 実行ファイル、Audrey のエントリポイント、データディレクトリ、エージェントの識別情報、および非シークレットのプロバイダー選択を固定します。ローカル埋め込みの場合、Autopilot インストールでは 1 回のウォームアップを実行するため、最初の実際のフックが最初のモデル読み込みを兼ねることはありません。スキップするには AUDREY_DISABLE_WARMUP=1 を設定します。

MCP 設定を適用せずに生成します:

audrey mcp-config codex
audrey mcp-config generic
audrey mcp-config vscode

インストール時と同じホストとスコープで、Audrey 所有の MCP 登録とフックを削除します:

audrey uninstall --host auto --scope user
audrey uninstall --host claude-code --scope local
audrey uninstall --host codex --scope project

--dry-run を追加すると、どちらのホストも変更せずにアンインストールをプレビューできます。--mcp-only は、Audrey のフックを意図的に保持したい場合にのみ追加してください。

Autopilot の安全契約

共有フックアダプターは、現在の Codex と Claude Code のペイロードを正規化します。

• コンテキスト注入は AUDREY_CONTEXT_BUDGET_CHARS によって制限されます（デフォルトは 4000。Autopilot は上書きされない限り、保守的に 3200 文字のパケットを使用します）。
• プロンプトとツール検索のクエリは、埋め込みの前に制限されます。大きな編集では、ファイル本体ではなくハッシュと長さを保持します。Guard の正確な同一性判定には、切り詰められたプレフィックスではなく、完全なマスク済みダイジェストを使用します。
• 生成されるデフォルトフックは、Bash、Edit、MultiEdit、Write、NotebookEdit、apply_patch、および接続された MCP サーバーからのすべての mcp__* ツールをガードおよび監視しますが、Audrey 自身のメモリツールは除外されるため、Guard が自分自身をガードすることはありません。
• Bash コマンドは、副作用を持つ可能性がある場合にのみガードされます。すべての部分が読み取り専用であると確実に認識されるコマンド（grep、ls、sed -n、git status、npm ls など。コマンド置換なし、/dev/null 以外へのリダイレクトなし、sudo、xargs、eval なし）はプリフライトをスキップし、その非ゼロ終了は記録されますが、回避すべき失敗として扱われることはありません。分類器が認識しないものはすべてガードされます。
• 記憶された Bash の失敗は、2 つのコマンド文字列がどれほど似ているかではなく、実行される動詞（npm run deploy、git push）によって提案されたコマンドと照合されます。
• Pre/Post の相関には session_id + tool_use_id を使用するため、並列のツール呼び出しが誤ったレシートに紐付くことはありません。
• Claude の PostToolUseFailure と、非ゼロ終了を明示的に公開する Codex の応答は、同じ失敗パスに正規化されます。現在の Codex フックは Bash の終了ステータスを省略する可能性があります。Audrey は不透明な結果を unknown として記録し、捏造された成功として記録することは決してありません。
• 内部エラーが発生した場合、すべてのフックは stderr にログを出力し、{} を出力します（意見なし、つまりツールは続行します）。AUDREY_HOOK_FAIL_CLOSED=1 の下で動作を変更するのは PreToolUse のみで、代わりに拒否の決定を出力します。コンテキスト注入フックとポストツールフックには拒否パスがなく、常に {} を出力します。
• Stop フックは常に有効な JSON を出力し、完了したターンを継続またはブロックすることはありません。

Codex のフック傍受はガードレールであり、完全なシェルポリシー境界ではありません。現在のホスト契約は、よりリッチなすべての unified_exec パスを傍受するわけではなく、サイレントな Bash 失敗の終了ステータスを省略する可能性があります。Codex フックのドキュメントを参照してください。Guard のレシートを証拠として使用し、サンドボックス化、承認、CI、およびデプロイメントの制御を引き続き維持してください。

JavaScript API

import { Audrey, MemoryController } from 'audrey';

const memory = new Audrey({
  dataDir: './audrey-data',
  agent: 'payments-agent',
  embedding: { provider: 'local', dimensions: 384 },
});

await memory.encode({
  content: 'Stripe returns HTTP 429 above 100 requests per second.',
  source: 'direct-observation',
  tags: ['stripe', 'rate-limit'],
  context: { service: 'billing' },
});

const capsule = await memory.capsule('increase Stripe throughput', {
  scope: 'agent',
  budgetChars: 3000,
});

const guard = new MemoryController(memory);
const before = await guard.beforeAction({
  action: 'deploy the billing worker',
  tool: 'Bash',
  command: 'npm run deploy:billing',
  cwd: process.cwd(),
});

console.log(before.decision, before.evidenceIds);
await memory.closeAsync();

REST サイドカー

AUDREY_AGENT=payments-agent audrey serve
curl http://127.0.0.1:7437/health

主要なルート:

目的	ルート
エピソードをエンコードする	POST /v1/encode
メモリを呼び出す	POST /v1/recall
コンテキストパケットを構築する	POST /v1/capsule
アクションの前に確認する	POST /v1/preflight
Guard レシートを作成する	POST /v1/guard/before
Guard レシートを閉じる	POST /v1/guard/after
統合と減衰	POST /v1/dream
ヘルスとインデックスの状態	GET /v1/status
学習した手順をルールファイルに昇格させる（管理者）	POST /v1/promote

非ループバックのデプロイメントには AUDREY_API_KEY を使用してください。X-Audrey-Agent は、信頼されたデプロイメント内でエンコード、呼び出し、カプセル、プリフライト、Guard、統合、および挨拶のスコープを設定します。これはルーティングヘッダーであり、認証境界ではありません。エージェント/テナントのアイデンティティは、任意の公開ヘッダーを信頼するのではなく、ゲートウェイでバインドしてください。すべてのルートは、リクエストごとにヘッダーを設定できない呼び出し元（Python クライアントなど）のフォールバックとして、JSON ボディ内の呼び出しごとの agent フィールドも受け付けます。両方が存在する場合はヘッダーが優先されます。

Python クライアント

from audrey_memory import Audrey

memory = Audrey(base_url="http://127.0.0.1:7437", agent="payments-agent")
memory_id = memory.encode(
    "Stripe returns HTTP 429 above 100 requests per second.",
    source="direct-observation",
)
results = memory.recall("Stripe rate limit", limit=5)
memory.close()

Python パッケージは REST サイドカーのクライアントであり、メモリランタイムは Node プロセスに残ります。

メモリと検索のパイプライン

episode
  ├─ transactional SQLite + vector + FTS write
  ├─ agent-scoped interference / resonance / validation
  ├─ reinforcement or contradiction evidence
  ├─ sleep-time consolidation into semantic or procedural memory
  └─ grounding checks that stored claims still hold in the project

query
  ├─ bounded vector candidates
  ├─ FTS5 lexical candidates
  ├─ reciprocal-rank fusion and confidence scoring
  ├─ context / affect / recency / interference modifiers
  └─ final-only retrieval bookkeeping

エージェントスコープのベクトル検索は、最近傍ランキングの前にネイティブの sqlite-vec パーティションキーを使用し、ストア全体の候補を後からフィルタリングする方式ではありません。フュージョンの結果が不足している場合、Audrey はパーティションローカルな再試行を 1 回だけ、上限付きで実行します。セマンティック検索と手続き的検索のカウントは、最終結果が yield されたときにのみ更新されます。重複排除された候補、上限を超えた候補、消費されなかったストリーム候補は、権威のブーストを受け取りません。

MCP サーフェス

Audrey は 23 個の MCP ツールに加えて、ステータス、最近のメモリ、原則のリソース、および briefing/recall/reflection プロンプトを公開しています。主なグループは次のとおりです:

• キャプチャ: memory_encode、memory_reflect、memory_observe_tool
• 検索: memory_recall、memory_capsule、memory_greeting
• アクションの安全性: memory_preflight、memory_guard_before、memory_guard_after、memory_reflexes
• ライフサイクル: memory_consolidate、memory_dream、memory_decay、memory_resolve_truth、memory_ground
• ガバナンス: memory_validate、memory_promote、memory_forget、memory_export、memory_import、memory_status、memory_introspect

また、このサーバーは、ライフサイクルフックが利用できない場合に Guard レシートループを説明するホスト指示を送信します。

環境変数

変数	デフォルト	目的
AUDREY_MODEL_CACHE_DIR	$XDG_CACHE_HOME/audrey/models または ~/.cache/audrey/models	ローカルモデルファイル用のユーザーごとの書き込み可能なキャッシュ
AUDREY_SHARED_STORE	0	意図的に共有されるストアに対して、運用者が管理する権限を保持するには 1 を設定します
AUDREY_DATA_DIR	~/.audrey/data	SQLite ストア。テナント/セキュリティ境界ごとに別のディレクトリを使用してください
AUDREY_AGENT	ホスト固有	スコープ付き操作に使用される論理的なメモリ所有者
AUDREY_EMBEDDING_PROVIDER	local	local、gemini、openai、または mock
AUDREY_LLM_PROVIDER	未設定	振り返り/統合には anthropic、openai、または mock。未設定（または auto）の場合はローカルのヒューリスティックのみを使用し、環境内の ANTHROPIC_API_KEY/OPENAI_API_KEY は決して使用しません
AUDREY_LLM_MODEL	プロバイダーのデフォルト	明示的な LLM モデルの上書き
AUDREY_DEVICE	gpu	ローカル埋め込みデバイス。CPU にフォールバックします
AUDREY_CONTEXT_BUDGET_CHARS	4000	デフォルトのカプセル最大サイズ
AUDREY_AUTOPILOT_SCOPE	agent	フックに対する agent または明示的なクロスエージェントの shared リコール
AUDREY_PACKET_FORMAT	compact	注入されるパケットのスタイル: compact の行形式または verbose の key=value
AUDREY_PACKET_DELTA	1	変更されていない各メモリバージョンをセッションごとに 1 回注入します。0 は毎プロンプトで完全なパケットを再送します
AUDREY_HOOK_FAIL_CLOSED	0	Audrey 自体が失敗したときにガードされたアクションを拒否します
AUDREY_API_KEY	未設定	REST アクセス用のベアラートークン
AUDREY_ALLOW_NO_AUTH	0	非ループバックの REST アクセスを認証なしで許可するには 1 を設定します
AUDREY_HOST	127.0.0.1	REST のバインドアドレス
AUDREY_PORT	7437	REST ポート
AUDREY_ENABLE_ADMIN_TOOLS	0	エクスポート、インポート、忘れる、および昇格の操作を有効にします
AUDREY_ENABLE_SHARED_SCOPE	0	明示的なクロスエージェントの REST リコールを許可します。管理ツールでも有効になります
AUDREY_PROFILE	0	ステージのタイミング診断を含めます
AUDREY_DISABLE_WARMUP	0	MCP 埋め込みのウォームアップを無効にします
AUDREY_PRAGMA_DEFAULTS	1	SQLite のパフォーマンスチューニングを無効にするには 0 を設定します

プロバイダーのシークレットが生成されたフックコマンドに埋め込まれることはありません。--include-secrets は MCP 登録にのみ適用されます。ホストの環境変数インジェクションまたはシークレットマネージャーを推奨します。

新しいローカルストアは、POSIX モードをサポートするファイルシステム上でプライベートなディレクトリおよびデータベースの権限を使用します。既存のデータベースおよび WAL ファイルは、オープン時に制限されます。Windows およびマウントされたボリュームには、適切なオペレーティングシステムの ACL が必要です。共有アクセスを自分で管理する場合にのみ、AUDREY_SHARED_STORE=1（SDK: sharedStore: true）を設定してください。

ローカルモデルは初回使用時にユーザーごとのキャッシュにダウンロードされます。オフラインでフックに依存する前に、その初回実行を完了させてください。初期化に失敗した場合は、同じプロセス内で再試行できます。root によってインストールされたシステムパッケージの場合、キャッシュが書き込み可能なままになるよう、デスクトップユーザーとして初期モデルロードを実行してください。

スナップショット形式 2 は、グラウンディングアンカー、その最後に認識された状態、および統合の取り消しジャーナルを保持します。古いスナップショットもインポート可能なままです。ワークツリーはリコールのためにリポジトリのアイデンティティを共有しますが、グラウンディングはアンカーが記録されたチェックアウトを確認します。ロールバックは、マージを取り消す際に以前の知識を保持します。取り消しジャーナルのないレガシーマージは、安全に逆戻りできない場合に拒否されます。

REST API は JSON リクエストボディを必要とし、クロスオリジンのブラウザーリクエストを拒否します。AUDREY_ALLOW_NO_AUTH=1 が明示的に設定されていない限り、認証されていないリクエストにはループバックホストが必要です。ネットワーク展開では AUDREY_API_KEY を設定してください。

本番運用チェックリスト

• すべてのテナントまたは厳密な分離ドメインに、それぞれ専用の AUDREY_DATA_DIR を割り当ててください。
• 埋め込みプロバイダーと LLM プロバイダーを明示的に固定してください。
• プロバイダー、次元、またはバージョンの移行前に、ストアをバックアップしてください。
• REST サイドカーは認証とレート制限の背後に置いてください。エージェント選択ヘッダーをアイデンティティとして公開しないでください。
• クロスエージェント検索が意図的であり、独自のアイデンティティレイヤーによって承認されている場合を除き、REST の共有スコープは無効のままにしてください。
• 認証情報および規制対象の生コンテンツを、エンコードされたメモリに含めないでください。
• 規制対象での利用前に、保持、削除、暗号化、および監査のポリシーを決定してください。
• audrey status --json --fail-on-unhealthy を監視してください。
• フックランタイムは、安定したインストール済みパスに置いてください。
• ご利用のトポロジーに対して、同時書き込みの負荷テストを実施してください。SQLite WAL は分散コーディネーションレイヤーではありません。

ローカル埋め込みは Transformers.js 4.3+ と sharp 0.35.4+ を使用し、公開された依存関係ツリーにおける以前の libvips/libheif の勧告を解決します。ホスト型の埋め込みプロバイダーはランタイムの実行を変更しますが、インストール済みパッケージを削除するものではありません。現在の勧告を確認するには、ご利用のインストールに対して npm audit --omit=dev を実行してください。

ベンチマークとエビデンス

リリースゲートをローカルで実行します:

npm test
npm run bench:memory:check
npm run bench:guard:check
npm run bench:guard:publication:verify
npm run smoke:cli
npm run pack:check

GuardBench には現在、繰り返し発生する障害、手順、スコープの変更、リカバリ、秘匿化、競合する指示、およびノイズの多いストアをカバーする、10 個のローカルで決定論的な事前アクションシナリオが含まれています。チェックインされている v1 の方法論は、モックの 64 次元埋め込みプロバイダーを使用し、リグレッションを検出するために存在します。ローカルで完全にパスすることは、実際のプロバイダーのレイテンシや本番環境の誤検知率に関する主張ではありません。

このチェックアウトにおける最新のローカル結果: 10/10 シナリオがパス、100% の防止率、0% の誤ブロック率、0 件の生シークレット漏洩、0 件の公開成果物漏洩、およびモックプロバイダーの方法論における Guard レイテンシの p50/p95 が 3.805ms / 13.445ms です。

benchmarks/perf-snapshot.js は、設定可能なコーパスサイズで、マシンおよびプロバイダーの来歴とともに、エンコードとハイブリッド検索の p50/p95/p99 を計測します。運用を予定しているハードウェアと埋め込みプロバイダーで実行してください。ホスト型プロバイダーのレイテンシは、そのネットワークラウンドトリップによって支配されます。

長期的な公開評価の対象には、LongMemEval、MemoryAgentBench、および敵対的なメモリポイズニングのケースが含まれます。関連する設計の方向性には、Zep/Graphiti におけるバイテンポラルナレッジグラフ、A-MEM における進化するメモリ編成、Sleep-time Compute におけるスリープタイムのエージェントコンピュートが含まれます。

開発

git clone https://github.com/Evilander/Audrey.git
cd Audrey
npm ci
npm run build
npm run lint
npm run format:check
npm test

CONTRIBUTING.md、SECURITY.md、および docs/MEMORY_BENCHMARKING.md を参照してください。

メンテナー向けリリースゲート

これらのコマンドが意図的に文書化されているのは、論文およびリリースエビデンス台帳が、公開ソースツリーに対してそれらを検証するためです:

npm run bench:guard:zep
npm run bench:guard:external:dry-run
npm run bench:guard:external:evidence
npm run bench:guard:external:evidence:strict

npm run paper:arxiv:compile
npm run paper:arxiv:compile:strict
npm run paper:launch-results
npm run paper:launch-results:strict

npm run release:cut:plan
npm run release:cut:apply
npm run release:readiness
npm run release:readiness:strict
npm run python:release:check

ライブの Zep 実行には ZEP_API_KEY が必要です。ZEP_GUARDBENCH_INGEST_DELAY_MS は取り込みの安定化時間を調整します。外部ドライラン行列は、認証情報なしでアダプターの形状を証明し、外部エビデンス検証は保留中の実行と検証済みのライブエビデンスを区別します。

公開パッケージングは、絶対パスのスイープを実行し、ソーシャルコピーに X URL リザーブを確保し、提出された artifact-url ターゲットをチェックします。リリース準備状況は、ソース管理の状態、ライブリモートヘッドの検証、npm レジストリ/認証の準備状況、および PyPI 公開の準備状況を個別に報告します。

MIT ライセンス。責任を失うことなく、仕事においてより良くなるべきエージェントのために作られました。