arka-deck concepts

This document explains product terms in logical order: from the most concrete (your machine, your files) to the most abstract (multi-agent orchestration).

Project

A project is a local folder on your machine. You point arka-deck at it, and arka-deck creates a .arka-deck/ subfolder inside it to store its working data (memory, sessions, logs, configuration).

Your files don’t move. arka-deck only reads what it needs.

Workspace

A workspace is a logical container that groups several projects. It does not exist on disk — it’s an organization label internal to arka-deck.

Example: a workspace “Client A” can contain the projects “audit-2026” and “api-rewrite”.

Provider

A provider is the LLM engine you configure to run the agents. arka-deck supports several providers:

Provider	Status	Notes
Claude Code (Anthropic)	beta	Official `@anthropic-ai/claude-agent-sdk` SDK
Google Gemini	beta	Generative Language API
Codex CLI (OpenAI)	beta	Codex CLI runtime

Each provider keeps its native capabilities. arka-deck does not erase specifics — it adds an orchestration layer on top.

Profile (HYOS)

A profile is a specialized agent: a set of rules, capabilities, flowmaps and atoms that define how the agent should work in a given domain.

The public Cortex offers several dozen ready-to-use profiles (architect, lawyer, QA, data scientist, etc.). You install a profile on a project to recruit that agent.

A profile is not a hand-written system prompt. It’s a versioned entity, fetched from the Cortex and injected into the context at the right moment.

Atom

An atom is an atomic unit of knowledge: a rule, a pattern, a constraint or an isolated capability, identified by a stable identifier.

Atoms compose profiles and blocs.

Bloc

A bloc is an executable rule or capability — a structured instruction that the agent can receive to frame its behavior: method, expertise, allowed tool, scope, constraint.

Blocs are organized into several types (skill, expertise, tool, methode, scope).

The cortex-actions addon lets you select a bloc before a chat turn to inject it into the agent’s context.

Flowmap

A flowmap is an agentic execution sequence: a chain of steps, decisions and transitions that the agent follows to handle a structured mission.

Flowmaps come from the Cortex. They give the agent an explicit progression frame rather than free improvisation.

Session

A session is a chat exchange with an agent on a project. It contains the complete timeline: messages, thinking blocks, tool calls, results. Everything stays local.

A session has a lifecycle: started → ended (normal), or aborted, or error.

Turn

A turn is a single exchange within a session: a user message followed by the agent’s response. The events chat.turn.started and chat.turn.ended bound each turn.

Memory

Memory is an active per-project persistence system. After a session, important elements (decisions, learnings, methods) can be captured as memory entries and reinjected into subsequent sessions.

Entries have an importance level from L1 (short note) to L5 (elaborated synthesis). Stored locally in <project>/.arka-deck/memory/.

Memory is not a chat history. It’s a semantic extraction of what is worth reusing.

Addon

An addon is a self-contained module that extends arka-deck’s capabilities. It subscribes to the event bus and can augment a turn’s context, write logs, or expose its own functionality.

Pre-installed (first-party) addons:

Addon	Role	Status
`cortex-actions`	Cortex artifact panel in chat	beta
`cortex-lite`	Local Cortex runtime sidecar	stable
`memory-local`	Per-project agentic memory	beta
`gouvernance-lite`	Local policies, snippets and followup	beta
`mission-guardian`	Mission state, leader and QA gates, evidence	beta
`squad-leader`	Squad composition and coordination	beta
`squad-orchestration`	Multi-agent LangGraph orchestration	beta
`notion-connect`	Notion connector	beta

The addon contract is stabilized to eventually allow external extensions. For now, all addons are wired explicitly in arka-deck.

Worker

A worker is a single-shot headless LLM process. It receives JSON as input, produces JSON as output, and exits. No chat, no multi-turn.

Workers are declared in a manifest.json and tied to a parent addon. Examples:

squad-creator — proposes a squad composition for a mission
cortex-favorites-suggester — proposes Cortex artifacts relevant to the project
memory-note-writer — drafts a memory note from a session
governance-policy-designer — designs a local governance policy

Squad

A squad is a team of specialized agents recruited to work together on a mission. Each agent has its profile and role. A leader coordinates.

The squad-leader addon manages squad composition and activation on a project. The squad-orchestration addon manages multi-agent mission execution with a LangGraph state graph.

Mission

A mission is a unit of work entrusted to a squad. It includes a goal, phases, expected evidence and a QA verdict.

The mission-guardian addon tracks the mission state (phases, gates crossed, evidence captured) and prevents an agent from moving to the next step until the gates are validated.

Governance

Governance is the set of rules, permissions and traces that frame the agents’ work. It can include allowed modes, permitted capabilities, control blocs and an action journal.

The gouvernance-lite addon implements local Cortex-compatible policies; snippets and followup are consultable per project.

Cortex

The Cortex is a structured knowledge repository. It stores profiles, atoms, blocs, flowmaps and documents as a graph.

Public Cortex (public.arkalabs.app) — read-only, no authentication. Provides the starter catalogue. Your projects are never sent there.
Dedicated Cortex — private instance for a team or organization. Allows storing internal profiles, decisions, traces and operational memory (upcoming offer).

ArkaDoc

An ArkaDoc is a business document attached to a project: report, brief, spec, task, decision, QA verdict. It persists on disk under <project>/.arka-deck/arkadoc/ and is consultable from the UI (list, timeline, kanban, tree).