Facthouse

Facthouse

Facthouse は、AI ツール向けのローカルメモリエンジンです。多くの「メモリ」製品はチャットログをインデックス化します。Facthouse はエージェントのアクティビティ（メッセージ、ツールの使用、その他の MCP トラフィック）を取り込み、神経科学に着想を得た統合処理を適用して、データ（セッションで起きたこと）→ 情報（抽出された事実）→ 知識（エンティティグラフ上で統合された信念）へと変換します。この処理の過程で、Facthouse はエンティティをリンクし、重複を除去し、矛盾を調整し、古くなった情報を新しい情報に置き換えます。ベクトル埋め込みを使うと、このグラフにセマンティック検索を追加できます。ストアはディスク上の SQLite ファイルです。

クイックスタート

Node 22.5 または 24 以降が必要です。

npx -y @facthouse/mcp
facthouse init

facthouse init --web はブラウザーのフォームと同じセットアップを行います。127.0.0.1 の URL を表示しますが、ブラウザーは開きません。

各デフォルトを受け入れるには Enter キーを押します（copy = Claude Code、Cursor、または Grok Build のセッションログをディスク上にコピーすること、type record = アシスタントが事実を保存すること）。copy を選択した場合、init は既存ログをコピーするかどうか、続いて抽出と統合を行うかどうかを尋ねます。ストアへの書き込みが完了すると、init はすぐに MCP スニペットを表示します。コピーや抽出の処理中に、クライアントの MCP 設定に追加してください。init が完了したら、クライアントを再起動します。

クライアントで、通常の会話の中で長期的に保持する情報を伝えてください。remember コマンドはありません。

次のセッションでその情報を尋ねるか、facthouse search を実行してください。それがストアです。

Claude Code、Cursor、または Grok Build のログからコピーするか、任意の MCP クライアントから記録できます：会話の取り込み方法。リプレイ：facthouse.dev/demo.html。CLI：以下。

利用できる機能

• ローカル SQLite。 Postgres も任意で利用できます。分離の単位はカラムではなくディレクトリです。
• エンティティグラフ。 人物、組織、プロジェクト、場所、製品などを抽出、分類し、リンクします。
• ハイブリッド検索。 BM25、構造化ドメイン、エンティティグラフの経路を Reciprocal Rank Fusion で統合します。埋め込みプロバイダーを追加すると、4 つ目のリストとして意味を検索できます。デフォルトでは無効です。
• セッション内メモリ。 get_session_context は memory://briefing と同じブリーフィングです。ツールのみを使うクライアントは、セッション開始時に呼び出してください。
• 不変の履歴。 事実は削除されず、新しい情報に置き換えられるだけです。

仕組み

1 つの SQLite データベースを使用します。その中にあるのは 3 つのテーブルであり、データベースが 3 つあるわけではありません。Data（セッションで起きたこと）→ Information（抽出された事実）→ Knowledge（統合された知識）です。

• D（session_events）— 発言された内容（コピーされたトランスクリプト、またはアシスタントが記録した内容）
• I（session_facts）— 抽出されたばかりの内容、または capture_fact
• K（facts）— 統合された知識

FTS5（単語）とオプションの埋め込み（意味）は、K のインデックスです。別のストアではありません。セマンティック検索は、有効にするまでオフです。search "shellfish" では貝類に関する事実が見つかりますが、埋め込みモデルを選択するまでは search "food" では見つかりません。モデルとは、「類似」の意味についての見解です。

処理速度は 2 段階です。Copy は、名前付きトランスクリプトを Data に順次取り込みます。Extract は、新しいトランスクリプト行を自己完結した事実に変換します（D→I）。Integrate は、ドメイン、エンティティ、重複、矛盾、グラフを考慮して、ストアがすでに持つ情報に組み込みます（I→K）。consolidate はこれらをまとめて実行する処理で、コピー、抽出、統合を一度に行います。1 回の実行で抽出できるのは最大 50 行です。そのため、初回のバックフィルで全件を一度に処理することはありません。抽出を実行すると、最も古い 50 行が対象になります。統合によって、誰も言っていない文が作られることはありません。

フックから MCP ツールを呼び出すことはできません。これらのツールはアシスタントの接続でのみ使用できるためです。また、モデル処理が終わるまで待機させてはいけません。そのため、フックは consolidate を呼び出しません。代わりに facthouse notify … を実行し、すでに実行中のサーバーにイベントが発生したことを通知して、すぐに戻ります。consolidate はパイプラインの動詞（MCP ツールまたは CLI）であり、呼び出し元は完了を待ちます。notify compaction は、その動詞を稼働中のサーバーに対して非同期で実行するものです。notify threshold は別のポリシーであり、条件を満たした場合に抽出のみを行います。

自動実行

呼び出し可能

追加のフックがないデフォルトのコピー・ストアでは、自動実行の表にある処理のみが行われます。Facthouse の起動時には 3 つすべてが実行され、指定されたソースが増えていれば Facthouse のツールまたはリソースの呼び出しごとにコピーが行われ、正常なプロセス終了時には統合が行われます。チャットウィンドウを閉じると終了時の処理がスキップされる場合がありますが、次回の起動時に統合されます。しきい値の条件を満たすとは、未確認の行が少なくとも 10 行あり、前回の制限付き実行から 2 分が経過していることを意味します。consolidate --all を使うと、抽出の上限が解除されます。Compaction では、PreCompact での使用を推奨します（notify compaction）。待機せずに、稼働中のサーバーで consolidate と同じ 3 つの手順を実行します。このフックはインストールしません。Stop フックではありません。record はレコード・ストアでしきい値による抽出を起動します。コピー・ストアには record フックをインストールしないでください。

ストレージには Node が必要です。インテリジェンスには言語モデルが必要です。デフォルトでは、既存のサブスクリプションで Claude Code CLI を使用します。これがない場合、統合は組み込みのヒューリスティックにフォールバックしますが、トランスクリプトから事実を抽出しません。capture_fact は引き続き事実を保存しますが、エンティティは作成されず、ドメインへの振り分けも行われません。

会話の取り込み方法

方法は2つあります。ストアごとにどちらかを選んでください。

コピー方式のストアでは、capture_fact は、JSONLを書き込むクライアントだけでなく、すべてのMCPクライアントで訂正に使います。Claude CodeとGrok Buildを1つのストアで使うには、同じ cwd を持つ claude-code ソースと grok ソースを指定します。どちらもコピーを行い、記録を求められることはありません。そのストアには記録フックもインストールしないでください。

facthouse init

copyを選び、cwdを設定します。初期化時に既存ログをコピーするかどうか、続いて抽出して統合するかどうかを尋ねられます（Enterでコピーしたすべての行が対象になります。500件以上を選択すると、選択内容をもう一度入力するよう求められます）。抽出を後回しにする場合は、facthouse consolidate を使ってください（--all は、調査対象外だった残りの行を処理します。7日間または30日間の期間外としてスキップされた行は対象になりません）。その後、サーバーはFacthouseの呼び出しを処理する際に新しい行をコピーします。抽出と統合の手順は、仕組みの表に従います。

コンパクション（推奨）：facthouse notify compaction — フックはインストールしません。ターン終了時のStopフックではありません。

MCP

MCP互換のツールであればどれでも動作します。デフォルトのストアは ~/.facthouse です。別のパスを使う場合は、MCPスニペットに "env": { "FACTHOUSE_DATA": "/absolute/path" } を指定します。WindowsでもJSONではスラッシュを使用できます。

Cursorはツールを利用しますが、後続のアダプターが追加されるまではリソースを利用しません。search_knowledge と get_entity は引き続き使えます。セッション開始時に get_session_context を呼び出してください。

リソースは、クライアントが自動的に読み込むコンテキストです。ツールの呼び出しは不要です。アシスタントが使うことを覚えていなければツールは役に立ちませんが、リソースは最初から利用できます。

• memory://briefing — 今すぐ知っておく価値のあるすべての情報です。プロフィール、直近の統合で学習した内容、未解決のスレッド、最近の知識が含まれます。Markdown形式で、画面1つ分ほどの長さに収まるようにしています。
• memory://profile — 重要度の高い順に並べた、基本的なアイデンティティ情報です。

どちらも、ツールがクエリする同じデータベースを読み取り専用で表示します。リソースを読み込まないクライアント（Cursor、Windsurf、Grok）でも、会話の開始時に get_session_context を呼び出せば、同じブリーフィングを取得できます。2つ目のプロフィールスキーマはありません。

ツール

セッション

• log_event — 会話イベント（メッセージ、成果物）を記録します。
• get_events — 現在または以前のセッションからイベントを取得します。
• get_session_context — 作業用ブリーフィング（memory://briefing と同じ Markdown）と、このセッションで記録された事実を取得します。クライアントがリソースを読み込まない場合は、すべての会話の開始時に呼び出してください。

読み取り

• get_entity — 名前の付いたあらゆる対象（人物、組織、プロジェクト、場所、製品）について、判明しているすべての情報と、それらのつながりを取得します。異なるタイプで複数の行に同じ名前がある場合は、それらすべての情報が返されます。ハイフン、アンダースコア、余分な句読点は、すでに別々の行として保存されている2つの名前を結合しない場合に限り、同じ文字として扱われます。その名前のエンティティがない場合も、空の結果ではなく、その表現に言及している情報が返されます。
• get_context — トピックに関連するすべての情報を取得します（検索＋エンティティのたどり）
• search_knowledge — 統合済みのナレッジ全体を対象にしたハイブリッド検索

書き込み

• capture_fact — 事実を保存します。コピー上では、抽出で見落とされた内容の修正として保存します。sources が空のストアでは、事実を追加する手段です。アシスタントに表示される説明も、同じルールに基づいて生成されます。
• consolidate — 保留中の事実を長期ナレッジに統合します。エンティティを抽出し、重複を解決し、矛盾を検出して、ナレッジグラフを構築します。
• 推論ツール — オプトイン方式で、デフォルトでは無効です（config.json の inferences.enabled）。仮説は既存の事実 ID を引用し、確認されるまで保留状態になります。ゲートを有効にするまで、これらのツールは登録されません。Consolidate は、誰も発言していない文を作り出すことはありません。

メタ

• get_schemas — 利用可能なドメインと構造
• get_stats — 事実数、エンティティ数、ドメインの分布、抽出の未処理数、インテリジェンスの使用量

CLI

MCP の JSON は npx 経由でサーバーを起動するため、グローバルインストールは不要です。npm install -g を実行すると facthouse が PATH に追加され、init、settings、stats、inspect を使えるようになります。PATH を通さずに同じ CLI を使うには、npx -y -p "@facthouse/mcp" -- facthouse を実行します。バージョンを固定してください。PowerShell がパッケージを展開しないよう、パッケージ名を引用符で囲んでください。-p と -- を指定すると、古いグローバルバイナリが優先されるのを防げます。-p を指定せずに npx -y @facthouse/mcp / facthouse を実行するとサーバーが起動します。init、settings、stats のためのシェルコマンドとして実行しないでください。MCP の貼り付け設定はサーバーを起動しますが、facthouse を PATH に追加するものではありません。ターミナルからファイルを確認する方法については、以下の CLI を参照してください。

これらの CLI コマンドは bash、zsh、PowerShell で使えます。PowerShell では @facthouse/mcp を引用符で囲んでください。Git Bash の /c/... パスは PowerShell 用ではありません。C:/... を使い、cd や export の代わりに --data を渡してください。Git Bash では、バックスラッシュを含むパスを引用符で囲むか、C:/... と記述してください。引用符で囲まない \ はエスケープ文字です。~/ はすべてのプラットフォームで展開されます。WSL では /mnt/c/... を使います。MCP スニペットの FACTHOUSE_DATA は、そのサーバープロセスにのみ適用されます。ターミナルで facthouse コマンドを使うには、--data、シェルが継承する環境の FACTHOUSE_DATA、またはこのプロジェクト内の .facthouse ストアが必要です。フックから mcp.json の env は参照できません。

npm install -g @facthouse/[email protected]
facthouse init --yes

mcp という名前のコマンドがすでに存在するため npm install -g が失敗した場合は、その残存コマンドを削除してから再試行してください。

npx -y -p "@facthouse/[email protected]" -- facthouse init --yes
npx -y -p "@facthouse/[email protected]" -- facthouse settings --json
npx -y -p "@facthouse/[email protected]" -- facthouse stats
npx -y -p "@facthouse/[email protected]" -- facthouse inspect

facthouse init [dir]

このウィザードは、人が初回実行時にconfig.jsonを作成するためのものです。スキップしても、初回のMCP起動時にサーバーがディレクトリを作成します。

ターミナルでは、initはデータディレクトリ、トランスクリプトをコピーするか、アシスタントの記録をコピーするか（デフォルトはコピー）、セマンティック検索、その他の設定を尋ねます。--yesを指定するとプロンプトは表示されず、sourcesは空のままになります。--webを指定すると127.0.0.1のURLを出力しますが、ブラウザーは開きません。--yesと--webの併用はできません。ターミナルでは、--forceを指定してもこれらの質問が表示された後、ファイル全体が置き換えられます。--yes --forceを指定すると、確認なしでリセットします。--forceは以前のファイルとマージしません。

facthouse init --yes

facthouse init --yes ~/my-memory

facthouse init --yes --force

生成されたconfig.jsonで統合の動作を変更できます。特に重要なのはintelligence.providerです（デフォルトはcliです。依存関係のない正規表現フォールバックにはheuristicを指定するか、実行時にFACTHOUSE_PROVIDER=heuristicを設定します）。initではこのフィールドについて尋ねません。

facthouse settings

既存のconfig.jsonの追加設定（CLIモデル、タイムアウト、オプションのローカル抽出）を変更します。ファイルの残りの部分はリセットしません。config.jsonがない場合は拒否します（このコマンドはストアを作成しません）。--jsonを指定するか、ターミナル以外で実行すると、現在の設定を表示するだけで書き込みは行いません。--webを指定すると、ローカルページで同じ設定を変更できます（URLを出力しますが、自動では開きません）。

facthouse settings

facthouse settings --data ~/my-memory

facthouse record

実行中のサーバーがなくても、イベントをデータベースに直接挿入します。デモや、名前付きソースのないストアで使用できます。Claude CodeやCursorのデフォルトの方法ではありません。デフォルトでは sourcesとfacthouse consolidateを使用します。

# From a hook (reads JSON payload from stdin):
echo '{"hook_event_name":"UserPromptSubmit","prompt":"hello"}' | facthouse record --role user

# With explicit content:
facthouse record --role user --event-type message --content "hello world"

# Options:
#   --role          user | assistant | system | tool (default: user)
#   --event-type    message | tool_call | tool_result | artifact (default: message)
#   --content-type  text | json | image | audio | binary (default: text)
#   --content       Event content (or pipe via stdin)
#   --speaker       Named participant when the transcript has one
#   --session-id    Target session (default: most recent)
#   --data          Data directory (default: FACTHOUSE_DATA, a .facthouse store in this project, or ~/.facthouse)

facthouse consolidate

config.sourcesから新しい行をコピーし、それらから候補となる事実を抽出して、保留中の事実をナレッジに統合します。モデル呼び出しを行う唯一のコマンドです。

facthouse consolidate
facthouse consolidate --copy            # copy only; spends nothing
facthouse consolidate --integrate       # pending facts to knowledge; no extract pass
facthouse consolidate --all             # extract the whole backlog now
facthouse consolidate --limit 200       # extract the oldest 200

# Steps — named steps run, in order; none named means all three:
#   -c, --copy       copy new transcript lines into the store
#   -e, --extract    turn new lines into candidate facts (the model call)
#   -i, --integrate  classify, link, dedupe, supersede, embed
# Extract is capped at 50 lines per run so a first backfill is never spent on
# the lot; the run says how many remain. --all lifts the cap, --limit N sets it.
#   --json           print the result object instead of the summary
#   --data           Data directory (default: FACTHOUSE_DATA, a .facthouse store in this project, or ~/.facthouse)

設定されたプロバイダーを使用します（デフォルトはclaude -pです）。sourcesが空の場合、コピー処理は何も行いません。すべてのプロジェクトグループをコピーする意図がない限り、ソースにcwdを設定してください。名前付きソースがあるストアでは、recordフックも実行しないでください。

facthouse notify <moment>

ある時点でイベントが発生したことを、実行中のMCPサーバーに通知します。サーバーが実行する処理を決定し、バックグラウンドで実行するため、フックはすぐに戻ります。

facthouse notify compaction   # client about to compact: copy new JSONL, extract, integrate (does not wait)
facthouse notify threshold    # events arrived: extract if the threshold is due

# Options:
#   --data     Data directory (default: FACTHOUSE_DATA, a .facthouse store in this project, or ~/.facthouse)

待ち受け中のサーバーがなくてもエラーにはなりません。コマンドはその旨を表示して終了コード0で終了し、次のセッション開始時に処理されます。これはPreCompactフックが呼び出すコマンドです。

facthouse search <query>

facthouse search "coffee"
facthouse search "coffee" --domain preferences
facthouse search "coffee" --json

# Options:
#   --domain   Prioritise a domain. Biases ranking; does not filter
#   --limit    Maximum results (default: 20)
#   --json     Emit the raw search payload
#   --data     Data directory (default: FACTHOUSE_DATA, a .facthouse store in this project, or ~/.facthouse)

--domainは**フィルタリングではなく、ランキングに重み付けします。**厳密なフィルターを使うと、類義語に近い表現で分類された事実が表示されなくなるためです。

facthouse stats

facthouse stats
facthouse stats --json

事実は不変であり、置き換えられた事実も保持されます。そのため、何かが置き換えられると、現在の件数と合計件数は正当に異なります。--jsonには、応答するバイナリのパッケージバージョンが含まれます。インテリジェンスの消費量は、抽出／分類／エンティティ／調整／置き換え／要約にかかった呼び出し回数、トークン数、経過時間で、各ステージのプロバイダーとモデルも表示します。埋め込みはこの数値に含まれません。

facthouse inspect

D、I、K、エンティティ、グラフをサンプル表示します。データディレクトリ（cwdではありません）にローカルHTMLファイルを書き込み、そのパスを出力します。ブラウザーは開きません。このファイルはメモリーのエクスポートです。stats --jsonと同様に扱ってください。同じページにはインテリジェンスの消費量も表示されます（Graph / Spend）。

facthouse inspect
facthouse inspect --graph
facthouse inspect --layer k
facthouse inspect --json
facthouse inspect --entity Helios --limit 20 --output ~/inspect.html

--layer health|d|i|k|entities|graph|allを指定すると、ターミナルに表を出力します（新しい順、件数に上限があります）。--graph（--layerも--jsonも指定しない場合のデフォルト）を指定すると、inspect.htmlを書き込みます。--limitのデフォルトは、表では10、キャンバスでは50です。--allを指定すると、すべてのノードを描画します。ノードが密集して読みにくくなりますが、明示的な指定です。ページ内の検索やタイプによるフィルターを使えば、上限から外れたノードも引き続き表示できます。

高度な機能

別のストア

ストアはこのディレクトリです。クライアントは同じパスを使うことで共有します。2つ目のストアは2つ目のディレクトリであり、2つ目のインストールではありません。デフォルトの MCP サーバー名は facthouse です。ストアを分けても、どのクライアントが行を書き込んだかでフィルターされるわけではありません。仕事用と個人用に分けるのは理由の一つですが、必須の設定ではありません。

デフォルト以外のデータディレクトリを指定すると、異なる MCP サーバー名が表示されるため、1つの mcp.json で2つのストアを共有できます。追加のディレクトリごとに Init を実行すると、その設定スニペットが表示されます。例：

{
  "mcpServers": {
    "facthouse-personal": {
      "command": "npx",
      "args": ["-y", "@facthouse/[email protected]"],
      "env": { "FACTHOUSE_DATA": "C:\\Users\\alex\\.facthouse-personal" }
    },
    "facthouse-work": {
      "command": "npx",
      "args": ["-y", "@facthouse/[email protected]"],
      "env": { "FACTHOUSE_DATA": "C:\\Users\\alex\\.facthouse-work" }
    }
  }
}

各ストアの sources.cwd（またはフックの --data）は、そのストアだけを指すようにしてください。両方に同じホームディレクトリをコピーすると、2つのディレクトリに分けても何も分離されません。

Postgres（任意）

SQLite がデフォルトで、追加のソフトウェアは必要ありません。代わりに Postgres を使うには、そのストアの config.json で storage.provider を "postgres" に設定するか、MCP エントリで FACTHOUSE_STORAGE=postgres を設定し、FACTHOUSE_POSTGRES_URL に postgres://（または postgresql://）URL を設定します。パスワードは config.json ではなく、環境変数に設定してください。URL がない場合やサーバーに接続できない場合、Facthouse は停止します。SQLite ファイルは作成しません。

データディレクトリは引き続きメモリとして使われます。config.json とスケジューラーソケットはそこに保存されます。テーブルは URL の接続先に保存されます。2つのメモリには、2つのディレクトリと2つのデータベースが必要です。

Init では、使用するエンジンを尋ねません。facthouse init --yes を実行しても、sqlite が書き込まれます。

例 — プレースホルダーのみです。コミットするファイルに実際のパスワードを記載しないでください。

{
  "mcpServers": {
    "facthouse": {
      "command": "npx",
      "args": ["-y", "@facthouse/[email protected]"],
      "env": {
        "FACTHOUSE_DATA": "C:\\Users\\alex\\.facthouse-work",
        "FACTHOUSE_STORAGE": "postgres",
        "FACTHOUSE_POSTGRES_URL": "postgres://USER:PASSWORD@localhost:5432/facthouse"
      }
    }
  }
}

コピーと記録

ストアごとに、どちらか一方の方式を選んでください。

推奨 — コピー。 claude-code、cursor、または grok のソース名を指定し（cwd を設定）、まず CLI から facthouse consolidate を実行します。MCP サーバーもセッション開始時と呼び出しの処理時にコピーします。Codex 用アダプターは後日追加されます。不明な kind 値は拒否されます。

{
  "sources": [
    {
      "kind": "claude-code",
      "home": "~/.claude",
      "cwd": "C:\\dev\\app"
    }
  ]
}

home はクライアントの設定ディレクトリです（~/.claude または ~/.cursor — 追加の検出先ではなく、パスの例です）。Cursor は "kind": "cursor" で、対象は home/projects/*/agent-transcripts/**/*.jsonl のみです — Composer の SQLite は対象外です。Cursor は C:\\dev\\app を c-dev-app としてエンコードします（Claude Code では C--dev-app が使われます）。50行を超えるデータの初回バックフィルには複数回の実行が必要ですが、facthouse consolidate --all を1回実行する方法もあります。

代替 — ソースなしで記録。 sources は空のままにします。クライアントのフックペイロードがあれば、facthouse record にパイプします。MCP の log_event / capture_fact は引き続き使用できます。

このストアには記録用フックをインストールしないでください — どちらも同じ行を書き込みます。Facthouse は既存のフック設定を検出したり、書き換えたりしません。

MCP のみの記録モード

ウィザードをスキップするには（記録のみ — トランスクリプトのコピーなし）、これを貼り付けます。サーバーは初回起動時に ~/.facthouse を作成します。これらの質問は表示されません。

{
  "mcpServers": {
    "facthouse": {
      "command": "npx",
      "args": ["-y", "@facthouse/[email protected]"]
    }
  }
}

フック

PreCompact notify compaction が便利です。クライアントがコンパクションを実行しようとすると、短時間動作するフックが実行中のサーバーに通知し、フックはすぐに戻ります。サーバーは新しい JSONL 行をコピーしてから抽出・統合します。コンパクションによってトランスクリプトが削除されることはなく、フックがライブウィンドウを丸ごとコピーすることもありません。Init は --data に値を設定したこの JSON を出力します。これを Claude Code の .claude/settings.json（ユーザーまたはプロジェクト）に貼り付けてください。こちらではインストールしません。Stop フックはインストールしないでください。このストアに記録フックをインストールしないでください。どちらも同じ行を書き込むためです。

mcp.json の env はフックから参照できません。同じ --data を渡すか、クライアント自体が引き継ぐ環境で FACTHOUSE_DATA を設定してください。コマンドでは必ず CLI（facthouse）を呼び出し、サーバーバイナリを呼び出さないでください。npx -y @facthouse/mcp を -p / facthouse なしで実行すると、MCP サーバーが起動してフックがハングします。パッケージのバージョンを固定し、フックが PowerShell で実行される場合は引用符で囲み、-- を facthouse の前に置いて、PATH 上にグローバルインストールされた古いバイナリが優先されないようにしてください。

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y -p @facthouse/[email protected] -- facthouse notify compaction --data /absolute/path/to/the-same-store"
          }
        ]
      }
    ]
  }
}

PreCompact notify compaction は、実行中のサーバーに統合を依頼します。最新の JSONL 行をコピーし、抽出して統合します。フックはすぐに戻り、サーバーが処理を行います。ターン終了時の Stop フックはインストールしません。Windows では、--data のパスは FACTHOUSE_DATA に設定する絶対ディレクトリと同じです（例：C:\\Users\\alex\\AppData\\Local\\Temp\\facthouse-try）。

頻繁な増分コピーでは、グローバルシーケンス上で会話が交互に並びます。開いたままの長いチャットは、ほかのチャットの間に分割されます。抽出の進捗は会話ごとに管理されるため、あるチャットでタイムアウトしても、別のチャットのデータは破棄されません。extraction.batch_size を小さくすると、抽出呼び出しが増え（タイムアウトの可能性も高まり）ますが、ストア全体をまとめて保留することにはなりません。facthouse stats は、その抽出ウォーターマークに対する未抽出イベントを報告します。

MCP サーバーが起動しない場合や、ツールが表示されない場合は、クライアントが実際に起動したパッケージのバージョンを確認してください。PATH 上のグローバルな facthouse は、この README に記載された固定バージョンより何年も古い可能性があります。facthouse stats --data <dir> で診断してください（CLI はスケジューラーがリッスン中かどうかを出力します）。また、stdio 経由で initialize の serverInfo.version と tools/list を調べてください。0.2.x は initialize に応答した後、tools/list で例外をスローします。

埋め込み、モデル、タイムアウト、二時点管理

config.json で embedding.provider を "ollama"（ローカル、API キー不要）または "voyage"（ホスト型）に設定して facthouse consolidate を実行すると、search "food" でアレルギーに関する情報が返されるようになります。事実は統合時に埋め込まれます。アカウントに支払い方法が登録されるまでは、Voyage に 1 分あたり 3 リクエストのレート制限が適用されます。

意味検索では、対象の集合が小さい場合、保存されたベクトルを正確に全件スキャンします。集合が大きくなると（デフォルトでは現在のモデルで 32 MiB）、そのベクトルの HNSW インデックスを使用します。SQLite ではプロセス内で、拡張機能が有効な場合は Postgres の vector サイドカーで動作します。小規模なストアでは引き続き正確な検索を使います。エンジンが見つからない場合も正確な検索を続け、警告を表示します。Facthouse はネイティブアドオンをインストールしません。embedding.ann は null（自動）、false（使用しない）、true（エンジンが対応している場合に強制使用）のいずれかです。これは埋め込みを有効にする設定ではありません。

intelligence.cli.model と intelligence.cli.timeout_ms で、さらに細かく設定できます。初回起動時のその他の設定（Y）で書き込めます。以降は facthouse settings を実行してください。Init では intelligence.provider の設定を求めません。FACTHOUSE_PROVIDER=heuristic は緊急停止用のスイッチです。ヒューリスティックによるフォールバックでは、トランスクリプトから事実を抽出しません。

名前のないユーザーチャネルの発言はストアの所有者に帰属します。表示名だけでは人物は作成されません。同意、ツールによる観察、別の話者による言い直しなどの追加の裏付けは記録されますが、スコア付けはされません。ただし、ストアで config.json に interlocutor の重みを設定した場合は除きます。エンジンには重みが含まれていません。重みのキーは保存された話者文字列と一致するため、同じ名前の二人には同じキーが適用されます。

temporal.mode を bitemporal に設定すると、システムがある信念を撤回した時点を記録し、特定の時点でストアが何を信じていたかを検索で回答できるようになります。

インテリジェンスの利用料金

facthouse stats と get_stats は、課金対象となる統合呼び出しについて、トークン数、経過時間、各段階（抽出、分類、エンティティ、照合、置き換え、要約）のプロバイダーとモデルを報告します。トークン数が報告されなかった実行では、これらのフィールドはゼロではなく省略されます。埋め込みは別の API を使うため、この数値には含まれません。

任意の intelligence.token_budget を設定すると、ローリング期間ごとにプロバイダー別の課金対象となる抽出を上限付きにできます。未設定の場合は無制限です。上限を超えると、consolidate は抽出をスキップしてウォーターマークを保持し、ヒューリスティックにはフォールバックしません。Stats と Inspect Spend には、各上限の使用量と残量、さらにその期間内で最も古い使用量が期限切れになる時刻（resets）が表示されます。

"intelligence": {
  "token_budget": {
    "cli": { "week": "10M" }
  }
}

hour、day、week、month はローリング期間です。スケールを省略すると、無制限になります。残りの上限は facthouse stats、get_stats、Inspect Spend で確認できます。このストアの config.json で上限を設定してください。予算コマンドはありません。

任意のローカルインテリジェンスは、埋め込みとは別の設定です。OpenAI 互換ホストで intelligence.http を追加してください。プロトコルは POST /v1/chat/completions で、変わるのはポートだけです。

モデル文字列には、そのホストに表示されるものを指定します。GET {base_url}/models でモデル名を表示できます。nomic-embed-text は埋め込み専用で、抽出には使えません。ホストが起動していて、チャットモデルをちょうど 1 つ提供している場合、Facthouse はこの実行でそのモデルを使用し、intelligence.http.model を固定するよう案内します。チャットモデルが複数表示される場合は、そのフィールドを設定してください。抽出時に推測することはありません。

その後の抽出と要約ではこのホストを使用します。照合と置き換えは、intelligence.stages に指定しない限り CLI のままです。各段階では、失敗時の動作として cli、http、none を設定できます（以下の JSON を参照）。HTTP 抽出は、デフォルトで CLI で再試行します（CLI のトークン予算に算入されます）。矛盾の処理はデフォルトで none で、プロバイダーは切り替わりません。none の場合、抽出のウォーターマークは保持され、ヒューリスティックにはフォールスルーしません。初回起動時の More settings（推奨パスの後に Y）では、ホスト、モデル、抽出失敗時の動作を設定できます。後から facthouse settings を実行すると、既存のファイルをリセットせずにこれらの設定をマージします。facthouse inspect の Spend には同じ設定が表示され、JSON をコピーできますが、config.json は保存されません。

ライブスクリプト npm run test:http-intelligence は qwen2.5vl:7b で成功しています。

"intelligence": {
  "http": {
    "base_url": "http://localhost:11434/v1",
    "model": "qwen2.5vl:7b"
  },
  "stages": {
    "extract": { "provider": "http", "on_fail": "cli" },
    "summarise": { "provider": "http", "on_fail": "cli" },
    "reconcile": { "provider": "cli", "on_fail": "none" },
    "supersede": { "provider": "cli", "on_fail": "none" }
  }
}

CLI デモ（トランスクリプトのソースなし）

使い捨てのストアであり、実際の Claude Code や Cursor のホームから取り込むための経路ではありません。次の 3 行を入力します。

export FACTHOUSE_DATA=/tmp/facthouse-demo
om() { npx -y -p "@facthouse/[email protected]" -- facthouse "$@"; }

om init --yes

om record --role user --content "I prefer dark mode in every editor, and I never want telemetry enabled."
om record --role user --content "I am allergic to shellfish, so avoid seafood restaurants when booking anything."
om record --role user --content "My colleague Robin at Acme is leading the Atlas migration project this quarter."

om consolidate
om search "Atlas"
om stats

$env:FACTHOUSE_DATA = Join-Path $env:TEMP "facthouse-demo"
function om { npx -y -p "@facthouse/[email protected]" -- facthouse @args }
om init --yes
om record --role user --content "I prefer dark mode in every editor, and I never want telemetry enabled."
om record --role user --content "I am allergic to shellfish, so avoid seafood restaurants when booking anything."
om record --role user --content "My colleague Robin at Acme is leading the Atlas migration project this quarter."
om consolidate
om search "Atlas"
om stats

allergies は Facthouse に付属するドメインではありません。エンジンに組み込みの語彙はなく、会話を読み取り、その事実に保存先が必要だと判断しました。ドメインはフィルタリングではなく、ランキングに偏りを与えます。クリーンアップするには、rm -rf /tmp/facthouse-demo（Git Bash／macOS／Linux）または Remove-Item -Recurse -Force $env:TEMP\facthouse-demo（PowerShell）を実行します。

統合

Facthouse のツール説明は、いつ検索するか、いつ修正をステージングする価値があるかをアシスタントに伝えます。Claude Code の会話をストアに取り込む方法ではありません。取り込みには、名前を指定したソースからコピーします。

設定なしの場合

Claude Code、Cursor、または Grok Build の場合は、sources エントリを指定して（cwd を設定）、まず CLI から facthouse consolidate を実行してください。MCP セッションの開始時にもコピーが行われます。コピーと抽出では生成されない内容をアシスタントが修正または追加する必要がある場合は、capture_fact を使います。

コピーアダプターのないクライアントでは、アダプターが用意されるまでは log_event／capture_fact に頼ります。

フックポイント

コンパクション前について： facthouse notify compaction はサーバーに統合を依頼します。これは record フックではありません。

Claude Code

プロジェクト内に .claude/rules/facthouse.md（または全体設定として ~/.claude/rules/facthouse.md）を作成します。

# Facthouse

- Conversations are copied from the named Claude Code source (first backfill: `facthouse consolidate` on the CLI)
- Do not install record hooks on this store — both write the same rows.
- Identity context loads automatically from the `memory://profile` resource — no tool call needed
- Before answering questions this store might already know, call `search_knowledge`
- Call `capture_fact` only to correct or add something that is not in the transcript
- When the conversation is getting long, call `consolidate` (or rely on PreCompact `facthouse notify compaction`)
- At natural breakpoints (topic change, task completion), call `consolidate` to keep the knowledge graph current

呼び出しごとの承認プロンプトなしで Facthouse ツールを使えるようにするには、.claude/settings.json の permissions.allow 配列に追加します。

{
  "permissions": {
    "allow": [
      "mcp__facthouse__*"
    ]
  }
}

Cursor / Windsurf

Cursor Directory では、Add to Cursor はコンポーネントごとに行います。MCP サーバー上でクリックし、もう一度ルール上でクリックしてください。これにより ~/.facthouse にレコードストアが作成されます。facthouse init は不要です。Hooks タブは Add to Cursor ではなく、~/.cursor/hooks.json へのコピーです。Agent のトランスクリプトをコピーするには、facthouse init を実行し、copy、kind cursor を選択します。

プロジェクトのルートにある .cursorrules（Cursor）または .windsurfrules（Windsurf）に追加します。

When the facthouse MCP server is available:
- At the start of every conversation, before answering, call get_session_context unless you already loaded the memory://briefing resource. That call returns the same working briefing the resource would have injected. Tools-only clients never fetch resources.
- Before answering questions this store might already know, call search_knowledge
- To find out everything known about a particular person, project, or thing, call get_entity
- Call capture_fact only to correct or add something copy or extraction missed

Cursor と Windsurf はツールを利用しますが、リソースは利用しないため、memory://profile はそこで自動的に読み込まれません。Cursor の会話自体は kind: "cursor" でコピーされます（~/.cursor/projects/ 内の JSONL であり、SQLite の composer ストアではありません）。

Grok Build の会話は kind: "grok" でコピーされます。対象は updates.jsonl ではなく、~/.grok/sessions/（または GROK_HOME）内の chat_history.jsonl です。推論、システム行、挿入されたリマインダー、サブエージェントの実行（親が subagents/ 以下に列挙するセッション）はスキップされます。

Claude Desktop / その他の MCP クライアント

コピー用アダプターはまだありません。ツールの説明で検索と任意の capture_fact を扱います。後続のアダプターが提供されるまで、会話の追跡は行われません。

空き容量の回復

Facthouse は、生の会話とツール出力を session_events に記録します。エージェント型クライアントに接続されたストアでは、これがデータベースのほぼすべてを占めるようになります。日常的に使われているストアを計測したところ、統合済みのファクトが21件だったのに対し、イベントは47,000件、容量は493 MBでした。

facthouse stats は、回収可能な容量も含め、ナレッジと並べて生データ層を報告します。回収するには、次の手順を実行します。

facthouse prune                    # report only — nothing is deleted
facthouse prune --apply --vacuum   # delete, then rebuild the file

config.json の retention.disk_budget に "2GB" などのサイズを設定すると、memory.db の容量を制限できます。未設定の場合は無制限で、init によって上限が書き込まれることはありません。上限を設定してファイルがいっぱいになると、参照されていない生イベントが自動的に整理され、新しいログでその容量を再利用できます。未使用のイベントが残っていない場合、それ以上の生イベントは拒否されます。この上限を満たすためにファクトが削除されることはありません。コンパクト化（--vacuum）は引き続き手動で行う必要があります。ファイル全体をコピーすることで、オペレーティングシステムにサイズの縮小を認識させます。

容量の大半がノイズだと判断したツール出力であれば、extraction.event_types と extraction.roles で調査対象を制限し、extraction.min_content_length で些細なイベントを除外できます。実行する前に計測してください。容量と価値は同じ尺度ではありません。

基準となるのは経過時間ではなく、到達可能性です。 次の3つすべてに該当する場合に限り、イベントは削除されます。

1. 抽出処理がすでに読み取り済みであること。統合処理のウォーターマークより先にあるイベントは、引き続き入力として扱われます。
2. どのファクトの出典情報にも記載されていないこと。
3. そのセッション内の直近の extraction.working_memory_size 件のイベントの範囲外であること。これは、統合処理が最近の生メモをざっと確認できるようにするための余裕です。このウィンドウは現在のトピックを示す証拠であり、代名詞の辞書ではありません。

ファクト、エンティティ、埋め込み、検索結果には影響しません。行を削除しただけではファイルは縮小されません。縮小には --vacuum を実行します。上限を設定しない場合、自動的な整理は行われません。

開発

git clone https://github.com/gordonkjlee/facthouse
cd facthouse
npm install
npm run build
npm test

npm test は常に、記録用エクストラクターを使った隔離されたパイプライン（フィクスチャの JSONL → コピー → 抽出 → 検索）を実行し、実際のモデルを必要とするライブ評価はスキップします。

• セマンティック検索の再現率テストには、nomic-embed-text を備えた Ollama が必要です。起動してから npm run test:semantic を実行してください。
• 最初のファクトに関するライブ評価には claude CLI が必要です。npm run test:first-fact を実行してください。
• コーディングストアのライブ評価（倉庫を想定した Cursor の文字起こし）にも claude CLI が必要です。npm run test:coding-store を実行してください。
• ローカル HTTP 抽出には、OpenAI 互換ホスト上のチャットモデルと FACTHOUSE_HTTP_MODEL が必要です（qwen2.5vl:7b で検証済み）。npm run test:http-intelligence を実行してください。

これらのスクリプトは、依存関係がない場合にスキップせず失敗します。そのため、テストが成功すれば、主張がひそかに見過ごされたのではなく、実際に検証されたことを意味します。

貢献

Issue とプルリクエストを歓迎します。誤字修正以上の変更を行う場合は、まず Issue を作成してください。

• 質問：GitHub Discussions
• ビルドとテストの方法：CONTRIBUTING.md

ライセンス

MIT