rekor

Rekor — System of Record for AI Agents

You have access to the rekor CLI, a system of record for storing, querying, and managing structured data. Use it as your persistent data layer for any task that involves creating, reading, updating, or deleting structured records.

Setup

All commands require --workspace (or set REKOR_WORKSPACE env var). Start by listing or creating a workspace:

rekor workspaces list

rekor workspaces create my-workspace --name "My Workspace"

Core Concepts

  • Collection: A schema (JSON Schema) that defines a record type. No migrations — create at runtime.
  • Record: A JSON document conforming to a collection's schema.
  • Relationship: A typed, directed link between two records with optional metadata.

Quick Start

1. Create a collection

rekor collections upsert invoices --workspace my-ws \

  --name "Invoices" \


  --schema '{"type":"object","properties":{"customer":{"type":"string"},"amount":{"type":"number"},"status":{"type":"string","enum":["draft","issued","paid"]}},"required":["customer","amount"]}'

2. Create a record

rekor records upsert invoices --workspace my-ws \

  --data '{"customer":"Acme Corp","amount":5000,"status":"draft"}'

With external ID for idempotent upsert:

rekor records upsert invoices --workspace my-ws \

  --data '{"customer":"Acme Corp","amount":5000}' \


  --external-id inv_123 --external-source billing

3. Query records

rekor query invoices --workspace my-ws \

  --filter '{"field":"data.status","op":"eq","value":"draft"}' \


  --sort '{"field":"data.amount","order":"desc"}' \


  --limit 10

4. Link records

rekor relationships upsert --workspace my-ws \

  --source invoices/rec_abc --target customers/rec_xyz \


  --type belongs_to

5. Traverse relationships

rekor query-relationships invoices rec_abc --workspace my-ws \

  --type belongs_to --direction outgoing

---

Full Command Reference

Workspaces

rekor workspaces list

rekor workspaces get <id>


rekor workspaces create <id> --name <name> [--description <desc>]


rekor workspaces delete <id>

Collections

rekor collections list --workspace <ws>

rekor collections get <id> --workspace <ws>


rekor collections upsert <id> --workspace <ws> --name <name> --schema <json|@file>


rekor collections delete <id> --workspace <ws>

Records

rekor records upsert <collection> --workspace <ws> --data <json|@file> [--id <uuid>] [--external-id <id>] [--external-source <src>]

rekor records get <collection> <id> --workspace <ws>


rekor records delete <collection> <id> --workspace <ws>

Query

rekor query <collection> --workspace <ws> [--filter <json>] [--sort <json>] [--limit <n>] [--offset <n>] [--fields <f1,f2>]
Filter operators: eq, neq, gt, gte, lt, lte, in, not_in, like, ilike, is_null, is_not_null, has Compound filters: 
{"and": [

  {"field": "data.status", "op": "eq", "value": "issued"},


  {"field": "data.amount", "op": "gt", "value": 5000}


]}

Aggregate

Run analytics queries — count, sum, avg, min, max — with optional grouping. Results come back in a single call instead of fetching raw records.

rekor query <collection> --workspace <ws> --aggregate \

  --aggregations '[{"fn":"sum","field":"data.amount","alias":"total"},{"fn":"count","alias":"count"}]' \


  --group-by data.status \


  --filter '{"field":"data.year","op":"eq","value":"2026"}' \


  --sort '[{"field":"total","direction":"desc"}]'

Aggregation functions: count (no field required), sum, avg, min, max (field required). Each needs an alias to name the output column. --group-by: Comma-separated fields to group by (e.g. data.status,data.region). Without it, aggregates over the entire result set.

Relationships

rekor relationships upsert --workspace <ws> --source <col/id> --target <col/id> --type <type> [--id <id>] [--data <json>]

rekor relationships get <id> --workspace <ws>


rekor relationships delete <id> --workspace <ws>


rekor query-relationships <collection> <id> --workspace <ws> [--type <type>] [--direction outgoing|incoming|both]

Hooks (inbound webhooks)

External systems push data into Rekor via hooks. Each hook provides a unique ingest URL.

rekor hooks create --workspace <ws> --name <name> --collection <collection>

rekor hooks list --workspace <ws>


rekor hooks get <id> --workspace <ws>


rekor hooks delete <id> --workspace <ws>

Hooks can only be created/deleted in preview workspaces. Promote to production when ready.

Triggers (outbound webhooks)

Triggers fire automatically when records change, notifying external systems via HTTP POST.

rekor triggers create --workspace <ws> --name <name> --collection <collection> --url <url> --events '["create","update","delete"]'

rekor triggers list --workspace <ws>


rekor triggers get <id> --workspace <ws>


rekor triggers delete <id> --workspace <ws>

Triggers are HMAC-signed (X-Rekor-Signature) and fire asynchronously. By default, writes from hooks don't re-fire triggers (skip_hook_writes: true). Triggers can only be created/deleted in preview workspaces.

Batch (atomic)

Execute up to 100 operations atomically — all succeed or all fail:

rekor batch --workspace <ws> --operations '[

  {"type":"upsert_record","collection":"invoices","data":{"customer":"A","amount":100}},


  {"type":"upsert_record","collection":"invoices","data":{"customer":"B","amount":200}},


  {"type":"upsert_relationship","rel_type":"related_to","source_collection":"invoices","source_id":"id1","target_collection":"invoices","target_id":"id2"}


]'

Operation types: upsert_record, delete_record, upsert_relationship, delete_relationship, upsert_collection, delete_collection

Provider Adapters

Import tool definitions from any LLM provider as collections, or export collections as tool definitions.

Import (creates collections from tool definitions): 
# OpenAI

rekor providers import openai --workspace <ws> --tools '[{"type":"function","function":{"name":"create_invoice","parameters":{"type":"object","properties":{"customer":{"type":"string"},"amount":{"type":"number"}},"required":["customer"]}}}]'



Anthropic


rekor providers import anthropic --workspace <ws> --tools '[{"name":"create_invoice","input_schema":{"type":"object","properties":{"customer":{"type":"string"}}}}]'



MCP


rekor providers import mcp --workspace <ws> --tools '[{"name":"create_invoice","inputSchema":{"type":"object","properties":{"customer":{"type":"string"}}}}]'



From file


rekor providers import openai --workspace <ws> --tools @tools.json

Export (get collections as tool definitions): 
rekor providers export openai --workspace <ws>

rekor providers export anthropic --workspace <ws> --collections invoices,customers


rekor providers export mcp --workspace <ws> --output tools.json

Import tool call (create a record from provider-native format): 
# OpenAI tool call → record

rekor providers import-call openai invoices --workspace <ws> \


  --data '{"arguments":{"customer":"Acme","amount":5000}}' \


  --external-id call_abc123 --external-source openai



Anthropic tool call → record


rekor providers import-call anthropic invoices --workspace <ws> \


  --data '{"input":{"customer":"Acme","amount":5000}}'

Supported providers: openai, anthropic, google, mcp

---

Output Format

Add --output json for machine-readable JSON output (default is table).

rekor records get invoices rec_abc --workspace my-ws --output json

Data Input

Any --data, --schema, --tools, or --operations flag accepts:

  • Inline JSON: '{"key":"value"}'
  • File reference: @path/to/file.json

Environments

Workspaces are either production or preview. As an agent, you can:

  • Read from any workspace (production or preview)
  • Write records and relationships to any workspace
  • Modify schemas (collections, triggers, hooks) only in preview workspaces

To modify schemas, create a preview workspace first:

rekor workspaces create-preview my-workspace --name "add-invoices"

Then work in the preview workspace:

rekor collections upsert invoices --workspace my-workspace--add-invoices \

  --schema '{"type":"object","properties":{"amount":{"type":"number"}}}'

When you're done, ask a human operator to promote your changes:

# Human runs: rekor workspaces promote my-workspace --from my-workspace--add-invoices
Promotion is a human-only operation. You cannot promote directly. Always work in preview for schema changes.

Best Practices

  • Use external IDs for idempotent upserts — retry-safe, no duplicates.
  • One workspace per context — keeps data isolated (per test run, per agent, per environment).
  • Preview for schema changes — modify collections, triggers, hooks in a preview workspace. Ask a human to promote.
  • Batch for atomicity — when multiple writes must succeed or fail together.
  • Relationships over nested data — link records instead of embedding. Enables traversal and flexible queries.
  • Schema first — define the collection schema before writing records. Validation catches bad data early.