facthouse

# Facthouse

<img src="brand/mark.png" width="128" align="right" alt="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.

[![npm](https://img.shields.io/npm/v/@facthouse/mcp.svg)](https://www.npmjs.com/package/@facthouse/mcp)
[![CI](https://github.com/gordonkjlee/facthouse/actions/workflows/ci.yml/badge.svg)](https://github.com/gordonkjlee/facthouse/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/github/license/gordonkjlee/facthouse)](LICENSE)

<a id="quick-start"></a>

## Quick Start

Needs Node 22.5 or 24+.

<!-- x-release-please-start-version -->
```bash
npm install -g @facthouse/mcp@0.31.0
facthouse init
```
<!-- x-release-please-end -->

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 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 or Cursor logs, or record from any MCP client: [How conversations get in](#how-conversations-get-in). Replay: [facthouse.dev/demo.html](https://facthouse.dev/demo.html). CLI: [below](#cli).

## 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 |

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](https://github.com/anthropics/claude-code) 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.

| | Copy from transcripts | The assistant records |
|---|---|---|
| Who | Claude Code or Cursor (session logs on disk, under the client home) | Any MCP client (Grok, Desktop, …) |
| How | Name a source; Facthouse copies new lines from those logs into the store | Empty `sources`; the assistant calls `capture_fact` |
| First run | TTY walk-through, pick **copy**, set cwd; init asks whether to copy existing logs, then whether to extract and integrate | TTY walk-through, pick **record** |

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.

```bash
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](#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