# COSMO Ecosystem & Brain Platform Vision

**Document Version:** 1.3  
**Date:** December 24, 2024  
**Status:** Planning / Vision → Ready for Implementation  
**Authors:** JTR + Claude

---

> ### What's New in v1.3
> 
> - **The `.brain` as atomic unit** - Like .mp3 for music, .git for code
> - **Interface vision** - Adaptive workspace, not another developer tool
> - **The Collective** - We release the format, imagination runs
> - **The Unlock** - Minimum Viable Brain Package defined (CLI + library)
> - **Implementation Reality** - 90% reshaping existing data, not building new
> - **V2 Merge done** - All 7 upgrades already in production

---

> ⚠️ **READ THIS FIRST**
> 
> This document contains a mix of:
> - **ACTUAL** - What currently exists in COSMO (verified against code/data)
> - **PROPOSED** - What we want to build for the Brain Platform
> 
> Each schema/section is clearly marked. Do not assume anything unmarked exists.
> When in doubt, check the codebase.

---

## Executive Summary

COSMO is an autonomous research system that produces **AI knowledge graphs** ("brains"). This document outlines the vision for a complete ecosystem where:

1. **COSMO** is the engine that produces brains
2. **Brain Platform** is the infrastructure for consuming, sharing, merging, and distributing brains
3. **Together** they create a flywheel of collective AI intelligence

Think: **Git + GitHub, but for AI knowledge.**

---

## Table of Contents

1. [The Vision](#the-vision)
2. [Core Concepts](#core-concepts)
3. [Architecture Overview](#architecture-overview)
4. [The `.brain` Specification](#the-brain-specification)
5. [COSMO Product](#cosmo-product)
6. [Brain Platform Product](#brain-platform-product)
7. [Integration Points](#integration-points)
8. [User Workflows](#user-workflows)
9. [Business Model](#business-model)
10. [Technical Roadmap](#technical-roadmap)
11. [Competitive Moat](#competitive-moat)
12. [Open Questions](#open-questions)

---

## The Vision

### The Problem

Today's AI systems are stateless. Each conversation starts fresh. Research done in one session doesn't compound into the next. Knowledge generated by AI is trapped in chat logs, scattered documents, and ephemeral contexts.

**And the tools we have suck.** GitHub is a developer tool built for code, not knowledge. IDEs are convoluted. There's no native space where humans and AI work together on knowledge—where the interface adapts to what you need (chat? editing? building? exploring?).

### The Solution

**Make AI knowledge portable, persistent, and collaborative.**

- **COSMO** runs autonomous research, building knowledge graphs over hours/days/weeks
- **Brains** are the packaged output—portable knowledge that can be shared, merged, and continued
- **The Interface** is an adaptive workspace where human + AI collaborate (we have this: intelligence dashboard, agent IDE)
- **The Collective** builds on top of the `.brain` format

### The `.brain` as Atomic Unit

```
┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   The .brain is NOT just an export format.                         │
│   It's the UNIT OF VALUE in the knowledge economy.                 │
│                                                                     │
│   Like:                                                             │
│   • .mp3 made music shareable → Napster, iTunes, Spotify           │
│   • .git made code collaborative → GitHub, GitLab, ecosystem       │
│   • .brain makes knowledge composable → The collective builds      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

**We don't need to build all the interfaces. We need to release the format and let imagination run.**

### The Analogy

| Concept | Software World | COSMO Ecosystem |
|---------|---------------|-----------------|
| Work Unit | Code | Knowledge (nodes + edges) |
| Package | Repository | Brain |
| Tool | Git | COSMO |
| Platform | GitHub | Brain Platform |
| Operation | Commit, Push, Merge | Research, Push, Merge |
| **Atomic File** | **.git folder** | **.brain package** |

---

## Core Concepts

### Brain
A self-contained package of AI-generated knowledge, including:
- Memory graph (nodes, edges, clusters)
- Research artifacts (documents, code, data)
- Metadata (provenance, sources, lineage)

### Node
A single piece of knowledge with:
- Content (the actual knowledge)
- Embedding (vector representation)
- Metadata (source, confidence, timestamp)
- Connections (edges to related nodes)

### Edge
A relationship between nodes:
- Weight (strength of connection)
- Type (semantic relationship)
- Provenance (how it was discovered)

### Operations

| Operation | Description | Analogy |
|-----------|-------------|---------|
| **Run** | Execute COSMO to generate/extend a brain | Work on code |
| **Export** | Package a run as a `.brain` | `git archive` |
| **Import** | Load a brain into COSMO | `git clone` |
| **Push** | Upload brain to registry | `git push` |
| **Pull** | Download brain from registry | `git pull` |
| **Fork** | Copy a brain to start independent work | `git fork` |
| **Merge** | Combine multiple brains | `git merge` |
| **Diff** | Compare two brains | `git diff` |
| **View** | Explore a brain's contents | Browse code |

---

## The Interface Vision

### Not Another Developer Tool

The interface is NOT another GitHub. It's an **adaptive workspace** where human and AI work together:

| Mode | What It Becomes |
|------|-----------------|
| **Exploring** | Knowledge graph visualization, semantic search |
| **Chatting** | Conversational interface with the brain |
| **Building** | IDE for creating documents, code, artifacts |
| **Editing** | Document editor with AI assistance |
| **Researching** | Research dashboard with agent swarm |

**One space. Transforms to what you need.**

### What We Already Have (ACTUAL)

- ✅ **Intelligence Dashboard** - Monitor runs, explore knowledge, view agent activity
- ✅ **Agent IDE** - Spawn agents, manage goals, view outputs
- ✅ **Graph Visualization** - 3D force-directed knowledge graphs
- ✅ **Query Interface** - Semantic search, document compilation
- ✅ **Export/Trace** - BibTeX, markdown, full run archives

### What the Collective Will Build

Once `.brain` is released as a clean, portable format:

| What People Will Build | On Top Of |
|------------------------|-----------|
| Brain viewers | `.brain` + graph libraries |
| Brain chat apps | `.brain` + RAG pipelines |
| Brain-powered products | `.brain` + custom UI |
| Brain marketplaces | `.brain` + commerce |
| Educational platforms | `.brain` + curriculum |
| Research tools | `.brain` + analysis |
| Mobile apps | `.brain` + native UI |
| Obsidian/Notion plugins | `.brain` + integrations |

**We can't let the brains go to waste. The collective needs to get involved.**

---

## Architecture Overview

```
┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│                         ☁️  BRAIN CLOUD                                  │
│                    (Registry + Collaboration)                            │
│                                                                          │
│     ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│     │ Brain A │  │ Brain B │  │ Brain C │  │ Brain D │  │ Brain E │    │
│     └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘    │
│          │            │            │            │            │          │
│          └────────────┴─────┬──────┴────────────┴────────────┘          │
│                             │                                            │
│                       PUSH / PULL / MERGE                                │
│                             │                                            │
├─────────────────────────────┼────────────────────────────────────────────┤
│                             │                                            │
│   ┌─────────────────────────┴─────────────────────────────────┐         │
│   │                                                           │         │
│   │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │         │
│   │  │   COSMO     │    │   COSMO     │    │   COSMO     │   │         │
│   │  │  Instance   │    │  Instance   │    │  Instance   │   │         │
│   │  │  (Alice)    │    │   (Bob)     │    │  (Acme Co)  │   │         │
│   │  └─────────────┘    └─────────────┘    └─────────────┘   │         │
│   │                                                           │         │
│   │              🖥️  DEPLOYED COSMOS                          │         │
│   │         (Self-hosted or COSMO Cloud)                      │         │
│   └───────────────────────────────────────────────────────────┘         │
│                                                                          │
│   ┌─────────────────────────────────────────────────────────────┐       │
│   │                    👁️  BRAIN VIEWER                         │       │
│   │              (Standalone exploration tool)                   │       │
│   │         Works offline with any .brain package                │       │
│   └─────────────────────────────────────────────────────────────┘       │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

### Component Responsibilities

| Component | Responsibility |
|-----------|---------------|
| **COSMO** | Produce brains through autonomous research |
| **Brain CLI** | Local brain operations (export, import, merge, diff) |
| **Brain Viewer** | Explore brain contents (standalone, read-only) |
| **Brain Cloud** | Host, share, and collaborate on brains |
| **Brain API** | Programmatic access to brain operations |

---

## The `.brain` Specification

> ⚠️ **IMPORTANT: Actual vs. Aspirational**
> 
> This specification describes the **target format** for portable brain packages. 
> Some parts reflect **what currently exists** in COSMO (marked as ACTUAL), while 
> others are **proposed additions** for the brain export format (marked as PROPOSED).
> 
> **Currently exists:**
> - `state.json.gz` - Full cognitive state (memory, goals, agents, etc.)
> - `outputs/` - Agent-generated artifacts
> - `run-metadata.json` - Basic run info
> - `thoughts.jsonl` - Thought stream
> - `agents/` - Per-agent journals
> - `coordinator/` - Meta-coordinator reviews
> 
> **Proposed additions for `.brain` format:**
> - `manifest.json` - Standardized metadata with versioning
> - `metadata/sources.json` - Aggregated source catalog
> - `lineage/` - Merge/fork history tracking
> - `index/` - Pre-computed search indices

### Overview

A `.brain` is a directory (or compressed archive) containing all artifacts needed to represent, share, and continue AI knowledge work.

### Directory Structure

**What currently exists in a COSMO run folder:**
```
{run-name}/
├── state.json.gz              # ✅ ACTUAL - Full cognitive state
├── run-metadata.json          # ✅ ACTUAL - Run configuration
├── thoughts.jsonl             # ✅ ACTUAL - Thought stream
├── dreams.jsonl               # ✅ ACTUAL - Sleep consolidations
├── agents/                    # ✅ ACTUAL - Per-agent journals (*.jsonl)
├── outputs/                   # ✅ ACTUAL - Agent outputs
│   ├── research/              #    Research corpus files
│   ├── document-creation/     #    Generated documents
│   ├── code-execution/        #    Code outputs
│   └── ...                    #    Other agent types
├── coordinator/               # ✅ ACTUAL - Meta-coordinator reviews
├── goals/                     # ✅ ACTUAL - Goal state files
├── tasks/                     # ✅ ACTUAL - Task definitions
├── plans/                     # ✅ ACTUAL - Active plans
├── milestones/                # ✅ ACTUAL - Phase tracking
├── checkpoints/               # ✅ ACTUAL - Recovery snapshots
└── exports/                   # ✅ ACTUAL - Dashboard exports
```

**Proposed `.brain` package structure (to be built):**
```
{brain-name}.brain/
├── manifest.json              # 🆕 PROPOSED - Standardized metadata
├── state.json.gz              # ✅ FROM ACTUAL - Core memory graph
├── run-metadata.json          # ✅ FROM ACTUAL - Run configuration
├── metadata/                  # 🆕 PROPOSED
│   ├── sources.json           #    Aggregated source catalog
│   ├── topics.json            #    Domain taxonomy
│   └── statistics.json        #    Content statistics
├── outputs/                   # ✅ FROM ACTUAL - Agent outputs
├── lineage/                   # 🆕 PROPOSED
│   ├── parents.json           #    Fork/merge history
│   └── changelog.md           #    Version history
└── index/                     # 🆕 PROPOSED (optional)
    └── clusters.json          #    Pre-computed search index
```

### run-metadata.json (ACTUAL - exists today)

This file **currently exists** in every COSMO run:

```json
{
  "created": "2025-12-23T22:55:14.033Z",
  "cleanStart": false,
  "explorationMode": "guided",
  "domain": "Business",
  "context": "History of business, modern practices, strategy...",
  "executionMode": "strict",
  "depth": "deep",
  "maxCycles": "100",
  "enableWebSearch": true,
  "enableSleep": true,
  "enableCodingAgents": true,
  "enableIntrospection": true,
  "maxConcurrent": 5,
  "fileAccessEnabled": true,
  "launcherVersion": "2.0-web"
}
```

### manifest.json Schema (PROPOSED - does not exist yet)

> ⚠️ **NOTE:** This file does not currently exist. The `run-metadata.json` above has 
> configuration info but lacks versioning, checksums, and content statistics. 
> This manifest schema is **proposed** for standardized brain packaging.

```json
{
  "$schema": "https://cosmo.ai/schemas/brain/v1/manifest.json",
  "version": "1.0.0",
  "brain": {
    "id": "uuid-v4",
    "name": "physics-quantum-2024",
    "displayName": "Quantum Physics Research",
    "description": "Comprehensive research on quantum computing, error correction, and applications",
    "version": "2.1.0",
    "created": "2024-12-20T10:30:00Z",
    "updated": "2024-12-24T15:45:00Z"
  },
  "cosmo": {
    "version": "2.5.0",
    "instanceId": "cosmo-user-local",
    "totalCycles": 847,
    "totalAgentRuns": 234
  },
  "content": {
    "nodes": 2847,
    "edges": 8234,
    "clusters": 47,
    "documents": 23,
    "sources": 412
  },
  "topics": [
    "quantum computing",
    "error correction",
    "quantum algorithms",
    "quantum hardware"
  ],
  "license": "CC-BY-4.0",
  "visibility": "public",
  "lineage": {
    "parents": [
      {
        "id": "brain-abc123",
        "name": "physics-foundations-2024",
        "version": "1.0.0"
      }
    ],
    "mergedFrom": []
  },
  "checksums": {
    "state": "sha256:abc123...",
    "outputs": "sha256:def456..."
  }
}
```

### state.json.gz Schema (ACTUAL - as of Dec 2024)

The compressed state file contains the full COSMO cognitive state. This is the **actual** structure from a real run:

**Top-level keys:**
```
cycleCount, journal, memory, goals, roles, reflection, oscillator, 
cognitiveState, temporal, coordinator, agentExecutor, forkSystem, 
topicQueue, goalCurator, evaluation, executiveRing, guidedMissionPlan, 
completionTracker, lastSummarization, gpt5Stats, goalAllocator, 
clusterSync, clusterCoordinator, timestamp
```

**Memory structure:**
```json
{
  "memory": {
    "nodes": [
      {
        "id": 123,
        "concept": "Strategy as cognitive architecture: design choices that...",
        "tag": "introspection",
        "embedding": [0.123, -0.456, ...],
        "weight": 1.0,
        "activation": 0.0,
        "cluster": 12,
        "accessCount": 5,
        "created": "2024-12-20T10:30:00Z",
        "accessed": "2024-12-24T15:00:00Z"
      }
    ],
    "edges": [
      {
        "source": 123,
        "target": 456,
        "weight": 0.87,
        "type": "semantic",
        "created": "2024-12-20T11:00:00Z",
        "accessed": "2024-12-24T14:00:00Z"
      }
    ],
    "clusters": [[1, [123, 456, 789]], [2, [101, 102]]],
    "nextNodeId": 2848,
    "nextClusterId": 48
  }
}
```

**Goals structure:**
```json
{
  "goals": {
    "active": [["goal_123", { "description": "...", "priority": 0.8, ... }]],
    "completed": [...],
    "archived": [...],
    "nextGoalId": 150
  }
}
```

**Cognitive state:**
```json
{
  "cognitiveState": {
    "curiosity": 0.8,
    "mood": 0.7,
    "energy": 0.6,
    "mode": "active",
    "lastModeChange": "2024-12-24T10:00:00Z",
    "surpriseAccumulator": 0.5,
    "recentSuccesses": 10,
    "recentFailures": 2
  }
}
```

**Other key sections:**
- `journal` - Last 100 thoughts with cycle, role, thought text, reasoning, cognitive state
- `roles` - Dynamic role configurations
- `oscillator` - Focus/explore oscillation state
- `agentExecutor` - Agent registry and execution state
- `executiveRing` - Executive coordinator statistics
- `guidedMissionPlan` - Current mission plan (if guided mode)
- `evaluation` - Performance metrics
- `timestamp` - When state was saved

### metadata/sources.json Schema (PROPOSED - does not exist yet)

> ⚠️ **NOTE:** This file does not currently exist in COSMO runs. Sources are tracked 
> within agent output files (e.g., `outputs/research/*/sources.json`) but not aggregated 
> at the run level. This schema is **aspirational** for the `.brain` export format.

```json
{
  "version": "1.0.0",
  "sources": [
    {
      "id": "src_001",
      "type": "arxiv",
      "identifier": "2401.12345",
      "title": "Quantum Error Correction: A Survey",
      "authors": ["Alice Smith", "Bob Jones"],
      "url": "https://arxiv.org/abs/2401.12345",
      "accessed": "2024-12-20T10:30:00Z",
      "citedBy": ["node_123", "node_456"]
    }
  ],
  "statistics": {
    "total": 412,
    "byType": {
      "arxiv": 89,
      "doi": 134,
      "web": 156,
      "wikipedia": 33
    }
  }
}
```

### lineage/parents.json Schema (PROPOSED - reshapes existing data)

> ✅ **UPDATE:** Lineage tracking **DOES exist** for merged brains! The merge tool creates
> `merge-report.json` with full `sourceRuns[]` data. See example from `_MegaMerge_12_13_25`:
> - 49 source runs tracked with name, cycles, nodes, edges, domain
> - Full merge statistics (deduplication rate, conflicts prevented)
> - Domain-specific quality metrics
>
> The proposed `lineage/parents.json` schema below is simply a **reshape** of existing 
> `merge-report.json` data, not new data collection.

```json
{
  "version": "1.0.0",
  "parents": [
    {
      "brainId": "brain-abc123",
      "name": "physics-foundations-2024",
      "version": "1.0.0",
      "relationship": "forked",
      "inheritedNodes": 1234,
      "timestamp": "2024-12-15T09:00:00Z"
    }
  ],
  "merges": [
    {
      "sourceBrainId": "brain-def456",
      "sourceName": "quantum-algorithms-2024",
      "sourceVersion": "1.2.0",
      "mergedAt": "2024-12-22T16:00:00Z",
      "nodesAdded": 567,
      "edgesAdded": 1234,
      "conflicts": 3,
      "conflictResolution": "source-priority"
    }
  ]
}
```

### File Size Guidelines

| Component | Typical Size | Max Recommended |
|-----------|--------------|-----------------|
| manifest.json | 2-5 KB | 100 KB |
| state.json.gz | 1-50 MB | 500 MB |
| metadata/* | 100 KB - 5 MB | 50 MB |
| outputs/* | 10 MB - 1 GB | 10 GB |
| index/* | 10-100 MB | 500 MB |
| **Total .brain** | 50 MB - 2 GB | 15 GB |

### Compression

- `state.json.gz` MUST be gzip compressed
- Other JSON files MAY be compressed (`.json.gz`)
- Binary files (embeddings.bin) are stored raw
- Archives (`.brain.tar.gz`) compress the entire directory

### Versioning

Brains use semantic versioning:
- **Major**: Breaking changes to knowledge structure
- **Minor**: New knowledge domains added
- **Patch**: Refinements, corrections, source additions

---

## Implementation Reality

> **Key Insight:** The `.brain` format is 90% a RESHAPING of existing data, not new data collection.
> The Merge V2 engine (`scripts/merge_runs.js`) already did the heavy lifting.

### What Already Exists (ACTUAL)

| Data Needed | Current Location | Status |
|-------------|------------------|--------|
| **Lineage (merged brains)** | `merge-report.json` → `sourceRuns[]` | ✅ Full data |
| **Merge quality metrics** | `merge-confidence.json` → `domainStats`, `conflictsPrevented` | ✅ Full data |
| **Brain metadata** | `run-metadata.json` → domain, context, created, config | ✅ Full data |
| **Node/edge counts** | `state.json.gz` → count arrays | ✅ Compute on export |
| **Research sources** | `outputs/research/*/sources.json` | ✅ Aggregate on export |
| **Provenance tracking** | Prefix-coded node IDs (e.g., `fa7572_123`) | ✅ In place |

### Real Example: `_MegaMerge_12_13_25`

This actual merged brain contains:
```
merge-report.json:
├── sourceRuns: 49 runs with full metadata
├── mergeTime: "70m 43s"
├── mergedState: { nodes: 6282, edges: 23913, goals: 4156 }
├── deduplication: { rate: "89.3%", removed: 52403 }
└── confidence: { conflictsPrevented: 74833, domainStats: [...] }
```

### Transformation Path

```
Current Run Folder          →    Proposed .brain Package
─────────────────────────────────────────────────────────
state.json.gz               →    state.json.gz (copy)
run-metadata.json           →    manifest.json (reshape)
merge-report.json           →    lineage/parents.json (reshape)
merge-confidence.json       →    metadata/merge-quality.json (rename)
outputs/research/*/sources  →    metadata/sources.json (aggregate)
outputs/                    →    outputs/ (optional, --with-outputs)
```

### Implementation Effort (Revised)

| Feature | Effort | Notes |
|---------|--------|-------|
| `brain export` command | **1-2 days** | Transform existing data |
| `brain import` command | **1 day** | Reverse of export |
| `--preserve-outputs` in merge | **1 day** | Copy outputs folders |
| `manifest.json` generation | **Few hours** | Reshape + compute checksums |
| Brain Viewer (read-only web) | **1-2 weeks** | New UI, but uses existing data |
| Brain Cloud (registry) | **Multi-week** | New infrastructure |

### What's Actually New Work

1. **Export/Import CLI** - Packaging existing data into `.brain` format
2. **Brain Viewer** - New read-only web interface
3. **Brain Cloud** - New registry infrastructure
4. **Optional outputs preservation** - `--preserve-outputs` flag for merge

### What's NOT Needed

- ❌ New data collection during runs (already captured)
- ❌ Backward-incompatible changes to COSMO
- ❌ Migration scripts for old runs (can export anytime)
- ❌ New provenance tracking (prefix IDs already work)

---

## COSMO Product

### What COSMO Is

COSMO is an **autonomous AI research system** that:
- Runs continuous research cycles
- Spawns specialist agents (research, analysis, synthesis, code, etc.)
- Builds knowledge graphs through investigation
- Produces structured outputs (documents, code, data)
- Self-coordinates via an "Executive Ring"

### Deployment Tiers

| Tier | Target User | Deployment | Features |
|------|-------------|------------|----------|
| **COSMO Local** | Developers, Researchers | npm/Docker | Full engine, local storage |
| **COSMO Team** | Small teams (2-10) | Docker Compose | Multi-user, shared runs |
| **COSMO Enterprise** | Organizations | K8s / On-prem | SSO, audit, compliance, HA |
| **COSMO Cloud** | Everyone | Hosted SaaS | Zero setup, managed |

### COSMO Local

```bash
# Installation
npm install -g @cosmo/cli
# or
docker pull cosmo/engine:latest

# Basic usage
cosmo init my-research
cosmo run --topic "quantum computing" --depth deep

# With brain
cosmo run --brain quantum-2024 --topic "error correction"
cosmo export --output quantum-extended.brain
```

### COSMO Cloud

```bash
# Cloud usage
cosmo cloud login
cosmo cloud run --topic "climate modeling" --hours 4
cosmo cloud export --to brain-cloud
```

### Configuration

```yaml
# cosmo.yaml
version: "1.0"

research:
  topic: "quantum computing"
  depth: deep  # light, medium, deep
  mode: strict  # strict, mixed, advisory

brain:
  source: null  # or "brain-cloud://quantum-2024"
  autoExport: true
  exportPath: "./outputs/brain"

agents:
  maxConcurrent: 5
  types:
    - research
    - analysis
    - synthesis
    - code_execution
    - document_creation

api:
  openai: ${OPENAI_API_KEY}

cloud:
  publish: false  # auto-publish to Brain Cloud
  visibility: private
```

---

## Brain Platform Product

### Components

#### 1. Brain CLI

Command-line tool for local brain operations.

```bash
# Installation
npm install -g @cosmo/brain-cli

# Core commands
brain init <name>              # Create empty brain
brain export <run-dir> <name>  # Export COSMO run to brain
brain import <brain> <run-dir> # Import brain for COSMO
brain view <brain>             # Open in viewer
brain info <brain>             # Show brain metadata

# Registry operations
brain login                    # Authenticate with Brain Cloud
brain push <brain>             # Upload to registry
brain pull <name>              # Download from registry
brain search <query>           # Search registry

# Collaboration
brain fork <name> <new-name>   # Copy brain
brain merge <brain1> <brain2>  # Merge brains
brain diff <brain1> <brain2>   # Compare brains
```

#### 2. Brain Viewer

Standalone web application for exploring brains.

**Features:**
- Memory graph visualization (nodes, edges, clusters)
- Semantic search across knowledge
- Document/artifact browser
- Source/citation explorer
- Statistics dashboard
- Export tools (bibliography, findings, summaries)

**Deployment:**
```bash
# Standalone
brain-viewer ./my-research.brain

# Or serve multiple brains
brain-viewer serve ./brains/ --port 3000
```

**Architecture:**
- Single-page React/Vue application
- Works offline (loads entire brain into browser)
- No server required for single-brain viewing
- Minimal server for multi-brain / search features

#### 3. Brain Cloud (Registry)

Hosted platform for brain storage and collaboration.

**URL Structure:**
```
https://brains.cosmo.ai/
├── /explore                    # Browse public brains
├── /brains/{owner}/{name}      # View specific brain
├── /brains/{owner}/{name}/merge # Merge interface
├── /users/{username}           # User profile
├── /organizations/{org}        # Org brains
└── /api/v1/                    # REST API
```

**Features:**
- Upload/download brains
- Public and private brains
- Organizations and teams
- Forking and merging
- Search across all public brains
- Lineage visualization
- Usage analytics

#### 4. Brain API

RESTful API for programmatic access.

```
# Brains
GET    /api/v1/brains                     # List brains
GET    /api/v1/brains/{id}                # Get brain metadata
GET    /api/v1/brains/{id}/download       # Download brain archive
POST   /api/v1/brains                     # Upload brain
DELETE /api/v1/brains/{id}                # Delete brain
PATCH  /api/v1/brains/{id}                # Update metadata

# Content
GET    /api/v1/brains/{id}/nodes          # List nodes
GET    /api/v1/brains/{id}/nodes/{nodeId} # Get node
POST   /api/v1/brains/{id}/search         # Semantic search
GET    /api/v1/brains/{id}/outputs        # List outputs

# Operations
POST   /api/v1/brains/merge               # Merge brains
POST   /api/v1/brains/{id}/fork           # Fork brain
GET    /api/v1/brains/diff                # Compare brains

# Users
GET    /api/v1/users/{username}/brains    # User's brains
GET    /api/v1/orgs/{org}/brains          # Org's brains
```

### Platform Tiers

| Tier | Price | Features |
|------|-------|----------|
| **Free** | $0/mo | 5 public brains, 1GB storage, basic viewer |
| **Pro** | $20/mo | Unlimited private, 50GB, API access, advanced search |
| **Team** | $15/user/mo | Collaboration, shared workspaces, permissions |
| **Enterprise** | Custom | On-prem option, SSO, SLA, dedicated support |

---

## Integration Points

### COSMO → Brain (Export)

```javascript
// In COSMO, after run completes
const brain = await cosmo.exportBrain({
  name: 'quantum-2024',
  includeOutputs: true,
  includeIndex: true
});

await brain.save('./outputs/quantum-2024.brain');
// or
await brain.push('brain-cloud://user/quantum-2024');
```

### Brain → COSMO (Import)

```javascript
// Start COSMO with existing brain
const cosmo = new COSMO({
  brain: './brains/quantum-2024.brain',
  // or
  brain: 'brain-cloud://user/quantum-2024'
});

await cosmo.run({
  topic: 'quantum error correction',
  continueFrom: 'latest'  // Continue from brain's state
});
```

### COSMO Config Integration

```yaml
# cosmo.yaml
brain:
  # Load from local
  source: "./brains/foundation.brain"
  
  # Or from cloud
  source: "brain-cloud://public/science-2024"
  
  # Export settings
  autoExport: true
  exportFormat: "brain"  # brain, json, tar.gz
  exportPath: "./outputs/"
  
  # Cloud publishing
  publish:
    enabled: true
    visibility: "private"
    name: "my-research-{{date}}"
```

### Webhook Events

Brain Cloud can notify external systems:

```json
{
  "event": "brain.pushed",
  "brain": {
    "id": "brain-abc123",
    "name": "quantum-2024",
    "owner": "user"
  },
  "timestamp": "2024-12-24T15:45:00Z"
}
```

Events: `brain.pushed`, `brain.forked`, `brain.merged`, `brain.deleted`

---

## User Workflows

### 1. Solo Researcher

```
┌─────────────────────────────────────────────────────────────────┐
│                    SOLO RESEARCHER WORKFLOW                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Day 1: Start Research                                          │
│  └─→ cosmo run --topic "protein folding" --depth deep           │
│  └─→ [COSMO runs for 4 hours, 200 cycles]                       │
│  └─→ cosmo export --output proteins-v1.brain                    │
│                                                                 │
│  Day 3: Continue Research                                       │
│  └─→ cosmo run --brain proteins-v1.brain --topic "misfolding"   │
│  └─→ [COSMO continues, 150 more cycles]                         │
│  └─→ cosmo export --output proteins-v2.brain                    │
│                                                                 │
│  Day 5: Share Findings                                          │
│  └─→ brain push proteins-v2.brain --public                      │
│  └─→ [Brain available at brains.cosmo.ai/user/proteins-v2]       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 2. Team Collaboration

```
┌─────────────────────────────────────────────────────────────────┐
│                    TEAM COLLABORATION WORKFLOW                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Alice: Research Proteins                                       │
│  └─→ cosmo run --topic "protein structure"                      │
│  └─→ brain push proteins.brain --org acme --private             │
│                                                                 │
│  Bob: Research Drugs                                            │
│  └─→ cosmo run --topic "drug binding"                           │
│  └─→ brain push drugs.brain --org acme --private                │
│                                                                 │
│  Team: Merge Knowledge                                          │
│  └─→ brain merge acme/proteins acme/drugs --output pharma       │
│  └─→ [Resolve 5 conflicts in Brain Cloud UI]                    │
│  └─→ brain push pharma.brain --org acme                         │
│                                                                 │
│  Carol: Continue Combined Research                              │
│  └─→ cosmo run --brain acme/pharma --topic "drug discovery"     │
│  └─→ brain push pharma-v2.brain --org acme                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 3. Building on Public Knowledge

```
┌─────────────────────────────────────────────────────────────────┐
│                  PUBLIC KNOWLEDGE WORKFLOW                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Discover: Find Relevant Brain                                  │
│  └─→ brain search "quantum computing"                           │
│  └─→ [Found: public/quantum-foundations (4.2k nodes, 89 ⭐)]    │
│                                                                 │
│  Fork: Start Your Own Work                                      │
│  └─→ brain fork public/quantum-foundations my-quantum           │
│                                                                 │
│  Extend: Add Your Research                                      │
│  └─→ cosmo run --brain my-quantum --topic "topological qubits"  │
│  └─→ brain push my-quantum --public                             │
│                                                                 │
│  Contribute: Merge Back (Optional)                              │
│  └─→ brain merge-request my-quantum → public/quantum-foundations│
│  └─→ [Maintainer reviews and accepts]                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 4. Enterprise Knowledge Management

```
┌─────────────────────────────────────────────────────────────────┐
│                  ENTERPRISE WORKFLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Central Knowledge Base                                         │
│  └─→ acme-corp/company-knowledge (master brain)                 │
│      ├── /engineering                                           │
│      ├── /research                                              │
│      ├── /market-analysis                                       │
│      └── /competitive-intel                                     │
│                                                                 │
│  Team Contributions                                             │
│  └─→ Each team runs COSMO on their domain                       │
│  └─→ Weekly merge into company-knowledge                        │
│  └─→ Automated quality gates before merge                       │
│                                                                 │
│  Consumption                                                    │
│  └─→ Employees query company-knowledge via API                  │
│  └─→ Integrated into internal tools (Slack, Notion, etc.)       │
│  └─→ Audit trail for compliance                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Business Model

### Revenue Streams

#### COSMO Revenue

| Stream | Model | Notes |
|--------|-------|-------|
| **COSMO Local** | Free / Open Core | Community growth |
| **COSMO Pro** | $50/mo | Power user features |
| **COSMO Team** | $200/mo | Multi-user, 5 seats |
| **COSMO Enterprise** | $2k+/mo | On-prem, SSO, support |
| **COSMO Cloud** | Usage-based | $0.10/cycle, $0.50/agent-hour |

#### Brain Platform Revenue

| Stream | Model | Notes |
|--------|-------|-------|
| **Free Tier** | $0 | 5 public brains, 1GB |
| **Pro** | $20/mo | Unlimited, 50GB, API |
| **Team** | $15/user/mo | Collaboration |
| **Enterprise** | Custom | On-prem, SLA |
| **Storage** | $0.10/GB/mo | Above tier limits |
| **API Calls** | $0.001/call | Above tier limits |
| **Marketplace** | 15% cut | Premium brain sales |

### Pricing Philosophy

1. **COSMO free tier** drives adoption and brain creation
2. **Brain Platform free tier** drives brain sharing
3. **Paid tiers** unlock collaboration and scale
4. **Marketplace** creates ecosystem value

---

## The Unlock: Minimum Viable Brain Package

> **This is what needs to ship to enable everything else.**

### The MVP Deliverables

| Deliverable | What It Does | Effort | Priority |
|-------------|--------------|--------|----------|
| `scripts/brain-cli.js` | export, import, info, validate | 2-3 days | **P0** |
| `.brain` spec documentation | Formal format docs | 1 day | **P0** |
| `@cosmo/brain` npm package | JS library for loading/querying brains | 3-4 days | **P0** |
| Example brains | Sample packaged brains from existing runs | Existing | **P0** |
| Brain API (local) | REST endpoints for querying a brain | 2-3 days | P1 |

### The CLI

```bash
# Export a run to .brain format
brain export Physics2 --output Physics2.brain --with-outputs

# Import a .brain into COSMO runs folder
brain import Physics2.brain --target ./runs/

# Show brain info
brain info Physics2.brain

# Validate a brain package
brain validate Physics2.brain

# Merge brains (wraps existing merge_runs.js)
brain merge Brain1.brain Brain2.brain --output Merged.brain
```

### The Library

```javascript
import { Brain } from '@cosmo/brain';

// Load a brain
const brain = await Brain.load('./Physics2.brain');

// Get metadata
console.log(brain.manifest);  // { name, created, nodes, edges, ... }

// Query nodes
const results = await brain.search('entropy');
const node = await brain.getNode('fa7572_1234');
const related = await brain.getRelated('fa7572_1234', { limit: 10 });

// Conversational query (requires embeddings)
const answer = await brain.ask('What is entropy?');

// Merge brains
const merged = await Brain.merge([brain1, brain2], {
  preserveOutputs: true,
  threshold: 0.85
});

// Save
await merged.save('./merged.brain');
```

### Why This Is The Unlock

```
                        ┌─────────────────┐
                        │  COSMO Engine   │
                        │  (produces)     │
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │     .brain      │◄──── THE UNLOCK
                        │   (portable)    │
                        └────────┬────────┘
                                 │
           ┌─────────────────────┼─────────────────────┐
           │                     │                     │
           ▼                     ▼                     ▼
    ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
    │   Share     │       │   Build     │       │   Merge     │
    │   ──────    │       │   ─────     │       │   ─────     │
    │ Brain Cloud │       │ Your App    │       │ Collective  │
    │ Marketplace │       │ Your Tool   │       │ Knowledge   │
    │ Public libs │       │ Plugins     │       │ BigBrain    │
    └─────────────┘       └─────────────┘       └─────────────┘
```

**Once `.brain` ships, the collective builds. We don't need to build everything.**

---

## Technical Roadmap

### Phase 1: Foundation (Q1 2025)

**Goal:** Establish the brain format and local tooling

> ✅ **REVISED:** Most data already exists. This phase is packaging, not building.

| Task | Priority | Effort | Notes |
|------|----------|--------|-------|
| Finalize `.brain` specification | P0 | **2-3 days** | Mostly done in this doc |
| `brain export` command | P0 | **1-2 days** | Reshape existing data |
| `brain import` command | P0 | **1 day** | Reverse transform |
| `brain info` command | P1 | **1 day** | Read manifest |
| `--preserve-outputs` flag in merge | P1 | **1 day** | Copy outputs folders |
| Brain Viewer MVP (local, read-only) | P1 | 2 weeks | New UI |
| Documentation | P1 | 3 days | |

**Deliverables:**
- [ ] `.brain` spec v1.0 (this document)
- [ ] `scripts/brain-cli.js` (export, import, info)
- [ ] `--preserve-outputs` flag in merge_runs.js
- [ ] Brain Viewer standalone app (optional, can defer)

### Phase 2: Platform MVP (Q2 2025)

**Goal:** Launch Brain Cloud with basic registry

| Task | Priority | Effort |
|------|----------|--------|
| Brain Cloud backend (upload/download) | P0 | 4 weeks |
| User authentication | P0 | 2 weeks |
| Web UI for browsing brains | P0 | 3 weeks |
| CLI push/pull commands | P0 | 1 week |
| Public/private brain support | P1 | 1 week |
| Basic search | P1 | 2 weeks |

**Deliverables:**
- [ ] Brain Cloud beta at brains.cosmo.ai
- [ ] User accounts
- [ ] `brain push/pull` working
- [ ] Public brain discovery

### Phase 3: Collaboration (Q3 2025)

**Goal:** Enable team workflows

> ✅ **REVISED:** Merge V2 engine is DONE. Fork system exists. This phase is mostly UI.

| Task | Priority | Effort | Notes |
|------|----------|--------|-------|
| Fork workflow | P0 | 1 week | ✅ Fork system exists, need `.brain` export |
| Merge engine | ~~P0~~ | ~~4 weeks~~ | ✅ **DONE** - V2 in merge_runs.js |
| Conflict resolution UI | P1 | 3 weeks | New (V2 already prevents conflicts) |
| Organizations and teams | P0 | 3 weeks | New |
| Permissions system | P1 | 2 weeks | New |
| Brain diff visualization | P2 | 3 weeks | New |
| Lineage explorer UI | P1 | 2 weeks | Display existing merge-report.json |

**Deliverables:**
- [x] Merge engine V2 (domain-aware, conflict detection, provenance)
- [ ] Fork → `.brain` export workflow
- [ ] Team workspaces
- [ ] Lineage explorer (visualize merge-report.json)

### Phase 4: Ecosystem (Q4 2025)

**Goal:** Scale and monetize

| Task | Priority | Effort |
|------|----------|--------|
| COSMO Cloud MVP | P0 | 8 weeks |
| Brain Marketplace | P1 | 4 weeks |
| API rate limiting / monetization | P0 | 2 weeks |
| Enterprise features (SSO, audit) | P1 | 4 weeks |
| Integrations (Notion, Obsidian, etc.) | P2 | 6 weeks |
| On-prem Brain Cloud option | P2 | 4 weeks |

**Deliverables:**
- [ ] COSMO Cloud GA
- [ ] Marketplace with paid brains
- [ ] Enterprise tier
- [ ] Third-party integrations

### Infrastructure Already Built ✅

The following infrastructure already exists and forms the foundation:

| Component | Location | Status |
|-----------|----------|--------|
| **Merge V2 Engine** | `scripts/merge_runs.js` | ✅ Production |
| **Domain-adaptive thresholds** | V2 CONFIG | ✅ 10+ domains |
| **Weighted similarity** | V2 `weightedCosineSimilarity()` | ✅ Cross-domain safe |
| **Conflict detection** | V2 `detectSemanticConflict()` | ✅ Negations, antonyms |
| **Prefix-coded provenance** | V2 `getRunPrefix()` | ✅ SHA256-based |
| **Confidence reports** | `merge-confidence.json` | ✅ Full metrics |
| **Lineage tracking** | `merge-report.json` | ✅ Full source history |
| **Fork system** | `src/core/trajectory-fork.js` | ✅ Works |
| **State persistence** | `state.json.gz` | ✅ 24 subsystems |
| **Run metadata** | `run-metadata.json` | ✅ All launcher config |
| **Research sources** | `outputs/research/*/sources.json` | ✅ Per-agent |
| **Run scanner** | `scripts/scan_runs.js` | ✅ Analysis tool |

**V2 Merge Features (from `MERGE_V2_UPGRADE_SUMMARY.md`):**
1. ✅ Domain-Adaptive Threshold Logic
2. ✅ Domain-Weighted Similarity  
3. ✅ Node-Level Merge Heuristics
4. ✅ Cross-Run Conflict Detection
5. ✅ Fragmentation-Aware Merge Ordering
6. ✅ Smarter ID Remapping (prefix-coded)
7. ✅ Post-Merge Confidence Heatmap

---

## Competitive Moat

### Network Effects

```
┌─────────────────────────────────────────────────────────────────┐
│                        FLYWHEEL EFFECT                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   More COSMO Users                                              │
│         │                                                       │
│         ▼                                                       │
│   More Brains Created ──────────────────┐                       │
│         │                               │                       │
│         ▼                               ▼                       │
│   Brain Cloud More Valuable    Better Merged Brains             │
│         │                               │                       │
│         ▼                               ▼                       │
│   More Users Join ◄─────────── COSMO More Valuable              │
│         │                                                       │
│         └───────────────────────────────────────────────────────│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Defensibility Layers

| Layer | Defense |
|-------|---------|
| **Format** | `.brain` becomes the standard (open spec helps adoption) |
| **Data** | Collective knowledge compounds (can't be replicated) |
| **Tooling** | Best-in-class CLI/viewer/cloud |
| **Community** | Researchers, teams, organizations |
| **Switching Cost** | Research history, team workflows |

### Competitive Landscape

| Competitor | What They Do | Our Differentiation |
|------------|--------------|---------------------|
| Notion AI | Doc assistant | We build knowledge, not assist |
| Obsidian | Local notes | We generate knowledge autonomously |
| Mem.ai | AI memory | We have structured graphs + merge |
| Semantic Scholar | Paper search | We synthesize, not just search |
| Elicit | Research assistant | We run autonomously for hours/days |

---

## Open Questions

### Technical

1. **Brain size limits?** How do we handle 100GB+ brains efficiently?
2. **Incremental sync?** Can we push/pull deltas instead of full brains?
3. **Real-time collaboration?** Multiple COSMO instances on same brain?
4. **Embedding compatibility?** What if embedding models change?

### Product

1. **Free tier limits?** What's the right balance for adoption vs. cost?
2. **Marketplace curation?** How do we ensure brain quality?
3. **Licensing?** What licenses make sense for shared brains?
4. **Attribution?** How do we track credit across merges?

### Business

1. **Open source strategy?** What's open vs. proprietary?
2. **Enterprise sales?** Build sales team or self-serve?
3. **Pricing experiments?** How do we find optimal pricing?
4. **Partnerships?** Academic institutions, research labs?

---

## Appendix A: CLI Reference

```bash
# Brain CLI Commands

# Initialization
brain init <name>                    # Create new empty brain
brain export <cosmo-run> <brain>     # Export COSMO run to brain
brain import <brain> <cosmo-run>     # Import brain for COSMO

# Information
brain info <brain>                   # Show brain metadata
brain stats <brain>                  # Detailed statistics
brain validate <brain>               # Validate brain format

# Local Operations
brain view <brain>                   # Open in viewer
brain search <brain> <query>         # Search within brain
brain export-bib <brain>             # Export bibliography

# Registry Operations
brain login                          # Authenticate
brain logout                         # Clear credentials
brain push <brain> [--name <name>]   # Upload to registry
brain pull <name> [--output <dir>]   # Download from registry
brain list [--user <user>]           # List brains

# Collaboration
brain fork <name> <new-name>         # Fork a brain
brain merge <brain1> <brain2> [--output <name>]  # Merge brains
brain diff <brain1> <brain2>         # Compare brains

# Options (apply to most commands)
--verbose, -v                        # Verbose output
--quiet, -q                          # Minimal output
--json                               # JSON output
--config <file>                      # Config file
```

---

## Appendix B: API Reference

See separate document: `docs/BRAIN_API_REFERENCE.md` (to be created)

---

## Appendix C: Glossary

| Term | Definition |
|------|------------|
| **Brain** | Packaged AI knowledge graph with artifacts |
| **Node** | Single piece of knowledge in the graph |
| **Edge** | Relationship between nodes |
| **Cluster** | Group of related nodes |
| **COSMO** | Autonomous research engine |
| **Brain Cloud** | Hosted platform for brain sharing |
| **Brain Viewer** | Tool for exploring brain contents |
| **Merge** | Combine multiple brains into one |
| **Fork** | Copy a brain to start independent work |
| **Lineage** | History of brain derivation/merging |

---

## Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2024-12-24 | JTR + Claude | Initial vision document |
| 1.1 | 2024-12-24 | JTR + Claude | **CORRECTED**: Audited against actual codebase. Clearly marked ACTUAL vs PROPOSED sections. Fixed hallucinated schemas (node metadata, sources, lineage). Added actual state.json.gz structure from real runs. |

---

*This is a living document. Update as the vision evolves.*

**Validation reminder:** Before adding to this document, verify against the actual codebase. 
Run `gunzip -c runs/{run}/state.json.gz | python3 -c "import json,sys; print(json.load(sys.stdin).keys())"` 
to check actual structure.

