Athena-Public README

The project's README from github.com/winstonkoh87/Athena-Public. As one markdown file: README.md.

Athena

A local-first memory, decision engine, and governance harness for AI agents — portable across IDEs.

Own the state. Rent the intelligence. Persistent memory, structured reasoning, and governed AI agents that work across any LLM — stored as plain Markdown and JSONL on your disk across Claude Code, Antigravity, Cursor, Gemini CLI, and VS Code.

CI PyPI License: MIT GitHub Stars

20-second demo: /start recalls last session → work → /end

Quickstart · How It Works · SDK & MCP Tools · Docs · Why Athena? · Safety

The Problem

You've spent months training ChatGPT to understand you. Then a model update resets the personality. You switch to Claude or Gemini — you start from zero. Worse, platform memory is designed to agree with you faster, not to stress-test your assumptions when stakes are high.

Athena moves the memory, problem-framing, and decision layer to your machine: plain Markdown and JSONL ledgers that you own, git-version, and mount into any IDE. The model is just whoever's on shift.

Quickstart

git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[local]"               # lightweight — no cloud deps
athena init --ide claude                # or: antigravity, cursor, gemini, vscode, kilocode, roocode
athena doctor                           # expect 0 failures

Then type /start in your IDE's AI chat panel. Work normally. Type /end to save.

Full install (cloud sync + cross-encoder reranking): pip install -e ".[full]" See Getting Started for Windows, advanced config, and Supabase setup.

How It Works

┌───────────────────────────────────────────────────────────────────┐
│  Your IDE (Claude Code / Antigravity / Cursor / Gemini / VS Code) │
└───────────────────────────────┬───────────────────────────────────┘
                                │ MCP Server (18 tools) + Lifecycle Hooks
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│  Athena SDK (src/athena/)                                         │
│  ├── 1. Memory & RAG: /start (~2K boot), hybrid search + reranker │
│  ├── 2. Problem Framing: VOI calculator, falsifier & R1-R13 gates │
│  ├── 3. Decision Engine: EEV, 1/3 Kelly, Ruin, MCDA, Monte Carlo  │
│  └── 4. Governance: Lambda risk router, ruin blocker, secret scan │
└───────────────────────────────┬───────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│  Your Disk (Plain Markdown + JSONL receipts/ledgers — git-native) │
│  └── Optional: Supabase pgvector (cloud sync) + DuckDB (analytics)│
└───────────────────────────────────────────────────────────────────┘

Three boot modes, one compounding loop:

Mode Boot Token Cost When
Lightweight Just chat, then /end ~500 Quick questions (SNIPER, Lambda < 10)
Standard /start → work → /end ~2K–10K Daily engineering & analysis (STANDARD, Lambda 10–30)
Deep /ultrastart → work → /ultraend ~20K High-stakes strategy & architecture (ULTRA, Lambda > 30)

What Ships in the SDK

Athena is not just a prompt pack — it ships executable Python engines and two Model Context Protocol (MCP) servers (athena.mcp_server and athena.duckdb_mcp_server):

Subsystem Module / MCP Tool What It Computes / Enforces
Hybrid RAG & Context Gate mcp_server.py (smart_search, context_gate) Document-level RRF fusion across BM25 FTS5 + pgvector + filename headers + ONNX cross-encoder rerank; Lambda risk-tier routing (SNIPER / STANDARD / ULTRA)
Problem Framing & VOI Ledger intelligence/frame_ledger.py (frame_open, frame_validate, frame_resolve, frame_status) Value of Information (EVI) stop-rule, falsifiable hypothesis pre-registration, R1–R13 commitment gates (loop budget, surviving contingency branch, irreversible ruin check), LUCK outcome-band gate, and Brier calibration scoring
Quantitative Decision Engine intelligence/gto_engine.py (decision_screen) Deterministic evaluators for Expected Economic Value (eev), One-Third Kelly (kelly), Absorbing-Barrier Ruin (ruin), MCDA with ruin vetoes (mcda), Decision Monte Carlo (decision-mc), Scenario Robustness (robustness), Barbell (barbell), and SHA-256 receipts (.athena/decision_receipts.jsonl)
Local Analytical SQL duckdb_mcp_server.py (query, profile, list_tables, export_result) Zero-dependency DuckDB engine for profiling and querying large CSV, JSON, and Parquet datasets without exhausting LLM context windows
Runtime Governance & Safety core/governance.py, core/permissions.py, .agent/scripts/hook_*.py Capability permission gates, Protocol 509 crisis safety screen, 14/16 destructive command blocker, secret egress scanner, and Doom-Loop circuit breaker

What's enforced in code vs. by prompt

Most AI-agent READMEs state every claim in the same confident voice. This one doesn't.

Claim Status Evidence
Storage & hybrid retrieval — memories stored and surfaced when relevant ✅ Shipped (code-enforced) Hybrid RAG with document-level RRF + cross-encoder rerank, hardened through logged regressions
Portability — Markdown and JSONL on your disk, movable across models ✅ Shipped (structural) Plain files on disk — inspect the repo
Quantitative decision screening — EEV, 1/3 Kelly, Ruin, MCDA, Monte Carlo ✅ Shipped (code-available) gto_engine.py emits SHA-256 receipts (107 tests); Stop hook blocks unreceipted numeric engine claims
Pre-registered problem framing — VOI stop-rule, R1–R13 commitment & falsifier gates ✅ Shipped (code-available) frame_ledger.py validates falsifiers, loop budgets, and Brier calibration (57 tests)
Governed autonomy — hooks block destructive commands, ungrounded claims, and secrets ✅ Shipped (partial) Ruin check blocks 14/16 destructive commands; 2 shell bypasses are known and tracked
Compounding personalization — session 2,000 recalls session 5 🟡 N=1 evidence 2,100+ sessions, 427 active protocols, and 587 case studies by the author; no multi-user study
Anti-sycophancy — personalization doesn't silently increase agreement 🟡 Partial mitigation Code-enforced meta-awareness gate (Claude Code hook); agent-discretion in hookless IDEs — see honest limits

Why publish this table? Because the failure mode of this product category is self-mythologizing — describing aspirations in the present tense. Athena's own convention (Epistemic Status) requires labeling every mechanism as code-enforced, code-available, agent-discretion, or aspirational. This table is that convention applied to the README.

Measured, Not Claimed

# Run the test suite (including frame_ledger and gto_engine red-team suites)
pytest tests/ -v --tb=short

# Screen a decision quantitatively (EEV / 1/3 Kelly / Ruin / MCDA / Monte Carlo)
python -m athena.intelligence.gto_engine --action mcda --help

# Validate a pre-registered problem frame against R1-R13 commitment gates
python -m athena.intelligence.frame_ledger calibrate

# Run the local KV cache & TTFT benchmark (Ollama / llama.cpp)
python scripts/benchmark_kv_cache.py --model qwen2.5-coder:14b

# Run the retrieval evaluator yourself (requires Supabase keys)
python examples/scripts/evaluator.py --gold-set .agent/eval/gold_set.json
Metric Value Verification Command
Local TTFT Scaling (2K Boot) ~35x–50x speedup vs 32K python scripts/benchmark_kv_cache.py
Retrieval Hit@5 (Strict) 0.569 (37 / 65) python examples/scripts/evaluator.py
Retrieval MRR@5 (Strict) 0.472 python examples/scripts/evaluator.py
Retrieval Hit@5 (Lenient) 0.892 (deprecated) Partial substring match (inflated)
Unit & Red-Team Tests 710+ passed (100%) pytest tests/
Secret Leaks (1,248+ commits) 0 detected Gitleaks + privacy_scan.py in CI
Code Quality & Lints 0 ruff findings ruff check src/

Anti-Goodhart Invariant: Why did our reported Hit@5 shift from 0.89 to 0.57? Lenient substring matchers count partial word overlaps as "hits," inflating benchmark scores by ~36% without improving retrieval. We killed the lenient matcher because vanity metrics mask regressions. See the full breakdown: Anti-Goodhart Benchmarking in RAG.

Agent Compatibility

IDE Config file Tested
Claude Code CLAUDE.md ✅
Antigravity AGENTS.md ✅
Cursor .cursor/rules.md ✅
Gemini CLI .gemini/AGENTS.md ✅
VS Code + Copilot .vscode/settings.json ✅
Kilo Code .kilocode/rules/athena.md ✅
Roo Code .roo/rules/athena.md ✅

Documentation

Doc What it covers
Getting Started Install, configure, first session
Your First Session 20-minute guided tutorial
How It Works 4-pillar architecture, search pipeline, and decision gates
Why Athena? Philosophy, problem classification, use cases, cost analysis
Engineering Depth Technical deep dives and honest limits
CLI Reference All commands
FAQ Common questions
Safety Limitations and responsible use
Changelog Release history

Contributing

PRs welcome. Please read CONTRIBUTING.md first.

The codebase uses ruff for linting, pytest for tests, and CI must pass before merge.

MIT License · Contributing · Safety · Security · Code of Conduct

Built and battle-tested solo across 2,100+ sessions by Winston Koh.

Clone it. Boot it. Make it yours.

Athena-Public (winstonkoh87/Athena-Public)

Searching Database…

618 ·GitHub
Athena-Public
这是什么？Athena 是一个本地优先的 AI 编程智能体记忆层：它把你的工作上下文以纯 Markdown 文件的形式存在你自己的磁盘上，这样任何模型或 IDE 都能接着上一次的进度继续。
这是一个聊天应用，还是接入我已在用的 AI 工具？它接入你已在用的智能体——基于 Python 的会话例程加钩子，驱动 Claude Code、Antigravity、Cursor、Gemini CLI 和 VS Code，规则通过钩子强制执行，而不只是靠提示词。
怎么用 Athena 开启一个会话？安装它（通过 pip install -e ".[full]" 完整安装，含云同步和重排序），然后在 IDE 的 AI 聊天面板输入 /start，正常工作，最后输入 /end 保存。
它实际支持哪些编程智能体和 IDE？它已在 Claude Code、Antigravity、Cursor、Gemini CLI、VS Code+Copilot、Kilo Code 和 Roo Code 上测试过，各自通过自己的配置文件（如 CLAUDE.md 或 AGENTS.md）接入。
安全防护真的能挡住所有危险操作吗？不能完全挡住——内置的 Ruin 检查能拦截 16 个已知破坏性命令中的 14 个，另有 2 个已记录的绕过方式，而防谄媚保护目前只在 Claude Code 内有效。
我的会话上下文实际存在哪里？在你自己的机器上，以纯文本、可版本控制的 Markdown 文件形式——Athena 绝不会把你的上下文锁在提供商的平台记忆里。
老实说，记忆召回的效果到底如何？在严格基准下，Retrieval Hit@5 为 0.569（37/65），MRR@5 为 0.472；作者舍弃了早先宽松口径下的 0.892，因为子串匹配把分数虚高了约 36%，并非真正的提升。
三种会话模式是什么？轻量模式（直接聊天，然后 /end，约 500 token）用于快速提问；标准模式（/start -> 工作 -> /end，约 2K-10K token）用于日常使用；深度模式（/ultrastart -> 工作 -> /ultraend，约 20K token）用于复杂规划。
作者为什么自己做这个，而不依赖 ChatGPT 或 Claude 的内置记忆？平台记忆在模型更新后会重置，而且被锁定在单一提供商，切换到 Claude 或 Gemini 就意味着从零开始；Athena 把记忆保存在磁盘上，与哪个模型“当班”无关。
“上下文复利”的说法有真实使用数据支撑吗？它基于作者单人超过 1900 个会话，其中较晚的会话能回忆起更早的会话——但 README 坦言这背后还没有多用户研究。
What are similar projects?ruflo, xerj, memvid, EverOS, operator-memory, m_flow, agentmemory, headroom
Which topics is it in?graphrag, hybrid-search, long-term-memory, antigravity, hooks, ai-assistant, vector-search, knowledge-management, knowledge-graph, context-engineering, vscode, semantic-search
Creator
winstonkoh87
Size
12.5 MB
Stars
618
Updated
CommitOct 18Releasev10.0.6Oct 17
Age
10mo
Commits · 90 Days