Filiation

A citation graph you build and keep on your own machine.
Give it one paper. It follows the references, maps what cites what, and shows you where an idea came from.

Quick start · Commands · AI assistants · How it works · Coverage · Roadmap · Docs

In textual criticism, filiation is the work of establishing which manuscript was copied from which, reconstructing the lines of descent between surviving texts. This tool does the same for research papers. Start from one paper, follow its citations back, and see the literature it grew out of.

Most citation-map tools are session-shaped: you run a query, get a picture, and close the tab. Filiation builds your map instead. It keeps growing as you add papers, lives in one file you own, and can be exported to any tool you like.

Highlights

• 🧭 Best-first expansion under a budget. The papers your library cites most are fetched first, so 500 works cover the literature that matters rather than whatever happened to be nearby. Stop at any time; the next run carries on where this one left off.
• 🌳 Lineage, not just links. fil path finds how one paper descends from another through its references. Citation cycles are real, and the search is safe on them.
• 🧹 Duplicates handled carefully. The same paper under two IDs, or a merged record, becomes one node. Papers that only share a title are reported for you to judge and never merged automatically: a book review carries the title of the book it reviews.
• 📊 Honest about the data. Every run reports how many works came with a reference list, and why that varies by field.
• 📦 One binary, nothing to install. A single file for Windows, macOS or Linux. No runtime, no database server, no Docker, no account, no API key.
• 🔒 Local and legal. Your library never leaves your machine. Reference data comes from OpenAlex, which is open, and full text will only ever come from open-access sources.

See it

_{Real output: one run of fil expand from The state of OA (2018), laid out from fil export graphml.
The early open-access literature (blue) sits on the left; the recent work around the seed (pink) sits on the right.}

Quick start

Download

Get the archive for your system from Releases, unpack it, and run fil. There is nothing else to install.

Or build from source

git clone https://github.com/codevector-2003/filiation
cd filiation
go build ./cmd/fil        # Go 1.26 or later. Pure Go, no C compiler needed.

First steps

fil add 10.7717/peerj.4375                  # a DOI, arXiv ID, PMID, OpenAlex ID, link, or title
fil expand                                  # follow the references, most-cited first
fil path 10.7717/peerj.4375 W4300313809     # how one paper descends from another
fil export graphml -o library.graphml       # open it in Gephi

On the first run fil asks where to keep your library: a folder you can see, Documents/Filiation/My Library unless you choose another. Papers go in its papers/ folder, one folder per paper with a readable name such as Piwowar-2018-The-state-of-OA--F7K2M9QXA. Move, rename and group those folders however you like; fil finds them again, and each folder you make becomes a collection. fil where shows where everything is.

Commands

Every command has --help. Exit codes are distinct per outcome (not found, ambiguous, network, and so on), so scripts can branch on them.

Use it from an AI assistant

fil mcp lets an assistant such as Claude, Cursor or any other MCP client use your library directly. It can add papers, grow the graph, and answer "how does this paper descend from that one?" against a map you own.

Claude Code

claude mcp add filiation -- fil mcp

Claude Desktop, Cursor and most other clients: add this to the client's MCP settings file.

{
  "mcpServers": {
    "filiation": { "command": "fil", "args": ["mcp"] }
  }
}

Use the full path to fil if it isn't on your PATH. Set-up for Cursor, VS Code and others is in the MCP guide. The assistant gets five tools:

Every paper the assistant sees carries its IDs — fil's own, which never changes, and OpenAlex's — and its open-access status. Papers known only by ID are marked as such, so the assistant can't talk about a paper as if it had read it.

📘 Full MCP guide: set-up for Claude Desktop, Claude Code, Cursor and VS Code; every tool's arguments and results; limits; troubleshooting.

How it works

• References come from OpenAlex, already resolved. fil never parses reference lists out of PDFs, a process whose errors compound across a graph.
• Edges before nodes. A paper's references become records the moment it's fetched. Deduplication is then a primary-key match, and "which unfetched paper matters most?" becomes a cheap count of how often your library cites it.
• Every batch is one transaction. Interrupting a run loses at most the batch in flight, and the library is never half-written.
• Polite to OpenAlex. Requests are batched 100 works at a time, rate-limited below the measured limit, retried with backoff, and cached.

The design, and the measurements behind it, are written up in docs/.

Know this before you start

The graph is only as deep as the reference data behind it, and that depends on your field. In the validation run (20 seed papers across 5 fields, 500 works each), the share of fetched works that came with a reference list was:

Where books and chapters dominate, publishers rarely deposit reference lists, and a random humanities sample fares worse still (spike 4). fil tells you when a work has no references. That's a gap in the data, not a fault in the tool.

Roadmap

Documentation

• docs/MCP.md: using fil from an AI assistant: set-up, tools, limits, troubleshooting
• docs/STATUS.md: where the project is, what's done, what's next
• docs/ARCHITECTURE.md: whole-system design
• docs/DECISIONS.md: decisions made, and options rejected, with reasons
• docs/SPIKES.md and docs/VALIDATION.md: measured answers from live data
• CLAUDE.md: working context, hard rules and build order

Contributing

Issues and pull requests are welcome. Before a larger change, read docs/STATUS.md and the hard rules in CLAUDE.md. A few are non-negotiable:

• no cgo;
• no paywalled full text, ever;
• no reference parsing;
• no network access in unit tests.

go test ./... runs the whole suite against recorded OpenAlex responses.

Acknowledgements

Reference data comes from OpenAlex, an open index of the world's research. SQLite runs in pure Go through ncruces/go-sqlite3. PDF text comes from PDFium, compiled to WebAssembly by klippa-app/go-pdfium and run by wazero. The command line is built with spf13/cobra.

Licence

Apache License 2.0. Use it, change it, and build on it, including commercially; keep the notices in NOTICE. The licence includes an explicit patent grant from contributors.