KontextOS Architecture

A Contextual Operating System for Applied AI

Purpose and Status

KontextOS is infrastructure for creating, governing, retrieving, sharing, and evolving organizational context. It is not merely a chatbot, prompt library, course platform, or thin interface around a language model.

The architecture is based on a simple observation:

AI systems rarely fail because they lack intelligence. They fail because they lack the right context, authority, history, or connection to the work being performed.

Organizations already possess policies, procedures, decision frameworks, workflows, learning materials, operational data, and institutional memory. That context is often fragmented across documents, applications, conversations, and individual experience. KontextOS provides a persistent and governed context layer between the organization and the AI systems it uses.

This document describes both the implemented foundation and the target architecture. The browser-based Django application, structured domain data, knowledge and reference content, permission controls, personas, audit records, and Retrieval-Augmented Generation (RAG) capabilities form the current foundation. The Context Memory Ledger and native Model Context Protocol (MCP) integration described below are planned capabilities and are not currently available.

Architectural Principles

Context Lives Where Work Happens

Context creates value when it participates in real learning, analysis, governance, and decision workflows. KontextOS therefore uses the web browser as its primary human interface. The browser provides cross-platform access, low deployment friction, and a practical integration point for the systems in which organizations already work.

The browser is not the only future interface. AI clients and organizational systems will also need governed, machine-readable access. Planned MCP support extends the same context and governance architecture beyond the browser without making the browser or any single AI provider the owner of organizational knowledge.

Intelligence Is Replaceable; Context Endures

AI models, providers, prices, and capabilities change rapidly. KontextOS treats models as replaceable execution services and organizational context as the durable asset.

This separation supports:

• Model and provider portability

• Preservation of institutional knowledge

• Lower migration costs

• Inspectable inputs and outputs

• Deployment choices appropriate to organizational risk

• Long-term architectural stability

The strategic goal is not dependence on a particular model. It is organizational ownership of the context, permissions, provenance, and workflows that allow models to operate effectively.

Canonical Context Outranks Episodic Context

KontextOS distinguishes two classes of context:

• Canonical context is approved, current, and authoritative knowledge, such as policies, reference documents, course content, role definitions, governance rules, and approved workflows.

• Episodic context is evidence of what happened over time, such as decisions, revisions, AI sessions, learner interactions, support incidents, rejected proposals, and implementation notes.

Episodic context can explain what was tried, why a decision was made, or what was true at a particular time. It must not silently override current canonical context. Retrieval, prompt construction, and user interfaces must preserve this distinction and show status, time, source, and supersession information.

Governance Precedes Retrieval and Action

Finding relevant information is not enough. Every request for context or action must first be bounded by organization, identity, role, purpose, sensitivity, and deployment boundary.

Authorization must be applied before ranking or packaging results, not after potentially sensitive data has already been retrieved. The same rule applies to planned MCP resources and tools: protocol connectivity never bypasses KontextOS governance.

Provenance Is Part of the Answer

Retrieved context must retain enough metadata for a person or AI system to evaluate it. Depending on the source, this includes its title, source type, source identifier, timestamp, actor or role, canonical status, trust level, sensitivity level, and links to superseded or superseding records.

AI output should cite the context it relies upon. It should distinguish authoritative knowledge from historical, raw, rejected, superseded, or uncertain evidence.

Capture Selectively and Minimize Context

KontextOS should not retain every interaction indefinitely or place entire transcripts into model prompts. Capture should focus on meaningful event types, apply retention and redaction rules, and exclude secrets and credentials. Retrieval should package the smallest sufficient set of permitted sources, expanding raw material only when needed.

Architecture at a Glance

This flow is a target architecture. Today, functionality is delivered through the Django web application and its existing data, governance, RAG, persona, learning, and audit capabilities. The ledger and MCP paths will be introduced incrementally.

Core Architectural Layers

Experience Layer

The experience layer provides role-appropriate interfaces for learners, course authors, staff, administrators, and organizational participants. It includes learning, simulations, knowledge and reference workflows, governance views, reports, context boards, and AI-assisted interactions.

All user-facing interfaces should remain translatable. Presentation concerns should not become the source of truth for authorization, provenance, or lifecycle state.

Canonical Context Layer

The canonical context layer stores and organizes approved organizational knowledge, including:

• Courses and lessons

• Knowledge bases and reference documents

• Policies and procedures

• Workflows and governance rules

• Personas and role definitions

• Organizational datasets

• Decision records and approved artifacts

• Rubrics, assessments, and diagnostic structures

These are first-class domain objects rather than undifferentiated prompt text. Their structure, ownership, revision state, and access rules allow the same knowledge to be reused by people, retrieval services, AI workflows, and future protocol clients.

Retrieval and Context-Packaging Layer

The existing retrieval layer uses RAG capabilities to index and retrieve course and organizational knowledge. The target retrieval architecture combines relevance with governance and provenance rather than treating similarity as sufficient.

The retrieval sequence should be:

1. Resolve the requesting identity, organization, role, and purpose.

2. Remove sources outside the requester's authorization and sensitivity boundary.

3. Search canonical and, when enabled, episodic sources.

4. Rank current canonical sources above historical evidence.

5. Package compact excerpts with citations and status metadata.

6. Send only the necessary package to the selected model or AI workflow.

7. Record the query, sources, model interaction, result, and relevant governance events according to policy.

Keyword search and semantic retrieval may both contribute to relevance. Neither is allowed to weaken access control or the canonical-first ranking policy.

Persona Layer

Personas define specialized AI participants with role-specific objectives, expertise, behavior, and constraints. Examples include an AI teacher, compliance reviewer, course-author assistant, executive advisor, or support assistant.

A persona does not grant authority. It operates within the permissions of the requesting user and workflow, and it receives only context permitted for that request. Persona instructions are subordinate to governance policies and source status.

Governance and Trust Layer

The governance layer supplies the controls that turn stored information into safe organizational context. It includes:

• Authentication and organization isolation

• Role-based authorization

• Context ownership and sensitivity labels

• Review, approval, rejection, and supersession workflows

• Auditability and decision accountability

• Retention, deletion, anonymization, and redaction

• Source provenance and trust classification

• Customer, cloud, hybrid, and on-premises boundaries

Governance applies consistently across the browser, application services, retrieval, model calls, the planned ledger, and planned MCP connections.

Orchestration and Model Layer

The orchestration layer coordinates users, workflows, personas, retrieved context, connected tools, and model services. It decides which approved sources to package, which persona and model configuration to use, whether an external tool is eligible, and what must be recorded.

Model adapters should isolate provider-specific APIs from domain and governance logic. A model processes a bounded context package; it does not become the system of record and must not be assumed to remember prior interactions.

Integration Layer

KontextOS integrates with storage, email, data, model, and operational services through explicit adapters. Planned MCP support adds a standard protocol boundary for AI-oriented resources and tools while keeping authorization, policy, provenance, and audit decisions inside KontextOS.

Planned Context Memory Ledger

The Context Memory Ledger is the planned governed episodic-memory layer for KontextOS. It will turn selected organizational activity into searchable, permission-aware, provenance-rich events.

The ledger is not generic chatbot memory and is not a second source of unchecked truth. Its purpose is to preserve historically meaningful evidence while making its status and relationship to canonical context explicit.

Event Model

An initial ledger implementation will use Django models and PostgreSQL rather than a graph database or specialized memory platform. A context event should include, at minimum:

• Organization and permitted audience

• Actor, source type, and source identifier

• Event type, title, summary, and optional raw content

• Event time, creation time, and optional validity window

• Canonical status and trust level

• Sensitivity level

• Tags and structured metadata

• Supersession relationships

Candidate events include decisions, rejections, revisions, analyses, incidents, governance actions, workflow events, integration events, support events, and implementation notes.

Event Lifecycle

The planned lifecycle is:

    raw -> reviewed -> promoted to canonical context
    raw -> rejected
    raw -> archived
    reviewed or promoted -> superseded

Promotion does not make an activity log authoritative by relabeling it alone. The promoted event should become or point to an appropriate canonical artifact, such as a reference document, decision record, policy revision, implementation note, or support article.

Ledger Ingestion and Retrieval

Ledger writes should pass through a service layer so capture rules, redaction, metadata, and audit behavior remain consistent. Event capture should begin with a narrow set of high-value staff and admin workflows rather than indexing all application activity.

The initial search implementation will use PostgreSQL full-text search with organization, permission, event type, status, trust, sensitivity, source, and date filters. Hybrid semantic search may be added later. Context packages should contain compact summaries first and raw text only when justified.

Future as-of retrieval should support questions about what the organization believed or had approved at a past date. That capability depends on immutable event time, validity windows, version history, canonical state, and supersession links.

Ledger Security and Privacy

The ledger must never be a global pool of memory. It requires strict organization isolation, role-aware retrieval, sensitivity labels, retention policies, redaction, exclusion rules, deletion or anonymization workflows, and auditable access.

Secrets, passwords, API keys, and credentials must not be indexed. Highly sensitive data should be excluded unless a defined use case, lawful basis, retention rule, and access policy justify capture.

Incremental Delivery

The planned implementation sequence is:

1. Capture selected staff/admin events and provide permission-aware search.

2. Add review, rejection, promotion, supersession, and archive workflows.

3. Package ledger results for selected internal AI actions.

4. Add tightly filtered learner-safe use cases.

5. Add governance and context-health views, such as pending reviews and stale or superseded context.

Planned Model Context Protocol Integration

MCP standardizes how AI applications discover and use external resources, prompts, and tools at runtime. It is a transport and capability interface; it does not by itself decide which organizational knowledge is authoritative, who may access it, or whether an action is appropriate.

KontextOS will use MCP as a governed boundary, not as a bypass around application services.

KontextOS as an MCP Server

The planned MCP server interface can expose permitted KontextOS capabilities to compatible AI clients. Examples include:

• Read-only resources for approved reference documents, courses, policies, and packaged context

• Search tools that apply organization and permission filters before retrieval

• Ledger queries that return cited historical evidence with status metadata

• Governed workflow tools for narrowly defined actions

The MCP interface should call the same domain, authorization, retrieval, and audit services used by the web application. It should not query unrestricted tables or duplicate business rules in a protocol-specific layer.

KontextOS as an MCP Client

The planned MCP client capability can allow KontextOS workflows to retrieve resources from or invoke tools in approved external systems. External results should carry source and connection metadata and should be treated as untrusted until policy, validation, and workflow rules establish otherwise.

Each connection should define:

• Owning organization and administrators

• Allowed resources and tools

• User or service identity mapping

• Credential storage and rotation policy

• Read and write scopes

• Sensitivity and retention treatment

• Timeouts, rate limits, and failure behavior

• Audit and revocation requirements

MCP Request Flow

A planned MCP request should follow this sequence:

MCP client or KontextOS workflow
        -> authenticate connection and resolve organization
        -> authorize the requested resource or tool
        -> retrieve and rank canonical or episodic context as permitted
        -> validate parameters and apply action policy
        -> return a minimal result with provenance
        -> record access, tool execution, result, and failure state

Read access and tool execution have different risk profiles. Tools that create, modify, send, approve, or delete information require narrow schemas, explicit scopes, validation, idempotency where applicable, and confirmation or approval controls proportionate to impact.

Relationship Between MCP and the Ledger

MCP and the Context Memory Ledger solve different problems:

MCP may deliver canonical context or permission-filtered ledger evidence to an AI client. MCP activity may also generate ledger events, such as an external resource connection, a consequential tool call, or a failed integration. The ledger does not replace MCP, and MCP does not replace the ledger.

For additional product framing, see MCP and the Future of Contextual AI in KontextOS.

Why Django and Python

KontextOS uses Django because governed context requires explicit data models, mature authentication and authorization patterns, migrations, administration, form handling, security controls, and long-term maintainability.

Django's model-centric design supports structured representations of courses, documents, personas, organizations, governance records, retrieval indexes, and future ledger events. Its service and application boundaries allow the browser UI, background work, AI orchestration, and planned MCP interfaces to reuse the same domain rules.

Python provides access to the wider AI, data, automation, and scientific-computing ecosystem. Provider and protocol integrations should remain adapters around KontextOS domain services so that framework convenience does not create model or vendor lock-in.

The platform can remain a cohesive Django deployment while its internal domains are separated through models, services, permissions, and stable interfaces. Additional infrastructure should be introduced in response to demonstrated operational requirements rather than assumed in advance.

Storage and Search Strategy

Relational data remains the source of truth for domain state, governance, provenance, and ledger metadata. Document or object storage holds source files where appropriate. Search indexes and vector stores are derived retrieval structures and must be rebuildable from governed source data.

The architecture should preserve these distinctions:

• Deleting or restricting a source must propagate to derived search data.

• An embedding is not an authority record and must retain a link to its source.

• Cached or packaged context must not outlive its authorization or retention boundary.

• Backups and restores must preserve organization isolation, version history, and audit requirements.

Deployment Architecture

Deployment is product-specific and evidence-gated. KontextOS does not currently offer cloud, on-premises, and hybrid deployment as three interchangeable, production-ready choices. The controlling adoption path is:

    Free Organizational Simulation
        -> Private Diagnostic Appliance
        -> Persistent KontextOS License

Each stage has a different data boundary, purpose, and implementation status.

Hosted Free Organizational Simulation

The current hosted product boundary is the Free Organizational Simulation. It is an organization-scoped entitlement rather than a recurring subscription and is limited to Intro to Applied AI in simulation mode for no more than three participants per simulated organization.

This describes the controlling product boundary, not an unconditional readiness claim. The simulation is operational only when its setup, persistence, authorization, enrollment, course, poll-analysis, dashboard, and end-to-end acceptance requirements have passed.

This environment is designed for fictional organizational data. One designated Course Coordinator configures the simulated organization, and the application generates fictional company context, roles, an employee roster, and course-poll responses. Users must not enter confidential or identifying information about a real organization, and simulation results must not be represented as an assessment of one.

The simulated-company document is a durable course artifact. Its bytes are stored in DigitalOcean Spaces, while application data retains its organization, course, ownership, status, version, and object reference. Access is restricted to the simulated organization's enrolled participants and authorized KontextOS administrators. Generated, participant-supplied, simulated, current, and planned content must remain visibly distinct.

The hosted simulation demonstrates the KontextOS method. It is not the deployment environment for real-organization diagnosis, the Context Memory Ledger, or persistent organizational operation.

Early-Testing Private Diagnostic Appliance

The Private Diagnostic Appliance is the early-testing paid environment for one course-led diagnostic using real organizational evidence. It is designed to run inside infrastructure controlled by the customer. The customer controls the infrastructure, supported AI-provider account, evidence, findings, retention, and exports.

The appliance should collect structured participant responses, compare perspectives across roles and functions, generate traceable candidate findings, require human review, and permit only customer-approved exports. Sensitive poll responses, prompts, model outputs, evidence, and unapproved findings should remain inside the customer boundary.

KontextOS licenses the appliance software. The customer operates the cohort through the self-service workflow. A qualified IT-services partner may separately scope optional installation, configuration, integration, remediation, training, and support. Partner service effort does not create separate appliance software tiers.

The application and deployment package are now in early testing. The initial appliance architecture uses a signed, containerized application installed with one command on a dedicated, customer-provided Linux virtual machine.

The initial package should use a deliberately small set of containers for the Django web application, background work, PostgreSQL, appliance-local object storage, the AI gateway, HTTPS termination, and signed updates. Persistent data must use explicit customer-controlled volumes so container replacement, application upgrades, backup, restoration, and removal do not obscure where customer data resides.

The supported Linux distribution and container-runtime matrix should remain intentionally small during initial pilots. The installer must perform preflight checks, validate or install the supported runtime, verify signed images and release metadata, configure local HTTPS and secrets, run observable migrations, and produce actionable installation results. Connected and offline installation should use the same signed release artifacts.

Early testing and pilot preflight must confirm the supported release configuration, security evidence, staffing, support, responsibilities, and first-customer requirements before a real-data commitment.

After the signed container installer is stable, the next packaging level is a preconfigured virtual appliance for VMware and Hyper-V. Those images should contain the same signed application release, a hardened Linux baseline, the supported container runtime, first-boot configuration, and documented backup and recovery behavior.

Kubernetes-based packaging is not part of the initial appliance or the next virtual-appliance level. Helm packaging, embedded Kubernetes, and multi-node deployment remain deferred until customer scale or enterprise deployment requirements justify their additional operational complexity. The simple single-VM appliance should remain available for bounded diagnostics even if an enterprise package is introduced later.

Target Customer-Controlled Boundary

The target appliance design separates sensitive diagnostic operations from hosted Simulation Mode. The PDA is never deployed in KontextOS-hosted infrastructure.

The customer-controlled data plane should perform authentication, participant and role management, course and poll delivery, response collection, AI configuration and inference, evidence storage, finding generation, review, redaction, export, and audit logging.

The PDA and Persistent KontextOS must not depend on a KontextOS-hosted control plane. Licensing, approved definition or taxonomy updates, software updates, and support materials must be delivered through customer-initiated, customer-approved mechanisms appropriate to the deployment boundary. Hosted Simulation Mode remains separate and must not receive real organizational responses, diagnostic evidence, findings, or persistent operational data.

Outbound access should be disabled unless explicitly enabled. Customer-authorized model endpoints should be allowlisted, external payloads should be displayed or otherwise inspectable, and telemetry must not include sensitive diagnostic data by default. Storage locations, encryption, backup, export, retention, and removal behavior must be explicit.

This boundary is a target requirement. Early testing does not establish general availability, production validation, or a claim that every planned administration, activation, update, and operational capability is complete.

Planned Persistent KontextOS Deployment

The planned Persistent KontextOS License continues from private diagnosis into context design, remediation governance, technical deployment, and ongoing operation. It includes all three KontextOS courses and positions KontextOS as the customer's durable governed context layer rather than a one-time diagnostic report.

Persistent deployment must remain customer-controlled. Its supported environment, installation model, identity integration, storage, AI-provider configuration, MCP connections, security package, updates, support responsibilities, and service levels must be defined through appliance discovery, partner validation, and early customer evidence. Optional partner services do not change the customer-controlled deployment boundary.

The persistent license must not be represented as a generic hosted subscription or as an already completed on-premises platform. Features needed only for broader persistent operation should follow validated requirements rather than being added to the diagnostic appliance by assumption.

Deployment Sequence and Deferrals

Substantial appliance engineering follows commercial validation rather than preceding it. The intended sequence is:

1. Operate and verify the bounded fictional-data simulation.

2. Validate the appliance proposition and delivery model with qualified partners and prospective customers.

3. Audit the minimum course-and-poll path, dependencies, privacy boundary, appliance-specific Django surface, and provisional Linux and container-runtime matrix.

4. Test the smallest internal prototype that retires the highest-risk product or technical assumption.

5. Isolate and containerize the diagnostic components, then produce the signed one-command installer and connected or offline image bundle for the supported customer-provided Linux VM.

6. Proceed to a guided customer pilot only after secure and reproducible installation, customer-controlled data and export, backup and removal, tested upgrades and rollback, tested model behavior, partner training, support boundaries, and appropriate agreements are credible.

7. Build the preconfigured VMware and Hyper-V appliance only after the containerized pilot workflow and installer are stable.

Broad connectors, enterprise identity, local-model breadth, and generalized enterprise infrastructure remain deferred until validated demand requires them. VMware and Hyper-V packaging is specifically sequenced after installer stability. Kubernetes and multi-node packaging remain deferred until customer scale or enterprise requirements justify them. A narrow prototype or approved architecture does not imply production readiness.

Across every stage, deployment topology must not change the meaning of organization isolation, authorization, canonical status, provenance, human approval, retention, or audit records.

Security and Reliability Boundaries

The architecture assumes that model output, external MCP content, uploaded documents, raw ledger events, and user-supplied text may be incorrect or hostile. Controls should include:

• Server-side authorization for every protected object and action

• Organization isolation in queries, indexes, caches, and logs

• Validation and sanitization at ingestion and execution boundaries

• Prompt-injection-aware handling of retrieved and external content

• Encryption and managed secrets appropriate to deployment

• Audit records for sensitive retrieval and consequential actions

• Timeouts, bounded retries, and failure isolation for external services

• Recoverable workflows for indexing, promotion, supersession, and tool execution

AI reasoning never substitutes for deterministic permission checks or workflow invariants.

Evolution and Compatibility

KontextOS is designed to evolve as organizations, regulations, models, and protocols change. Stable domain models and service boundaries should protect organizational context from changes in AI providers, embedding models, vector stores, protocol libraries, or deployment platforms.

The target architecture creates a continuous but governed loop:

    canonical knowledge + permitted historical evidence + connected tools
        -> retrieval and orchestration
        -> model reasoning or workflow action
        -> cited output and auditable event
        -> human review
        -> corrected, rejected, superseded, or promoted context

This loop is how KontextOS turns isolated AI interactions into durable organizational learning without confusing accumulated history with approved truth.

Architectural Commitments

As KontextOS implements the ledger and MCP roadmap, the following commitments remain constant:

• Organizations own and control their context.

• Canonical context outranks episodic evidence.

• Authorization is enforced before retrieval and action.

• Provenance and lifecycle status travel with context.

• Models and integrations are replaceable adapters, not systems of record.

• Search indexes and context packages are derived from governed sources.

• Historical memory is scoped, selective, reviewable, and subject to retention.

• MCP extends governed access; it does not weaken governance.

• Human accountability remains explicit for consequential decisions and actions.

That is the purpose of KontextOS: not merely to provide access to intelligence, but to provide the durable contextual infrastructure that allows intelligence to create accountable and lasting organizational value.