Coalent

AI エージェントと RAG に向けた、出典の変更を検知して無効化されるリアルタイムコンテキスト。
一度理解した内容を、どこでも再利用。自動で常に最新の状態に保ちます。

📖 ドキュメント  ·  coalent.ai  ·  💬 Discord

クイックスタート · v0.7 の新機能 · ゲートの階層 · お好みのスタックを利用 · MCP · LangChain · ベンチマーク · CLI

---

エージェントは呼び出しのたびに同じソースを読み直します。そしてソースが変更された瞬間、キャッシュされた回答はすべて、気づかないうちに誤ったものになります。

Coalent は、一度「理解」した内容をクエリの意味に基づいてキャッシュし、元となるソースが変更された瞬間に、必要な箇所だけを無効化します。あらゆる情報を読み直すのと同じ精度を、わずかなコストで実現し、古い情報を残しません。

Coalent を選ぶ理由

あらゆるコンテキストレイヤーは、3つの要素の間で妥協を強いられます。Coalent は、3つすべてを同時に実現できるように設計されています。

• 🧠 チャンクではなく、抽出による理解。 LLM が抽出した、クエリに依存しない一連の原子的で出典に基づく主張をキャッシュし、すべての数値と事実を保持します。そのため、キャッシュされた1つの単位で、その後のさまざまな質問に答えられます。各単位には元の証拠も保持されるため、クエリを十分にカバーできない場合は、内容の薄い回答を返すのではなく、検索にフォールバックします。
• ♻️ クエリ、エージェント、そしてドキュメントをまたいで再利用。 クエリの意味をキーにしたセマンティックキャッシュです。同じ質問をもう一度した場合も、別のエージェントから質問した場合も、キャッシュがヒットします。ユニット横断の想起では、複数のユニットにまたがる主張を集約し、証拠が複数のドキュメントにまたがるマルチホップの質問にも、LLM 呼び出しを追加せずに答えられます。
• 🌿 出典情報に基づく鮮度。 各ユニットは、使用した正確なソースを記録します。ソースが変更されると、そのソースを実際に使用したユニットだけが、正確に、自動で、必要になったときに古い状態になります。

Coalent は検索の上位レイヤーとして機能します。任意の検索システム（ベクトル DB、ハイブリッド検索、GraphRAG、ツール、API）を導入できます。これは鮮度と再利用を担うレイヤーであり、別の検索システムではありません。GraphRAG の「最初にグラフ全体を構築する」というコストとは、意図的に正反対の設計です。軽量な独立ユニットを、クエリで実際に必要になったときだけ遅延構築し、単一ユニットをダーティにするだけで更新できます（グラフの修正は不要です）。

v0.7 の新機能 — 自己修復リリースです。失敗時の流れは次のとおりです。読み取りに失敗すると、 エージェントが repair(read_id) を呼び出し、キャッシュが構築時に見落とした内容を再抽出して、 永続的に修復します。同じ固定の605問テスト環境で測定した結果は、最も強力な v0.6 の構成の 0.774 に対し 0.826、提供時のトークン予算を約983で揃えた状態で5.3ポイント向上し、 最終的な回答拒否は69％減でした。また、デフォルトの読み取りパスが pool に切り替わります。セマンティック埋め込みモデルがある場合、読み取りパスは自動的に "pool" に解決されます（read_path="unit" はバイト単位で完全に同一の代替手段として引き続き利用できます）。v0.7 の新機能をご覧ください。

v0.6.1 の新機能 — MCP サーバーです。coalent-mcp を使うと、Claude Code、Cursor、または任意の MCP クライアントから1行でキャッシュを利用できます（Claude Code / Cursor から利用する）。さらに langchain-coalent により、既存の LangChain スタックをキャッシュの基盤として利用できます。どちらも既存機能への追加のみです。

v0.6 — pool 読み取りパス（read_path="pool"）では、すべての読み取りで、トークン予算に合わせたグローバル順位付け済みの最新の主張プールを提供します。同じベンチマークでの測定結果は、コンテキストトークン数981で精度0.731。これは、素朴な方式で測定した最高精度（top-12：1,729トークンで0.731）と同じ精度を、約43％少ないトークン数で実現します。さらに、デフォルトで無効の行動スタックも追加され、同じストアで回答拒否が33％減、精度が3.1ポイント向上しました。

インストール

pip install coalent          # the core has zero required dependencies

クイックスタート

そのまま実行できます。StubSynthesizer は API キーが不要なので、10秒で処理の流れを試せます。

from coalent import SemanticCache, InMemoryRetriever, StubSynthesizer

# 1. Any retriever — a vector DB, a tool, an API. (In-memory here for the demo.)
retriever = InMemoryRetriever()
retriever.add("confluence:hr", "Leave policy: 21 days of annual leave per year.")

# 2. Build the cache. Swap StubSynthesizer for a real LLM below.
cache = SemanticCache(retriever, StubSynthesizer())

# 3. Ask. The first call builds understanding and caches it; the next is a warm hit.
result = cache.get("what is our leave policy?")
print(result.context["understanding"])
print(result.cache_hit)        # False (cold) -> True on the next call

# 4. A source changed? Only the units that used it go stale — surgically.
cache.source_changed("confluence:hr", text="Leave policy: now 25 days.")
# the next matching read rebuilds just that one unit, lazily

（上記の API キー不要のデモでは、従来の unit 読み取りパスが実行されます。セマンティック埋め込みモデルが利用できないため、その旨が明示されてフォールバックします。以下のように実際の埋め込みモデルを接続すると、デフォルトで測定済みの pool 読み取りパスになります。）

実際のモデルを接続します。テキスト入力／テキスト出力に対応する任意の LLM を使用できます。v0.4 では、シンセサイザーがデフォルトで抽出的な理解（すべての事実を保持する、クエリに依存しない原子的な主張）を構築し、キャッシュはユニット横断の想起を行います。どちらも自動的に有効になります。

from coalent import SemanticCache, LLMSynthesizer, OpenAIProvider, OpenAIEmbedder

cache = SemanticCache(
    retriever,
    LLMSynthesizer(OpenAIProvider(), model="gpt-4o-mini"),   # extract=True by default (v0.4)
    embedder=OpenAIEmbedder(),   # match queries by MEANING (recommended for real use)
)
# ^ with a semantic embedder, v0.7 resolves the default read path to "pool" — the
#   measured path. Pass read_path="unit" for the pre-0.7 unit default, byte-identical.
# Multi-hop across documents? recall is already on; raise its trigger to bridge units:
#   SemanticCache(retriever, synth, embedder=..., recall_threshold=0.7)

pool 読み取りパス — v0.7 以降のデフォルト（セマンティック埋め込みモデルが利用できる場合）：各読み取りでは、ルーティングされた1つのユニットではなく、予算に合わせてまとめられた、グローバル順位付け済みの最新の主張プールを提供します。接続が必要なのは出典情報だけです。各ユニットを、独自のコーパスメタデータから [title | source | date] に対応付ける3行の pool_header 呼び出し可能オブジェクトを指定します。これが測定済みの最適な方法です。厳密採点の605問ニュースベンチマークでは、同じストア、同じクエリで、組み込みの簡易ヘッダーでは精度 0.68、この呼び出し可能オブジェクトを使うと 0.73 でした。

DOC_META = {  # your corpus metadata, keyed by artifact id
    "docs:azure-refresh": {"title": "Azure region refresh", "source": "CloudWire", "date": "2026-05-02"},
}

def pool_header(unit) -> str:   # the [title | source | date] golden path — 3 lines
    meta = DOC_META.get(unit.evidence[0].artifact_id if unit.evidence else "")
    return f"[{meta['title']} | {meta['source']} | {meta['date']}]" if meta else f"[source: {unit.id}]"

cache = SemanticCache(retriever, synthesizer, embedder=OpenAIEmbedder(),
                      pool_header=pool_header)   # pool is the resolved default (v0.7)
result = cache.get("which regions got the refresh?")
result.context["pool"]   # the packed, attributed claim payload — hand it to your answer model

拒否ループも含む、API キー不要ですぐ実行できるデモ：examples/pool_read_path.py。

Claude Code / Cursor から使う（MCP）

coalent-mcp は、Coalent キャッシュから新鮮で出典付きの事実をあらゆる MCP クライアントに提供します。事実は、情報源が変更された瞬間に無効化されます。Claude Code への接続は 1 行です：

pip install "coalent[mcp,openai]"
claude mcp add coalent -- coalent-mcp --cache-factory my_cache:build

（Cursor / Claude Desktop / あらゆる MCP クライアント：MCP 設定に同じ coalent-mcp ... コマンドを登録します。）

独自のキャッシュを使用する（--cache-factory module:function）— 基本のモードです。 ファクトリーは、ベクトル DB、埋め込みモデル、LLM、あらゆる設定項目を含む、完全に構築済みの SemanticCache を返します。サーバーが追加するのはプロトコル連携のみで、その連携による品質低下がゼロであることは測定済みです。ファクトリーモードでは、ライブラリ独自のベンチマーク結果をバイト単位で完全に再現しました（n=605 のニュースベンチマークから抽出した 100 問の検証実行で 0.710、信頼区間は同一、100/100 件を提供、回答ペイロード 98/100 件がライブラリ実行とバイト単位で一致）。

# my_cache.py — importable from the directory you launch in
from coalent import (SemanticCache, LLMSynthesizer, OpenAIProvider,
                     OpenAIEmbedder, SQLiteCognitionStore)

def build() -> SemanticCache:
    return SemanticCache(
        my_vector_retriever,                  # YOUR vector DB / retriever
        LLMSynthesizer(OpenAIProvider()),     # YOUR synthesis model
        embedder=OpenAIEmbedder(),            # YOUR embedder
        read_path="pool",
        residual_spans=True, query_keys=True, # the behavioral stack, opt-in as ever
        pool_header=my_metadata_header,       # [title | source | date] — the measured golden path
        store=SQLiteCognitionStore("kb.db"),  # persistence is yours too
    )

ここでの鮮度はシグナル駆動型です。ドキュメントが変更されたら、取り込みパイプラインから source_changed ツールを呼び出すと、影響を受ける事実がただちに無効化されます。（ファクトリーと合わせて --watch DIR を指定すると、ファイルの編集時にも呼び出されます。無効化のみを行い、インデックスへの取り込みは行いません。また、アーティファクト ID が監視対象ディレクトリからの相対パスと一致する場合にのみ照合されます。）

設定不要のフォルダーモード（--watch DIR）— デモ向けの導入方法です。 ドキュメントが入ったフォルダーを指定するだけで、コードなしで推奨される v0.6 のデプロイ構成（プールパス、残余スパン、クエリーキー、SQLite による永続化、自動の [path | modified date] による出典表示）を利用できます：

claude mcp add coalent --env OPENAI_API_KEY=$OPENAI_API_KEY -- coalent-mcp --watch ./docs

読み取りのたびに、提供前に監視対象ファイルを再スキャンします（mtime + コンテンツハッシュ）。ファイルを保存した後に古い回答が返ることはありません。変更されていないフォルダーは、再起動後も完全にウォーム状態を保ちます。正直な数値： 同じ 100 問の検証実行で、フォルダーモードのスコアは、ファクトリーで構築したキャッシュの0.71 に対して 0.46でした（拒否は 40 件に対して 18 件）。これは、汎用段落チャンカーとオンデマンドのキーホール構築による測定済みのコストです。鮮度の仕組みを 1 分で試すにはフォルダーモードを使い、本番品質が必要な場合は独自のスタックを使用してください。注意点が 1 つあります。追加したばかりのファイルに関する質問は、読み取りによってそのファイルの初回構築が行われるまで、ウォームキャッシュから正当に拒否される場合があります。古い回答や誤った回答ではなく、拒否が返されます。

複数のエージェントで 1 つの共有キャッシュを使う（--transport http）。

COALENT_MCP_TOKEN=<secret> coalent-mcp --cache-factory my_cache:build --transport http --port 8765

1 つの長時間稼働プロセスで、多数の MCP クライアントが 1 つの共有キャッシュを使います。共有による効果の蓄積が得られ、ストアの競合は発生しません（検証済み：2 つのクライアントを同時に実行した場合、20 件すべての読み取りで逐次実行の参照結果と一致し、重複構築はゼロでした）。COALENT_MCP_TOKEN が設定されている場合、すべてのリクエストに Authorization: Bearer <token> が必要です。localhost または信頼できるネットワークにバインドしてください。stdio に関する補足：stdio を起動するたびに別プロセスになるため、2 つのアプリで同じ --store パスを指してはいけません。HTTP モードこそが共有キャッシュへの答えです。

7 つのツール： get_context(query, budget?) → 出典付きで、予算に合わせてまとめられたペイロードと read_id · report_refusal(read_id) / report_success(read_id) → MCP を介した動作修復ループ · source_changed(artifact_id, text?) → BYO 鮮度フィード（変更のないコンテンツはハッシュで検出してスキップ） · list_sources() · cache_stats() · refresh().

LangChain

langchain-coalent は、Coalent を LangChain ネイティブな鮮度／再利用レイヤーにします。BYO を優先する設計で、既存の VectorStore（またはリトリーバー）、埋め込みモデル、チャットモデルを変更せずにキャッシュの基盤として使用できます。

pip install langchain-coalent

from langchain_coalent import create_coalent_cache, CoalentRetriever

cache = create_coalent_cache(my_vectorstore, llm=my_chat_model, embeddings=my_embeddings)
retriever = CoalentRetriever(cache=cache)      # drop-in LangChain BaseRetriever

docs = retriever.invoke("what is our leave policy?")
docs[0].page_content              # the served, attributed context payload
docs[0].metadata["read_id"]       # -> cache.report_refusal() / report_success()
docs[0].metadata["cache_hit"]     # True == served with zero LLM spend

cache.source_changed("policy.md", text=new_text)   # surgical, provenance-keyed invalidation

すべての Coalent 設定項目は create_coalent_cache に渡されます。拒否から修復へのループは、パッケージ内の実行可能な LangGraph 形式のサンプルとして提供されています。依存関係は coalent>=0.6 と langchain-core>=0.3 のみです。

v0.7 の新機能

自己修復リリース — そして、デフォルトの読み取りパスを切り替えるリリースです。読み取り処理には独自の疑念が組み込まれ、キャッシュにはエージェントが実行する明示的な失敗チェーンが加わりました。各段階は読み取りに失敗した場合にのみ実行されるため、読み取りが成功すれば新たなコストは発生しません。意図的に変更されるデフォルトは1つ（以下の最初の項目にある読み取りパス）です。すべての新しい v0.7 の設定はデフォルトで無効で、明示的に有効化するまではバイト単位で影響しません（テストで確認済み）。詳細は変更履歴をご覧ください。

v0.5 以降のすべての基準値と同じ固定ニュース環境で測定しました（記事609件、保留テストの質問605件、厳密な採点＋固定された判定ルール）。v0.7 の完全な構成のスコアは 0.826 で、最強の v0.6 構成の 0.774 を上回ります。サービング時の予算は約983トークンで同一ながら、5.3ポイント向上し、最終的な拒否は 69％減少しました（61 → 19）。失敗時にのみ修復を実行することで、抽出呼び出しの **14％**で常時実行と同等の精度を達成できます。

エージェント型のループ — 評価を決めるのはお使いのエバリュエーターで、キャッシュは自ら修復します。

cache = SemanticCache(
    retriever, synthesizer, embedder=OpenAIEmbedder(),
    # read_path resolves to "pool" automatically under a semantic embedder (v0.7 default)
    gap_detector=True,               # observe-only: the read reports its own holes
    repair_extractor=my_extractor,   # BYO callable(span, region, existing_claims) -> [claims]
)

r = cache.get(
    question,
    subs=planner_subquestions,       # your planner's decomposition (optional)
    constraints={"dates": ["2023-10-05"], "sources": ["TechCrunch"]},  # intent metadata (optional)
)
answer = my_answerer(r.context["pool"])          # your model, your prompt
r.sources                                        # artifact ids behind the payload
r.max_source_age_s                               # freshness age of this serve
r.gaps                                           # [{probe, span, source, kind}, ...] — the read's own doubt

if failed(answer):                               # the failure chain — each rung ONLY on failure
    cache.repair(r.read_id)                      # re-extract what the build missed — PERMANENT
    r2 = cache.get(question, subs=planner_subquestions)   # repaired claims now compete
    answer = my_answerer(r2.context["pool"])
    if failed(answer):
        r3 = cache.reprobe(r2.read_id)           # entity-probe re-rank of the same pool
        answer = my_answerer(r3.context["pool"]) if r3 else answer
    if failed(answer):
        r4 = cache.serve_unserved(r2.read_id)    # last rung: force-pack admitted-but-unserved claims
        answer = my_answerer(r4.context["pool"]) if r4 else answer

• 破壊的変更 — デフォルトの読み取りパスが pool に解決されます。 read_path は None がデフォルトになり、セマンティックエンベッダーが利用可能な場合、常に "pool" に解決されます。対象は、キーが設定されたすべての実運用環境（OPENAI_API_KEY が設定されている場合、または字句エンベッダー以外の embedder= が指定された場合）です。Pool は実測済みのパスです（公開済みの v0.6／v0.7 の数値はすべてこのパスによるものです。切り替え基準は 0.7 のバッテリー証拠で満たされました — 上記の 0.826 対 0.774）。キー不要のゼロ設定では、単体テスト用パスにフォールバックし、2 つの対処法（OPENAI_API_KEY の設定／embedder= の指定）を明示する強い警告が出ます。回避策： 明示的な read_path="unit" は引き続き完全にサポートされ、0.7 より前のデフォルトとバイト単位で同一です。read_path が明示的に指定されている場合は、常に解決結果より優先されます。
• 読み取り結果に、その出所と不確実性が含まれます。 Result.sources（ペイロードの実際の根拠となったアーティファクト ID）、Result.max_source_age_s（提供時の鮮度経過時間）、さらに gap_detector=True の場合は Result.probes／probe_coverage／gaps が含まれます。各プローブについて、生のエビデンス文がすべての主張を上回るか（extraction_hole → 修復対象）、またはプローブに届くものがないか（corpus_hole → ツールに振り分け）を示します。設計上、観測のみを行います。ON と OFF で提供内容はバイト単位で同一であることが固定されており、文の階層のコストは提供時に $0 です（遅延処理で一度だけ埋め込み、キャッシュされます）。
• repair(read_id) — 改善を回す仕組みです。 読み取りで蓄積されたギャップ候補と制約候補、および提供された内容の近くにあるブリッジ候補を消費します。候補ごとに、スパンをアンカーとする BYO 抽出器呼び出しを 1 回行います（ライブラリ自体が LLM を呼び出すことはありません）。機械的に近似重複や欠陥（先行詞のない代名詞主語、途中で切れたスパン）を却下したうえで、追記専用で、出所が記録され、永続的なストアの改善を行います。コストは一度だけ発生し、以後のすべての読み取りに効果があります。RepairReport を返します。
• serve_unserved(read_id) と reprobe(read_id, hint=None) — 拒否時の追加手段です。 パッキング競争に負けた主張を強制的に詰め込むか、提供された内容から抽出したエンティティプローブを使って、変更されていないプールを再ランク付けします。埋め込みのみを行い、LLM の呼び出し、検索、ストアの変更はありません。また、契約上、拒否時にのみ実行されるため、正しい読み取りの回答が変わることはありません。
• get() の subs=／constraints=。 プランナーから読み取りに分解結果（subs=["...", ...] — decompose= の呼び出し可能オブジェクトより優先）と、メタデータに対する意図（constraints={"dates": ..., "sources": ..., "entities": ...} — キー間は AND、同一キー内は OR。読み取り結果が無効になる場合は OR にフォールバック）を渡します。制約は候補を供給するだけです。修復候補を蓄積しますが、プールのスコアリングや提供内容には影響しません（固定済み）。
• 取り込みメタデータにより、v0.6 の帰属情報の不足が解消されます。 retriever.add(..., meta={"title": ..., "source": ..., "date": ...}) はメタデータをユニットに設定し（source_meta）、デフォルトのプールヘッダーでは pool_header の呼び出し可能オブジェクトなしに、実測済みの標準形式 [title | source | date] を表示します。メタデータなしの取り込みは 0.6 とバイト単位で同一です。
• 切り替え状況： 0.6.0 で事前登録された pool パスのデフォルト切り替えは、0.7.0 で実施されました — 0.7 のバッテリー証拠とメンテナーによる明示的な判断（2026-09-15）に基づくもので、指定どおりには実施されなかった 3 つの事前登録済みゲートに代わるものです。設計上、条件付きです（契約上、pool にはセマンティックエンベッダーが必要なため、字句フォールバックは引き続き unit を使用し、明確な警告が出ます）。非推奨化ではありません。read_path="unit" は DeprecationWarning なしで引き続き完全にサポートされ、serve="pool"（v0.5 のプレビュー）も 0.7 で変更なく維持されています。

v0.6 の新機能

プール優先のリリースです。以下の n=605 の数値はすべて、固定された同一の評価環境から得られたものです。609 件のニュースコーパス、605 件の保留質問、回答には gpt-4.1-mini、厳密な採点を使用しています。v0.5 の数値を測定した環境と同じです。詳しくはCHANGELOGとUPGRADE-0.5-to-0.6.mdをご覧ください。

• read_path="pool" — 主張プール優先の読み取りパス（0.6 ではオプトイン。セマンティックエンベッダーを使用する場合、v0.7 以降は解決後のデフォルト）。読み取りは、グローバルな最新の主張プールを予算内に詰めて回答します。ユニットは所有権／鮮度／出所情報の骨格として引き続き機能します。測定値：厳密な正解率 0.731 @ コンテキストトークン平均 981。素朴な top-9（0.711 @ 1,311）と同等の精度でトークンを約25%削減し、測定された素朴な方式の最高値（top-12：0.731 @ 1,729）と同等の精度で約43%削減しています。示されたのはより少ないトークンで同等の精度（信頼区間は重なります）であり、精度の向上ではありません。ゴールド主張の提供順位：プール順でp50/p75/p90 = 1/6/15。
• デフォルトで出所を明示し、ヘッダーを段階的に測定。 pool_header=None では、ソースごとの組み込みヘッダーを出力するようになりました。同一のストア、同一のクエリで、識別情報なしの ID は0.641 → 出荷時のデフォルトは0.678 → 独自の [title | source | date] メタデータ callable は0.731です。この差はユニットのメタデータによる制約です（媒体名／日付はコーパスにあり、ユニットにはありません）。callable を接続してください（上記のクイックスタートをご覧ください）。
• 動作スタック（すべてデフォルトで無効）：span → fallback → repair → keys。 residual_spans=True を設定すると、抽出器が見落とした事実を含む文をユニット上の tier-2 span として取得します（プールには入りません）。独自の回答エンジンが拒否した場合、report_refusal(read_id) は出所情報付きの再試行ペイロードを返し、report_success(read_id) は救済が成功したことを確認します。また、query_keys=True の場合は永続的な代替キーを獲得します。損失ありとマークされたユニットは、次回の再構築時に追記のみで自己修復します。フルループを通して実行した測定では、拒否は91 → 61（−33%）、最終精度は**+3.1ポイント**（トークンは**+2.1%、同一ストアでの比較）、新たに誤った回答はゼロでした。キー付けされたクラスでは、言い換えによる再質問時の初回正解率が0% → 61%**になりました。
• 適応型提供ゲート（serve_gate=None）は、プール自体のノイズ上限を基準に適応します。明示的に float 値を指定すると適応が無効になり、ベンチマークを再現できます。$0 のリプレイゲートを経てのみリリースしました。両方の条件で提供判断は605件すべて一致し、ビルドはゼロ、LLM 呼び出しもゼロでした。
• 堅牢化と基盤整備： すべてのペイロードで出所情報（プールのペイロードおよびエスカレーション時の生データ）を保持します。所有者が異なる近似重複の主張は、裏付け情報として保持します。新たに14件の可観測性イベント（pool_served、residual_fallback、key_confirmed、...）を追加しました。reranker フック（提供順のみを変更し、誤った提供を引き起こすことはありません）、BYO プールストレージの claim_index、v0.5 のプールプレビューにあった古い情報を提供する不具合の修正も含まれます。
• 非推奨： serve="pool"（v0.5 のプレビュー機能）。0.6 および 0.7 でも従来どおり動作しますが、read_path="pool" への移行を推奨します。0.6 では、事前登録された5つの切り替え条件を設け、デフォルトの読み取りパスを "unit"（v0.5 と完全に同じ動作）のままにしました。v0.7 で切り替えを実施しました（v0.7 の新機能をご覧ください）。

正直な制約（仮説ではなく、測定結果）

• **拒否時のフォールバックが自然な拒否を反転させる割合は約20%**です（ペイロードに回答がそのまま含まれる場合は33%）。ラボの質問で得られた68%という数値は、構成上ペイロードに回答が含まれている場合にのみ当てはまります。これは抽出の取りこぼしを補うものであり、2つ目の検索器ではありません。
• クエリキーは、同じトピックの記事が密集したコーパスでは、関連記事間で衝突する可能性があります（605件の読み取りで3件確認。回答は引き続き正解）。そのような場合は key_floor をデフォルトの0.85より高く設定してください。キーによって拒否後の再試行が初回回答に変わりますが、多様な言い換えに対する最終精度は向上しません。
• 出荷時のデフォルトヘッダーが出所として示せるのは、ユニットが把握している情報に限られます。0.678 → 0.731 の差はユニットのメタデータによる制約です。現時点では pool_header callable で解消できます。取り込み時の任意メタデータフィールドは v0.7 の項目です。

v0.5 の新機能

プールリリースです。実際のニュースデータを使った1か月間の事前登録済みベンチマーク競争 （MultiHopRAG、609件の記事、第三者が作成した質問）から得られた知見を、オプトイン機能として実装しました。

• preset="multi_hop" — 引数を1つ指定するだけで、キャリブレーション済みのしきい値を使って、ユニット横断の想起と hop-2 ブリッジを有効にします。明示的に指定したキーワード引数が常に優先されます。
• ソースの範囲拡大（widen_chunks=24）— ミスを検知すると、取得した狭い範囲だけでなく、主要なソースから最大 N 個のチャンクを読み込んで再構築します。E2E での効果は、再構築の繰り返しが460回から31回に減少し、ウォームパスの精度が低下から向上へと転じました。取り込み時には実行されません。
• 出典情報に基づく採用判定（provenance_admission=True）— 正確なテキスト包含プローブにより、理解の重複を防ぎます。内容がカバーされていれば再構築せずに読み取りを返し、カバーが不十分な場合はその場で範囲を広げて再構築します。
• 適応型ヒットゲート（adaptive_hit=True）— キャッシュの成長に伴うスコアのインフレを自動で調整します（固定しきい値では、規模が大きくなるとすべてを取り込んでしまうことが実証されています）。
• プール提供のプレビュー（serve="pool"、serve_budget=600、pool_header=...）— ルーティングされた1つのユニットではなく、トークン予算内で全体をランキングした最新のクレームプールを提供します（実験的。v0.6 では read_path="pool" に置き換えられていますが、このプレビューは0.6および0.7でもそのまま動作します）。 保留データ n=605 では、ユニット提供の0.579に対して精度は0.699でした（z=6.66）。当時もっとも高い測定値だった naive の k9 アームと統計的に同等でありながら、トークン数はその0.79倍で、帰無仮説に対する正直さは95％でした。ソースが変更された瞬間に、古いユニットのクレームはプールからマスクされます。
• fast="auto" — numpy がインストールされている場合に numpy で高速化された読み取りパスを使用します（pip install "coalent[fast]"）。結果は純粋な Python コアと同等であることが固定テストで検証されています。
• 可観測性（on_event=...）— 構築、再構築、採用時の再利用、古い読み取りの防止、想起、ブリッジの動作に関する構造化された鮮度イベントを提供します。
• 非推奨：select_floor（プール提供に置き換えられました）。

詳細な数値と手法については、ベンチマークのセクションと CHANGELOG をご覧ください。

v0.4 の新機能

オプトインのプレビューだった2つの機能が、デフォルトになりました。Coalent が対象とする構造化データや再利用の多いコーパスでは明確に優れており、それ以外では追加コストがかからないか、休止状態のままだからです。どちらも1行で v0.3 の動作に戻せます（extract=False、cross_unit_recall=False）。

• 🎯 抽出的理解（extract=True、デフォルト）。 質問に合わせた文章形式の要約ではなく、シンセサイザーがクエリに依存しない、ソースに根拠のある原子的なクレームのリストを抽出します。同じユニットで、後からのさまざまな質問に答えられるようになり、数値も漏れません。テストでは、文章形式の要約でソース内の数値の約40％がひそかに失われていました。
• 🔗 ユニット横断のクレーム想起（cross_unit_recall=True、デフォルト）。 1つのユニットでクエリを十分にカバーできない場合、キャッシュは最新の全ユニットからクレームごとのメモリーを集約し（MaxSim）、ブリッジとなる事実を提示します。これにより、素朴な検索では構造的に答えられないマルチホップの質問（質問に似ていない文書内の証拠）にも、追加の LLM 呼び出しなしで答えられます。シングルホップでは休止状態で追加コストがなく、非セマンティックな埋め込みモデルでは自動的に無効になります。結果は result.recalled として提示されます。
• 🛡️ 精度と提供方法の調整機能（オプトイン、デフォルトでは無効）： hit_margin（曖昧な同点を拒否）、select_floor（意味に基づいて原子要素を提供し、トークン数を削減）、residual_floor（抽出器が見逃した数値範囲を回収）。どれを使うかについては、ゲートの段階をご覧ください。

v0.3 からアップグレードしますか？ UPGRADE-0.3-to-0.4.md をご覧ください。追加的な変更で、動作の変更は1点（理解の形式が文章からクレームになったこと）です。

仕組み

        query ──► embed ──► semantic cache
                               │  hit & fresh?  ──► serve cached understanding  (no retrieval, no LLM)
                               │  miss / stale? ─┐
                               ▼                 ▼
                          your Retriever ──► your Synthesizer ──► Cognition unit
                          (vector/tool/API)   (LLM or passthrough)  { understanding
                               ▲                                      + raw evidence
                               │                                      + provenance }
   source changed ────────────┘   dirties ONLY the units that used that source

1. クエリを埋め込み表現に変換し、意味が似ている既存のユニットを検索します。
2. ヒットし、かつ最新の場合 → キャッシュされた理解を返します（検索もLLMの呼び出しもありません）。
3. ミスした場合、または古くなっている場合 → 検索して理解を統合し、生の証拠を保持し、出典情報（使用した正確なソース）を記録して、キャッシュします。
4. ソースが変更された場合 → source_changed(id) は、そのIDを出典情報に含むユニットのみを対象としてマークします。次回読み込まれる際に、それらのユニットが遅延再構築されます。

変更されていないコンテンツはコンテンツハッシュの比較によってスキップされるため、実質的な変更がない場合はコストがかかりません。

読み取りパス — ゲートの階段

これはユニット読み取りパス（read_path="unit" — v0.5 の正確な動作です。キーなしのフォールバックであり、v0.7 のプール既定値からバイト単位で同一の動作に切り替える方法です）。v0.6 のプールパス — セマンティック埋め込みモデルを使用する場合、v0.7 以降の解決済み既定値 — は、ユニットのルーティングをグローバルなクレームプールのパッキングに置き換え、これらのユニットルーティング用ノブを無効にします。プールパス独自のノブについてはUPGRADE-0.5-to-0.6.mdをご覧ください。

Coalent は、ユニットが知っていること — クエリの単語ではなく、理解を埋め込んだもの — を基準にキーを設定します。そのため、"休暇は何日取れますか？" は休暇ユニットにヒットしますが、"交換ポリシー" はヒットしません。その後、get(query) のたびに、固定されたゲートの階段を順に進みます。既定値は追加モデルも重い依存関係もない純粋なコサイン類似度で、各ゲートは調整可能なノブです。発動順は次のとおりです。

#	ゲート	既定値	発動条件 → 動作
1	hit_threshold — マッチング	自動（OpenAI の場合は約 0.33）	最良ユニットのブレンドスコア（0.7·topic + 0.3·seed）がこれを下回る → ミス → 新しいユニットを取得＋合成
2	hit_margin — 精度ガード	0.0（オフ）	1 位のユニットと次点の差がマージン未満 → 曖昧 → クエリ専用のユニットを作成
3	鮮度	プロベナンス／TTL	マッチしたユニットが変更済み、または期限切れ → 再マテリアライズ
4	カバレッジ — 回答できるか	クレームごとの最大コサイン類似度	マッチしたユニットがこのクエリをどの程度カバーするか（完璧なクレームが 1 つあればカバー済み）
5	cross_unit_recall	オン（v0.4）	カバレッジ < recall_threshold → すべての最新ユニットから最良のクレームをプールする（MaxSim）。カバレッジを引き上げることができます。休止中は無料で、LLM 呼び出しもありません
6	coverage_scorer（S2）	None（オフ）	曖昧な範囲 [coverage_floor, coverage_ceiling) に入る → クロスエンコーダー／NLI／LLM による含意チェックでコサイン類似度を上書き
7	coverage_floor — RAG の下限	自動（約 0.28）	カバレッジが依然としてこれを下回る → エスカレーション：最新の生の検索結果を追加（LLM 呼び出しなし）。そのため、カバレッジが薄いヒットは誤答する代わりに検索へフォールバックします
8	select_floor — 提供	None（語句ベースのトリミング）	キーワードによるトリミングの代わりに、意味（クレームごとのコサイン類似度 ≥ 下限値）に基づいてユニットのアトムを提供 — クエリに関連する事実を、より少ないトークンで返します

さらに、構築時のノブが 1 つあります — residual_floor：抽出器が除外した、数値を含むソースの範囲（クレームごとのコサイン類似度が最良でも下限値未満）を、追加のアトムとして保持します。埋め込みのみを使用します。 その他のフック：route_by_claim（大きなユニットのクレームを使った後期相互作用型ルーティング）、relevance_gate（合成前の BYO リランキング）、depth（合成の完全性とコストの調整）、calibrate_thresholds() ／ suggest_thresholds()。

ワークロード別のノブ — 既定値は構造化された単一ホップの再利用向けに調整されています。データの性質が異なる場合は、次のノブを使ってください。

ノブ	使用する場面
recall_threshold ≈ 0.7	マルチホップ／文書横断の質問 — 部分的にカバーされた読み取りをリコールでつなぎます（マルチホップの利点を十分に活かします）
hit_margin > 0	ほぼ同点の候補が曖昧になる、矛盾や衝突の多いコーパス（再構築のコストがかかるため、クリーンなデータではオフのままにしてください）
select_floor	大きなユニットに対する言い換えの多いクエリ（クエリとクレームで単語が重ならない場合、キーワードによるトリミングでは見落とします）
residual_floor	抽出器が数値を除外する可能性のある、実際の雑多な文章（低コストの保険になります）
coverage_scorer（S2）	誤った回答を返すコストが高い、重大な曖昧さがある場面（境界域の読み取りごとに判定呼び出しが 1 回追加されます）

stats() は hit_rate、escalation_rate、有効な閾値を報告するため、キャッシュの動作を正確に把握して調整できます。

独自のスタックを持ち込む

Coalent が所有するのは小さな契約だけで、それ以外はすべてお使いのツールに引き渡します。

リトリーバー — 1 行の実装から完全な制御まで、段階的に選べます。

お持ちのもの…	使用するもの
Qdrant / Chroma / pgvector	同梱アダプター（クライアントは独自に用意）
その他のベクトル DB	BaseVectorRetriever を拡張
既存の検索関数	FunctionRetriever
複数のソースを統合する場合	CompositeRetriever
その他	Retriever を実装（メソッドは 1 つ）

from coalent import QdrantRetriever

retriever = QdrantRetriever(client=my_client, collection="docs", embed=my_embed)

シンセサイザー — 証拠を理解に変換します。

• LLMSynthesizer — お使いの LLM（OpenAI、Anthropic、または任意のプロバイダー）を通じて、構造化され、引用に裏付けられた理解を生成します。instruction と fields はお客様が所有し、ソース／厳格な JSON／引用のエンベロープは Coalent が所有するため、どのような指示を出しても情報の出所が記録されます。
• JSONPassthroughSynthesizer — すでに構造化されたツール／API の JSON 用です。LLM 呼び出しは行わず、JSON をそのまま理解としてキャッシュします。

埋め込み — キャッシュがクエリを意味で照合する方法です。coalent[openai] をインストールし、OPENAI_API_KEY を設定すると、キャッシュは OpenAI の埋め込みを自動的に使用します。それ以外の場合は警告を出し、語彙マッチャーにフォールバックします。いつでも上書きできます。

from coalent import SemanticCache, OpenAIEmbedder, FunctionEmbedder

cache = SemanticCache(retriever, synthesizer, embedder=OpenAIEmbedder("text-embedding-3-large"))
# or a local model: embedder=FunctionEmbedder(lambda t: my_model.encode(t).tolist())

意味的な照合には実際の埋め込みモデルを使用してください。キーがない場合の HashingEmbedder フォールバックは意味ではなくキーワードの重複で照合するため、似ていても表現が異なるクエリではキャッシュを見つけられないことがあります。

ストア — 永続性があり、再起動後も安全に使えます（無効化グラフは起動時に再構築されます）。

from coalent import SemanticCache, SQLiteCognitionStore   # stdlib, no server
from coalent import RedisCognitionStore                   # shared across processes / hosts

cache = SemanticCache(retriever, synthesizer, store=SQLiteCognitionStore("coalent.db"))

あらゆるエージェントフレームワーク — 読み取り API は 1 回の呼び出しで使えるため、どこにでも組み込めます。グラフノードと MCP ツール向けのヘルパーも同梱しています。

from coalent import make_cognition_node, build_mcp_tools

node = make_cognition_node(cache)     # a graph node: state -> { context: fresh understanding }
tools = build_mcp_tools(cache)        # expose the cache as an MCP tool

スタンドアロン MCP サーバーの全機能（鮮度を保つループ、7 つのツール、HTTP トランスポート）については、 次のセクションを参照してください。LangChain については langchain-coalentを参照してください。

ベンチマーク

実環境：v0.7 の失敗連鎖（n=605）

以下のすべての基準と同じ固定テスト環境（実際のニュース記事 609 件、保留された質問 605 件、回答モデルは gpt-4.1-mini、厳格な採点と固定された裁定ルール）を使い、素朴な構成ではなく、独自の最強の v0.6 構成に対する v0.7 の全構成を測定します。

構成	正解率	コンテキストトークン数	最終的な拒否数
最強の v0.6 構成（メタデータヘッダー + 動作スタック）	0.774	約 983	61
v0.7 の構成（サブスクリプション + ギャップ検出器 + 制約 → 失敗連鎖）	0.826	約 983	19（−69%）

• 同一のサービング予算で +5.3 ポイント — サービングトークンの追加はゼロです。この連鎖でコストが増えるのは、読み取りに失敗した場合だけです（失敗時にのみ修復を行うことで、常時修復の正解率を**抽出呼び出しの 14%**で達成します）。
• 57 件の修正の内訳： 初回処理で 37 件（分解 + メタデータのサービング）、repair() で 10 件、serve_unserved() で 6 件、reprobe() で 4 件 — どの段階にも役割があります。
• 各段階が実行されるのは読み取りに失敗した場合だけです。拒否は正解ではないため、後続の段階で壊れるものはありません。修復は永続的です。主張はそれぞれの出所情報とともにストアに追加され、今後はすべてのユーザーのあらゆる読み取りに役立ちます。

実環境：プールの読み取りパス（v0.6、n=605）

以下の v0.5 の数値と同じ環境です。実際のニュース記事 609 件、固定されたホールドアウト質問 605 件、 回答モデルは gpt-4.1-mini、厳密な採点条件で、今回は最良の測定点まで拡張した、naive 独自のトークン数スケーリング曲線を公平性の対照として使用しています。

アーム	正解率	コンテキストトークン数
naive top-9	0.711	1,311
naive top-12（測定済みの最高値）	0.731	1,729
Coalent read_path="pool"（デフォルト設定＋メタデータヘッダー）	0.731	981

• 主張は、正解率で上回ることではなく、より少ないトークン数で同等の正解率を達成することです。 どの組み合わせでも信頼区間は重なっています。981 トークンでの 0.731 は、naive top-9 と同じ正解率を約 25％少ないコンテキストトークン数で達成し、測定済みの naive の最高値も約 43％少ないトークン数（その予算の 57％）で達成します。さらに、検索だけでは実現できないもの（鮮度、来歴、振る舞いの累積効果）も提供します。
• 配信時の順位： ゴールドクレームは、プール内の順序で p50/p75/p90 = 1/6/15 に位置します（クレームが存在するクエリが対象）。デフォルトのコサイン順位付けを使用し、リランキングは行いません。
• ヘッダーは感覚ではなく、測定に基づいています： 不透明な ID では 0.641 → 出荷時のデフォルトでは 0.678 → 独自の [title | source | date] 呼び出し可能オブジェクトでは 0.731 です。上記の 0.731 の行ではメタデータ呼び出し可能オブジェクトを使用しています。pool_header を設定してください（クイックスタートを参照）。
• 振る舞いのスタック（オプトイン）：最終正解率は +3.1 ポイント、トークン数は +2.1％、拒否は −33％、新たに誤答となった回答はゼロです。同じストア、同じ母集団で、完全な report_refusal/report_success ループを通して比較しています。
• この環境での v0.5 の基準値は 0.699 @ 約 1,036 でした。v0.6 の書き換えではこの値を維持し（信頼区間は重なっています）、古いデータを提供する問題を修正し、帰属情報をデフォルトで有効にしています。

実環境：MultiHopRAG（v0.5、事前登録済み）

実際のニュース記事 609 件、サードパーティのゴールド質問を、gpt-4.1-mini で回答し、完全一致で採点しました。これはチャンク検索に最も有利なコーパスです（質問は記事の文から生成されています）。敵対的テストとして選定しました。多くのベンチマークが省略する公平性の対照、つまり同じデータに対する naive 独自のトークン数スケーリング曲線も実施しています（k4 0.58 @ 590 tok · k6 0.64 @ 882 · k9 0.71 @ 1311、n=605 のホールドアウト）。

• プール配信（serve="pool"、キャッシュをウォームアップ済み）：約 1,036 トークンで 0.699 — naive k6 を上回り（対応のある McNemar 検定 z=3.22）、当時の測定済み最高値である naive の k9 アームと統計的に同等の正解率を、そのトークン数の 0.79 倍で達成します（z=0.60）。ここではスケーリング曲線を上回るとは主張しません。主張するのは、より少ないトークン数で同等の結果を得ることと、検索だけでは実現できないもの（鮮度、来歴、再利用による累積効果）です。
• 回答不能時の誠実さ（回答不能な質問 n=100）：プールの拒否率は 95％、naive は 85～88％です。
• 構築レイヤー（コールドスタート、オンザフライ）：拡張されたユニットは、ソースから中央値で 23 チャンクを読み取ります。キーホール構築では 2 チャンクです。再構築の変動は 460 → 31、ウォームパスの正解率は低下（−0.03）から累積（+0.04）に転じました。
• 誤帰属は 2～6％で、読み取りの約 90％でユニット間再現率が発動しました（完全に計測済み）。

過去のベンチマーク履歴 — v0.4 の構造化レジーム調査とベンチマーク透明性に関する注記（判明したこと、修正した内容、その方法） — はドキュメントにあります。

CLI

Coalent をインストールすると、認知キャッシュ（SQLite ストア上）のための redis-cli のような coalent コマンドを利用できます。

$ coalent ls
STATUS  HITS  AGE SRC  ID                  QUERY
fresh      6   2m   2  cog:c95a9d2897e0af  what is our leave policy?
dirty      1  12m   1  cog:7f1a0b9c3d2e4f  remote work rules

$ coalent show cog:c95a9d2897e0af      # understanding + provenance + raw evidence
$ coalent invalidate confluence:98231  # fire a change event
$ coalent stats

ドキュメント

📚 ドキュメント全文：coalent.ai/docs — 概念、来歴と鮮度、リトリーバー、シンセサイザー、永続化、実例（ベクトル検索、MCP とツール、エージェント）、および get() / データモデルの完全なリファレンスを掲載しています。

インストール方法

pip install coalent                 # core, zero required deps
pip install "coalent[openai]"       # OpenAI provider      (also: anthropic)
pip install "coalent[qdrant]"       # vector adapters      (also: chroma, pgvector)
pip install "coalent[redis]"        # distributed store
pip install "coalent[dev]"          # tests + lint + types

コントリビューション

Issue と PR を歓迎します。プッシュする前にゲートを実行してください。

pip install -e ".[dev]"
pytest && ruff check src && mypy src

CI について知っておくべき点が一つあります。このプロジェクトでは mypy の解析対象を 3.10 に固定しています（pyproject.toml の python_version）。しかし numpy >= 2.5 がインストールされている場合（Python 3.12 以降では [fast] の追加依存が解決するバージョン）、そのスタブは 3.10 の解析対象では解析できない構文を使用します。その場合は、CI マトリックスと同じく、実行環境に合わせて mypy src --python-version 3.12 を実行してください。

ステータスとライセンス

アルファ版 — 1.0 より前に API が変更される可能性があります。完全に型付けされ（mypy --strict）、リンターによるチェックとテストが行われています。

Apache-2.0 ライセンスのもとで提供されています。

_{安さだけでなく、信頼できるコンテキストを。}