Introduction
How Spool's parts fit together, who it is for, and what each page of these docs covers.
Spool pulls records out of text and rows, decides which are the same real-world thing, and gives each thing an ID that stays the same as more arrive. Working out which records are the same thing is called entity resolution, or record linkage. Spool does that, takes records from text as well as from tables, and keeps the IDs.
How the parts fit
Spool is one server. It is written in Rust and keeps its data in one file of DuckDB, a database that runs inside the server's process. It is driven by a project, which is a directory of YAML and SQL files that you keep in Git.
- A project is a directory. Sources, features, rules and extractors are files, and a file's path is its name. Project structure
- Records come from rows or from text. A row of a source becomes a record. A document is stored, and an extractor finds the places where it names a thing: each place becomes a record. An extractor is a pattern that Spool runs itself, or your own code in Python or TypeScript, which the server runs as a child process. A record is never changed, and loading it twice does nothing. Records and sources, Extraction
- Records are compared by features. Each source's columns are mapped onto the features of an entity type, such as
company, that you declare. Entity types and features - Rules judge pairs. A match compares what is new with what is known and records a judgement for each pair:
matchorno_match. A rule is a SQL condition over two records. Matching - Judgements become identities. New records join an identity or start one. A match never merges or splits identities that exist. Every change is an entry in a log, with an author and a reason, and can be undone. Identities
- What cannot be decided waits. A record that fits two identities, and an identity that may have come apart, are left for a person or an agent. Review
- Other systems store the ID. They look it up by a row's source and key, and follow the log to learn of merges and splits. Using the IDs
There are four ways in, and they reach the same server:
| For | Page | |
|---|---|---|
| The command line | Loading, extracting, matching, showing and explaining | Command line |
| The HTTP API | Everything. The other three call it | HTTP API |
The MCP endpoint at /mcp | An agent that loads, looks things up and corrects | MCP |
| The studio, in a browser | Looking, reviewing, merging, splitting and undoing | Getting started |
Who it is for
- You maintain a list of companies, people or products that several sources feed, and other systems refer to them by ID.
- Some of what you know about them is in text: notes, articles, emails.
- You want to read why two records were matched, and take a wrong match back without rebuilding everything.
- You want matching rules reviewed like code, in files, with a history.
- You have people or agents making corrections, and need every correction attributed and reversible.
- You have thousands to a few million records, and one machine is enough.
If that is not you, Limits says what Spool is not meant for, and Compared with other tools says what to use.
The pages
Start
- Getting started: install it, load rows, match them, extract records from a note. Five minutes.
- Limits: what it is not meant for, what stable IDs cost, what it does not do yet, how large it has been run.
- Compared with other tools: Splink, dedupe, Zingg, Senzing, nomenklatura, GoldenMatch, and a
GROUP BY.
Concepts. Each page starts from the sample project and can be run by itself.
Use
- Using the IDs: from another system.
- MCP: connecting an agent, and every tool.
- Deploying: running it for other people.
Reference
Where it stands
Spool's first commit was on 14 November 2026. It is version 0.1.0, under the MIT licence, and formats and the API can still change.
Every command on these pages is run by a script, site/scripts/check-samples.ts, against a build of the source, and the output shown is compared with what was printed. It is run by hand before a page changes.
The source is at github.com/alexpatow/spool.