Athena-Public

Athena-Public

The Linux OS for AI Agents โ€” A local OS that gives any LLM persistent memory, autonomy, and time-awareness. Own the state. Rent the intelligence.

Stars: 288

Visit
 screenshot

Project Athena is a Linux OS designed for AI Agents, providing memory, persistence, scheduling, and governance for AI models. It offers a comprehensive memory layer that survives across sessions, models, and IDEs, allowing users to own their data and port it anywhere. The system is built bottom-up through 1,079+ sessions, focusing on depth and compounding knowledge. Athena features a trilateral feedback loop for cross-model validation, a Model Context Protocol server with 9 tools, and a robust security model with data residency options. The repository structure includes an SDK package, examples for quickstart, scripts, protocols, workflows, and deep documentation. Key concepts cover architecture, knowledge graph, semantic memory, and adaptive latency. Workflows include booting, reasoning modes, planning, research, and iteration. The project has seen significant content expansion, viral validation, and metrics improvements.

README:

Athena Banner

๐Ÿ›๏ธ Project Athena โ€” The Linux OS for AI Agents

GitHub Stars Last Updated License: MIT Python Version Reddit Views Open in GitHub Codespaces

Athena is not an AI Agent. It is the Linux OS they run on. Open Source ยท Sovereign ยท Model-Agnostic


What Is Athena?

Athena gives AI agents something they don't have: persistent memory, structure, and governance.

Most AI agents reset every session โ€” brilliant but amnesiac. Athena provides the state layer that any agent (Claude, Gemini, GPT, Llama) reads on boot and writes to on shutdown. Think of it as a memory card that works in any game console.

OS Concept Linux Athena
Kernel Hardware abstraction Memory persistence + retrieval (VectorRAG, Supabase)
File System ext4, NTFS Markdown files, session logs, tag index
Scheduler cron, systemd Heartbeat daemon, daily briefing, auto-indexing
Shell bash, zsh MCP Tool Server, /start, /end, /think
Permissions chmod, users/groups 4-level capability tokens + Secret Mode
Package Manager apt, yum Protocols, skills, workflows

You own the data (Markdown files on your machine, git-versioned). You only rent the intelligence (LLM API calls). Switch models tomorrow and your memory stays exactly where it is.

๐Ÿ’ก "But I have ChatGPT Memory / 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.

SaaS Memory (ChatGPT/Claude) Athena
Ownership Rented (Vendor Lock-in) Owned (Local Files)
Lifespan Until session/project deleted Forever (Git Versioned)
Structure Opaque Blob Structured Knowledge Graph
Search Basic keyword Hybrid RAG (5 sources + RRF fusion)
Agency Zero (waits for you) Bounded Autonomy (Heartbeat, Cron)
Tool What It Does How Athena Differs
ChatGPT Memory Stores flat facts ("User likes Python") Athena stores structured state โ€” project context, decision logs, evolving architecture
Claude Projects Single context file per project Athena is a multi-file system with semantic search across 1,000+ documents
Mem0 SaaS memory layer Athena is local-first, MIT-licensed โ€” your data never leaves your machine
Obsidian + MCP Note-taking with AI plugins Complementary โ€” Athena adds semantic search, auto-indexing, and session lifecycle
Custom RAG DIY vector search Athena includes RAG but adds governance, permissioning, scheduling, and sessions
๐Ÿ“– Jargon Decoder
Athena Term What It Actually Is Do You Need It?
"Memory" RAG โ€” storing text in a database and retrieving it later Yes. This is the core
"Protocols" System prompts / reusable instructions Yes. Saved templates for AI behavior
"Cold Storage" Markdown files on your disk Yes. Plain text you can read/edit anywhere
"Hot Storage" Vector database (Supabase + pgvector) Optional. Enables semantic search
"Heartbeat" A background daemon that auto-indexes your files Optional. Passive awareness without manual /start
"Adaptive Latency" The AI uses more compute for hard tasks, less for easy ones Automatic. You don't configure this

๐Ÿ‘‰ Full glossary: docs/GLOSSARY.md


โšก Quickstart (3 Steps)

Step Action
1. Get an IDE Antigravity ยท Cursor ยท VS Code + Copilot ยท GitHub Codespaces
2. Clone this repo git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
3. Open folder โ†’ Type /start The AI reads the repo structure and takes it from there
4. Type /brief interview Athena asks about YOU โ€” goals, style, domain โ€” and builds your personal profile

That's it. No config files. No API keys. No database setup. The folder is the product.

[!TIP] When you're done, type /end to save. Next time you /start, the agent picks up exactly where you left off. Your first session takes ~30 minutes (mostly the interview). Every session after that boots in seconds.

๐Ÿ”ง CLI Reference
pip install -e .              # Install SDK
athena                        # Boot session
athena init .                 # Initialize workspace in current directory
athena init --ide cursor      # Init with IDE-specific config
athena check                  # System health check
athena save "summary"         # Quicksave checkpoint
athena --end                  # Close session and save
athena --version              # Show version (v9.0.0)
๐Ÿ“ฅ Import Existing Data (ChatGPT, Gemini, Claude)

Athena's memory is just Markdown files. Any text you can export becomes part of your memory:

Source How to Import
ChatGPT Settings โ†’ Data Controls โ†’ Export โ†’ Copy .md files into .context/memories/imports/
Gemini Google Takeout โ†’ Select "Gemini Apps" โ†’ Extract into .context/memories/imports/
Claude Settings โ†’ Export Data โ†’ Copy transcripts into .context/memories/imports/
Any Markdown Drop .md files into .context/memories/ โ€” indexed on next /start

After importing, run athena check to verify files are detected.


๐Ÿชž Your First Session

Athena is a skeleton โ€” protocols, search, and infrastructure. You provide the soul.

On your first /start, run /brief interview. Athena will ask you about everything โ€” your name, profession, goals, decision style, strengths, blind spots, even your life context. This isn't small talk. It's the foundation that makes every future session compound.

What Athena Asks Why
Identity โ€” Name, age, nationality Communication style, cultural context
Professional โ€” Role, industry, salary range Domain expertise, decision-making context
Goals โ€” 3-month, 1-year, 5-year Aligns every response to your actual trajectory
Decision Style โ€” Risk appetite, speed vs quality Calibrates how options and tradeoffs are framed
Blind Spots โ€” Recurring mistakes, weak areas Athena proactively flags these before they bite
Communication โ€” Tone, verbosity, directness Sets the default voice across all interactions

[!IMPORTANT] Everything stays local. Your profile is stored as a Markdown file on your machine (user_profile.md). No cloud. No tracking. Be as candid as you want โ€” this is your private operating system.

Pattern: The more you share โ†’ the faster Athena stops being generic โ†’ the sooner it starts thinking like you.

๐Ÿ‘‰ Full First Session Guide โ€” detailed walkthrough with examples


Core Features

๐Ÿ”„ The Loop

After you install Athena, you repeat one cycle: /start โ†’ Work โ†’ /end. Every cycle deposits training data into memory. Over hundreds of cycles, Athena stops being generic and starts thinking like you.

flowchart TD
    START["๐ŸŸข /start"] -->|"Load identity + recall"| WORK["๐Ÿ”ง Work Session"]
    WORK -->|"Auto-save every exchange"| WORK
    WORK -->|"Done for the day"| END["๐Ÿ”ด /end"]
    END -->|"Finalize, sync, commit"| MEMORY["๐Ÿง  Memory"]
    MEMORY -->|"Next session boots richer"| START

    style START fill:#22c55e,color:#fff,stroke:#333
    style END fill:#ef4444,color:#fff,stroke:#333
    style MEMORY fill:#8b5cf6,color:#fff,stroke:#333
    style WORK fill:#3b82f6,color:#fff,stroke:#333
Sessions What Happens
1โ€“50 Basic recall. Remembers your name and project.
50โ€“200 Pattern recognition. Anticipates your preferences.
200โ€“500 Deep sync. Knows your frameworks, blind spots, style.
500โ€“1,000+ Full context. Anticipates patterns before you state them.

๐Ÿง  Persistent Memory

Your data lives in Markdown files you own โ€” on your machine, git-versioned. Optionally backed up to Supabase (cloud insurance).

  • Local-first: No vendor lock-in. Switch models anytime.
  • Hybrid search: Canonical + GraphRAG + Tags + Vectors + Filenames, fused via RRF
  • Auto-quicksave: Every exchange is logged without manual action

๐Ÿ“š 120+ Starter Protocols

Starter decision frameworks across 13 categories โ€” architecture, engineering, decision-making, reasoning, and more. These are templates, not prescriptions. The real value comes when you write your own protocols from your own friction and failures.

๐Ÿ”Œ MCP Server (9 Tools)

Expose Athena's capabilities to any MCP-compatible client:

Tool Description
smart_search Hybrid RAG search with RRF fusion
agentic_search Multi-step query decomposition with parallel search
quicksave Save checkpoint to session log
health_check System health audit
recall_session Read session log content
governance_status Triple-Lock compliance state
list_memory_paths Memory directory inventory
set_secret_mode Toggle demo mode (blocks internal tools)
permission_status Show access state & tool manifest

๐Ÿ‘‰ Full MCP Documentation

โšก Slash Workflows

Command Purpose
/start Boot system, load identity and context
/end Close session, commit to memory
/think Deep reasoning mode
/ultrathink Maximum depth analysis
/research Multi-source web research
/save Mid-session checkpoint
/refactor Workspace optimization
/plan Structured planning with pre-mortem
/vibe Ship at 70%, iterate fast

๐Ÿ‘‰ Full Workflow Documentation โ€” all 20 workflows in .agent/workflows/

๐Ÿ›ก๏ธ Permissioning & Governance

  • 4 capability levels: read โ†’ write โ†’ admin โ†’ system
  • 3 sensitivity tiers: public โ†’ internal โ†’ restricted
  • Secret Mode: Toggle for demos โ€” only public tools remain accessible
  • Evaluator Gate: 50-query regression suite (MRR@5 = 0.44) to prevent search degradation

Repository Structure

Athena-Public/
โ”œโ”€โ”€ src/athena/              # SDK package (pip install -e .)
โ”‚   โ”œโ”€โ”€ core/                #   Config, governance, permissions, security
โ”‚   โ”œโ”€โ”€ tools/               #   Search, agentic search, reranker, heartbeat
โ”‚   โ”œโ”€โ”€ memory/              #   Vector DB, delta sync, schema
โ”‚   โ”œโ”€โ”€ boot/                #   Orchestrator, loaders, shutdown
โ”‚   โ”œโ”€โ”€ cli/                 #   init, save commands
โ”‚   โ””โ”€โ”€ mcp_server.py        #   MCP Tool Server (9 tools, 2 resources)
โ”œโ”€โ”€ examples/
โ”‚   โ”œโ”€โ”€ protocols/           # 120+ starter frameworks (13 categories)
โ”‚   โ”œโ”€โ”€ scripts/             # 17 core OS scripts
โ”‚   โ”œโ”€โ”€ workflows/           # 20 slash commands
โ”‚   โ”œโ”€โ”€ templates/           # 36 starter templates
โ”‚   โ””โ”€โ”€ quickstart/          # Runnable demos
โ”œโ”€โ”€ docs/                    # Architecture, benchmarks, security, guides
โ”œโ”€โ”€ community/               # Contributing, roadmap
โ”œโ”€โ”€ pyproject.toml           # Modern packaging (v9.0.0)
โ””โ”€โ”€ .env.example             # Environment template

๐Ÿ“ฃ Community

"I gave Gemini a brain..." โ€” Viral on r/GeminiAI and r/ChatGPT (700K+ views)


๐Ÿ“š Further Reading

๐Ÿ—๏ธ Architecture & Design
Document Description
ARCHITECTURE.md System design, data flow, hub architecture
SPEC_SHEET.md Technical specification, data schema, API surface
GRAPHRAG.md Knowledge graph layer โš ๏ธ ~$50 API cost
VECTORRAG.md Semantic memory implementation
SEMANTIC_SEARCH.md Hybrid RAG implementation
MCP_SERVER.md MCP architecture & IDE configuration
KNOWLEDGE_GRAPH.md Compressed concept index
๐Ÿš€ Getting Started & Guides
Document Description
GETTING_STARTED.md Step-by-step setup guide
YOUR_FIRST_AGENT.md 5-minute quickstart
WHAT_IS_AN_AI_AGENT.md Beginner primer
DEMO.md Live walkthrough
WORKFLOWS.md All 48 slash commands
FAQ.md Common questions
GLOSSARY.md Key terms and definitions
๐Ÿ“Š Performance & Case Studies
Document Description
BENCHMARKS.md Boot time, search latency, token economics
CS-001: Boot Optimization 85% boot time reduction
CS-002: Search Quality RRF fusion results
CS-003: Protocol Enforcement Governance engine
TOP_10_PROTOCOLS.md MCDA-ranked essential protocols
ENGINEERING_DEPTH.md Technical depth overview
๐Ÿ”’ Security & Data
Mode Where Data Lives Best For
Local Your machine only Sensitive data, air-gapped environments
Cloud Supabase (your project) Cross-device access
Hybrid Local files + cloud embeddings Best of both
  • Use SUPABASE_ANON_KEY for client-side. Never expose SUPABASE_SERVICE_ROLE_KEY.
  • Enable Row-Level Security on Supabase tables.
  • Restrict agent working directories โ€” never grant access to ~/.ssh or .env.

๐Ÿ‘‰ SECURITY.md ยท LOCAL_MODE.md

๐Ÿง  Philosophy & Deep Dives
Document Description
MANIFESTO.md The Bionic Unit philosophy
USER_DRIVEN_RSI.md How you and AI improve together
TRILATERAL_FEEDBACK.md Cross-model validation ("Watchmen")
Quadrant IV How Athena surfaces unknown unknowns
Adaptive Latency Macro-Robust, Micro-Efficient (RETO)
REFERENCES.md APA-formatted academic citations
ABOUT_ME.md About the author
โš™๏ธ Prerequisites (Optional)

The quickstart needs zero configuration. These are only needed for advanced features:

# Required for cloud features
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
ANTHROPIC_API_KEY=your-anthropic-key

# Optional (for multi-model validation)
GOOGLE_API_KEY=your-google-api-key
OPENAI_API_KEY=your-openai-key
cp .env.example .env
# Add your keys
๐Ÿ› ๏ธ Tech Stack
Layer Technology Purpose
SDK athena Python package (v9.0.0) Core search, reranking, memory
Reasoning Claude Opus (primary) Main reasoning engine
Optimization DSPy Prompt optimization & self-correction
Reranking FlashRank Lightweight cross-encoder RRF
IDE Antigravity, Cursor, VS Code Agentic development environment
Embeddings text-embedding-004 (768-dim) Google embedding model
GraphRAG NetworkX + Leiden + ChromaDB Knowledge graph โš ๏ธ ~$50 API
Memory Supabase + pgvector / local ChromaDB Vector database
Routing CognitiveRouter Adaptive latency by query complexity
๐Ÿ“‹ Changelog

February 2026

  • v9.0.0 (Feb 16 2026): First-Principles Workspace Refactor โ€” Root directory cleaned (28โ†’14 files), 114 stub session logs archived, build artifacts purged, dead .framework/v7.0 archived, .gitignore hardened. Zero regressions (17/17 tests pass).
  • v8.6.0 (Feb 15 2026): Massive Content Expansion โ€” 200 protocols (was 75), 535 scripts (was 16), 48 workflows (was 14), 36 templates. 23 protocol categories. Repo audit for recruiter readiness. Content sanitization pass.
  • v8.5.0 (Feb 12 2026): Phase 1 Complete โ€” MCP Tool Server (9 tools, 2 resources), Permissioning Layer (4 levels + secret mode), Search MRR +105% (0.21โ†’0.44), Evaluator Gate (50 queries). SDK v2.0.0.
  • v8.3.1 (Feb 11 2026): Viral Validation Release โ€” 654K+ Reddit views, 1,660+ upvotes, 5,300+ shares. #1 All-Time r/ChatGPT, #2 All-Time r/GeminiAI.
  • v8.2.1 (Feb 9 2026): Metrics Sync โ€” Fixed batch_audit.py automation, linked orphan files, reconciled tech debt, 8,079 tags indexed

๐Ÿ‘‰ Full Changelog โ€” Complete version history from v1.0.0 (Dec 2025)


License

MIT License โ€” see LICENSE


This is a starter kit. Your instance will reflect your domain, your decisions, your voice. Clone it, make it yours.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for Athena-Public

Similar Open Source Tools

For similar tasks

For similar jobs