athena-agent 9.2.6

Athena Bionic OS — The Linux Distro for AI Agents. Model-agnostic, local-first, sovereign.

Project Athena

Your memory. Your machine. Any model.

Open-source AI personalisation layer that gives you persistent memory, structured reasoning, and full data ownership — across ChatGPT, Claude, Gemini, and any model you switch to next.

Platforms forget. Athena doesn't.

Quickstart · How It Works · Docs · FAQ · Contributing

Last updated: 25 February 2026

---

The Problem

You've spent months training ChatGPT to understand you. Then a model update resets the personality. Your custom instructions stop working. You can't find that conversation from last Tuesday. And if you switch to Claude or Gemini? You start from zero.

Platform memory is unreliable, opaque, and locked to one provider. You don't own it, you can't inspect it, and you can't take it with you.

Why Athena?

Athena moves the memory layer to your machine. Plain Markdown files that you own, version-control, and point at any model.

• 🧠 Your Memory, Your Machine — Files on your disk, not in OpenAI's cloud. Read them, edit them, git-version them.
• 🔌 Switch Models Freely — Claude today, Gemini tomorrow, GPT next week. The memory stays. The model is just whoever's on shift.
• 📈 It Compounds — Session 500 recalls patterns from session 5. Platform memory decays; Athena's doesn't.
• ⚡ ~10K Token Boot — 95% of your context window stays free, even after 10,000 sessions.
• 🛡️ Governed Autonomy — 6 constitutional laws, 4 capability levels, bounded agency.

The LLM is the engine. Athena is the chassis, the memory, and the rules of the road. Swap the engine anytime — the car remembers every road you’ve driven.

---

"…But doesn't ChatGPT / Gemini / Claude already do this?"

Kind of. But there's a difference between remembering your name and thinking in your frameworks:

Capability	Platform Memory (ChatGPT, Gemini, Claude)	Athena
Who owns the data?	The platform	You
Can you inspect it?	No — it's a black box	Yes — it's markdown files you can read and edit
Can you search it?	Vague recall, no precision	Full semantic + keyword search with file links
Cross-platform?	Locked to one provider	Same memory works across Claude, Gemini, GPT, Grok
Version history?	None — no rollback, no audit trail	Full git log, git diff, git blame
What if you switch providers?	Start over	Nothing changes — your data stays

💡 Think of platform memory like photos on Instagram — you can view them, but you don't own them, can't move them, and can't search them precisely. Athena is keeping the originals on your hard drive, with albums, metadata, and full edit history.

"How is Athena different from...?"

Tool	What It Does	How Athena Is Different
ChatGPT Projects	Uploads files per-project, but resets every new chat. Locked to OpenAI.	Athena persists across all chats, all models, with full version history.
OpenClaw	Prompt distribution — share and discover prompts.	Athena is personalisation — your compounding memory system, not a prompt marketplace. Different layer, different problem.
Claude Code	Great for Claude coding workflows.	Athena works across any model and any IDE. Not coding-specific — used for research, strategy, writing, life management.
Gemini Gems	Custom chatbots inside Gemini.	Gems are locked to Gemini and lose context between chats. Athena is portable and persistent.
Custom Instructions	1,500-character personality prompt.	Athena loads ~10K tokens of structured protocols, decision frameworks, and session history — re-injected every session from your disk.

---

🧬 Why Thousands of Files?

Athena's workspace looks unusual — 6,000+ Markdown files and 1,000+ Python scripts instead of one big config. This is deliberate.

AI agents don't read files top-to-bottom like humans. They query — by filename, semantic search, or tag lookup. Each small file is an addressable memory node the agent can retrieve surgically, without loading everything else.

Principle	What It Means
JIT Loading	Boot at ~10K tokens. Load specific files only when the query demands them. A monolith forces the full context into every session.
Zero Coupling	A marketing protocol loads without touching the trading stack. Change one file, break nothing else.
Surgical Retrieval	The agent pulls CS-378-prompt-arbitrage.md by name — not page 47 of a 200-page doc. The file system is the index.
Git-Friendly	Atomic diffs per file. Clean commit history. No merge conflicts from a single giant file.
Composable Agents	Swarms, workflows, and skills are mix-and-match. Each file is a Lego brick, not a chapter in a novel.

A monolith is optimized for a human reading a book. A modular workspace is optimized for an agent querying a database. Athena chose the agent.

---

⚡ Quickstart

Works on macOS, Windows, and Linux.

# 1. Fork & clone
git clone https://github.com/YOUR_USERNAME/Athena-Public.git && cd Athena-Public

# 2. Install the SDK (optional — enables CLI commands)
pip install -e .

# 3. Open the folder in your AI IDE (VS Code, Cursor, Claude Code, etc.)

# 4. Boot:
/start

# 5. First time? Take the guided tour:
/tutorial

# 6. When you're done:
/end

[!IMPORTANT] Athena works through AI-enabled code editors (IDEs), not through ChatGPT.com or Claude.ai. You need an app like VS Code + Copilot, Cursor, or Claude Code that can read files from your computer. Think of Athena as a plugin for your editor, not a plugin for a chatbot.

[!CAUTION] Forks of public repos are public by default. If you plan to store personal data (health records, finances, journals), create a new private repo instead of forking. Copy the files manually or use git clone + git remote set-url to point to your private repo. GitHub docs on fork visibility →

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

[!TIP] /tutorial walks you through everything: what Athena is, how it works, builds your profile, and demos the tools (~20 min). Confident users can skip it and jump straight to work.

⚠️ Don't pip install athena-cli — that's a different package. Use pip install -e . inside the cloned repo.

See the full guide →

---

🔄 How It Works

Every session follows one cycle: /start → Work → /end. Each cycle deposits structured memory. Over hundreds of cycles, the AI stops being generic and starts thinking like you.

flowchart LR
    A["/start"] --> B["Work"]
    B --> C["/end"]
    C --> D["Memory"]
    D --> A

    style A fill:#22c55e,color:#fff,stroke:#333
    style C fill:#ef4444,color:#fff,stroke:#333
    style D fill:#8b5cf6,color:#fff,stroke:#333
    style B fill:#3b82f6,color:#fff,stroke:#333

Sessions	What Happens
1–50	Basic recall — remembers your name, project, preferences
50–200	Pattern recognition — anticipates your style and blind spots
200+	Deep sync — thinks in your frameworks before you state them

The Linux Analogy

Concept	Linux	Athena
Kernel	Hardware abstraction	Memory persistence + retrieval (RAG, Supabase)
File System	ext4, NTFS	Markdown files, session logs, tag index
Scheduler	cron, systemd	Heartbeat daemon, 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

---

📦 What's In The Box

Everything you need to turn a generic AI into your AI — pre-configured, no assembly required.

Component	What It Does For You
🧠 Core Identity	Your AI's personality, principles, and boundaries — editable, version-controlled — template
📋 120+ Protocols	Ready-made decision frameworks (risk analysis, research, strategy) across 13 categories — browse
⚡ 50+ Slash Commands	One-word triggers: /start, /end, /think, /research — full list
🔍 Smart Search	Finds the right memory even if you describe it vaguely (5 sources, auto-ranked) — how it works
🔌 Tool Integration	Your agent can search, save, and execute scripts on your behalf — docs
🛡️ Safety Rails	Controls what the AI can and can't do autonomously (4 levels, from read-only to full agency) — security

[!TIP] Run /tutorial on your first session for a guided walkthrough (~20 min). It explains everything above and builds your personal profile.

Agent Compatibility

Athena works through AI-enabled code editors — apps that connect to AI models while reading your local files. It does not work through ChatGPT.com, Claude.ai, or Gemini web — those are closed sandboxes that can't read your disk.

Agent	Status	Init Command
Claude Code	✅	athena init --ide claude
Antigravity	✅	athena init --ide antigravity
Cursor	✅	athena init --ide cursor
Gemini CLI	✅	athena init --ide gemini
VS Code + Copilot	✅	athena init --ide vscode
Kilo Code	✅	athena init --ide kilocode
Roo Code	✅	athena init --ide roocode

More agents planned — full compatibility list →

"How is this different from ChatGPT Projects?" — Projects reset every new chat and are locked to one platform. Athena persists across all chats, all models, with full version history. Details →

---

🎯 Use Cases

	Use Case	What It Looks Like
🏠	Life Management	Daily routines, health tracking, pet care, family scheduling — see how one user built a full life OS in 72 hours
💼	Work & Projects	Switch between multiple client projects without losing context. Meeting prep, cross-team knowledge, shift scheduling.
✍️	Writing & Voice	After 30 sessions, the AI stops sounding like ChatGPT and starts sounding like you. Learns your style from your own writing samples.
🎯	Decision-Making	"Should I take this job offer?" — answered using your actual risk tolerance, career goals, and decision history.
🔬	Research & Synthesis	Compile 200 sources into one framework — still searchable and citable 6 months later.
📐	Strategic Planning	Long-term planning across dozens of sessions. Budget modeling, scenario analysis, with full context of your past decisions.

Not just for coding. Athena is used for personal knowledge management, health tracking, creative writing, business strategy, and daily life — by people who've never written a line of code.

---

💰 Cost

Athena is free. Forever. MIT licensed. You only pay for the AI subscription you're probably already paying for.

Plan	Cost	Who It's For
Google Antigravity (free tier)	$0	Try Athena first — included with any Google account
Claude Pro / Google AI Pro	~$20/mo	Daily users — the sweet spot for most people
Claude Max / Google AI Ultra	$200+/mo	Power users managing multiple domains (8+ hrs/day)

Try before you buy. Athena works with Google Antigravity's free tier — clone the repo, type /start, and see if it clicks. No credit card, no trial period, no catch. Upgrade only when you hit the free tier's daily limits.

Boot cost is ~10K tokens — constant whether it's session 1 or session 10,000. Details →

[!NOTE] Athena works with any model, but governance protocols and multi-step reasoning perform best with frontier models (e.g. Claude Opus 4.6, Gemini 3.1 Pro, GPT-5.3). Start with the free tier to test compatibility with your preferred model.

---

📚 Documentation

📖 Getting Started	🏗️ Architecture	🔒 Security
🎯 Your First Session	🔍 Semantic Search	📊 Benchmarks
💡 Tips	🔌 MCP Server	❓ FAQ
🔄 Updating Athena	📥 Importing Data	⌨️ CLI Reference
📋 All Workflows	📐 Spec Sheet	📓 Glossary
🧠 Manifesto	📈 Changelog	🔀 Multi-Model Strategy
✅ Best Practices

---

🛠️ Tech Stack

Layer	Technology
SDK	athena Python package (v9.2.6)
Search	Hybrid RAG — FlashRank reranking + RRF fusion
Embeddings	text-embedding-004 (768-dim)
Memory	Supabase + pgvector / local ChromaDB
Routing	CognitiveRouter — adaptive latency by query complexity

📂 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, doctor commands
│   └── mcp_server.py        #   MCP Tool Server (9 tools, 2 resources)
├── scripts/                 # Operational scripts (boot, shutdown, launch)
├── examples/
│   ├── protocols/           # 120+ starter frameworks (13 categories)
│   ├── scripts/             # 500+ reference scripts
│   └── templates/           # Starter templates (framework, memory bank)
├── docs/                    # Architecture, benchmarks, security, guides
└── pyproject.toml           # Modern packaging

📋 Recent Changelog

• v9.2.6 (Feb 25 2026): Kilo Code + Roo Code IDE integration, COMPATIBLE_IDES.md, issue #19 closed
• v9.2.5 (Feb 24 2026): Life Integration Protocol Stack — Protocols 381-383, Emotional Audit, /review workflow
• v9.2.3 (Feb 21 2026): Multi-agent safety hardening, CLAUDE.md symlinks, issue deflection
• v9.2.2 (Feb 21 2026): S-tier README refactor, docs restructure
• v9.2.1 (Feb 20 2026): Deep Audit & PnC Sanitization — 17 patterns sanitized across 13 files
• v9.2.0 (Feb 17 2026): Sovereignty Convergence — CVE patch, agentic search, governance upgrade
• v9.1.0 (Feb 17 2026): Deep Audit & Sync — Fixed 15 issues (dead links, version drift)
• v9.0.0 (Feb 16 2026): First-Principles Workspace Refactor — root dir cleaned, build artifacts purged

👉 Full Changelog →

---

🌟 Star History

MIT License · Contributing · Security · Code of Conduct

Clone it. Boot it. Make it yours.