Skip to main content

​
General

Athena is an open-source framework for building AI agents with persistent memory. Unlike ChatGPT or Claude’s built-in memory, Athena stores everything in Markdown files you own — portable, version-controlled, and model-agnostic.
No. Athena is a system architecture:
  • .framework/ — Your AI’s identity and operating principles
  • .context/ — Long-term memory (decisions, case studies, session logs)
  • .agent/ — Workflows, scripts, and automation
The prompts are part of it, but the real value is the structure that compounds over time.
Athena separates the IDE from the Reasoning Engine, so you are never locked into a single platform or model.1. The IDE (Where you type):
  • Antigravity (Google)
  • Cursor / VS Code
  • Claude Code / Gemini CLI
2. The Reasoning Engine (Who does the thinking):
  • Gemini 3.1 Pro
  • Claude Opus 4.6
  • GPT-5.3
  • Any LLM that can read your local Markdown files

​
Setup & Installation

5 minutes for the basic install:
git clone https://github.com/winstonkoh87/Athena-Public.git
cd Athena-Public
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
For full power features (vector search, GraphRAG), budget 30-60 minutes.
Minimal setup: No API keys required. Works with local files only.Full setup (recommended):
  • ANTHROPIC_API_KEY — For Claude reasoning
  • GOOGLE_API_KEY — For embeddings (text-embedding-004)
  • SUPABASE_URL + SUPABASE_ANON_KEY — For vector database (optional)
Yes. Athena is IDE-agnostic. Use:
athena init --ide cursor    # Creates .cursor/rules.md
athena init --ide antigravity  # Creates AGENTS.md
No. Three options:
ModeHowBest For
StandaloneOpen Athena/ as your workspace. Navigate to your project from there.All-in-one brain
Multi-RootOpen your project → File → Add Folder to Workspace → select Athena/Existing repos
NestedDrop your project folder inside Athena/Quick prototypes
All three work. Start with Standalone and adjust to taste.
Keep Athena as your personal brain. Create client folders outside the workspace (e.g., ~/Desktop/Client-A/). When working on a client project, point Athena to that external folder. This keeps your personal context clean and prevents client data from polluting your memory bank.When the engagement ends, archive the generalized learnings back into Athena (strip client-specific data) and archive or delete the external folder. Athena keeps the wisdom. The client keeps the execution.

​
Cost & Performance

ComponentCost
Basic usage (local files only)Free
Embeddings (Google API)~$0.001 per 1K tokens
Claude API (direct calls)Depends on usage
Supabase (vector DB)Free tier available
GraphRAG (knowledge graph)⚠️ ~$50 one-time API cost
Most users spend < $5/month on API calls.
ModeTime
Cold boot (first session)~1–2 minutes
Warm boot (cached)< 5 seconds

​
Privacy & Security

Local Mode: Everything stays on your machine. Zero data leaves.Cloud Mode: Only embeddings (vectors) are sent to Supabase. Raw text stays local.Hybrid Mode (default): Local files + cloud embeddings for search.
Yes, if you use Local Mode. For enterprise use, see the Security documentation for RLS policies and key management.

​
Still stuck?

Build docs developers (and LLMs) love

Get started for freeTalk to us