gordonkjlee/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+.
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**
| When | Copy | Extract (D→I) | Integrate (I→K) |
|------|------|---------------|-----------------|
| Facthouse MCP server starts | yes | yes (cap 50) | yes |
| A Facthouse tool or resource is called | yes, if sources named and JSONL grew | no | no |
| Facthouse MCP process exits | no | no | yes |
**Callable**
| Call | From | Copy | Extract (D→I) | Integrate (I→K) |
|------|------|------|---------------|-----------------|
| consolidate | MCP tool or CLI. Caller waits. | yes | yes (cap 50) | yes |
| facthouse notify compaction | Other process (recommended PreCompact; we do not install). Does not wait. | yes | yes (cap 50) | yes |
| facthouse notify threshold | Other process. Does not wait. Not a copy-store hook. | no | yes, if due (cap 50) | no |