Concepts

Covenant is organized around a fixed vocabulary. Intents, agents, capabilities, memory records, audit events, and settlement receipts are the primary types in the data model; every higher-level behavior in the system is defined in terms of these.

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.

Intents are submitted over the local socket, the HTTP gateway, or the CLI. The daemon routes each intent by keyword overlap against the capability cards of registered agents; an intent that matches no agent receives 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. Persists until purged via the memory garbage-collection primitive.
  • 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 secondary key system. Refer to Identity and keys and Security model for key-management practices.

Audit

Every state-changing operation emits an AuditEvent: intent dispatch, capability check, capability grant, capability revocation, ignored intent. Events are appended to $COVENANT_HOME/audit/events.jsonl under a deterministic schema. The audit log is the system of record; 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, a memory record id when the resource is memory, and an optional on-chain signature. Receipts accumulate in $COVENANT_HOME/receipts/working.jsonl. Chain fields remain empty unless a future settlement integration records them.

See Settlement for the current local receipt model and the planned on-chain boundary.

End-to-end intent flow

A successful intent dispatch exercises every primitive. The daemon receives the intent, validates the issuer's capabilities, selects an agent through the router, executes the agent under a wall-clock budget, captures the result, persists a memory record, emits a settlement receipt, and writes the corresponding audit events. Operational state is fully reconstructible from the audit log.