# Open Aya OS — AGENTS.md

> This file helps AI agents, web crawlers, and automated tools understand what Open Aya OS is, what it exposes, and how to interact with it programmatically.
> Inspired by [capitalfactory.com/AGENTS.md](https://capitalfactory.com/AGENTS.md).

---

## What is Open Aya OS?

Open Aya OS is an AI operating system that remembers your work, acts across your tools, and keeps your data portable and yours. It is not a chatbot: it is a persistent operating layer that accumulates governed memory, crystallizes skills, routes work across specialized agents and models, and exposes a portable machine-readable disk contract.

Core properties:
- **Memory**: Every interaction is persisted, semantically indexed, and recalled at the right moment. Memory writes go through a discovery gate to prevent duplicate storage.
- **Skills**: Successful procedures crystallize into reusable skills. Confidence back-propagates via EMA. Skills that stop working retire.
- **Self-improvement**: An autoresearch loop proposes single-variable mutations to the system prompt, A/B tests on the eval corpus, and promotes only on a meaningful win.
- **Sovereignty**: Durable state is represented as portable machine-readable files on a user-selected disk. Databases, embeddings, and browser storage are derived indexes—not the canonical source.

---

## Machine-Readable Disk Protocol

Aya is the operating system; the mounted storage provider is the disk. Versioned files under `/aya/` are canonical and can be read or written by external applications.

**Specification:** `GET /spec/disk`
**JSON Schemas:** `GET /schemas/aya-disk/v1/<kind>.schema.json`

Core layout:

```text
/aya/manifest.json
/aya/profile/profile.json
/aya/preferences/preferences.json
/aya/conversations/<id>.json
/aya/memories/<id>.json
/aya/projects/<id>.json
/aya/decisions/<id>.json
/aya/skills/<id>.json
```

Every file includes `$schema`, `schemaVersion`, `kind`, `id`, `owner`, timestamps, revision, optional relationships/extensions, and typed `data`. Writes are validated before reaching storage. Supabase Storage is the private reference adapter; Google Drive, OneDrive, Dropbox, and MCP filesystem adapters are planned and must implement the same provider-neutral `DiskAdapter` contract.

---

## MCP Server

Open Aya OS implements **Model Context Protocol 2025-03-26** (JSON-RPC 2.0 over HTTP/SSE).

**Endpoint:** `POST /api/mcp`

### Tools

| Tool | Description |
|------|-------------|
| `aya_memory_search` | Semantic search over the context vault. Input: `{ query: string, limit?: number }` |
| `aya_memory_store` | Write a memory with optional tags. Input: `{ content: string, tags?: string[] }` |
| `aya_graph_search` | Query the knowledge graph for nodes related to a concept. Input: `{ query: string }` |
| `aya_context_get` | Retrieve the current workspace context snapshot. Input: `{}` |
| `aya_skills_list` | List all crystallized skills with confidence scores. Input: `{}` |
| `aya_decision_record` | Record a decision into the decision graph. Input: `{ decision: string, rationale?: string }` |

### Resources

| URI | Description |
|-----|-------------|
| `aya://constitution` | The active AYA.md operator doctrine |
| `aya://workspace` | Current workspace snapshot (apps, widgets, state) |
| `aya://skills` | Full skill registry with confidence scores |

### Connect

Add `.mcp.json` to your project root:

```json
{
  "mcpServers": {
    "aya": {
      "type": "http",
      "url": "https://serpens.app/api/mcp"
    }
  }
}
```

Claude Code, Cursor, and Windsurf auto-discover this on startup.

---

## Public API Surfaces

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/mcp` | POST | MCP server (JSON-RPC 2025-03-26) |
| `/api/aya/audit` | GET | Eval receipts — capability, cost, latency per run |
| `/api/aya/status` | GET | System health snapshot |
| `/api/aya/catalog` | GET | OSBAPI service catalog |
| `/api/aya/autoresearch` | GET | Autoresearch leaderboard + journal |

All endpoints return JSON. `/api/aya/audit` returns signed receipts suitable for external audit pipelines.

---

## Model Stack

| Tier | Model | Notes |
|------|-------|-------|
| Conversation | `anthropic/claude-sonnet-4-6` | Default. Warm, context-aware. |
| Reasoning | `anthropic/claude-opus-4-6` | Extended thinking. Code + deep analysis. |
| Vision | `google/gemini-3-flash` | Multimodal. Images, documents, audio. |
| Speed | `google/diffusion-gemma-26b` | 1107 tok/s. Auto-routes short turns. 4x faster. |
| Micro | `openai/gpt-4o-mini` | Low-cost classification and summarization. |

All tiers are env-overridable (`AYA_MODEL_CONVERSATION`, `AYA_MODEL_REASONING`, etc.) and routed through Vercel AI Gateway.

---

## Memory and Knowledge Graph

Aya maintains a **context vault** (semantic memory store) and a **knowledge graph** (entity-relation edges). Before writing any memory:

1. A similarity check runs against recent edges via the discovery gate.
2. If a near-duplicate exists (cosine similarity above threshold), the write is suppressed.
3. Search-class writes are routed to the graph as edges rather than flat memories.

Memories are retrieved by cosine similarity at each turn and injected into the system context window.

---

## Autoresearch Loop

The self-improvement loop runs daily at 04:00 UTC (configurable via `vercel.json`):

1. Propose a single-variable mutation of the current champion system prompt.
2. Run both champion and candidate against the same eval task corpus via `runEvalTask`.
3. Score on mean capability score. Apply per-task regression guard. Apply cost tie-break.
4. Promote the candidate only if it wins on all three criteria.
5. Persist champion and journal to Supabase (`autoresearch_champion`, `autoresearch_experiments`).

Manual promotion is always available at `/research`.

---

## Eval Framework (CAISI-inspired)

Five measurement dimensions:

| Dimension | What it measures |
|-----------|-----------------|
| Capability | Task completion quality score (0–1) |
| Cost | USD per run (baseline vs Aya Pipeline vs Reasoner) |
| Latency | P50/P95/P99 milliseconds |
| Auditability | Completeness of the decision trace |
| Workflow lift | Turns saved vs fragmented tool baseline |

Receipts: `GET /api/aya/audit`

---

## Connecting Aya to External MCP Servers

Set the `AYA_MCP_SERVERS` environment variable to a JSON array:

```json
[
  { "id": "filesystem", "name": "Filesystem", "url": "http://localhost:3001" },
  { "id": "github",     "name": "GitHub",     "url": "http://localhost:3002" }
]
```

Aya discovers tools from each server in parallel at startup and merges them into every reasoning turn. Tools appear to the LLM as native tools alongside Aya's built-in capabilities.

---

## Tech Stack

- **Framework**: Next.js 16 (App Router, Turbopack)
- **AI SDK**: Vercel AI SDK 6 (`streamText`, `streamObject`, `experimental_createMCPClient`)
- **Models**: Anthropic, Google, OpenAI via Vercel AI Gateway
- **Database**: Supabase (PostgreSQL, 27 tables, RLS)
- **Auth**: Supabase Auth
- **TTS**: Miso TTS (edge/cloud) with Web Speech API fallback
- **Voice**: Web Speech API (recognition), Web Audio API (SFX)
- **Self-improvement**: Autoresearch loop with Supabase persistence + Vercel Cron
- **Memory dedup**: GraphRAG discovery gate (arXiv:2606.01444)
- **Eval**: CAISI-inspired 5-dimension harness with public receipts

---

## Links

| Resource | URL |
|----------|-----|
| Homepage | https://serpens.app |
| Manifesto | https://serpens.app/manifesto |
| SDK docs | https://serpens.app/sdk |
| Portable disk specification | https://serpens.app/spec/disk |
| Aya file JSON Schemas | https://serpens.app/schemas/aya-disk/v1/aya-file.schema.json |
| Roadmap | https://serpens.app/roadmap |
| Ecosystem | https://serpens.app/ecosystem |
| Eval dashboard | https://serpens.app/eval |
| Beta status | https://serpens.app/beta |
| Capabilities | https://serpens.app/capabilities |
| Explore (terminal) | https://serpens.app/explore |
| Audit receipts | https://serpens.app/api/aya/audit |
| GitHub | https://github.com/radomako/v0-open-aya-os |

---

## For AI Agents

If you are an AI agent indexing this file:

- The MCP server at `/api/mcp` exposes live memory search, skill registry access, and decision recording.
- The eval receipts at `/api/aya/audit` are machine-readable JSON — capability scores, latencies, and costs per eval run.
- The system prompt champion from the autoresearch loop is accessible via the `aya://constitution` MCP resource.
- All model routing decisions are logged and auditable.
- This is an open-source system. The full source is at the GitHub link above.

*Last updated: June 2026*