veracium

Veracium

Veracium は、エージェント型システム向けの出所情報を考慮したメモリープラグインです — 素朴なエージェントメモリーを悩ませる、注入や作話による障害に強い、ユーザーごとの永続的なメモリーです。出所情報とは、すべての事実に 誰が述べたか が記録されることを意味します。エージェントが読んだだけのメールに含まれる主張が、エージェントの断言する「事実」になることはありません。ユーザーの発言、過去のやり取り、うまくいったことを記憶し、それぞれの情報源も記憶します。

Veracium は、評価主導の研究プロジェクト（agent-memory）から実用化された成果です。以下の設計判断はすべて測定結果に基づいており、研究で使われた合成コーパスのハーネスを回帰テストスイートとして再利用しています。

研究： これらの知見を導いた評価手法である、エージェントメモリーの長期的なベンチマークについては、Q. Spencer, 「Ground Truth First: A Longitudinal Evaluation Instrument for Agent Memory, and the Tenure Crossover in Memory-Architecture Rankings」 (arXiv:2607.21962, 2026) で説明されています。

このような設計にした理由

• 型付きグラフと日付付きエピソードが記録の正本です。 エンティティの事実はリレーショナルなエッジ（偽造できない出所情報付き）として保持し、やり取りの履歴は日付付きエピソードとして保持します。整理された「wiki」ビューはこれらから生成してキャッシュしますが、正本としては扱いません。(階層型設計は短期と9週間の両方の評価期間で優れた結果を示しました。フラットなストアはいずれかの条件で失敗しました。)
• 消去ではなく、置き換えの記録を残します。 雇用主、所在地、期限など単一の値を取る事実は、以前の値を履歴として保持しながら、現在の値を1つだけ保持します。そのため、「Xは以前どうだったか？」にも引き続き答えられます。複数の値を同時に持てる事実（好み、測定値、健康状態など）は、代わりに蓄積されます。(これは商用メモリーシステムが最も苦手とするカテゴリであり、Veracium が最も強みを発揮する分野です。)
• 表現方法はセキュリティ制御です。 第三者からの主張（受信メール、外部ドキュメントなど）は、構造上、隔離されます。主張者を主体とする third_party_claim エッジとして保存され、ユーザーの事実として扱われることはありません。コンテンツタイプに基づく隔離により、もっともらしく見えるかどうかにかかわらず、義務、債務、更新に関する主張を検出します。(連絡先へのなりすましを含む、信憑性の段階を網羅したテストでも耐えました。)
  この仕組みが行うこと、行わないこと： ストアが制御するのは、保持、取得、説明、推奨、つまり何を 発言するか と、それにどのようなラベルを付けるかです。何かを生成、許可、実行するものではありません。それらはホストのハーネスが担います。ラベルを利用する排他的なハーネス経路がない場合、Veracium の信頼クラスは強制ではなく、助言的なラベル付けにとどまります。
• モデルは自由に選べます。 Veracium は API キーやモデルの選択を管理しません。利用者が指定した Complete 呼び出し可能オブジェクトを呼び出します。リファレンス実装として Anthropic プロバイダーが同梱されています。
• デフォルトで組み込み型です。 外部サービスは不要で、SQLite ファイルを1つ使います。後から Store インターフェイスを介して Neo4j/Postgres に切り替えられます。

インストール

pip install "veracium[anthropic]"   # core + the reference LLM provider

Python と SQLite の要件。 Veracium の実行には Python 3.14 以降が必要です。また現在、動作確認済みの唯一の SQLite ビルドである Ubuntu 24.04 に同梱された SQLite 3.45.1 でのみ、ストアを開くか作成できます。このシステム SQLite にリンクされた Python 3.14 は実行できます。GitHub の setup-python ビルドも同様です。一方、uv、python.org、Homebrew の 3.14 ビルドにはより新しい SQLite が同梱されており、新規ストアであっても拒否されます。Ubuntu 24.04 のシステム Python 自体は 3.12 で、必要な最低バージョンを下回っています。そのため、そこで pip を使うと、対応している最後のリリースである 0.26.1 がインストールされます。ほかのすべての SQLite ビルドでは、ビルドが異なれば 3.45.1 であっても、ストアの作成も既存ストアを開くことも拒否されます。そのため、SQLite が異なる Python に移行すると、そのビルドがサポートされるまで以前のストアを開けなくなります。バージョンチェックで分かるのは、自分の環境が拒否されるかどうかだけです。python -c "import sqlite3; print(sqlite3.sqlite_version)" の出力が 3.45.1 以外なら拒否されます。ただし、3.45.1 は必要条件であり、十分条件ではありません。より幅広い SQLite への対応を予定しています。

追加機能：[mcp] は MCP サーバーを、[dev]は pytest を追加します。コア部分の依存関係はpydantic` のみです。ソースから使用するには、次のようにします。

git clone https://github.com/veracium-ai/Veracium.git && cd Veracium
pip install -e ".[anthropic,dev]"

リンク：ドキュメント · veracium.ai · PyPI

使用方法（ライブラリ）

from veracium import Memory, EvidenceAuthor, EvidenceContext
from veracium.llm.anthropic import AnthropicComplete

mem = Memory(llm=AnthropicComplete())   # or pass your own Complete callable

# Remember interactions. `author` says WHO wrote the event; `context` is
# your positive attestation of HOW you captured it. Without a context the
# content class floors to derived(THIRD_PARTY) — never assertable — so a
# host that means "I captured this first-hand" says so:
mem.remember("alice", "USER: I'm vegetarian and have a dog named Ollie.",
             context=EvidenceContext.direct())
mem.remember("alice", "From billing@scam: you owe $900.",
             author=EvidenceAuthor.THIRD_PARTY, event_type="email",
             source_id="billing-mailbox",   # third-party content needs a source id
             context=EvidenceContext.direct())

# Recall grounded, provenance-flagged context for a prompt.
ctx = mem.recall("alice", "suggest a lunch spot")
print(ctx.context)   # states the vegetarian constraint; the $900 "claim" is
                     # rendered under a never-assert flag, not as a fact.

Anthropic API キーをお持ちでない場合でも問題ありません。AnthropicComplete は便利な機能にすぎず、Veracium は指定した任意の Complete 呼び出し可能オブジェクトを呼び出します。SDK やキーの設定なしで実行するには、すでにお持ちのクライアントをラップしてください。examples/claude_cli_provider.py は claude CLI をドロップインのプロバイダーとしてラップします（from claude_cli_provider import ClaudeCLIComplete）。また、examples/openai_provider.py は OpenAIComplete を使って、OpenAI 互換のチャット補完 API（OpenAI 自体、vLLM、Ollama の /v1 エンドポイント）をラップします。OpenAIComplete(base_url=...) でローカルサーバーを指定し、models をそのサーバーが提供する任意のモデル名で上書きしてください。

使用方法（MCP）

veracium-mcp は、ホスト側に Python がなくても、MCP 互換の任意のエージェント（Claude Desktop/Code など）に remember / recall / answer / maintain ツールを公開します。設定 JSON とツールのリファレンスについては、docs/mcp.md をご覧ください。

ドキュメント

ホスト版ドキュメント：veracium-ai.github.io/Veracium

• examples/demo.ipynb — 詐欺メールによるインジェクションのデモを、最初から最後まで実行できます（Colab で開く）。
• examples/langchain_memory.py — LangChain チャットアプリの長期記憶レイヤーとして Veracium を使用します（セッションキー付きのハイブリッド方式：LangChain が直近のターンをバッファーし、Veracium が出典情報と隔離機能を備えた永続的な事実を保持します。既存の LangChain モデルが両方を担います）。
• docs/concepts.md — 基本的な考え方：エッジ、エピソード、コンパイル済み Wiki の違い、出典情報と作成者、隔離、回答保留ゲート、ライフサイクル。
• docs/recipes.md — 機能ごとに 1 つずつ、短くてコピーして使える例（隔離、複数の出典情報、予算を考慮した想起、ポータビリティ、フィードバックの動詞、監査、ローカルモデル）。
• docs/api.md — 公開 API：Memory、MemoryConfig、EvidenceAuthor、独自の LLM 呼び出し可能オブジェクトやストアの指定方法。
• docs/mcp.md — MCP サーバーの実行と登録。
• docs/design-rationale.md — update() / delete() がない理由、LLM を使わない抽出がない理由、TTL による削除がない理由、そして実際にロードマップにある内容。
• docs/telemetry.md — オプトイン方式の、匿名でコンテンツを含まない使用統計（デフォルトでは無効）。
• docs/diagnostics.md — オプトイン方式のエラー報告：ローカル優先のエラーログ、同意を得たうえでの編集済み情報の送信。
• ROADMAP.md · CHANGELOG.md

ステータス

検証済みのレイヤー設計が実装され、テスト済みです（オフラインテスト44件に加え、オプトインのライブ層として、受け入れ評価と実際のコーパスを使った堅牢性ハーネスを実施）。独自の研究主張の基準も満たしています（5/5、インジェクションに関するアサーションは0件）。ロードマップのv0.1～v0.7を完了し、オプトインのテレメトリー、セルフチェック、同意に基づくエラー報告、操作監査ログも実装済みです。ROADMAP.mdをご覧ください。

ライセンス

MIT