Athena – Portable, self‑hosted AI‑agent memory

What it is – Athena is a Python‑based SDK that lets you keep an LLM agent’s “memory” on your own disk as ordinary Markdown files. The idea is that the same context can travel with you across different IDE‑integrated chat assistants (Claude Code, Antigravity, Cursor, Gemini CLI, VS Code, etc.) and across any underlying model. Athena provides a small command‑line interface (athena init, /start, /end, /ultrastart, …) that hooks into the chat panel of those IDEs, records the session, and later retrieves relevant facts with a hybrid keyword‑plus‑vector RAG pipeline.

---

Why it matters

• Portability – No vendor‑locked memory. Your knowledge lives in plain, git‑trackable Markdown, so you can switch from Claude to Gemini (or any future model) without losing context.
• Local‑first – The “lightweight” install has no cloud dependencies; everything runs on your machine. An optional “full” install adds Supabase‑backed pgvector storage for cloud sync and reranking.
• Safety hooks – Athena injects code‑enforced guardrails (ruin‑check, secret scanning, grounding) that stop destructive commands before they reach the model.
• Cost‑aware – Different usage modes (lightweight, standard, deep) let you control how many tokens are loaded/saved per session, keeping API costs predictable.

---

Core components

Component	Role
IDE hook	Minimal, code‑enforced integration that captures /start … /end commands from the chat UI of supported IDEs.
Athena SDK	Handles the session lifecycle, writes Markdown logs, runs a hybrid retrieval pipeline (keyword search + optional vector embeddings + cross‑encoder rerank).
Disk storage	Plain Markdown files, version‑controlled with git. Optional Supabase pgvector store for cloud‑sync and faster vector search.

The architecture is visualised in the README as a three‑layer flow: IDE → Athena SDK → Disk (or Supabase).

---

Getting started (quick)

# Clone & set up a virtual environment
git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
python3 -m venv .venv && source .venv/bin/activate

# Install the lightweight package (no cloud deps)
pip install -e "[local]"

# Initialise for your IDE (example: Claude Code)
athena init --ide claude

# Verify the installation
athena doctor   # should report 0 failures

After that, type /start in the IDE’s AI chat panel, work as usual, and finish with /end. The session is automatically saved to Markdown.

---

Safety & reliability

• Guardrails – Built‑in “ruin check” blocks 14 of 16 known destructive commands; the remaining two are tracked in docs/TECH_DEBT.md.
• Secret scanning – CI runs Gitleaks on every commit; the README reports zero leaks across 1,248 commits.
• Benchmarking – The repo ships scripts to measure:
  • KV‑cache warm‑up speed‑up (≈35‑50× faster for a 2K‑token boot vs a 32K boot).
  • Retrieval quality (Hit@5 = 0.569, MRR@5 = 0.472) on a strict evaluator.
• Testing – 644 unit & integration tests all pass (pytest). Linting with ruff shows no issues.

---

Who should use it?

• Developers who rely on AI‑assisted coding and want their personal context to survive model or provider changes.
• Teams that already version‑control documentation and want a reproducible, auditable memory layer for their LLM assistants.
• Privacy‑conscious users who prefer local storage over proprietary cloud memory.

---

Limitations

• The “compounding personalization” claim is based on a single author’s 1,900+ sessions; no formal multi‑user study yet.
• Anti‑sycophancy mechanisms are only implemented for Claude Code at the moment.
• Full cloud‑sync and vector reranking require a Supabase account and extra configuration.

---

Where to learn more

• Docs – docs/GETTING_STARTED.md, docs/ARCHITECTURE.md, docs/CLI.md.
• Safety – SAFETY.md explains limits and responsible use.
• Benchmarks – docs/BENCHMARKS.md details the retrieval and KV‑cache measurements.
• Contribution – Follow the guidelines in CONTRIBUTING.md if you want to add IDE support or improve the retrieval pipeline.

---

TL;DR

Athena is a real, open‑source tool that moves LLM‑agent memory from opaque platform services to user‑owned Markdown files, with IDE hooks, hybrid RAG retrieval, and safety guardrails. It works locally out‑of‑the‑box and can be extended to cloud‑sync via Supabase.