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+.

npm install -g @facthouse/mcp@0.30.0
facthouse init

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

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 or Cursor 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 — paste it into the client and restart.

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 or Cursor 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. Extract turns new transcript lines into self-contained facts. Integrate fits them into what the store already knows: domains, entities, duplicates, contradictions, the graph. consolidate runs copy, extract, and integrate together — in the server at session start and at compaction, or by hand from the CLI. Extract is capped at 50 lines per run, so a first backfill is never spent on the lot; each automatic run extracts facts from the oldest 50 lines. The MCP server copies the raw log on a call; it does not extract then. Consolidation does not invent a sentence nobody said.

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. Grok has no transcript adapter — do not put Claude Code on copy and Grok on the same store expecting Grok to record.

facthouse init

Pick copy, set cwd. Init asks whether to copy existing logs, then whether to extract and integrate (Enter = all copied lines). Decline extract to do that later with facthouse consolidate (--all takes the whole backlog). After that, the server copies new lines when it handles a call.

Compact (optional): facthouse notify compaction — 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, or FACTHOUSE_DATA in the environment that shell inherits. Hooks do not see mcp.json env.

npm install -g @facthouse/mcp@0.30.0
facthouse init --yes

npx -y -p "@facthouse/mcp@0.30.0" -- facthouse init --yes
npx -y -p "@facthouse/mcp@0.30.0" -- facthouse settings --json
npx -y -p "@facthouse/mcp@0.30.0" -- facthouse stats
npx -y -p "@facthouse/mcp@0.30.0" -- facthouse inspect