The citation manager
How do I format, fix, de-duplicate and export my references without Zotero's
servers? Attestation keeps them in its own library store and manages them
locally: attest bib searches, shows, formats (APA, IEEE, Chicago
author-date, Nature, Vancouver), imports, edits, merges and exports them, and
the MCP tool cite.format gives an agent the same formatted text and BibTeX.
Nothing leaves the machine. Uploaded .bib files are only ever read; your
edits live in the store and reach the .bib Attestation generates for you.
What it works on
The library store (attest library sync, or cite.sync) already holds one
row per paper from every .bib in ATTEST_BIB_PATHS, a local Zotero
database (read-only, optional), feed items with a DOI or arXiv id, and saved
research papers. See Claims and citations.
The citation manager adds four things to that store (migration 014):
- the BibTeX entry type, volume and pages, and every other field a
.bibentry carried (publisher,number,note, a custom field...) inextra, so an imported entry renders back with them. Afilefield is dropped: it is a path on the machine that exported the.bib; - notes and an edit log (
reference_edits): every field, tag and note change, and every merge, with the old and new value; - aliases: the names a merged-away row answered to;
- a formatted-citation cache, so a style is rendered once per row.
.bib files are read and written with bibtexparser v2 (MIT). It is the
one parser: the cite.* lookup path, the library sync and attest bib import
all read through it, so year = 2022 (unbraced), @string macros and quoted
values parse everywhere. A truncated entry is reported and skipped; the
entries around it still load.
Commands
attest bib search "equivariant potentials" # semantic when embedded, keyword otherwise
attest bib show batzner2022 # every field, sources, tags, note, BibTeX, citation
attest bib format batzner2022 vaswani2017 --style ieee
attest bib format batzner2022 --bibtex
attest bib import ~/Downloads/thesis.bib # reads the file, never writes it
attest bib import --zotero # ~/Zotero/zotero.sqlite, read-only
attest bib edit vaswani2017 --set pages=5998--6008 --set publisher="Curran" \
--note "the transformer paper" --tag attention
attest bib merge # list duplicate pairs; changes nothing
attest bib merge 10.5555/nequip nequip2021 # keep the first, fold the second into it
attest bib export --out refs.bib # the whole library as BibTeX (new files only)
attest bib export batzner2022 --style apa # formatted text to stdout
A key can be a citation key, a DOI, an arXiv id, a library identity, a key
from a second .bib that holds the same paper, the key a persona's generated
.bib gave it, or a key a merge folded away.
Formatting
citeproc-py (BSD) renders five CSL styles shipped in
src/attestation/csl_styles/ (CC BY-SA 3.0, copied unmodified from the
citation-style-language/styles repository; see its LICENSE.md):
| id | style |
|---|---|
apa |
APA 7th edition (the default) |
ieee |
IEEE |
chicago-author-date |
Chicago Manual of Style 18th edition, author-date |
nature |
Nature |
vancouver |
NLM/Vancouver citation-sequence |
ATTEST_CITATION_STYLE sets the default; a name outside the table is refused,
never replaced by another style. The en-US locale ships inside citeproc-py,
so formatting needs no network.
A reference is converted to CSL-JSON (article, inproceedings, book, preprint,
misc and the other BibTeX types; authors, year, venue, volume, pages, issue,
publisher, DOI, URL), with LaTeX folded to text (Sch{\"u}tt is Schütt). An
arXiv paper with no journal is a preprint: publisher arXiv, its id as the
number, the abs page as URL.
Each reference is rendered alone. A whole-library bibliography would
disambiguate across entries (APA's 2022a/2022b), so one paper's text would
change when an unrelated one was added, and that disambiguation is quadratic
(81 s for 5,000 APA entries, against ~20 ms each alone). A numeric style's
label ([1], 1.) is dropped for the same reason. Output is plain text and
deterministic.
Editing
attest bib edit KEY changes the store row (fields with --set, the note with
--note, tags with --tag/--untag) in one transaction, logs it, and saves
the reference to the owner's bibliography, so
<ATTEST_BIB_OUT>/<owner>.bib carries the edited entry under its stable key.
The owner is ATTEST_DESK_USER, else owner, created if absent. With
ATTEST_BIB_OUT unset the entry is recorded and written once it is set.
- Any BibTeX field can be set;
title,authors(A and B),year,venue,doi,arxiv,url,abstract,type,volumeandpagesare columns, the rest go toextra. An empty value clears a field; a title cannot be cleared. - Keys and identities are not editable: a key, once given, is what every
\citeuses. - A DOI or arXiv id another row already holds is refused with "merge the two instead".
- A sync never overwrites an edited field (merging fills only empty fields), but a field you cleared is filled again by the next sync of a source that has it.
Duplicates and merging
attest bib merge with no keys lists pairs that are one paper: the same DOI,
arXiv id, or normalised title and year in two rows, or an id a sync refused
because another row already held it (the store's own record of a duplicate).
The suggested row to keep has a DOI, else an arXiv id, else is the older row.
attest bib merge KEEP DROP (or --all for every listed pair) folds DROP into
KEEP in one transaction:
- KEEP fills its empty fields from DROP; nothing on KEEP is overwritten;
- DROP's sources, tags, citation edges, full text, note, edit history and each
persona's bibliography entry move to KEEP (an entry keeps its cite key, so a
\citeof it still builds); - every name DROP answered to (identity, DOI and arXiv forms,
.biband Zotero keys, cite keys) becomes an alias of KEEP, so a lookup, a\citekey check and the next sync of the file DROP came from all land on KEEP; - DROP is deleted from the store only. No
.bibfile is touched.
Importing
attest bib import FILE.bib validates the file (exists, at most 50 MB, at
least one readable entry) and reads it into the store as bibtex:<file name>,
the same source name a sync of that file uses. It reports the count added,
merged and unchanged, the entries it could not read (with line numbers), the
untitled ones, keys defined twice in the file (the first is kept, as BibTeX
does), and key clashes: keys that already named a different paper in the
store. --zotero [PATH] reads a local zotero.sqlite the same way.
For an agent: cite.format
cite.format(keys, style) returns, for up to 5 keys, the formatted text, the
cite_key and the bibtex of each, plus missing for keys the library does
not hold. It is served wherever cite.* is (the default surface and
knowledge). cite.search rows carry arxiv beside doi, so a page can link
both. Edits stay a CLI action (attest bib edit), which an agent runs on the
owner's word.
In library.json
attest library dashboard adds, per reference, bibtex, formatted
({style id: text} for the default style), a truncated abstract, and
cited_by (where the workspace's drafts cite it), plus top-level
citation_styles and default_style. See
The library dashboard for the
shapes and the size budget. cited_by scans every .tex and .md under
ATTEST_WORKSPACE, else <HERMES_HOME's root>/workspace (the folder the
host's Files page shows) for \cite-family keys and claims' cite= keys.
When it goes wrong
unknown citation style:ATTEST_CITATION_STYLEor--styleis not one of the five ids above.no library reference matches: runattest library sync(orattest bib import) first;attest bib searchfinds the key.... already names ...: merge the two instead: the DOI or arXiv id you set belongs to another row.attest bib merge KEEP DROP.- The edited entry is not in my
.bib:ATTEST_BIB_OUTis unset; the edit is recorded and the file appears once it is set (attest library bib). repeatedinattest claims --citations: two.bibfiles the paper loads define the same key -- usually an uploaded file and the generated owner.bibafter a save or an edit. Cite from one of them.