Key terminology.

Core concepts

Agent

The running OpenCAS process. It holds a persistent identity, memory, and autonomous background activity. Unlike a stateless chatbot, the agent continues operating between conversations: daydreaming, consolidating memory, and executing queued work.

Bootstrap / BootstrapContext

The startup sequence that initializes every subsystem in order and assembles a BootstrapContext object containing all wired managers. Nothing runs until bootstrap completes. The ready readiness state is emitted at the end of bootstrap.

Operator

The human (or system) that owns and configures the agent. The operator accesses the agent through the dashboard, API, or CLI. In single-user deployments the operator and the conversational user are typically the same person.

State directory

The local directory where all persistent state is stored. Defaults to ./.opencas. Contains SQLite databases, telemetry JSONL files, provider material, and identity snapshots. Moving or backing up this directory is how you migrate an agent between machines.

Provider material

Credentials and routing configuration for external model providers, managed by open_llm_auth. Stored under state_dir/provider_material/ as a config.json and a .env. The TUI bootstrap wizard copies these from an existing open_llm_auth installation.

Readiness state

A state machine (booting → ready / degraded) that tracks whether the agent is fully initialized. Exposed at /readiness with the current state, entry timestamp, and transition history.

Memory

Episode

A single turn or event stored in memory. Episodes carry content, a source tag, timestamp, embedding, and optional tags. They are the atomic unit of memory and the primary input to retrieval.

Distilled memory

A higher-level memory object created by consolidating related episodes into a durable, semantically stable entry. Distilled memories have their own embeddings and edge links and survive compaction.

Memory edge

A weighted directed link between two memory objects. Edges are built by the consolidation engine and decayed over time. High-confidence edges surface related memories during retrieval without requiring a direct text match.

Consolidation

The periodic background process that reweights memory edges, promotes high-signal episodes to distilled memories, rebuilds autobiographical continuity, and prunes weak links. Managed by NightlyConsolidationEngine.

Compaction

Reducing the active context window by summarizing older conversation turns into a synthetic system message. Prevents unbounded context growth while preserving continuity. Managed by ConversationCompactor.

Retrieval fusion

Combining multiple retrieval signals — semantic vector similarity, keyword match, recency, graph edges, salience, emotional resonance, temporal echo, and reliability — into a single ranked result list using Reciprocal Rank Fusion (RRF). This is how the agent selects relevant memories for each conversation turn.

Embedding

A dense vector representation of a piece of text, used for semantic similarity search. OpenCAS uses google/gemini-embedding-2-preview via open_llm_auth by default. Embeddings are cached to SQLite and never recomputed for identical source text.

Embedding backfill

A startup background task that computes embeddings for any memory records that were stored without one, for example during offline operation or before the embedding model was configured.

Identity

Self-model

The agent's structured representation of itself: name, persona, values, traits, goals, narrative, and current somatic and relational state. Persisted across restarts and updated by identity recording, ToM belief sync, and nightly consolidation.

User model

The agent's representation of the operator or user: name, bio, known preferences, and recent interaction history. Updated on each conversational turn.

Continuity

The identity record that tracks boot count, session IDs, and a recent-activity log. Gives the agent a minimal autobiographical timeline that survives restarts.

Self-knowledge registry

A versioned JSONL file of structured self-beliefs keyed by domain and key (for example domain="capability", key="code_writing"). High-confidence ToM beliefs about the self are mirrored here automatically.

Somatic state

Somatic state

A set of physiological-analogue dimensions — arousal, fatigue, tension, valence — that modulate how the agent behaves. These are not cosmetic. They directly influence LLM temperature, prompt style, memory salience, and whether the agent recommends pausing background work.

Somatic modulators

Derived signals from the live somatic state. to_temperature() adjusts LLM sampling heat. to_prompt_style_note() injects a behavioral directive into the system prompt. to_memory_retrieval_boost() emotionally tunes memory ranking toward affectively aligned content.

Relational state (musubi)

Musubi

The composite relational score derived from four dimensions: trust, resonance, presence, and attunement. Named after the Japanese concept of generative connection. A higher musubi score loosens self-approval thresholds, boosts creative-ladder promotion, and increases memory salience for relational content.

Relational engine

The subsystem (RelationalEngine) that tracks the four musubi dimensions and exposes modifiers for memory retrieval, creative ladder promotion, and self-approval risk. Updated as the agent and operator interact over time.

Autonomy

Self-approval ladder

A risk-tiered evaluation system that decides whether the agent can proceed with an action without operator intervention. Tiers range from low-risk (auto-approved) to high-risk (escalated or blocked). Every evaluation is recorded to the durable approval ledger.

Creative ladder

A seven-stage promotion system for internal creative work: spark → note → artifact → micro_task → project_seed → project → durable_work_stream. Work objects are promoted based on intrinsic value signals and relational boost. Demotion also occurs when value signals are weak.

Work object

A unit of autonomous work tracked through the creative ladder. Has a stage, content, value signal, and optional plan and commitment links.

Executive state

The agent's current intention, active goals, and capacity-limited task queue. Tracks whether the agent should pause background work (based on somatic fatigue) and manages goal persistence across restarts.

Daydream

A background creative process that generates sparks from memory and somatic tension during idle periods. High-value daydreams ("keeper daydreams") are persisted to durable memory with embeddings and can seed new work objects.

Execution

BAA (Bounded Assistant Agent)

The background execution engine. Accepts RepairTask objects, queues them, and executes them with concurrency limits and lane routing. Supports retry, recovery, and failure-rate throttling. BAA tasks come from scheduled items, harness objectives, and operator-submitted work.

RepairTask

The unit of work submitted to the BAA. Has an objective, optional commitment and project links, stage history, and metadata. Progresses through PENDING → RUNNING → SUCCEEDED / FAILED / RECOVERING.

Repair Executor

Executes a RepairTask through a plan → execute → verify → recover loop using the tool registry and optional LLM planning. Records a git checkpoint before destructive steps when git is available.

Lane

A named execution queue with configurable concurrency. Current lanes: chat (conversational turns), baa (background repair tasks), consolidation (nightly memory work), cron (daydream, schedule processing, and related background work). Prevents background work from crowding out conversation.

Execution receipt

A durable audit record created at the end of every terminal BAA task. Stored in receipts.db and surfaced through the dashboard Operations tab. Answers "what did the agent actually do?"

Retry governor

The control layer that decides whether a failed task should retry, salvage, or stop. It preserves blocked-vs-resumable intent instead of blindly replaying low-divergence failures.

Salvage packet

The durable retry metadata attached to a failed task. It captures the last meaningful attempt state so the governor can resume without losing provenance.

Scheduling

Schedule item

A durable cron or calendar entry with a recurrence rule, action, priority, and optional commitment and plan links. Kinds: task (triggers BAA execution) and event (reminder-only, records without executing). Recurrence options: none, interval_hours, daily, weekly, weekdays.

Schedule run

An audit record for each time a schedule item fires, whether automatically or via manual trigger. Stores the resulting BAA task ID, run status, and any error message.

Schedule service

The subsystem (ScheduleService) that detects due items every 60 seconds and fires them. Applies a catch-up policy: if the agent was offline and multiple occurrences were missed, it fires once for the latest due occurrence and then advances to the next future time rather than replaying every missed run.

Theory of Mind (ToM)

Belief

A structured record of something the agent infers about the user or itself: subject, predicate, confidence, and optional evidence. Beliefs about the self are mirrored into the self-knowledge registry when confidence is high enough.

Intention

A record of a user or agent goal inferred from a conversation turn. Tracked with confidence and staleness so outdated intentions can be pruned automatically.

ToM engine

The subsystem (ToMEngine) that records beliefs and intentions on every conversational turn, detects contradictions between existing beliefs, and syncs high-confidence self-beliefs into the identity self-model.

Channels

Voice chat

The chat lane's microphone and speech lane. It transcribes audio into chat text and can synthesize spoken replies. Voice output metadata is stored alongside the message history.

Phone bridge

The Twilio-backed voice surface for live inbound and outbound calls. It supports owner-vs-caller screening, workspace separation, and recent-call inspection.

Telegram

The existing chat channel for paired and policy-controlled Telegram access. It supports bot pairing, allowlists, typing indicators, and edited replies.

Tools and workflow

Tool registry

The central registry of callable tools available to the agent. Tools are validated through a safety pipeline (command classification, filesystem path enforcement, content size limits) before execution. Plugin-provided tools are auto-registered at startup.

Workflow tools

Higher-level composite tools that reduce round-trips for common patterns. Examples: workflow_create_writing_task (scaffold + commitment + plan in one call), workflow_repo_triage (quick repo and work summary), workflow_supervise_session (start, observe, and interact with a PTY terminal session), and workflow_create_schedule (create a durable scheduled task). Designed to reduce tool-call round-trips for common operator patterns.

Tool loop guard

A circuit breaker inside the agent's tool-use loop. Stops execution after 24 rounds or if the same tool call is made identically twice in a row. Prevents runaway tool loops.

PTY session

A pseudo-terminal session managed by PtySupervisor. Lets the agent interact with terminal applications (vim, shells, external coding tools) the way a human would. Sessions expose screen-state heuristics that classify what the terminal application is currently doing.

HookBus

An event bus for pre-execution policy hooks. Hook points: PRE_TOOL_EXECUTE, PRE_COMMAND_EXECUTE, PRE_FILE_WRITE, PRE_CONVERSATION_RESPONSE. Hooks can mutate arguments or short-circuit an action before it runs.

Platform

Capability

The canonical platform capability descriptor. It carries identity, kind, source, owner, status, dependencies, and validation metadata for a tool or service entry.

Extension

A packaged capability bundle with manifest/version metadata. Extensions can be installed, updated, enabled, disabled, or uninstalled through the platform surface.

Plugin trust policy

A persisted rule describing whether a publisher, signer, checksum, or other trust dimension is trusted, user-approved, or blocked.

Plugin trust feed

A curated trust update feed that can be synced into the current trust policy set.

Observability

Telemetry store

An append-only JSONL event log. Every meaningful runtime event — bootstrap stages, tool calls, memory operations, LLM calls — is logged with a session ID and optional span ID. Queryable through /api/monitor/events and the Logs dashboard tab.

Token telemetry

Per-call LLM usage recording: prompt tokens, completion tokens, latency, and estimated cost. Rolled up by session and by day. Surfaced in the Usage dashboard tab.

Health monitor

A background process that runs Doctor checks every 60 seconds and emits health events to the event bus. Checks include memory store connectivity, embedding latency, BAA queue depth, and compaction lag.

Doctor

The diagnostic subsystem that runs named health checks across the full substrate and returns a HealthReport with pass / warn / fail / skip status per check. Also exposed at /api/monitor/health.

Readiness state

A state machine (booting → ready / degraded) that tracks whether the agent is fully initialized. The /readiness endpoint exposes the current state, the time it entered that state, and a history of transitions.

Dashboard tabs