folder_notes, a kind that collects the .txt files of a folder, one Record per file.
Prerequisites
- Go 1.26 or later, a
quivrcheckout in$QUIVR_REPO, and thequivrcommand on yourPATH(Build your first plugin shows how). - Read How plugins work for what Quivr keeps and what the plugin decides.
How a run works
On each instance’s schedule, the Quivr worker callsfetch with the instance’s configuration, its decrypted credential and the checkpoint the plugin returned last (null on the first run). The plugin answers a page of items and a new checkpoint. Quivr stores the items through the normal ingestion path and only then saves the checkpoint, so a crash never loses an item. With more: true Quivr asks for the next page at once, up to 10 pages per run.
The plugin keeps no state. Anything it must remember between runs, such as a cursor or the revisions it already returned, goes in the checkpoint, up to 64 KiB.
Common document metadata
Your connector can emit the reservedquivr.metadata extension with
schema_version: "1". Fill the fields you know and omit unknown values.
Do not declare ownership of this namespace in your plugin manifest.
The engine validates its shared schema; your plugin still owns its other
extension namespaces. Metadata filters
lists the fields and explains how clients query them across sources.
Steps
1
Create the module
The Go SDK is not published as a separate module yet, so point Go at your checkout:
2
Declare the kind
Each kind declares the JSON Schema of its instance configuration, and of its credential when the source needs one. Quivr validates both when an instance is created, and shows them to clients through
GET /v0/connector-kinds.quivr-plugin.yaml
3
Implement fetch
The checkpoint maps each file name to the revision already returned, so a run returns only new or changed files. Each item has a stable The error type tells Quivr what to show operators in the instance’s health:
RecordKey; a new Revision for the same key becomes a correction, a new Version of the same Record.main.go
A kind with a credential receives it decrypted in
req.Credential. The SDK redacts it from logs and error messages, and the Contract Runner fails a plugin that echoes it.4
Add a fixture
A connector fixture names the kind, the configuration and what each page should return:
fixtures/notes.json
5
Certify it
Check it worked
Pin the plugin in your deployment, then look for the new kind:folder_notes is listed next to the other kinds. Create an instance as for any kind, with "kind": "folder_notes" and "config": {"path": "/srv/notes"}: see Collect from a source.
To add the plugin to a deployment that is already running, register it with its fixtures/ folder instead of pinning it: Quivr runs the same checks, and you activate it without a restart. See Upgrade or switch a plugin.
Receive data through a Quivr key
Write a push source to declare aquivr_key route and implement its handler. Operate the instance for admission, retries and audit.
Receive data through an instance token
Write a push source to declare aninstance_token route. Manage tokens for issuance, rotation and revocation.
Go further
A kind can also store binary attachments next to an item: declarecontributions.connector.attachments and implement OpenAttachment, and Quivr asks for each file’s size and checksum, then gives the plugin a one-time upload URL. A kind with modes: [pull, push] also receives the webhooks a source sends to Quivr, through receive; the X list connector works this way. The plugin protocol lists every field of fetch and its answer, and the first-party plugins/rss is a complete connector built on this SDK.