Facthouse

Facthouse

Facthouse is a local memory engine for AI tools. Most “memory” products index chat logs. Facthouse takes agent activity - messages, tool use, and other MCP traffic - and applies neuroscience-inspired consolidation so it moves through Data (what happened in the session) → Information (extracted facts) → Knowledge (integrated beliefs on an entity graph). During this process, Facthouse links entities, drops duplicates, reconciles conflicts, and supersedes what is out of date. Vector embeddings add optional semantic search on top of that graph. The store is a SQLite file on your disk.

Quick Start

Needs Node 22.5 or 24+.

npx -y @facthouse/mcp

facthouse init

facthouse init --web is the same setup as a browser form — it prints a 127.0.0.1 URL and does not open a browser.

Press Enter to accept each default (copy = Claude Code, Cursor or Grok Build session logs on disk; type record if the assistant should save facts). If you picked copy, init asks whether to copy existing logs, then whether to extract and integrate. Init prints an MCP snippet as soon as the store is written — add it to the client's MCP config while copy/extract run. Restart the client when init finishes.

In the client, state something durable in ordinary conversation — there is no remember command.

Ask it back in the next session, or facthouse search. That is the store.

Copy from Claude Code, Cursor or Grok Build logs, or record from any MCP client: How conversations get in. Replay: facthouse.dev/demo.html. CLI: below.

What you get

• Local SQLite. Optional Postgres. Isolation is the directory, not a column.
• Entity graph. People, organisations, projects, places, products — extracted, typed and linked.
• Hybrid search. BM25 + structured domain + entity-graph paths, merged via Reciprocal Rank Fusion. An embedding provider adds meaning as a fourth list; off by default.
• In-session memory. get_session_context is the same briefing as memory://briefing. Tools-only clients should call it at session start.
• Immutable history. Facts are never deleted, only superseded.

How it works

One SQLite database. Three tables in it, not three databases: Data (what happened in the session) → Information (extracted facts) → Knowledge (integrated beliefs).

• D (session_events) — what was said (copied transcripts, or what the assistant records)
• I (session_facts) — what was just extracted, or capture_fact
• K (facts) — integrated knowledge

FTS5 (words) and optional embeddings (meaning) are indexes of K. They are not a second store. Semantic search is off unless you turn it on: search "shellfish" finds a shellfish fact, search "food" does not, until you choose an embedding model — a model is an opinion about what “similar” means.

Two speeds. Copy tails named transcripts into Data. Extract turns new transcript lines into self-contained facts (D→I). Integrate fits them into what the store already knows: domains, entities, duplicates, contradictions, the graph (I→K). consolidate is the umbrella: copy, extract, and integrate together. Extract is capped at 50 lines per run, so a first backfill is never spent on the lot; when extract runs, it takes the oldest 50 lines. Consolidation does not invent a sentence nobody said.

A hook cannot call MCP tools — those exist only on the assistant’s connection — and it must not wait for a model pass. So it does not invoke consolidate. It runs facthouse notify …, which tells the already-running server that a moment happened and returns at once. consolidate is the pipeline verb (MCP tool or CLI); the caller waits. notify compaction is that verb asked of the live server, asynchronously. notify threshold is a different policy (extract only, if due).

Automatic

Callable

On a default copy store with no extra hooks, only the automatic table runs: Facthouse starts (all three), copy on each Facthouse tool or resource call if named sources grew, and integrate on a clean process exit. Closing a chat window may skip the exit row; the next start still consolidates. Due on threshold means at least 10 unexamined lines and two minutes since the last gated run. consolidate --all lifts the extract cap. Compaction is recommended PreCompact (notify compaction): same three steps as consolidate, on the running server, without waiting. We do not install the hook. Not a Stop hook. record wakes threshold extract on a record store — do not install record hooks on a copy store.

Storage needs Node. Intelligence needs a language model. By default that is the Claude Code CLI on your existing subscription. Without it, consolidation falls back to a built-in heuristic that does not extract facts from transcripts. capture_fact still stores facts, with no entities and no domain routing.

How conversations get in

Two ways. Pick one per store.

On a copy store, capture_fact is a correction for every MCP client, not only the one that writes JSONL. To use Claude Code and Grok Build on one store, name a claude-code source and a grok source with the same cwd: both copy in, and neither is asked to record. Do not also install record hooks on that store.

facthouse init

Pick copy, set cwd. Init asks whether to copy existing logs, then whether to extract and integrate (Enter = all copied lines; a selection of 500 or more asks you to type the choice again). Decline extract to do that later with facthouse consolidate (--all takes remaining unexamined lines, not ones skipped as outside a 7-day or 30-day window). After that, the server copies new lines when it handles a Facthouse call. Extract and integrate follow the table in How it works.

Compact (recommended): facthouse notify compaction — we do not install the hook. Not a turn-end Stop hook.

MCP

Works with any MCP-compatible tool. Default store: ~/.facthouse. A different path is "env": { "FACTHOUSE_DATA": "/absolute/path" } on the MCP snippet. JSON accepts forward slashes on Windows.

Cursor consumes tools but not resources until a later adapter exists — search_knowledge and get_entity still work there; call get_session_context at session start.

Resources are context the client loads automatically — no tool call. Tools only help if the assistant remembers to reach for them; resources are simply present.

• memory://briefing — Everything worth knowing right now: profile, what was learned in the last consolidation, open threads, and recent knowledge. Markdown, kept to roughly a screenful.
• memory://profile — Core identity facts, most important first.

Both are read-only views over the same database the tools query. Clients that never load resources (Cursor, Windsurf, Grok) get the same briefing by calling get_session_context at the start of a conversation. No second profile schema.

Tools

Session

• log_event — Log conversation events (messages, artifacts).
• get_events — Retrieve events from current or previous session.
• get_session_context — Working briefing (the same markdown as memory://briefing) plus facts captured in this session. Call at the start of every conversation if the client does not load resources.

Reading

• get_entity — Everything known about any named subject — person, organisation, project, place, product — and how it connects. When several rows share the name under different types, facts from all of them come back. Hyphens, underscores, and stray punctuation count as the same letters only when that does not join two names already stored as separate rows. If there is no entity by that name, facts that mention the wording still come back rather than an empty miss.
• get_context — Everything relevant to a topic (search + entity traversal)
• search_knowledge — Hybrid search across integrated knowledge

Writing

• capture_fact — Store a fact. On a copy store this is a correction for something extraction missed; on a store with empty sources it is how facts get in. The description the assistant sees is generated from that same rule.
• consolidate — Integrate pending facts into long-term knowledge. Extracts entities, resolves duplicates, detects contradictions, builds the knowledge graph.
• Inference tools — Opt-in, off by default (inferences.enabled in config.json). A hypothesis cites existing fact ids and stays pending until confirmed. Those tools are not registered until you turn the gate on. Consolidate never invents a sentence nobody said.

Meta

• get_schemas — Available domains and structure
• get_stats — Fact count, entity count, domain distribution, extract backlog, intelligence spend

CLI

The MCP JSON starts the server via npx and does not need a global install. npm install -g puts facthouse on PATH for init, settings, stats, and inspect. The same CLI without PATH is npx -y -p "@facthouse/mcp" -- facthouse — pin the version; quote the package so PowerShell does not splat. -p and -- stop an older global binary winning. npx -y @facthouse/mcp with no -p / facthouse is the server; do not run it as a shell command for init, settings, or stats. The MCP paste starts the server. It does not put facthouse on PATH. To inspect the file from a terminal, see CLI below.

These CLI commands work in bash, zsh, and PowerShell. Quote @facthouse/mcp in PowerShell. Git Bash /c/... paths are not PowerShell; use C:/... and pass --data instead of cd or export. In Git Bash, quote a backslash path or write C:/... — unquoted \ is an escape. ~/ is expanded on every platform. WSL uses /mnt/c/.... FACTHOUSE_DATA on an MCP snippet applies only to that server process. A terminal facthouse command needs --data, FACTHOUSE_DATA in the environment that shell inherits, or a .facthouse store in this project. Hooks do not see mcp.json env.

npm install -g @facthouse/mcp@0.31.0

facthouse init --yes

If npm install -g fails because a command named mcp already exists, remove that leftover command and retry.

npx -y -p "@facthouse/mcp@0.31.0" -- facthouse init -