arcana-os 0.2.0

The OS that gives your agents a soul.

Arcana OS is a multi-agent system where each AI agent is assigned a tarot card archetype that defines its personality, behaviour, and defaults. The card is not cosmetic — it generates the agent's system prompt and sets its temperature. Blend a primary card with modifier cards to tune the mix.

The project ships as two packages — a Python library you build agents with, and a CLI that wraps it for everyday use — plus arcana-os, a meta-package that installs both.

uv tool install arcana-os

arcana init
arcana providers add -p ollama -m hermes-3 -n local
arcana agent create --name researcher --card hermit --model local
arcana run "what are the tradeoffs between RAG and fine-tuning?" --agent researcher --stream

The two packages

arcana-core — the Python library

The real product. Card-configured agents that run through a model gateway.

from arcana import Agent, Card
from arcana.models import ConnectionStore, ModelGateway

async with ModelGateway(ConnectionStore()) as gw:
    agent = Agent(
        name="researcher",
        card=Card.HERMIT,               # IX · The Hermit — Researcher / Deep Analyst
        modifier_cards=[Card.EMPRESS],  # blend in the Empress's warmth
        gateway=gw,
        model="ollama/hermes-3",
    )
    result = await agent.run("summarize recent advances in RAG")

It includes the card engine and all 22 Major Arcana, the model gateway with adapters for Ollama, Anthropic, and OpenAI-compatible providers, agent + session persistence, and a federated memory layer (tiered SQLite / vector stores, an Obsidian-vault folder connector, and a wikilink knowledge graph). See the arcana-core README for the full module map.

arcana-cli — the command line

A thin Typer wrapper around the library: init, status, providers, agent, run, chat, cards, and soul. Create and manage agents, connect models, hold an interactive memory-backed chat session, and run prompts without writing Python. See the arcana-cli README for every command.

The 22 Major Arcana

Installation

The quickest way — no Python or uv required first (the installer bootstraps both):

curl -LsSf https://arcanaos.cloud/install.sh | sh

Already have uv? Install directly:

# As a CLI tool (installs core + CLI)
uv tool install arcana-os

# As a library
uv add arcana-core

Requirements: Python 3.11+ (the curl installer fetches a managed one for you). For local models, Ollama with your preferred model.

Roadmap

Card-configured agents now run with persistent sessions and the federated memory layer wired into the run path — recalling and extracting memory across sessions, in both arcana run and the interactive arcana chat. Still ahead: a tool/MCP gateway and The World, a meta-agent (card XXI) that routes work across agents.

License

Apache License 2.0. Arcana OS is open source and will stay that way; the Apache license also lets us offer a hosted edition in the future.