🏛️ Project Athena: The Linux of AI Agents

![Athena Banner](./docs/athena_banner.png)

> **Last Updated**: 12 February 2026

# 🏛️ Project Athena: The Linux of AI Agents

![GitHub Stars](https://img.shields.io/github/stars/winstonkoh87/Athena-Public?style=social)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Protocols](https://img.shields.io/badge/Protocols-93_Starter-blue)
![Sessions](https://img.shields.io/badge/Sessions-1076+-green)
![Reddit Views](https://img.shields.io/badge/Reddit_Views-650k+-FF4500?logo=reddit&logoColor=white)
![Reddit Shares](https://img.shields.io/badge/Shares-5300+-00B2FF?logo=reddit&logoColor=white)

![Python](https://img.shields.io/badge/Python-3.13-3776AB?logo=python&logoColor=white)
![Built with Claude](https://img.shields.io/badge/Reasoning-Claude_Opus_4.6-CC785C?logo=anthropic)
![Built with Gemini](https://img.shields.io/badge/Gemini-3.0_Pro-4285F4?logo=google)
![IDE](https://img.shields.io/badge/IDE-Antigravity-000000?logo=google)
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/winstonkoh87/Athena-Public)

> **Athena is not an AI Agent. It is the Operating System they run on.**  
> **Open Source. Sovereign. Bounded.**

---

## What Is Athena?

Calling Athena an "AI Agent" is overselling it (the LLM is the agent). Calling it a "memory tool" is underselling it.

**Athena is the Linux for AI Agents.**

Just as Linux provides the kernel, file system, and permissions for applications like Firefox to run, Athena provides the **memory, persistence, scheduling, and governance** for AI models (Claude, Gemini, GPT) to run as continuous agents.

| OS Layer | Linux | Athena |
|----------|-------|--------|
| **Kernel** | Hardware abstraction | Memory persistence + retrieval (VectorRAG, Supabase) |
| **File System** | ext4, NTFS | Canonical Memory, Session Logs, Tag Index |
| **Process Management** | cron, systemd | Heartbeat, Daily Briefing, Self-Optimization (launchd) |
| **Shell / CLI** | bash, zsh | MCP Tool Server, `/start`, `/end`, `think` |
| **Permissions** | chmod, users/groups | 4-level Permissioning Layer, Secret Mode |
| **Package Manager** | apt, yum | Protocols, Skills, Workflows |

Most "AI Agents" are just scripts that call an API. They have no state.
Athena is the **infrastructure** that gives them state, time-awareness, and self-correction.

---

## "But I Have ChatGPT / Claude Projects"

> You're confusing **RAM** with a **Hard Drive**.

ChatGPT Memory and Claude Projects are **context window tricks**. They are RAM—fast, useful, but fragile. They get wiped, compressed, or hallucinated away.

Athena is a **Hard Drive**.

- **Files you own**: stored in Markdown on *your* machine.
- **Physics-based**: It doesn't "remember" by magic; it remembers because it wrote a file to disk in Session 42.
- **Model-Agnostic**: Switch from Claude to Gemini tomorrow? Your memory stays here.

| | SaaS Memory (ChatGPT/Claude) | **Athena OS** |
|---|---|---|
| **Ownership** | Rented (Vendor Lock-in) | **Owned (Local Files)** |
| **Lifespan** | Until session/project deleted | **Forever (Git Versioned)** |
| **Structure** | Opaque Blob | **Structured Knowledge Graph** |
| **Agency** | ZERO (Waits for you) | **Bounded Autonomy (Heartbeat, Cron)** |

## Table of Contents

- [Frequently Asked Questions](#frequently-asked-questions)
- ["But My AI Already Has Memory"](#but-my-ai-already-has-memory)
- [What You'll Get](#what-youll-get)
- [⚡ 5-Minute Quickstart](#-5-minute-quickstart)
- [The Loop](#the-loop)
- [The Hub Architecture](#the-hub-architecture)
- [What Can Your Agent Do?](#what-can-your-agent-do)
- [Why This Matters](#why-this-matters-beyond-me)
- [The Process](#the-process-the-schlep)
- [The Result](#the-result)
- [What I Learnt](#what-i-learnt)
- [📚 Further Reading](#-further-reading)

---

## What You'll Get

| Feature | Description |
|---------|-------------|
| 🧠 **Memory That Persists** | Your agent remembers context across sessions, even after IDE restarts |
| 📚 **93 Handpicked Protocols** | Curated decision frameworks from the private repo's 324 unique collection |
| 🔄 **Platform Independence** | Your data lives in Markdown files you own — take it anywhere |
| 🔌 **MCP Server** | 9 standardized tools via [Model Context Protocol](https://modelcontextprotocol.io/) — works with any MCP client |
| 🛡️ **Permissioning** | 4 capability levels + 3 sensitivity tiers + Secret Mode for demo/external sharing |
| 📊 **Evaluator Gate** | 50-query regression suite with MRR@5 scoring to prevent search quality degradation |
| 🤖 **Full Autonomy** | Your agent can act on your behalf while you sleep |

## ⚡ 5-Minute Quickstart

> [!IMPORTANT]
> **Prerequisites**: Desktop computer (Mac, Windows, or Linux) + an AI-powered IDE ([Antigravity](https://antigravity.google/), [Cursor](https://cursor.com), or VS Code with Copilot). Basic terminal comfort (copy-paste commands). **Not available on mobile.**

### Option A: Cloud Factory (Fastest)

1. Click the **[Open in GitHub 

... (truncated)