Factum

Factum — AI エージェント向けの監査可能なメモリ

ステータス：v0.1.3 — 初期段階のため、初期の協力者を募集中です。 コアとなる書き込み／クエリ／撤回パイプラインは動作します。本番環境での利用には対応していません。アーキテクチャ上の決定は、今後変更される可能性があります。

インタラクティブドキュメント — アニメーション付きの構文解析、7要素タプルエクスプローラー、クエリパイプライン、トークン効率チャート、MCP アーキテクチャ図を掲載しています。

エージェントが書き込むすべての事実には、必須の来歴情報が付与されます。情報源が撤回されると、そこから派生したすべての情報が自動的に無効化されます。これがカスケード撤回です。事実が矛盾する場合、Factum は推測せずに Ambiguous を返します。

構造化ナレッジ言語（S 式ベース）、Rust による実装、stdio MCP サーバーを備え、Claude Code、Cursor、その他のあらゆる MCP クライアントで動作します。

ステータス：v0.1.3、初期段階です。 コアとなる書き込み／クエリ／撤回パイプラインは動作しますが、セマンティック検索やメモリの統合にはまだ対応していません。Factum が扱うのは検証済みの構造化された事実であり、会話のコンテキストではありません。コンプライアンスに配慮が必要なエージェント、複数エージェントで共有するナレッジベース、「エージェントが X を信じた理由」への回答が必要なあらゆる場面に最適です。共有ナレッジベースのパターンについては、複数エージェントの使用ガイドをご覧ください。

Mem0／Zep／Letta との違いは何ですか？

Factum 独自の機能： 文法によって強制される来歴情報 · カスケード撤回 · 矛盾時の回答拒否。

Factum が（まだ）備えていない機能： 埋め込みベースのセマンティック検索 · メモリの統合 · HTTP トランスポート。

互いに補完できます。Mem0／Letta はコンテキストを保存・検索し、Factum は監査可能な構造化された事実を保存します。MCP を介して、両者を並行して実行できます。

実際にはどういう意味ですか？

エージェントのメモリに関する課題	Factum の仕組み
「ユーザーが言ったこと」と「LLM が推論したこと」を区別できない	5段階の来歴情報と、Extracted ノードのモデル名を文法によって強制
古いメモリを現在の事実として使用してしまう	ソフト削除と、逆依存関係グラフを介したカスケード撤回
矛盾するメモリのうち、ひとつが暗黙に選ばれる	Ambiguous — 推測する代わりに回答を拒否
メモリ汚染（プロンプトインジェクション）	来歴チェーンによって汚染の追跡と撤回が可能
企業がエージェントに機密データを保存させられない	インデックスレベルでの権限フィルタリング — クエリ後に情報が漏れることはありません

学術的背景： STALE ベンチマーク（2025年）によると、最高性能の LLM エージェントでさえ、自身のメモリが古くなったことを検出する精度はわずか55.2％です。これは、メモリの陳腐化がエージェントシステムにおいて未解決の問題であることを裏付けています。

主な機能（実装済み）

• ノードの7要素：すべてのナレッジノードは、id、predicate、validity、provenance、confidence、authority、permissionsを持ちます。さらに、人が読めるコンテキスト用の:noteを任意で指定できます。
• ノードIDの自動生成：factum_insertまたはfactum_assertでノードIDに"auto"を指定すると、コンテンツに基づくIDを自動生成できます。手動でIDを管理する必要はありません。
• 5段階のprovenance：Verbatim／Summary／Extracted／Derived／Assertedによる完全な監査チェーンです。
• 文法で強制されるモデル参照：Extractedノードには、モデルとバージョンを必ず含める必要があります。パーサーは、これらが欠けている場合に拒否します（単なるドキュメント上の規約ではありません）。
• カスケード取り消し：上流のソースが取り消されると、派生ノードは自動的に無効化されます（逆依存グラフdeps_revを使用）。大規模なナレッジベースでのカスケードの急増を防ぐため、ノード数の上限を設定できます。
• 裏付けの検出：2つ目のエージェントが同じ事実を主張すると、factum_assertはエラーではなくcorroboratedを返します。独立した合意は、マルチエージェントで最も価値の高いシグナルです。
• 競合の裁定：LatestWins／HighestAuthority／Unanimous／WeightedVoteに対応します。パターンを考慮したグループ化により、値の競合に対して確実に裁定が行われます。一意に解決できない場合はAmbiguousを返します。
• インデックスレベルの権限管理：クエリ後のフィルタリングは行わず、集計情報の漏えいを防ぎます。
• 数値の損失なし：すべての数値にDec(i128, u8)を使用し、浮動小数点誤差をゼロにします。
• MCP ブリッジ：JSON-RPC 2.0のツール／リソースに対応します。実際のMCPクライアント（Claude Code、Cursor）でstdioトランスポートを検証済みです。

実装済みの機能と未実装の機能

モジュール	ステータス	備考
factum-core（types、lexer、parser、serialize）	✅ 実装済み	構文の往復テストで100%一致
factum-rt（store、query、arbitration、permissions、verifiers）	✅ 実装済み	インメモリストア（デフォルト）＋RocksDB永続化（--features rocksdb）。5つのカラムファミリー、WriteBatchによるアトミックな書き込み
factum-mcp（JSON-RPC bridge）	✅ プロトコル＋ハンドラー	エンドツーエンドでstdioトランスポートを検証済み。HTTPトランスポートは未実装（リモートでのデプロイにはカスタムラッパーが必要）
factum-bench（benchmarks）	✅ 実装済み	構文の往復テスト＋トークン効率＋クエリ性能
factum-l（latent space projection）	❌ 未着手	研究項目 — ROADMAP.mdを参照
Wikidata/Mathlibコーパスコンバーター	❌ 未着手	M2マイルストーン
Lean/Z3検証器	❌ 未着手	実装済みなのはSchemaとDecimalRangeの検証器のみ
埋め込みベースのセマンティック検索	❌ 未着手	ロードマップにはありません — Factumと併せてMem0の使用を検討してください
メモリーの統合／要約	❌ 未着手	ロードマップにはありません — Factumと併せてLettaの使用を検討してください
Inspector（ビジュアルデバッガー）	❌ 未着手

クイックスタート

# Build
cargo build

# Run tests
cargo test

# Run demo
cargo run -p factum-demo

# Build with RocksDB persistence backend
cargo build --features rocksdb
cargo test --features rocksdb

# Build MCP server with RocksDB persistence
cargo build --release -p factum-mcp --features rocksdb --bin factum-mcp-server

# Fuzz (requires nightly)
cargo +nightly fuzz run fuzz_parser -- -max_total_time=600

MCP サーバーとして使用する（Claude Code／Cursor）

# Build the MCP server binary (in-memory, default)
cargo build --release -p factum-mcp --bin factum-mcp-server

# Or build with RocksDB persistence (survives restarts)
cargo build --release -p factum-mcp --features rocksdb --bin factum-mcp-server

# Register with Claude Code (in-memory)
claude mcp add --transport stdio --scope local factum -- "$(pwd)/target/release/factum-mcp-server"

# Register with Claude Code (persistent — recommended for agent memory)
claude mcp add --transport stdio --scope local factum -- \
  "$(pwd)/target/release/factum-mcp-server" --db-path ~/.factum/store

# Verify connection
claude mcp get factum

詳しい手順については、Factum MCP のはじめ方を参照してください。

Factum-F の構文例

; Acme Corp knowledge graph
(node n001
  :pred (instance-of @ACME-CORP organization)
  :conf 0.99 :auth 0.95 :perm public
  :src (asserted "wikidata"))

(node n004
  :pred (shareholder-major @ACME-CORP @FOUNDER-1 0.73 :since #date(2001-03-15))
  :conf 0.85 :auth 0.8 :perm confidential
  :src (extracted "doc002" [100 200] (model "claude-sonnet-4" "2025-01")))

(node n006
  :pred (subsidiary-of @ACME-SUB @ACME-CORP :since #date(2001-03-15))
  :src (derived n001 "rule-subsidiary-merge")
  :deps [n001])

n001が取り消されると、n006は自動的に無効化されます。これにより、エージェントは従属関係をもはや信頼できないことを認識できます。

3層アーキテクチャ

層	意味	ステータス
エージェントによる読み取り	エージェントはMCP経由でFactum-Fをコンテキストとして受け取ります。冗長なJSONよりもトークンのオーバーヘッドを抑えられます	✅ トークン効率を測定済み（実際のo200k_baseで、JSON比：canonical −62%、compact −53%）
エージェントによる書き込み	エージェントがFactum-Fノードを生成します。パースの一意性により解釈は1つに定まり、エラークラスにより自己修正が可能になります	✅ 作成ガイドを参照
潜在空間での推論	factum-l：Factum-Fを連続的な思考ベクトルにエンコードし、潜在空間で推論して、監査用にデコードして戻します	🔬 研究項目 — 未着手、レイヤー1～2を妨げるものではありません

構造化ナレッジ言語がメモリーレイヤーの基盤です。パースの一意性を実現するS式ベースの形式であり、損失のない数値表現にはDec(i128, u8)を使用し、LLMの自己監査にはモデル参照が必須です。設計の詳細な根拠については、docs/design-rationale.mdを参照してください。

トークン効率 — LLM ネイティブの指標

要約：Factum の正規形式は、同じメタデータを含む冗長な JSON と比べて、トークン数を約 62% 削減します。すべての数値は、tiktoken-rs を介した実際の o200k_base（GPT-4o）トークナイザーで測定しています。

形式	実トークン数（5 ノード）	冗長な JSON との比較	含まれる内容
Factum 正規形式	238	−62%	完全な 7 要素タプル：来歴＋信頼度＋有効性＋権限
Factum コンパクト形式（JSON）	290	−53%	同じ 7 要素タプル、数値タグ付き JSON
Markdown	181	−71%	アサーションテキストのみ — 来歴、信頼度、権限なし
JSON（整形済み）	623	基準値	冗長な JSON エンコードによる同じ 7 要素タプルのメタデータ

cargo test -p factum-bench test_token_efficiency_real_tokenizer -- --nocapture を実行すると再現できます。

主な発見：正規の S 式形式（238 トークン）は、コンパクトな JSON 形式（290 トークン）よりもトークン効率に優れています。BPE トークナイザーは JSON の区切り記号を分割する一方で、S 式の括弧はまとめて処理します。正確性を重視して設計された形式が、最もトークン効率にも優れています。

ラウンドトリップの忠実性 — 具体的に何が 100% なのか？

1. 構文上のラウンドトリップ ✅ — parse(serialize(parse(x))) == parse(x)。テストスイートとファジングで検証済みの 100% です。 これが信頼の基盤です。

2. 意味上のラウンドトリップ ❌ まだ測定されていません — factum-l（潜在空間への射影。未実装）が必要です。

形態素語彙 — 現状

• 初期形態素：9 種類（Entity、Relation、Quantifier、Modal、Temporal、Status、Action、Attribute、Classification）にわたる 200 以上の形態素。組織、人、空間、金融、製品／プロジェクト、バージョン管理、ドキュメント／ナレッジ、エージェントメモリ、権限、原因／結果の各領域をカバーします
• 設計目標：200～500（build.rs を介して morphemes.toml から読み込み）
• ステータス：エージェントメモリのユースケースには十分です。morphemes.toml のコード生成は、外部からの貢献に向けた今後の M2 項目です。

他の形式との関係

形式	Factum との違い
RDF / JSON-LD	RDF のトリプルには、ノードごとの来歴、信頼度、権限がありません。Factum ではこれらを第一級の要素として扱い、必須にしています。
Markdown	Markdown にはメタデータがありません。Factum は、人間にとっての読みやすさと引き換えに、機械による検証可能性を高めます。
JSON	JSON にはスキーマ、来歴、時間的な有効性がありません。Factum のコンパクト形式は、トランスポートとして JSON を使いながら、構造と監査チェーンを追加します。
Mem0 / Zep / Letta	これらはエージェントメモリを保存・取得します。Factum は文法で強制される来歴、カスケード撤回、競合の拒否を追加します。競合するものではなく、相互補完的です。

プロジェクト構成

factum/
├── crates/
│   ├── factum-core/     # Data model, lexer, parser, serialization
│   ├── factum-rt/       # Runtime: store (InMemory + RocksDB), query, arbitration, permissions, verifiers
│   ├── factum-mcp/      # MCP bridge: JSON-RPC tools/resources, stdio transport
│   ├── factum-bench/    # Benchmarks: round-trip, token efficiency, query perf
│   └── factum-demo/     # End-to-end demonstration
├── fuzz/              # cargo-fuzz targets (parser, serialize round-trip, lexer)
├── spec/              # Conformance test vectors (JSON, language-agnostic)
├── docs/site/         # Interactive visualization (GitHub Pages)
├── .github/workflows/ # CI: test + fuzz + gitleaks + Pages deploy
├── Cargo.toml         # Workspace root
├── ROADMAP.md         # What's planned and in what order
├── SECURITY.md        # Vulnerability disclosure
├── CONTRIBUTING.md    # How to contribute
├── CHANGELOG.md       # Version history
├── docs/design-rationale.md     # Why each architectural decision was made
├── docs/authoring-for-llms.md   # LLM guide for generating Factum-F
└── docs/getting-started-mcp.md  # MCP setup guide (Claude Code / Cursor)

テスト結果

現在の件数を確認するには cargo test を実行してください。テスト対象：型、レキサー、パーサー、シリアライズ、形態素、深度制限／DoS 対策、適合性ベクトル、ストア、クエリ、調停、権限、検証器、サブスクリプション、MCP プロトコル／ツール／ハンドラー、ベンチマーク。

この README の上部にある CI バッジには、最新のビルドステータスが表示されます。

セキュリティ

• パーサーには 深度制限（128 レベル）があり、悪意のある入力によるスタックオーバーフロー DoS を防止します
• レキサーには トークン数の上限（100 万トークン）があり、OOM を防止します
• パーサー、シリアライズのラウンドトリップ、レキサーを対象とした cargo-fuzz
• CI では gitleaks を実行し、漏えいしたシークレットをスキャンします

脆弱性の報告については SECURITY.md を参照してください。

ライセンス

MIT

商標

「Factum」と Factum-F 言語仕様は、プロジェクト名です。この MIT ライセンスが対象とするのはコードのみであり、仕様は将来的に別のプロセスで管理される可能性があります。

貢献

貢献には DCO 署名（git commit -s）が必要です。CONTRIBUTING.md を参照してください。

---

• MCP レジストリ名：mcp-name: io.github.factum-project/factum