Skip to content

Types

All Pydantic models are re-exported from arcana.types. Import from there, not from sub-modules, so your code is insulated from internal restructuring.

from arcana.types import Agent, ModelConnection, Session

Agent record

arcana.types.agent.Agent

Bases: BaseModel

An agent definition. Persisted to ~/.arcana/agents/{id}/agent.json.

arcana.types.agent.AgentStatus

Bases: StrEnum

Model connection

arcana.types.model.ModelConnection

Bases: BaseModel

A connection to an LLM. Persisted to ~/.arcana/connections/models.json.

arcana.types.model.ModelProvider

Bases: StrEnum

arcana.types.model.ModelCapabilities

Bases: BaseModel

arcana.types.model.ModelTransport

Bases: StrEnum

Session

arcana.types.session.Session

Bases: BaseModel

A single conversation or task run with an agent.

arcana.types.session.Message

Bases: BaseModel

arcana.types.session.MessageRole

Bases: StrEnum

arcana.types.session.SessionStatus

Bases: StrEnum

Memory

arcana.types.memory.MemoryEntry

Bases: BaseModel

A single memory. Scope determines who can access it. Confidence guards against context poisoning from hallucinated facts.

arcana.types.memory.MemoryEdge

Bases: BaseModel

A directed, typed relation between two memory nodes.

Endpoints are stable node ids (src_id → dst_id); a node may live in any tier, so an id need not correspond to a MemoryEntry row (a folder connector's uuid5 note id is a valid endpoint). relation names the edge type and source its producer; together with the two endpoints they form the edge's identity — one edge per (src_id, dst_id, relation).

arcana.types.memory.MemoryQuery

Bases: BaseModel

arcana.types.memory.MemoryScope

Bases: StrEnum

arcana.types.memory.MemoryType

Bases: StrEnum

arcana.types.memory.MemoryAdapter

Bases: Protocol

Structural interface for any memory backend wired into an Agent.

health_check async 

health_check()

Probe whether the backend is reachable and usable.

Must not raise — return AdapterHealth(healthy=False, ...) on failure. The resilience layer uses this as the half-open recovery probe after a breaker has opened, so it must be cheap (e.g. SELECT 1) and honest.

Source code in packages/arcana-core/arcana/types/memory.py 
481
482
483
484
485
486
487
488
async def health_check(self) -> AdapterHealth:
    """Probe whether the backend is reachable and usable.

    Must not raise — return ``AdapterHealth(healthy=False, ...)`` on failure.
    The resilience layer uses this as the half-open recovery probe after a
    breaker has opened, so it must be cheap (e.g. ``SELECT 1``) and honest.
    """
    ...

arcana.types.memory.AdapterCapabilities

Bases: BaseModel

arcana.types.memory.AdapterHealth

Bases: BaseModel

arcana.types.memory.EmbeddingMeta

Bases: BaseModel

The embedding model a database is pinned to.

Written when the first embedding is stored; one row per database. Locks the database to a model so a later, incompatible embedder cannot silently corrupt similarity scores against existing vectors. Datetimes persist as ISO-8601 TEXT, matching MemoryEntry.

arcana.types.memory.PruneMode

Bases: StrEnum

arcana.types.memory.PrunePolicy

Bases: BaseModel

Selects low-value entries to remove. Pinned entries are never selected.

min_importance and max_entries compose: an entry is a victim if it falls below the importance floor OR sits outside the top max_entries by importance. At least one criterion must be set.

arcana.types.memory.PruneReport

Bases: BaseModel

Outcome of a prune pass, aggregated across tiers at the federation layer.