State Managers

Distributed domain managers communicating through English-language APIs

Architecture

Unity’s intelligence is distributed across specialized state managers, each owning a different aspect of the assistant’s cognition:

CodeActActor (generates Python plans, calls primitives.* APIs)
    │
    ▼
State Managers (each runs its own async LLM tool loop)
    │
    ├── ContactManager        — people and relationships
    ├── KnowledgeManager      — domain facts, structured knowledge
    ├── TaskScheduler         — durable tasks, execution with live handles
    ├── TranscriptManager     — conversation history and search
    ├── GuidanceManager       — procedures, SOPs, how-to knowledge
    ├── FileManager           — file parsing and registry
    ├── ImageManager          — image storage, vision queries
    ├── FunctionManager       — user-defined functions
    ├── WebSearcher           — web research
    ├── SecretManager         — encrypted secret storage
    ├── BlacklistManager      — blocked contact details
    └── DataManager           — low-level data operations

Each manager exposes a small public surface — typically ask (read-only), update (mutations), and sometimes execute (start durable work). The Actor orchestrates them through code-first plans.

English as API

The defining design choice: managers communicate through natural-language interfaces. The public methods take plain text: str parameters, not structured queries.

# ContactManager.ask — the parameter is English, not SQL
await primitives.contacts.ask("Who did we meet at the conference last month?")

# KnowledgeManager.update — the instruction is English, not a CRUD operation
await primitives.knowledge.update(
    "Record that the Henderson project deadline moved to March 15"
)

Each manager has its own internal LLM tool loop that interprets the English request and orchestrates lower-level tools (database queries, API calls, etc.) to fulfill it. The caller never sees the implementation details.

This matters because:

• Managers are swappable. The ContactManager could use a SQL database, a vector store, or an external CRM. The caller’s code doesn’t change.
• The system is inspectable. You can read the Actor’s plan and understand what it’s doing without reading implementation code.
• Composition is natural. The Actor can write for contact in contacts: await primitives.knowledge.ask(f"What was {contact} working on?") — the English flows through cleanly.

Base class contracts

Every manager has an abstract base class (base.py) that defines the public API contract. The docstrings on these abstract methods are the API — they’re attached to derived classes via @functools.wraps and visible to the LLM when the methods are exposed as tools.

class BaseContactManager(BaseStateManager):
    @abstractmethod
    async def ask(self, text: str, ...) -> SteerableToolHandle:
        """Answer questions about stored contacts.

        text : str
            The user's plain-English question
            (e.g. "Show me Alice's phone number.").
        """

    @abstractmethod
    async def update(self, text: str, ...) -> SteerableToolHandle:
        """Execute English instructions that create or change contacts.

        text : str
            The user's instruction
            (e.g. "Add Bob's email: [e-mail]").
        """

The base class docstrings are implementation-agnostic — they never reference internal tools, database schemas, or other managers. This creates a clean separation: the public API is stable even as the implementation evolves.

Each manager runs its own LLM

This is important: when the Actor calls primitives.contacts.ask(...), the ContactManager starts its own async LLM tool loop. That loop has its own system prompt, its own set of internal tools (search contacts, filter by field, etc.), and its own conversation context.

This means:

• The Actor’s LLM doesn’t need to know how contacts are stored
• The ContactManager’s LLM is specialized for contact operations
• Each manager can use a different model if needed (fast model for simple lookups, powerful model for complex reasoning)
• The loops are independently steerable via their handles

Manager inventory

Manager	ask	update	execute	What it owns
ContactManager	Who people are, relationships, contact details	Create, edit, delete, merge contacts	—	People
KnowledgeManager	Domain facts, structured knowledge	Create, change facts; refactor schemas	—	What the assistant knows
TaskScheduler	Task status, queue state	Create, edit, reorder tasks	Start tasks (returns live handle)	What the assistant needs to do
TranscriptManager	Conversation history, search, analysis	—	—	What was said
GuidanceManager	Procedures, SOPs, strategies	Add, edit, delete guidance	—	How to do things
FileManager	File metadata, parsing, content questions	—	—	Received files
WebSearcher	Web search, crawl, extract	—	—	The public internet
SecretManager	Secret metadata (not values)	Store, edit, delete secrets	—	API keys, tokens
MemoryManager	—	—	—	Offline consolidation (not interactive)

Where to start reading

File	What’s there
unity/contact_manager/base.py	Example base class contract
unity/common/state_managers.py	BaseStateManager with caller context injection
unity/actor/environments/state_managers.py	How primitives are assembled
unity/function_manager/primitives/registry.py	The typed Primitives API surface