Getting started

Install Spool, load sample rows, match them, see each company keep its ID as more rows arrive, and get records out of a text, from the command line, over HTTP and over MCP.

This page installs Spool, makes a project with sample rows, matches them, shows that each company keeps its ID when more rows arrive, and gets three records out of a call note. It takes five minutes. Each step is shown three ways: the command, the HTTP call and the MCP tool. Use the command and read the other two. To find out first whether Spool fits your problem, read Limits.

What you need

  • Linux on x86-64 or arm64, or macOS on Apple silicon. There is no Windows build.
  • curl.

Install

curl -fsSL https://github.com/alexpatow/spool/releases/latest/download/install.sh | sh

The script downloads the release for your machine, checks it against its checksum, unpacks it under ~/.local/share/spool/0.1.0 and links ~/.local/bin/spool. It needs no root and changes nothing else. To do it by hand, download spool-0.1.0-<target>.tar.gz from the release, unpack it and put its bin directory on your search path. Keep bin and lib together: the binary loads the DuckDB library from ../lib.

spool --version
Output
spool 0.1.0

Create a project

spool init companies
cd companies
Output
created   companies

  sources/crm.yaml                   the columns of a CRM export
  sources/notes.yaml                 what a record found in a note may say
  entities/company/entity.yaml       what companies are compared by
  entities/company/rules/            three rules, one line of SQL each
  transforms/name_key.sql            the lower-case name the rules compare
  extractors/companies.yaml          a pattern that finds company names in text
  samples/crm-1.csv                  six rows to load first
  samples/crm-2.csv                  three more for later
  samples/notes-1.txt                a call note that names three companies
  .gitignore                         keeps the server's data, .spool/, out of Git

  cd companies
  spool dev                          runs the server on this machine
  spool load samples/crm-1.csv       loads the first rows
  spool extract samples/notes-1.txt  finds the companies in the note

A project is a directory of files that you keep in Git. This one declares a source of rows, crm, a source of documents, notes, and one entity type, company. An entity type is a kind of thing you want one ID for. The sample rows:

samples/crm-1.csv
id,name,country
c-1,Acorn Tools,GB
c-2,ACORN TOOLS,GB
c-3,Acorn Tools Ltd,GB
c-4,Larkfield Logistics,GB
c-5,Halden Group,GB
c-6,Halden Group,US

Start the server

spool dev
Output
project   .
store     ./.spool/dev.duckdb
applied   7e7d66320c2599ececa81aaa5885550a150b4b93f3cca956ee3deefba46921fd (declared company)
accounts  ./.spool/dev.auth.sqlite
listening on http://127.0.0.1:7765
studio    http://127.0.0.1:7765/
mcp       http://127.0.0.1:7765/mcp

It listens on this machine only and asks nobody to sign in. Its data is in .spool/dev.duckdb, and it applies changes to the project's files as you save them. The last two lines are the addresses of the browser interface and of the endpoint an agent connects to. Leave it running and open a second terminal in the companies directory.

If something else is listening on port 7765, spool dev says so and names the fix: add --listen 127.0.0.1:7766 to the command, set SPOOL_URL=http://127.0.0.1:7766 in the second terminal, and use that address in the HTTP calls. A second spool dev on the same project is refused, because one server runs on a store at a time.

Load rows

spool load samples/crm-1.csv
Output
source  crm
type    company
read    6 rows from samples/crm-1.csv
loaded  6 new, 0 already held, 0 new versions
next    `spool match` places them in identities

Each row is now a record. Loading does not match, and loading the same file again adds nothing.

The same over HTTP. The API calls loading "ingest":

curl -s -X POST 'http://127.0.0.1:7765/v1/ingest?source=crm&entity_type=company' -H 'content-type: text/csv' --data-binary @samples/crm-1.csv

The same as an MCP tool call, with one object for each row:

MCP tool call
{ "name": "load_rows", "arguments": { "source": "crm", "entity_type": "company",
  "rows": [ { "id": "c-1", "name": "Acorn Tools", "country": "GB" } ] } }

Match

spool match
Output
run         2
type        company
examined    6 records
candidates  4 pairs
judgements  3 match, 1 no_match
placed      6 records, 4 identities created
left out    0 records in 0 review items

A match run compares the records that are new, with each other and with the ones it has placed before, and puts each in an identity. Four pairs were worth comparing. Three were judged the same company and one was not.

The same over HTTP, where a match is a run:

curl -s -X POST http://127.0.0.1:7765/v1/runs -d '{"entity_type": "company"}'

The same as an MCP tool call:

MCP tool call
{ "name": "run_match", "arguments": { "entity_type": "company" } }

See the result

spool show records
Output
source and key  name                 identity
crm:c-1         Acorn Tools          01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-2         ACORN TOOLS          01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-3         Acorn Tools Ltd      01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-4         Larkfield Logistics  01a1ef8e-5a8d-76d4-acb6-2bb802d5ca25
crm:c-5         Halden Group         01a1ef8e-5a8d-76d4-acb6-2bb793e9d0ae
crm:c-6         Halden Group         01a1ef8e-5a8d-76d4-acb6-2bb65a02262a

That is the listing without its first column, which holds each record's own ID and is left out here to fit.

An identity is one company, with its ID and the records that belong to it. The three spellings of Acorn Tools have one identity. Its ID, in the last column, is the company's ID, and it is what other systems store. Yours differs from this one, because an identity's ID is minted when the identity is created. A record's ID is derived from its source, its key and its content, so yours are the same as the ones on these pages.

The same over HTTP:

curl -s 'http://127.0.0.1:7765/v1/records?source=crm'

The same as an MCP tool call:

MCP tool call
{ "name": "search_records", "arguments": { "source": "crm" } }

Ask why

spool explain crm:c-5 crm:c-6
Output
`crm:c-6` belongs to identity 01a1ef8e-5a8d-76d4-acb6-2bb65a02262a and `crm:c-5` to identity 01a1ef8e-5a8d-76d4-acb6-2bb793e9d0ae.
Run 2 (strategy `rules`) judged them `no_match` (no_match rule `different_country` held).
Both were placed at log position 1 by `engine` (reconcile run 3, "reconcile new records").
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and no_match rule `different_country` holds, so they would be judged `no_match`.

left   34a5d12a-11a0-e461-c6e4-0576f546d165  crm:c-6  identity 01a1ef8e-5a8d-76d4-acb6-2bb65a02262a
right  38f040c9-82b9-2f94-813b-697309e52dab  crm:c-5  identity 01a1ef8e-5a8d-76d4-acb6-2bb793e9d0ae

features
            left          right
  country   US            GB
  name      Halden Group  Halden Group
  name_key  halden group  halden group

rules as they are now
  block     name_prefix        holds
  no_match  different_country  holds
  match     similar_name       holds

runs that compared them
  run 2  rules  succeeded  block: name_prefix  no_match

The two Halden Groups have the same name and different countries. The rule that kept them apart is one line:

entities/company/rules/no_match/different_country.sql
-- A no_match rule says a pair is not the same thing, and wins over any
-- match rule. This one holds only when both rows have a country.
l.country <> r.country

The rule that matched "Acorn Tools Ltd" to "Acorn Tools" is one line too:

entities/company/rules/match/similar_name.sql
-- A match rule says a pair is the same thing: here, two names that are
-- close. The similarity is 1 for equal names and 0 for names with nothing
-- in common.
jaro_winkler_similarity(l.name_key, r.name_key) >= 0.92

A rule is a SQL condition over two records, l and r. Matching explains the three kinds.

The same over HTTP:

curl -s 'http://127.0.0.1:7765/v1/explain?a=crm:c-5&b=crm:c-6'

The same as an MCP tool call:

MCP tool call
{ "name": "explain_pair", "arguments": { "a": "crm:c-5", "b": "crm:c-6" } }

Send more rows

The second sample file has two names that are spelt wrongly and one company that is new:

samples/crm-2.csv
id,name,country
c-7,Larkfeild Logistics,GB
c-8,Kestrel Analytics,US
c-9,Acorn Tool,GB
spool load samples/crm-2.csv
spool match
Output
source  crm
type    company
read    3 rows from samples/crm-2.csv
loaded  3 new, 0 already held, 0 new versions
next    `spool match` places them in identities
run         5
type        company
examined    3 records
candidates  4 pairs
judgements  4 match, 0 no_match
placed      3 records, 1 identity created
left out    0 records in 0 review items
spool show records
Output
source and key  name                 identity
crm:c-1         Acorn Tools          01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-2         ACORN TOOLS          01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-3         Acorn Tools Ltd      01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
crm:c-4         Larkfield Logistics  01a1ef8e-5a8d-76d4-acb6-2bb802d5ca25
crm:c-5         Halden Group         01a1ef8e-5a8d-76d4-acb6-2bb793e9d0ae
crm:c-6         Halden Group         01a1ef8e-5a8d-76d4-acb6-2bb65a02262a
crm:c-7         Larkfeild Logistics  01a1ef8e-5a8d-76d4-acb6-2bb802d5ca25
crm:c-8         Kestrel Analytics    01a1ef8e-5f06-7397-9a0c-445aaacfd3fe
crm:c-9         Acorn Tool           01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada

"Acorn Tool" and "Larkfeild Logistics" joined the identities that existed, and those kept their IDs. Kestrel Analytics is new and got a new one. Nothing that was placed before moved.

Extract records from text

Rows are one way in. The other is text: an extractor reads a document and says where it names a company, and each place becomes a record. The project has a sample document and a sample extractor.

samples/notes-1.txt
Call with Dana Reyes on 12 November. She has moved to Acorn Tools Ltd and runs
purchasing there. They now ship through Larkfield Logistics Ltd, and she asked
whether we work with Brightwater Foods Ltd, their new supplier.
extractors/companies.yaml
entity_type: company
attribute: name
pattern: '(?:[A-Z][A-Za-z]+ )+(?:Ltd|Inc|LLC|GmbH|plc)\b'

This extractor is a pattern, which Spool runs itself: no model, no key and nothing to install. A run of capitalised words that ends in a legal form is a company, and the text it matched is the record's name.

spool extract samples/notes-1.txt
Output
source     notes
read       1 document from samples/notes-1.txt
loaded     1 new, 0 already held, 0 new versions
extractor  companies
found      3 records in 1 document: 3 new, 0 already held

  company  Acorn Tools Ltd          notes-1.txt[54-69]
  company  Larkfield Logistics Ltd  notes-1.txt[119-142]
  company  Brightwater Foods Ltd    notes-1.txt[179-200]

next       `spool match` places them in identities

Three records came out of the note. Each keeps where it was found: the document and the characters. They are records like the rows, so the same rules match them.

spool match
Output
run         10
type        company
examined    3 records
candidates  6 pairs
judgements  6 match, 0 no_match
placed      3 records, 1 identity created
left out    0 records in 0 review items
spool show records --source notes
Output
source and key              name                     identity
notes:notes-1.txt[54-69]    Acorn Tools Ltd          01a1ef8e-5a8d-76d4-acb6-2bb5ad4d4ada
notes:notes-1.txt[119-142]  Larkfield Logistics Ltd  01a1ef8e-5a8d-76d4-acb6-2bb802d5ca25
notes:notes-1.txt[179-200]  Brightwater Foods Ltd    01a1efb4-93c3-7745-8408-dcbf0c81e6f3

"Acorn Tools Ltd" in the note has the ID that the CRM rows for Acorn Tools have, and Larkfield Logistics has its own. Nothing held Brightwater Foods, so it got a new ID. spool show records <record> prints the sentence a record was found in.

The same over HTTP, in two calls: store the document, then run the extractor.

curl -s -X POST 'http://127.0.0.1:7765/v1/documents?source=notes&key=notes-1.txt' -H 'content-type: text/plain' --data-binary @samples/notes-1.txt
curl -s -X POST http://127.0.0.1:7765/v1/extractions -d '{}'

The same as MCP tool calls:

MCP tool call
{ "name": "load_documents", "arguments": { "source": "notes",
  "documents": [ { "key": "notes-1.txt", "text": "Call with Dana Reyes on 12 November. ..." } ] } }
MCP tool call
{ "name": "run_extraction", "arguments": { "extractor": "companies" } }

A pattern finds only what is written the way it expects: "Acorn Tools" without "Ltd" is missed. The next step up is an extractor that asks a language model. That is a Python or TypeScript file in extractors/, which Spool runs with uv or bun, so one of those has to be installed for it. Extraction writes one.

Connect an agent

The server speaks the Model Context Protocol (MCP) at the mcp address it printed. spool dev asks for no token. For Claude Code:

claude mcp add --transport http spool http://127.0.0.1:7765/mcp

For Codex:

codex mcp add spool --url http://127.0.0.1:7765/mcp

Then ask it, for example: "Load samples/crm-2.csv into Spool, match it, and tell me why c-5 and c-6 are different companies." The tools it has for that are load_rows, run_match, search_records and explain_pair, with load_documents and run_extraction for text. MCP lists every tool and what an agent cannot do.

Look at it in a browser

The studio is at http://127.0.0.1:7765/. Its Identities screen lists the six companies:

The studio's Identities screen, listing six companies with the number of records each has

The studio shows the same records, identities and explanations, and it can merge two identities, split one and undo a change.

Stop

Ctrl-C in the first terminal stops the server. The data stays in .spool/dev.duckdb. To start from nothing, stop the server and delete .spool.

Next

  • Point it at your own rows: edit the columns in sources/crm.yaml and the rules, then spool load your-file.csv --source crm. Project structure lists every file.
  • Write an extractor that asks a model. Extraction
  • What happens when a rule gets better. Matching
  • Merge, split and undo. Identities
  • Read the IDs from your own code. Using the IDs