HeyAira MVP

Purpose

The first HeyAira prototype validates continuity between independent AI work sessions. It is not a complete collaboration platform, an agent orchestrator, or a public multi-tenant service.

Hypothesis

A fresh Codex thread, without the previous thread's conversation, can use a shared MCP service to recover project decisions and task state, check out the referenced Git state, continue the work, and leave a durable handoff for the next thread.

The first validation uses multiple Codex threads. Different models inside the same harness may be tested after the same-model flow works. Different harnesses and model providers are later compatibility stages.

Minimal vertical slice

The first implementation contains only what is required to test the hypothesis:

• one Python MCP server using Streamable HTTP;
• one PostgreSQL database;
• a real remote deployment at https://mcp.heyaira.eu/mcp after the local vertical slice is validated;
• human-readable endpoint and tool documentation suitable for client/lab registration;
• project records, memberships and project-scoped authorization;
• MCP-standard OAuth 2.1 authorization for public clients, with the existing project-scoped Bearer path retained only for internal compatibility;
• append-only memory entries for notes and decisions;
• tasks with status, handoff information, version, and optimistic concurrency;
• work-session receipts identifying the logical worker/thread and Git state;
• repository references, never repository contents;
• Docker Compose for repeatable development and deployment preparation;
• persistence across service restarts.

The database schema may support more than one project, but the first continuity experiment needs only one synthetic test project.

Minimal durable records

Project

• ID and name
• creation timestamp

The project is the tenant and security boundary. A project may have multiple members with roles (owner, admin, contributor, viewer) and multiple repository bindings.

Project membership

• project ID and user/subject ID
• role
• creation and revocation timestamps

Membership is required for project access. A subject may belong to multiple projects, but an OAuth grant is explicitly scoped to the selected project and requested scopes.

Project repository binding

• project ID
• GitHub owner and repository
• repository URL and default branch
• optional GitHub App installation reference
• creation and revocation timestamps

Bindings store references and permissions, never repository contents. A repository may be bound to more than one project.

The authenticated token determines the project. MCP tools do not accept a caller-supplied project ID.

Memory entry

• ID and project ID
• type: note or decision
• title and body
• rationale for decisions
• declared source
• server-generated creation timestamp

Supersession chains, semantic search, embeddings, and automated summaries are deferred until the basic continuity test succeeds.

Task

• ID and project ID
• title and description
• status: todo, in_progress, blocked, or done
• handoff fields: completed work, next step, and blockers
• integer version
• creation and update timestamps

Every update supplies expected_version. A stale update fails atomically instead of overwriting another thread's work.

Task hierarchies, assignment, leasing, scheduling, and notifications are deferred.

Work-session receipt

• ID and task ID
• harness name
• logical session or thread reference
• optional model name
• start and finish timestamps
• starting commit and resulting commit
• branch name
• changed paths and test summary
• completed work, next step, and blockers

The first prototype may use a logical session label such as codex-thread-a when a stable native thread ID is not available. A task can have multiple work-session receipts.

Initial interaction surface

The initial MCP surface should remain small:

• memory: add, get, and search/list recent entries;
• tasks: create, get, list, and update with expected_version;
• work receipts: start and finish a task work session, or an equivalently small append-only receipt operation.

The exact schemas are fixed before implementation. Repository metadata is returned as project/task context; Git operations themselves remain outside HeyAira.

Validation experiment

The experiment uses synthetic data and at least three independent Codex threads.

Before the real-thread experiment, scripts/multi_client_smoke.py provides a reproducible local check with two independent MCP clients. It verifies tool discovery, memory recovery, task recovery, and an atomic version conflict when both clients update the same task from the same starting version.

Thread A: author

1. Records a decision and its rationale.
2. Creates and starts a task.
3. Records a Git starting point and a clear next step.

Thread B: continuation

1. Receives no transcript or manual summary from Thread A.
2. Reads memory and open tasks only through HeyAira.
3. Checks out the referenced repository state.
4. Explains the decision and next step.
5. Performs a bounded change or synthetic work step.
6. Commits the reproducible result and updates the task and work receipt.

Thread C: verifier

1. Receives no transcript from Threads A or B.
2. Reads the current state through HeyAira.
3. Identifies what was done, by which recorded session, at which commit, and what remains.

Thread A then reads the update left by Thread B.

Test isolation

The continuity test is invalid if another channel carries the missing context. During the experiment:

• do not send messages between the test threads;
• do not give later threads summaries of earlier conversations;
• do not store the synthetic test decision in shared repository documentation;
• do not use a common scratch file as memory;
• use separate clean working directories or worktrees where practical;
• make HeyAira the only source of task and memory context;
• use Git only for code and committed file state.

Acceptance criteria

The first hypothesis is confirmed when:

• the MCP server uses a real PostgreSQL database;
• memory and tasks survive a restart;
• an unauthenticated request is rejected;
• a stale task update is rejected without losing the current state;
• Thread B continues work without Thread A's conversation;
• the relevant code state is reproducible from Git references;
• Thread C reconstructs the handoff from HeyAira and Git alone;
• the result clearly records which checks used real Codex threads.

Explicitly deferred

• public UI or website
• advanced account UI, organization administration, and billing
• GitHub API automation, issues, PR creation, and webhooks
• live wake-up or direct messaging of old harness threads
• cross-provider routing
• model-based routing, planning, or task decomposition
• task assignment, leases, queues, and schedulers
• embeddings and vector search
• repository or artifact storage inside HeyAira
• production-grade public HTTPS and DNS configuration
• automatic live wake-up or messaging of a historical harness thread
• open-source release packaging and license selection

Public infrastructure boundary

The product scope is intentionally small, but the first usable deployment is a real remote MCP service rather than a localhost-only demo. PostgreSQL remains private, the MCP service is exposed through HTTPS at the approved domain, and the public documentation describes the protocol endpoint and tools. Cloudflare/DNS and TLS are infrastructure concerns; they do not expand the HeyAira data model.

The public endpoint is accepted only after an external MCP client completes initialization, tool discovery, an authenticated synthetic write/read flow, and an unauthenticated rejection check. No real project data or secrets are used in this test.

Later direction

If the hypothesis succeeds, HeyAira may gain routing models, task queues, harness adapters, asynchronous questions, and the ability to resume addressable sessions. Those are later layers built on the durable state model, not prerequisites for proving it.