Concepts

Covenant is built around a small vocabulary. Once you know what an intent, an agent, a capability, and a settlement receipt are, the rest of the system follows.

Intent

An intent is a natural-language request issued by a user (or another agent) and routed to whichever agent can fulfil it. Every intent has a stable UUID, an issuer (an AgentId), an issuing timestamp, a priority, and an optional parent. Intents do not carry credentials — the issuer's capabilities are determined by their identity.

Submit an intent over the local socket, the HTTP gateway, or the CLI. The daemon routes it via keyword overlap against the capability cards of registered agents; an unmatched intent falls through to a deterministic echo response.

Agent

An agent is anything Covenant can dispatch an intent to. Agents are registered via an agent.toml manifest under $COVENANT_HOME/agents/. The manifest declares:

  • a stable agent.id in the form name@host,
  • a runtime (currently rust-bin, python3, or node),
  • an entry path to the binary or script,
  • the capabilities the agent needs to operate,
  • per-task resources (CPU budget, memory, disk, network policy),
  • optional settlement hints (per-hour credit budget, priority).

See Agent manifest for the full schema and validation rules.

Runtime contract

At dispatch the runtime spawns the agent binary, sends one JSON line containing the Intent on stdin, reads one JSON line containing the AgentResult on stdout, and kills the process if it exceeds resources.cpu_ms_per_task. Stderr is streamed to the daemon's tracing log.

Capability

A capability is a typed permission slip. It names an action (a dotted string from a reserved namespace such as tool.web_search, memory.write, tool.call.<name>) and optionally a scope constraint expressed as JSON.

A signed capability is a capability plus an ed25519 signature by the granter over a deterministic byte encoding of the fields. Signed capabilities are stored in an append-only JSONL log under $COVENANT_HOME/capabilities/granted.jsonl; revocations land alongside them in capabilities/revoked.jsonl. The active set at any moment is the granted set with revocations subtracted.

At dispatch, the daemon enforces capabilities hard — a request whose required actions are not all present in the active set is rejected, and the rejection itself is audited.

The full token shape, the deterministic encoding, and the verification path are documented in Capability tokens.

Memory

Covenant's memory is a single store partitioned into three tiers:

  • working — short-lived per-task scratch. Cleared with intent completion in the steady state; today persists until GC'd explicitly.
  • episodic — task-grained records that survive across runs.
  • long-term — durable, intentionally retained context; the slowest tier and the one most likely to influence future routing.

Records are written as MemoryRecord values: a UUID, a tier, an owner AgentId, the result text, an embedding vector, free-form JSON metadata, a creation timestamp, and an optional parent. Persistent backing is SQLite at $COVENANT_HOME/memory.db; an in-memory backend is available for tests.

Searches are cosine-similarity over the stored embedding vectors, scoped to a tier or unioned across all tiers. See Memory tiers for details.

Identity

Every Covenant install owns a single ed25519 keypair persisted at $COVENANT_HOME/identity/local.key (raw 32-byte seed, mode 0600). The same key:

  • signs capability grants,
  • signs Solana settlement transactions,
  • fronts the daemon's issuer field on audit events and memory records.

There is no second key system. Operator key hygiene matters accordingly — see Identity and keys and Security model.

Audit

Every state-changing surface in Covenant emits an AuditEvent: intent dispatch, capability check, capability grant, capability revoke, ignored intent. Events are appended to $COVENANT_HOME/audit/events.jsonl with a deterministic schema. The audit log is the system's ground truth — operators read it; covenant verify cross-checks it against the other state files for drift.

See Audit log for the event schema.

Comms

The daemon exposes three transports today:

  • Unix socket at $COVENANT_HOME/sock — the canonical, length-prefixed JSON IPC. The CLI uses this transport.
  • HTTP gateway at 127.0.0.1:8421 — for browser-facing UIs and third-party tooling. Same surface, JSON over HTTP. See HTTP API.
  • MCP and A2A adapters for protocol-grade tool and agent-to-agent communication. See MCP integration and Agent-to-agent.

Settlement

Covenant accounts for resource usage as it happens. Every memory write, every tool call, and (eventually) every external compute or LLM token spent produces a settlement receipt — a UUID, a payer, a resource kind, a credits-consumed integer, a timestamp, and an optional on-chain signature. Receipts accumulate in $COVENANT_HOME/receipts/working.jsonl until they are batched and flushed to the on-chain settlement program; at that point onchain_sig is populated.

See Settlement for the credit model and the buyback shape.

Compositor

The compositor is whatever surface the operator uses to drive Covenant — CLI today, web UI alongside, TUI on the way, and an optional Wayland compositor in the longer term. Compositors talk to the daemon through the same transports listed above; the daemon does not assume any specific UI.

Putting it together

A successful intent flow touches every primitive. A user submits an intent. The daemon checks the issuer's capabilities, picks an agent via the router, runs it through the runtime with a wall-clock budget, captures the result, writes a memory record, emits a settlement receipt, and lands one or more audit events describing what happened. The operator can replay the day from the audit log alone.