Iris Domain — Feature Reference

Iris is the Universal Intelligent Assistant Platform of the Oshun ecosystem. It delivers AI conversation powered by multiple language models, deep personalization through a four-tier hierarchical memory architecture (core, working, archival, episodic), autonomous agents capable of using tools and delegating to each other, knowledge base integration with cited retrieval, and full multimodal interaction across text, voice, vision, and spatial computing. Iris is purpose-built for both individual productivity and enterprise deployment: it works equally well as a personal AI companion on a smartwatch, a corporate knowledge assistant in Microsoft Teams, or a code intelligence engine embedded in a developer's editor. Critically, Iris runs models on any hardware — from local Ollama instances for air-gapped deployments to frontier models like Claude and GPT-4 for maximum capability — with intelligent routing that selects the right model for every task automatically.

Library prefix: @iris/* | 258 library packages under libs/iris/** (45 cluster directories) and 11 application packages under apps/iris/**. Iris is partially implemented: the fully built-out, verifiable pieces are @iris/types, the @iris/api Hono service, @iris/conversation-core, @iris/conversation-orchestration, the @iris/agents catalog, and @iris/core/@iris/config. Many leaf packages exist as Nx scaffolds. Features below describe the product surface; consult DOMAINS/iris/specifications.md for what is verified in code today.

1. Platform Access#

Iris is available on every major platform, surface, and device form factor so users encounter a consistent AI experience regardless of where they work.

1.1 Applications#

1.2 Interface Elements#

1.3 Keyboard Shortcuts#

2. AI Conversations#

The core of Iris is natural, context-aware, multi-turn AI conversation with rich formatting, file understanding, and deep conversational intelligence.

2.1 Conversation Management#

• Create conversations: Start new conversations on any topic with a single click or keyboard shortcut. Each conversation maintains independent context so multiple simultaneous threads do not bleed into each other.
• Conversation history: Permanent, searchable record of all past conversations. Past conversations load instantly for reference or continuation months later.
• Auto-generated titles: The system infers a descriptive title from the first message exchange, eliminating manual naming while keeping the list navigable.
• Custom titles: Override auto-generated titles with any custom name for long-lived conversations.
• Full-text search: Search across conversation titles and full message text simultaneously, returning results from any point in history.
• Conversation export: Export individual conversations as Markdown (for documentation), JSON (for programmatic use), or PDF (for sharing with people outside the platform).
• Conversation branching: Fork a conversation at any message to explore an alternative direction without losing the original thread — useful when a conversation reaches a decision point with multiple viable paths.
• Conversation deletion: Delete individual conversations or bulk-delete history with confirmation.

2.2 Message Features#

• Real-time streaming: AI responses appear token by token as they are generated — no waiting for the full response before reading begins.
• Message editing: Edit any sent message and regenerate the AI's response from that point, effectively revising the conversation history in place.
• Response regeneration: Request a different response to the same message without editing the input — useful for exploring alternative phrasings or approaches.
• One-click copy: Copy any complete message or individual code block with a single click.
• File attachments: Attach documents, images, code files, and data files for the AI to analyze and reference in its response.
• Syntax-highlighted code blocks: Code responses are automatically formatted with language-specific syntax highlighting and a copy button.
• Markdown rendering: Full rich-text rendering of headings, lists, nested lists, tables, bold, italic, links, and blockquotes.
• LaTeX support: Mathematical equations written in LaTeX notation are rendered as formatted formulas inline.
• Citation links: When the AI draws on knowledge base documents, it includes inline citations that link directly to the source document, page, and section.
• Stop generation: Halt the AI's response at any point mid-generation.

2.3 Supported File Attachments#

2.4 Conversation Intelligence#

• Context coreference resolution: The system tracks pronouns and references across turns ("it", "that approach", "the earlier example") so the AI always knows what the user is referring to, even several messages later.
• Intent classification: Each user message is classified into a semantic intent category (question, task request, clarification, follow-up) to route to the most appropriate response strategy.
• Slot filling: When a request requires multiple pieces of information, the system identifies what is already provided and asks targeted clarifying questions for the missing values rather than making assumptions.
• State machine dialogue management: Conversations follow configurable state machines with guard conditions, ensuring coherent multi-step interactions such as onboarding flows or structured workflows.

3. AI Model Selection and Routing#

Iris provides intelligent access to multiple AI models and automatically selects the best one for each task, balancing quality, cost, and speed — without requiring users to understand or choose models manually.

3.1 Available Models#

3.2 Intelligent Model Routing — @iris/model-routing#

Model routing automatically selects the appropriate model for each request based on declared task requirements, without requiring the user to choose:

• Task-based routing: Different task types (code generation, creative writing, factual Q&A, analysis, long-document reasoning) are routed to the model with the strongest track record for that category.
• Cost optimization: Routes to the most cost-effective model that satisfies the quality threshold for the task — uses a smaller, cheaper model when a frontier model is unnecessary.
• Latency optimization: In interactive sessions, routing can prioritize faster models when response speed matters more than maximum quality.
• Fallback chains: If the primary model is unavailable (API error, rate limit, outage), the system automatically retries with the next model in the fallback chain, transparent to the user.
• Circuit breaking: When a provider experiences sustained high error rates, the circuit breaker temporarily stops routing to that provider to prevent cascading failures.
• Provider health monitoring: Continuous health checks track each model provider's availability, latency, and error rate to inform routing decisions in real time.
• Manual override: Users can explicitly select a specific model for any conversation, bypassing automatic routing.

3.3 Multi-Model Ensemble — @iris/ensemble#

The ensemble system queries multiple models and combines their outputs for higher-confidence responses, particularly valuable for factual questions where accuracy is paramount:

• Ensemble voting: Send the same request to multiple models and use a voting mechanism to determine the consensus answer.
• Response aggregation: Combine distinct insights from multiple model responses into a single synthesized answer, drawing on the strengths of each model.
• Confidence scoring: Each model response includes a confidence estimate that influences how heavily it is weighted in the final aggregated output.
• Self-consistency checks: For complex reasoning tasks, generate multiple independent reasoning chains and select the answer that appears most consistently across them.

3.4 Model Failover — @iris/failover#

• Automatic failover: When any model provider fails, the failover system switches to the next available provider in the configured chain without any user-facing interruption.
• Failover history: Records of every provider failure and failover event for reliability analysis and SLA reporting.

4. Memory System#

Iris remembers users across conversations through a four-tier, MemGPT-inspired memory architecture — core, working, archival, and episodic (the MemoryTier enum in @iris/types). Each tier operates at a different timescale and scope, together providing continuity from the current turn to the user's entire relationship with Iris.

The tiers form a pyramid from fastest to slowest access: core memory is always in context, working memory covers the active session, archival memory is a searchable long-term store of durable facts, and episodic memory is a time-ordered event log of what happened across conversations. When Iris assembles a response, the context assembler allocates a token budget across all four tiers (default: core 15%, working 40%, archival 30%, episodic 15%) and truncates the lowest-priority chunks when the budget is exceeded.

4.1 Core Memory — @iris/memory-core#

Core memory holds essential identity and persona information that is always kept in the model's context window:

• Persona, user, system, goals blocks: Core memory is divided into CoreMemorySection blocks (persona, user, system, goals), each with a token budget that is enforced against a total budget.
• Always in context: Unlike searchable tiers, core memory blocks are injected into every turn so the assistant never loses its persona or the key facts it has been told.
• Block update operations: Blocks support replace, append, prepend, and insert edits.

4.2 Working Memory#

Working memory covers the current session's active context and recent interactions:

• Active task context: The AI maintains an understanding of what task is currently being worked on across multiple conversational exchanges — for example, "we are refactoring this function" persists across back-and-forth questions.
• Relevance and recency scoring: Each working-memory entry carries relevance, recency, and accessCount scores; a configurable decay rate and relevance threshold prune low-value entries.
• Bounded and TTL'd: Working memory is capped by entry count and token budget, with an optional TTL (the default working-memory config expires entries after one hour).
• Temporary state storage: Session-scoped state that persists until the session ends, protecting ephemeral information from permanent storage.

4.3 Archival Memory — @iris/memory-core / @iris/memory-persistence#

Archival memory is the long-term, searchable store of durable facts and preferences about the user:

• User preferences: Communication style, preferred response format (bullet points vs. prose), programming language preferences, and domain-specific preferences learned over time.

• Explicit teaching: Users can directly instruct Iris to remember specific information ("Remember that I prefer TypeScript over JavaScript"); the system acknowledges and confirms storage.

• Confidence scoring: Each memory carries a confidence score that increases when the same information is observed multiple times across conversations.

• Source attribution: Every long-term memory record links back to the specific conversation that created it, enabling traceability and manual verification.

• Manual memory management: Users can view all stored memories, edit incorrect ones, and delete memories they no longer want retained.

• Vector-backed semantic retrieval: Archival entries carry an optional embedding (default model text-embedding-3-small, 1536 dimensions) so they are found by conceptual similarity rather than keyword match. Search results are tagged semantic, keyword, or hybrid.

• Entity extraction: Archival entries can carry extracted EntityReference links, building an incremental graph of the user's projects, colleagues, and domain knowledge.

• Importance scoring: Each entry carries an importance level (critical, high, medium, low, trivial); search and context assembly weight entries by importance.

4.4 Episodic Memory — @iris/memory-episodic#

Episodic memory stores time-ordered events and significant past interactions, functioning as Iris's record of the user's history:

• Time-ordered event log: Episodic entries record typed events (conversation_start, conversation_end, milestone, decision, learning, preference_change, goal_update, context_switch, and more) with timestamps.
• Conversation summaries: Important conversations are summarized and stored as episodic memories, capturing key decisions, discoveries, and outcomes.
• Emotional context: Episodic entries can carry an EmotionState (valence/arousal/dominance) so the assistant can recall how an interaction felt, not just what happened.
• Milestone tracking: Significant accomplishments are flagged so Iris can acknowledge progress over time.

4.5 Context Assembly#

The four tiers are assembled into a single LLM context window under a token budget. The default memory-context configuration allocates the budget across tiers (core 15%, working 40%, archival 30%, episodic 15%) and truncates the lowest-priority chunks when the budget is exceeded.

4.6 Memory Operations#

The libs/iris/memory/ cluster (22 packages) provides the supporting operations:

• Memory consolidation (@iris/memory-consolidation): Working-tier memories are processed and promoted into longer-lived storage — analogous to how sleep consolidates human memories.
• Tier transitions (@iris/memory-transitions): Manages promotion and demotion of memories between tiers.
• Memory persistence (@iris/memory-persistence): Cross-session persistence of memory records.
• Memory retrieval (@iris/memory-retrieval): Retrieval that injects contextually relevant memories into the prompt for each conversation turn.
• Memory visualization (@iris/memory-visualization): An interface showing the user's memory graph — what Iris knows and where it came from.
• Memory debugging (@iris/memory-debugging): Developer tools for inspecting which memories were retrieved for a given turn.
• Memory sharing (@iris/memory-sharing): Selective sharing of memory contexts — e.g. sharing a project knowledge base across a team while keeping personal preferences private.
• Memory migration (@iris/memory-migration): Import and export of memory packages for account transfers, backups, or moving between Iris instances.
• Memory analytics (@iris/memory-analytics): Aggregate statistics over the memory tiers.

5. Knowledge Base#

Upload documents and let Iris search them to provide informed, cited answers grounded in your specific content rather than general training knowledge.

5.1 Document Management — @iris/knowledge#

• Document upload: Upload PDFs, Word documents (DOCX), Markdown files, plain text, code files, CSV, JSON, and HTML pages.
• Bulk upload: Upload entire folders of documents simultaneously with a progress indicator.
• Collection organization: Group related documents into named collections (e.g., "Company Policies", "API Documentation", "Research Papers") for organized retrieval.
• Tagging: Apply custom tags to documents for cross-collection filtering and organization.
• Version control: Upload updated versions of existing documents. The system detects content changes and re-indexes modified sections, preserving the full version history.

5.2 Knowledge Retrieval#

• Semantic search: Meaning-based search that finds relevant passages by conceptual similarity rather than exact keyword matches — searching "how do users log in" will find passages about "authentication flow" even without those exact words.
• Hybrid retrieval: Combines vector-based semantic search with traditional BM25 keyword matching (a probabilistic relevance ranking algorithm), then merges and reranks results for the best of both approaches.
• Automatic chunking: Documents are intelligently split into overlapping chunks at natural boundaries (paragraph, section, sentence) sized to fit within the LLM's context window.
• Citation engine: Every AI response that draws on a knowledge base document includes inline citations identifying the document, section, and page number. Citations are clickable, jumping to the source passage.
• Knowledge graph: Entities and relationships extracted from documents are linked into a graph — a question about "how Product X relates to Service Y" can traverse these links even if no single document mentions both.
• Real-time knowledge: Access to current information through web search integration for questions that require data beyond the knowledge base.
• Knowledge freshness detection: The system flags documents that appear outdated based on date references and conflicting information, prompting the user to upload updated versions.

5.3 Knowledge Sources#

5.4 Enterprise Knowledge Features#

• Team knowledge bases: Shared knowledge bases accessible to all members of an organization or team.
• Access control: Fine-grained permissions determining which users or roles can view, edit, and delete knowledge documents.
• Knowledge analytics: Track which documents are most frequently retrieved, identifying the highest-value knowledge assets.
• Grounding: Configure the AI to answer only from the knowledge base and refuse to speculate beyond it — critical for regulated industries or customer support accuracy requirements.
• Personal knowledge base: Private knowledge bases visible only to the individual user, separate from team-shared content.

6. AI Agents and Tool Use#

Specialized AI agents designed for particular task domains, capable of using tools, browsing the web, executing code, and coordinating with other agents. Agents extend conversational AI into autonomous task execution.

6.1 Built-In Agents — @iris/agents#

6.2 Agent Capabilities#

• Task decomposition: When given a complex goal, agents automatically break it into a sequence of manageable sub-tasks and create an execution plan before starting.
• Plan generation: Agents generate an explicit step-by-step plan with a confidence estimate before beginning multi-step tasks, allowing the user to review and modify the plan.
• Tool use: Agents can invoke registered tools — file operations, web search, code execution, API calls — to gather information and take actions during task execution.
• Multi-agent collaboration: Multiple specialized agents can collaborate on tasks too complex for any single agent. The Supervisor agent coordinates handoffs and merges outputs.
• Proactive suggestions: Based on context and usage patterns, agents proactively suggest relevant next steps, related queries, or potentially useful resources.
• Workflow automation: Define reusable workflows (sequences of agent steps with conditional branches) that execute automatically when triggered.

6.3 Agent Tools#

6.4 Agent-to-Agent Protocol (A2A) — @iris/a2a#

@iris/a2a is a private, unmounted compatibility prototype. It does not expose the current A2A wire protocol and is not evidence of external interoperability; ADR-0091 defers adoption until a named independent agent boundary exists. Its local experiments model concepts used by internal multi-agent workflows:

• Agent registry: A central registry where agents advertise their capabilities so the Supervisor knows which agents can handle which tasks.
• Agent communication: Agents send structured messages to each other, sharing partial results and requesting assistance without human involvement.
• Task delegation: A generalist agent can delegate a specialized sub-task to the best-equipped specialist agent and collect the result asynchronously.
• Result aggregation: The Supervisor agent collects partial outputs from multiple agents and synthesizes a unified, coherent final response.

6.5 Model Context Protocol (MCP) — @iris/mcp#

MCP (Model Context Protocol) is an industry standard for connecting AI systems to external tools and data sources. Iris has both server and client MCP capabilities:

• MCP server: Iris exposes its own capabilities (memory, knowledge base, conversation history) as an MCP server so external AI clients like Claude Code can access them.
• MCP client: Iris connects to external MCP servers to acquire additional tools — for example, connecting to a company's internal MCP server that exposes CRM data.
• Standard protocol compatibility: Compatible with the broader MCP ecosystem, allowing third-party MCP tools to be used in Iris conversations with no custom integration code.

6.6 Computer Use — @iris/sandbox#

The computer use system enables agents to operate a sandboxed web browser during conversations:

• Sandboxed Chromium: A fully isolated headless Chromium browser that the agent controls during a session. The sandbox prevents the agent from accessing anything outside the designated browser session.
• Observe-Reason-Act loop: The agent takes a screenshot, asks the LLM what to do based on the screen content, executes the decided action, verifies the result, and repeats until the task is complete.
• Action types: Click, type text, navigate to URLs, scroll pages, select from dropdowns, upload files, download files.
• Action safety validation: Every action is checked against safety rules before execution. High-risk actions (form submissions, purchases, deletions) require explicit human confirmation.
• Maximum iteration limit: Configurable maximum of 50 actions per task to prevent runaway automation loops.

7. Code Intelligence#

Specialized capabilities for developers and engineering teams, providing an AI-powered development environment that understands code at both the line and architectural levels.

7.1 Code Features — libs/iris/code/*#

The code-intelligence capability is a cluster of packages under libs/iris/code/ (@iris/code-generation, @iris/code-review, @iris/code-explanation, @iris/code-understanding, @iris/code-architecture, and others) — there is no single @iris/code package.

• Code generation: Generate complete functions, classes, modules, or entire files from natural language descriptions. Generates idiomatic code in the target language and follows project conventions when given context.
• Code explanation: Explain what existing code does in plain language — from individual lines to entire modules — with varying levels of technical depth.
• Code review: Automated code review identifying bugs, security vulnerabilities, performance issues, and deviations from best practices, with specific line-level feedback.
• Code debugging: Identify the root cause of bugs from error messages, stack traces, or unexpected output, with suggested corrections and explanations.
• Code refactoring: Suggest and apply refactoring improvements — extract functions, simplify conditionals, remove duplication — with before/after comparison.
• Test generation: Generate unit tests with appropriate edge cases and assertions for existing functions, targeting the testing framework used in the project.
• Documentation generation: Create JSDoc comments, docstrings, README sections, and inline comments from code.
• Architecture advice: Guidance on system design patterns, module organization, API design, and architectural tradeoffs.

7.2 Codebase Understanding#

• Repository analysis: Analyze an entire code repository to understand its structure, key modules, entry points, and overall architecture.
• Dependency mapping: Map out package dependencies, internal module dependencies, and their relationships to understand coupling and the impact of changes.
• Semantic code search: Search a codebase by meaning — "find where user authentication happens" — rather than just text matching.
• Static analysis: Identify potential issues in code without running it — dead code, unreachable branches, type inconsistencies, and common error patterns.

8. Voice Interaction#

Speak to Iris naturally for hands-free AI assistance across all supported platforms, with support for continuous conversation, wake words, and multi-language recognition.

8.1 Voice Features — @iris/voice#

• Voice input: Speak messages instead of typing. Real-time transcription appears as speech is recognized, with the final message sent on a detected pause.
• Voice response synthesis: AI responses are read aloud using high-quality neural text-to-speech with natural prosody and emotional expressiveness. Multiple voice profiles are available.
• Continuous voice conversation: Hold a natural back-and-forth voice conversation with turn detection — the system knows when the user has finished speaking and responds promptly without requiring a button press.
• Wake word detection: On desktop and mobile, activate Iris by saying a configurable wake word without pressing any button.
• Multi-language voice: Voice input recognition and output synthesis available in dozens of languages, with automatic language detection.
• Voice commands: Perform navigation actions ("New conversation", "Stop", "Copy that") with voice commands while keeping hands free.
• Voice shortcuts: Define custom voice trigger phrases for frequently used actions or common queries.

8.2 Voice Customization#

• Voice profile selection: Choose from multiple synthesized voice profiles varying in gender presentation, accent, warmth, and age.
• Speaking rate control: Adjust the playback speed of AI voice responses from 0.5x to 2.0x to match comprehension preference.
• Tone adaptation: The AI adjusts spoken delivery (formal, casual, empathetic, energetic) based on the conversation context and user preference settings.

8.3 Accessibility Voice Features#

The voice interface serves as a complete primary interaction mode for users with motor disabilities or visual impairments. It supports full application navigation by voice — including searching conversations, starting new conversations, and accessing settings — not just message input.

9. Vision and Multimodal#

Iris can understand images, analyze documents visually, and interact with extended reality environments, making it useful for any task where visual context matters.

9.1 Vision Features — libs/iris/multimodal/vision/*#

Vision is a cluster under libs/iris/multimodal/vision/ (@iris/multimodal/vision plus @iris/vision-understanding, @iris/vision-documents, @iris/vision-diagrams, @iris/vision-screenshare, and others) — there is no single @iris/multimodal package.

• Image analysis: Upload any image for AI analysis — the AI describes it, answers questions about its content, extracts information, or compares it to other images.
• Screenshot analysis: Take a screenshot of any screen for the AI to analyze, enabling natural-language Q&A about visible software, errors, or interfaces.
• Document scanning: Capture paper documents with a camera for extraction and analysis — forms, receipts, notes, whiteboards.
• Diagram understanding: The AI understands charts (bar, line, pie, scatter), diagrams (flowcharts, UML, network diagrams), and visual data without requiring manual data extraction first.
• OCR (Optical Character Recognition): Extract text from images of documents, street signs, handwritten notes, and screenshots.

9.2 Spatial Interaction (XR)#

• Spatial AI assistant: In XR environments (Meta Quest, Vision Pro, WebXR browsers), Iris appears as a spatial entity the user can interact with through gaze, voice, and gesture.
• Gesture control: Navigate the Iris interface and trigger actions with hand gestures in XR environments.
• Spatial pinning: Pin AI responses to specific locations in augmented reality — for example, pinning assembly instructions next to the physical component they describe.
• 3D object recognition: In AR, the AI can identify and discuss real-world objects visible through the headset's cameras.

9.3 Brain-Computer Interface (BCI) — @iris/bci#

• BCI input support: Experimental support for commercially available consumer BCI (Brain-Computer Interface) devices (Emotiv, OpenBCI, Muse) as an input modality for hands-free interaction.
• Neural signal processing: Processing pipeline for raw neural signals including noise filtering, feature extraction, and intent classification from EEG (electroencephalography) or EMG (electromyography) signals.
• Adaptive responses: The AI adapts response complexity and pacing based on cognitive state indicators detected via BCI data, reducing information overload for fatigued users.

9.4 IoT Integration#

• Smart device control: Issue natural language commands to connected IoT devices and smart home systems through Iris.
• Sensor data analysis: AI analysis of time-series data streams from connected sensors — temperature trends, energy usage patterns, anomaly detection.
• Ambient intelligence: Iris can respond to environmental context changes from connected sensors (e.g., adjusting communication style based on detected meeting room occupancy).

10. Emotional Intelligence#

Iris understands emotional context and responds with appropriate empathy and sensitivity, making it more effective in situations involving stress, frustration, or personal topics.

10.1 Emotion Recognition — libs/iris/emotional/*#

Emotional intelligence is a cluster under libs/iris/emotional/ (@iris/emotional-recognition, @iris/emotional-response, @iris/emotional-rapport, @iris/emotional-social, @iris/emotional-ethics, @iris/emotional-wellbeing, @iris/emotional-voice-analysis, and others) — there is no single @iris/emotional package.

• Text sentiment analysis: Detects emotional tone in written messages — frustration, excitement, confusion, sadness — from linguistic patterns and phrasing.
• Voice emotion detection: Analyzes voice tone, pacing, and prosody to identify emotional state from speech characteristics beyond word choice.
• Contextual emotion inference: Understands emotional subtext in context — someone asking "is this normal?" after describing a difficult situation is seeking reassurance, not merely information.

10.2 Empathetic Responses#

• Empathetic response generation: When emotional distress or difficulty is detected, the AI responds first with acknowledgment and empathy before providing information or solutions.
• Rapport building: Iris builds conversational rapport over time through consistent personality, remembered preferences, and appropriate reference to shared conversation history.
• Social context awareness: Understands social dynamics — the difference between venting, seeking advice, and requesting concrete help — and responds accordingly.
• Wellbeing monitoring: Gently monitors for patterns suggesting user stress or difficulty and offers supportive responses without being intrusive.
• Ethical guardrails: The AI applies ethical reasoning in sensitive conversations, identifying when a topic requires professional help and communicating that boundary respectfully.

10.3 Communication Style Adaptation#

• Tone control: Switch between formal, casual, professional, and friendly registers based on conversation context or explicit preference.
• Verbosity control: The user can request concise bullet-point summaries or detailed long-form explanations based on the current need.
• Audience awareness: Adjust technical complexity from beginner-friendly analogies to expert-level technical detail based on demonstrated expertise.
• Cultural sensitivity: Adapt communication style for different cultural contexts, avoiding culturally specific idioms that may not translate well.

11. Advanced Reasoning#

Advanced reasoning capabilities for complex, multi-step problems that require careful, transparent thought before reaching conclusions. These features are grouped under the libs/iris/reasoning-thinking/ cluster (@iris/reasoning-thinking) and apply on top of any supported AI model — they control how the model approaches a problem, not which model answers it.

• Chain-of-thought reasoning: The AI walks through its reasoning step by step before reaching a conclusion, making the reasoning process transparent and auditable.
• Extended thinking mode (@iris/reasoning-thinking): For particularly complex problems, the AI enters an extended deliberation mode where it spends additional compute time on planning and verification before responding.
• Self-consistency checking: For important conclusions, the AI generates multiple independent reasoning chains and cross-checks them — if all chains reach the same conclusion, confidence is high.
• Metacognitive monitoring: The AI actively monitors its own reasoning for logical leaps, unsupported assumptions, or areas where its knowledge is limited.
• Uncertainty disclosure: The AI explicitly communicates when it is uncertain about an answer, distinguishing between confident knowledge and educated estimation.
• Confidence scoring: Responses include confidence indicators that reflect the AI's assessed reliability of the information provided.

12. Agent Marketplace#

A curated directory for discovering, installing, and publishing AI agents and plugins that extend Iris's capabilities beyond the built-in set.

• Agent directory: Browse a curated catalog of specialized AI agents created by Anthropic, verified third-party publishers, and the Iris developer community.
• Plugin library: Install plugins that add new tool categories, data sources, or workflow integrations to Iris.
• One-click install: Install agents and plugins directly from the Marketplace with a single confirmation — no configuration required for standard setups.
• Reviews and ratings: Community ratings and written reviews help users identify the highest-quality agents for their use cases.
• Developer publishing: Any developer with an Iris developer account can publish agents and plugins to the Marketplace, subject to a review process.
• Version management: Installed agents and plugins receive automatic updates with version notes. Users can pin to a specific version or roll back if needed.
• Agent archetypes: Pre-defined templates for common agent use cases (customer support bot, coding assistant, research agent) that developers can customize and publish.
• Custom personalities: Customize any agent's name, personality description, visual avatar, and tone without modifying its underlying capabilities.

13. Privacy and Security#

Iris is built with privacy as a core design principle, with controls that range from full local-only operation to enterprise compliance certification.

13.1 Privacy Controls — @iris/privacy#

• End-to-end encryption: All conversation content is encrypted in transit (TLS 1.3) and at rest (AES-256). Only the authenticated user can decrypt their conversation history.
• Local-only mode: Iris can be configured to run AI models entirely on-device with zero data leaving the device — no cloud API calls, no telemetry.
• Data minimization: The system collects only the data necessary to provide the requested service. No behavioral tracking beyond what is needed for personalization.
• Differential privacy: Analytics processing uses differential privacy techniques (mathematical methods that add calibrated noise to statistics) that prevent individual user data from being reconstructable from aggregate analytics.
• Consent management: Users configure granular consent for each category of data processing: conversation storage, personalization learning, analytics, and third-party integrations.
• Data residency: Enterprise users choose which geographic region (US, EU, Asia-Pacific) stores their data, supporting data sovereignty requirements.
• Data portability: Export all personal data, conversations, and memories at any time in standard formats (JSON, Markdown).
• Data deletion: Request deletion of all personal data, triggering verifiable deletion across all storage systems within 30 days.
• Audit logging: Complete, tamper-evident logs of all data access and processing operations for compliance reporting.

13.2 Security Features#

• API key management: Generate, scope, and revoke API keys from the developer dashboard with configurable per-key permission sets.
• Rate limiting: Per-user and per-IP rate limiting to prevent abuse and enforce fair usage quotas.
• Secret detection: Automatic scanning of user inputs for accidental inclusion of credentials, API keys, and other sensitive data, with warning and optional redaction.
• Sandboxed execution: All agent tool invocations and code execution run in isolated sandboxes with no access to host system resources outside the permitted scope.
• Role-based access control (RBAC): Enterprise deployments define roles with specific permission sets — a "viewer" role can read conversations but cannot create API keys or modify settings.

13.3 Compliance#

13.4 Rate Limits and Quotas#

Default per-user limits by plan tier. Enterprise limits are configurable per contract. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-Token-Budget-Remaining headers.

14. Accessibility#

Iris is designed to be usable by everyone, with comprehensive support across all disability categories built into the core design rather than added as an afterthought.

14.1 Visual Accessibility — @iris/accessibility#

• Screen reader support: Full compatibility with VoiceOver (macOS/iOS), NVDA and JAWS (Windows), and TalkBack (Android). All interactive elements have correct ARIA labels and roles.
• High contrast mode: Enhanced contrast themes for low-vision users, including both high-contrast dark and high-contrast light themes.
• Scalable text: Text size scales throughout the entire interface in response to system font size settings or in-app size controls.
• Color blind modes: Alternative color themes for protanopia (red-green), deuteranopia (green-red), and tritanopia (blue-yellow) color vision deficiencies.
• Braille display support: Compatible with refreshable Braille displays through standard screen reader interfaces.

14.2 Motor Accessibility#

• Complete keyboard navigation: Every feature and action in Iris is accessible via keyboard alone — no mouse required. Tab order is logical and follows visual layout.
• Switch access: Support for single-switch and multi-switch scanning input methods used by users with limited motor control.
• Dwell control: Activate interface elements by hovering for a configurable dwell duration, supporting users who cannot physically click.
• Customizable shortcuts: Define custom keyboard shortcuts for any frequently used action.

14.3 Hearing Accessibility#

• Closed captions: Real-time synchronized captions displayed during AI voice response playback.
• Visual notifications: All audio notifications have visual counterparts (flashes, animated indicators) ensuring deaf users do not miss alerts.
• Conversation transcripts: Full text transcripts of voice conversations, downloadable as plain text or Markdown.

14.4 Cognitive Accessibility#

• Simplified interface mode: An optional simplified layout that reduces visual complexity, removes decorative elements, and presents only core features.
• Reading level adjustment: Request AI responses at a specific reading level — from simple (Grade 3) to technical (Graduate level).
• Step-by-step mode: Break complex instructions into individually confirmed steps, presenting one step at a time.
• Summary mode: Get a concise summary of any long response with a single click.
• Reduced motion mode: Disable all non-essential animations and transitions for users sensitive to motion.

14.5 Language Accessibility#

• 100+ languages: AI conversation and understanding in over 100 languages with high-quality comprehension.
• RTL layout support: Full right-to-left text direction support for Arabic, Hebrew, Persian, and other RTL languages, including mirrored UI layouts.
• Automatic language detection: Iris detects the language of each message and responds in the same language without requiring manual selection.

15. Personalization#

Iris adapts to each user over time, becoming progressively more useful as it learns individual preferences and working patterns through the memory and conversation systems.

• Communication style learning (@iris/personalization): Iris learns whether a user prefers formal or casual language, concise or detailed responses, technical or accessible explanations — and applies these preferences automatically in future sessions.
• Domain expertise modeling: As users demonstrate knowledge in specific areas, Iris adjusts the complexity and depth of explanations in those domains without being asked.
• Tool preference memory: Iris remembers which tools, workflows, and approaches each user gravitates toward and suggests or defaults to those in relevant contexts.
• Schedule awareness: Iris considers the time of day, day of week, and typical usage patterns to calibrate response urgency and style.
• Automatic context carry-over: Important context from past conversations (ongoing projects, recurring challenges, established preferences) is automatically carried into new conversations without the user needing to re-explain.
• Proactive suggestions: Based on observed patterns, Iris proactively surfaces relevant information or suggests next actions before being asked — analogous to a well-attuned human assistant anticipating needs.

16. Analytics and Insights#

Understand how AI assistance is being used and track the value it delivers to individuals and organizations.

16.1 Usage Analytics — @iris/analytics#

• Conversation metrics: Total conversations started, average length, messages exchanged, and time spent per session over configurable date ranges.
• Model usage breakdown: Which AI models are being used most frequently, enabling cost allocation and optimization decisions.
• Token consumption: Track token usage per model, per conversation type, and per user for budget management and billing reconciliation.
• Response quality tracking: User ratings on individual responses are aggregated into quality trend reports.
• Usage patterns: Heatmaps and trend charts showing when Iris is used most heavily, which features are most popular, and how usage evolves over time.

16.2 Productivity Insights#

• Time saved estimates: Statistical models estimate how much time Iris assistance saves compared to completing tasks without AI help.
• Task completion rates: Track the percentage of AI-assisted tasks that are marked as successfully completed by users.
• Knowledge base utilization: Which documents are most frequently retrieved and cited, identifying the highest-ROI knowledge assets.
• Agent performance comparison: Compare different agent configurations on key performance metrics — satisfaction score, task completion rate, average session length.

16.3 Advanced Analytics#

• A/B testing framework: Compare different model configurations, prompt variants, or agent behaviors on controlled user cohorts with statistical significance testing.
• Cohort analysis: Segment users by onboarding date, use case, or organization and compare behavior and outcome metrics across cohorts.
• Funnel analytics: Define user journey funnels and measure completion rates at each step.
• Real-time dashboards: Live monitoring dashboards for active session counts, message rates, error rates, and latency percentiles.

17. Cross-Platform Presence#

17.1 Notifications and Presence — @iris/presence-sync, @iris/presence-integration#

• Task completion alerts: Push notifications when background agent tasks (long research sessions, code generation jobs, batch processing) finish running.
• Multi-device sync: Conversation state, preferences, and ongoing tasks synchronize instantly across all the user's signed-in devices.
• Online/offline status: Iris adapts its behavior to network availability — queuing requests when offline and flushing when connectivity returns.
• Cross-platform notifications: Native notification integration on all platforms (iOS, Android, macOS, Windows, browser) ensures alerts reach the user wherever they are.

18. Integrations#

Iris integrates primarily with the other Oshun domains through dedicated bridge libraries, and exposes a webhook surface (@iris/platform-webhooks) for external systems.

The domain boundary is deliberate: each Oshun domain (Psyche, Sophia, Maya, etc.) has its own specialized product logic, but none of them should own a separate AI conversation stack. Instead, they depend on Iris for everything related to model access, memory, and agent execution, and connect via typed bridge packages that encapsulate the Iris API contract. This keeps AI infrastructure centralized and consistently versioned, while allowing each domain to build its own UX on top of shared capabilities. Third-party SaaS connectors (Slack, Teams, Jira, GitHub, etc.) are planned but not yet implemented in libs/iris.

18.1 Cross-Domain Bridges — @iris/integrations-*#

libs/iris/integrations/ contains one bridge package per sister Oshun domain — these are cross-Oshun-domain bridges, not third-party SaaS connectors. Each package owns the typed contract that lets the corresponding domain use Iris capabilities without depending directly on @iris/api internals:

There is no top-level @iris/integrations package, and no Slack / Microsoft Teams / Notion / Jira / GitHub / Confluence connector exists in libs/iris. Third-party SaaS connectors of that kind are planned, not implemented.

18.2 Webhooks and API Access#

• Webhook support (@iris/platform-webhooks): Outbound webhooks that notify external systems of Iris events for integration with custom workflows.
• API-first design: Iris capabilities are exposed through the @iris/api REST + GraphQL service so teams can embed Iris functionality in their own products and internal tools.

18.3 Domain Event Vocabulary#

@iris/types (events.ts) defines the domain-event type system using a CloudEvents-style DomainEvent<T> model. This gives every Iris event a consistent envelope (id, type, category, aggregateId, payload, metadata) that any consumer can parse without knowing the specific event schema upfront. The interfaces IEventBus and IEventStore define the publish/subscribe and append/replay contracts, while per-category event-type literals such as conversation.created, message.created, memory.summarized, task.completed, and tool.completed form the typed vocabulary.

The shared cross-domain transport is the Redis-backed @oshun/event-bus (libs/shared/event-bus). No libs/iris package publishes onto that bus today, and there are no Kafka topics — event publication from iris services is planned.

19. Developer Platform#

Full developer access for building custom integrations, agents, and applications on top of Iris.

19.1 SDK and API#

• Typed REST API: Complete REST API with OpenAPI specification for all Iris capabilities — conversations, memory, knowledge, agents, analytics.
• SDK (@iris/sdk): TypeScript SDK providing typed methods for every API endpoint with built-in authentication, retry logic, and pagination handling.
• WebSocket API: Real-time streaming API for conversation responses, agent progress updates, and event notifications.
• gRPC API: High-performance gRPC interface for server-to-server integrations requiring low latency.

19.2 Testing and Configuration#

• Testing library (@iris/testing): Utilities for writing unit and integration tests for agent workflows and knowledge retrieval pipelines — including mock providers and conversation simulators.
• Configuration library (@iris/config): Typed configuration management for all Iris service settings with environment variable support and validation.
• Developer portal: Interactive API playground, SDK documentation, usage dashboards, and API key management in a self-service web interface.

19.3 Platform Providers#

• Conversation providers (@iris/conversation-providers-anthropic, @iris/conversation-providers-openai, @iris/conversation-providers-google, @iris/conversation-providers-local): Individual provider adapters exposing a uniform interface regardless of which model is in use.

20. Wearable and XR#

Dedicated experiences for extended reality headsets and wearable devices.

20.1 Wearable Features#

• Wrist-based interaction: Compressed AI responses optimized for small screen formats and glanceable consumption.
• Haptic feedback: Use device haptics to signal AI response completion, task updates, and notification delivery on wearable devices.
• Voice-first on wearable: On smartwatches where typing is impractical, voice input is the primary interaction mode with one-word command recognition.

20.2 XR Features#

• Spatial conversations: In XR environments, Iris renders as a spatial entity with positional audio that sounds like it comes from a specific direction in the user's space.
• Environment awareness: The AI receives context about the XR environment — what the user is looking at, spatial objects nearby — and incorporates this into responses.
• Collaborative XR: Multiple users in the same XR space can interact with a shared Iris instance, enabling collaborative AI-assisted workflows in virtual environments.

Library Summary#

libs/iris/** holds 258 packages organized into roughly 20 functional clusters. The table below lists the representative packages by cluster, with their filesystem path and primary capability. Package names are taken from the package.json name field — several do not match their directory path (for example, @iris/knowledge lives at knowledge/core, and @iris/voice lives at multimodal/voice/recognition), and a few clusters have no single umbrella package. The full inventory and counts are in DOMAINS/iris/specifications.md §14.

Planned Concordia Mediation Assistant#

The Concordia domain handles cross-domain dispute resolution — contract disagreements, community moderation appeals, structured negotiations — but it needs conversational scaffolding to guide the parties through intake, agreement drafting, and consent. That conversational layer lives in Iris rather than Concordia because Iris already owns model routing, memory, multilingual support, and consent management; Concordia only needs the orchestration and agreement search logic.

Phase 179 adds planned Iris Concordia capabilities under libs/iris/concordia-assistant/. Iris owns the conversational surfaces for party-isolated private intake, low-stakes conflict brainstorming, two-device or multi-device participant flows, "turn this conversation into a structured agreement" commands, meeting co-mediator mode, consent disclosures, and inappropriate-case routing to human or professional support. The Concordia domain owns the orchestration and agreement search; Iris owns assistant UX, conversation state, model routing, multilingual interaction, and participant controls.

V2 now consumes @iris/concordia-assistant through @v2/concordia-substrate for anti-cheat appeals, tournament-result disputes, and crew conflicts. The V2 integration uses Iris consent-gated intake flows, canonical prompt scripts, and party-isolated prompt contexts to scaffold appellant / arbiter dialogue while exposing only sealed private-context refs to the dispute surface.

V2 Real-Time Translation Bridge#

The V2 fighting-game platform serves a global audience across dozens of languages. Rather than each broadcast surface owning its own translation pipeline, V2 routes all real-time language work through Iris's voice and translation stack, keeping the translation logic in one place and benefiting from Iris's provider failover and latency budgeting.

@v2/iris-realtime-translation composes @iris/voice for V2 spectator chat translation and commentary localization. It routes per-recipient target languages for chat, commentary subtitles, broadcast overlays, and companion second-screen feeds, preserves failed-delivery metadata during provider outage, and remains presentation-only and off rollback.

Domain Boundary Summary#

Iris owns the assistant interfaces, conversation engine, memory system, agent orchestration, model routing, and all related UX. Neighbouring domains own adjacent concerns: Nous owns model serving, training, and on-device inference; Sophia owns research knowledge and academic knowledge bases; Concordia owns cross-domain bargaining orchestration and agreement search; Psyche owns embodied virtual-assistant behavior and avatar rendering. Iris integrates with each of these through typed bridge packages rather than owning their domains.

Neural World Model Look-Ahead (Phase 176)#

Iris is a co-owner of the neural world models track (Phase 176, centered in Nous). Iris's side is the look-ahead planner: the assistant uses Nous world-model imagine() rollouts to plan multi-step tool actions before executing them, distinguishing confident predictions from uncertain extrapolation via the model's uncertainty signal. Nous owns the world model; Iris owns the planning-and-execution loop.