Athena-Public

winstonkoh87MIT活跃维护

给 AI Agent 用的本地优先记忆、决策引擎与治理框架，状态存在本地、可跨 IDE 迁移，解决 Agent 长期记忆和可控性问题。

Turn stateless LLMs into a stateful, compounding AI agent. Local-first persistent memory, quantitative decision screens, and governance harness across Claude Code, Antigravity, Cursor, and VS Code. Own the state. Rent the intelligence.

v10.0.6发布于 2026-10-17 02:45 UTC622star +2 / 7 天85fork同步于 2026-11-10 23:55 UTC

Agent 框架本地优先长期记忆决策引擎 GraphRAG

对比 GitHub 官网 antigravity chatgpt claude-code context-engineering decision-intelligence

怎么上手

由 README 提炼，执行前请确认

原文

git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[local]"
athena init --ide claude
athena doctor

硬件要求按 README 说明

README 未说明显存或 GPU 要求；本地基准脚本支持 Ollama / llama.cpp 运行模型，但未列出具体型号。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

没人工点评？写下你的经验

本地优先的 AI 智能体记忆与决策引擎，把状态存在自己磁盘上，跨 IDE 通用

给 AI Agent 用的本地优先记忆、决策引擎与治理框架，状态存在本地、可跨 IDE 迁移，解决 Agent 长期记忆和可控性问题。

核心能力

用纯 Markdown 和 JSONL 在本地存记忆，可 git 版本化
混合检索融合 BM25、pgvector 与 ONNX 交叉编码器重排
内置 EEV、1/3 Kelly、破产检验、MCDA 等决策评估器
预注册问题框架，用 R1–R13 承诺门与 VOI 停止规则校验
通过 MCP 服务器与钩子拦截破坏性命令和密钥外泄

容易踩的坑

local 安装不含云端同步与交叉编码器重排，需要这些功能要改用 .[full]；检索评估脚本需要 Supabase 密钥才能运行；部分治理能力依赖 IDE 钩子，无钩子的 IDE 只能靠智能体自觉。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v10.0.6

全部 release

v10.0.6v10.0.6 — Problem-Solving Control Plane, Two-Loop State Machine, & 4-Pillar Positioning Sync最新正式版2026-10-17 · 2026-10-17 02:45 UTC

Athena v10.0.6 delivers the Problem-Solving Control Plane and Two-Loop state machine, integrates fail-closed Law #1 ruin pre-filters into the VOI frame ledger, adds multidimensional risk vector evaluation to the quantitative decision engine, formally transitions to canonical 4-pillar positioning ("Local-first memory, decision engine, and governance harness for AI agents — portable across IDEs. Own the state. Rent the intelligence."), and synchronizes canonical metrics across all public surfaces.

⚖️ Decision Engine & Frame Ledger Control Plane

Ruin Pre-Filter Before VOI Fast-Path (frame_ledger.py):
- Wired max_candidate_ruin_prob and reversibility_score directly into validate_frame().
- Ensures Value of Information (VOI == 0) fast-pathing to ACT is strictly blocked whenever max_candidate_ruin_prob > 0.05 (Law #1 hard floor) or reversibility_score >= 4.
- Prevents premature commitment to irreversible or ruinous actions even when information value is nominally exhausted.
Typed Two-Loop State Machine (frame_ledger.py):
- Added CandidateCluster and CommitmentGate requiring explicit kill_criteria before execution and preserving a typed fallback_cluster_id for Loop 2 -> Loop 1 tactical pivot.
- Added typed LoopState (EXPLORING, COMMITTED, EXECUTING, ITERATING, PIVOTING, CLOSED, ABANDONED) with a bounded max_iterations loop budget, preventing open-ended reasoning loops.
Multidimensional Risk Vector (gto_engine.py):
- Added RiskDimension (FINANCIAL, REPUTATIONAL, LEGAL, RELATIONAL, HEALTH, OPERATIONAL, EPISTEMIC, MIXED, UNKNOWN) and RiskVector (composite_ruin_prob, dominant_dimension, is_acceptable) to Option and DecisionContext.
- Replaces single-scalar financial ruin assumptions with comprehensive multi-attribute risk vectors across heterogeneous real-world decision domains.
RBAC Registration (permissions.py):
- Formally registered decision_screen (read capability) in TOOL_CAPABILITIES and READ_ONLY_SAFE allowlists for safe MCP execution.

🏛️ Canonical Positioning & 4-Pillar Bionic Architecture

4-Pillar Positioning:
- Unified product positioning across all declared documentation surfaces: "Local-first memory, decision engine, and governance harness for AI agents — portable across IDEs. Own the state. Rent the intelligence."
4-Pillar Bionic Architecture & SDK Surface (README.md):
- Codified the 4 architectural pillars: Pillar 1 (Memory & Retrieval), Pillar 2 (Decision & Frame Engine), Pillar 3 (Governance & Safety Harness), and Pillar 4 (Portable Control Plane).
- Shipped the comprehensive "What Ships in the SDK (src/athena/)" MCP tool table and 3-tier epistemic status convention (code-enforced, code-available, agent-discretion).
Canonical Metrics Synchronization:
- Reconciled all documentation and reference metrics with CAPS.json ground truth (428 active protocols / 462 total across 26 categories, 77 workflows [56 root + 21 domain], 44 active skills, 293 scripts, 5,924 memories, 627 case studies, 2,100+ sessions).

📊 Canonical System Metrics (CAPS.json Ground Truth)

Metric	Count / State	Operational Purpose
Active Protocols	428 active (462 total)	Reusable decision frameworks across 26 categories
Slash Workflows	77 commands (56 root + 21 domain)	Slash command triggers for autonomous workflows
Cognitive Skills	44 active (17 archived)	Path- and topic-triggered runtime capabilities
Automation Scripts	293 scripts	Python automation stack (boot, search, sync, governance)
Memory Corpus	5,924 files	Grounded episodic session logs, case studies, and knowledge
Case Studies	627 files	Longitudinal decision analyses across 15 domains
Corpus Scale	2,100+ sessions	Continuous context across 200+ days of bilateral execution

v10.0.5Athena v10.0.5 — Memory Retrieval Substrate, Server-Side Asymmetric Constraints & Zero-Stdout IPC2026-10-07 · 2026-10-07 18:11 UTC
查看更新说明
Athena v10.0.5 delivers major resilience upgrades across the memory retrieval substrate, introduces canonical document-level RRF grouping and cross-encoder header representation, enforces server-side asymmetric constraints on MCP tool execution, eliminates Model Context Protocol (MCP) sys.stdout buffer hijacking with direct payload IPC, tightens Stop Governance gate enforcement, resolves CodeQL security alert #47 (CWE-20), and integrates Gemini 3.8 Flash model cascade support.

🧠 Memory & Retrieval Substrate
- Canonical Document-Level RRF Grouping (search.py):
  
  Implemented regex-based document identity extraction in _doc_prefix() to eliminate false prefix deduplication across distinct documents in the RRF diversity pass.
  
  Resolves the prefix collision trap where distinct protocols and case studies were conflated under generic channel prefixes (Protocol:, Case Study:) and prematurely pruned.
- Cross-Encoder Code Header Representation & Stem Boosting (search.py):
  
  Enriched collect_filenames() with module header extraction (first 300 chars), eliminating cross-encoder logit penalties on code paths (-4.95 to +5.32).
  
  Added exact stem match boost (+0.35) and canonical codebase path boost (+0.25 for src/athena/, .agent/scripts/, scripts/, examples/scripts/).
  
  Pruned noise directories (.venv, __pycache__, .worktrees, .claude) and pre-filtered unranked candidate allocations to top-20 scored items.
- Cache Isolation & Schema Versioning (search.py):
  
  Bumped SEARCH_SCHEMA_VERSION = "2026-10-15.1", strictly isolating search cache state across hybrid retrieval model and score distribution changes.
- FTS5 Query Compiler & Syntax Resilience (fts_search.py):
  
  Implemented compile_fts_query() to sanitize raw search inputs before FTS5 execution.
  
  Automatically quotes hyphenated alphanumeric tokens (e.g. "CS-101", "DOC-123"), strips syntax-critical SQLite operators (:, ?, *, ^), and provides graceful exception handling on sqlite3.OperationalError.
- Corpus Hygiene & Path Exclusion Pruning (fts_search.py):
  
  Implemented in-place directory walk pruning across noise directories (raw_data, cache, self_optimization, archive, node_modules, .venv, .git, .worktrees) and hidden files.
  
  Filtered large non-runtime compilation blobs (graphrag_source_blob.md, scripts_compressed.md), preventing index dilution and maintaining high-precision search ranking.
- RRF Multi-Channel Identity Unification (search.py):
  
  Added _normalize_rrf_key() to unify document identity keys across FTS and vector channels to repo-relative paths (file:...).
  
  Normalized raw BM25 scores to [0.2, 1.0] and bounded dynamic score modifiers strictly to [0.5, 1.5].
  
  Eliminated intra-channel duplicate counting in Reciprocal Rank Fusion (RRF).
- SearchResult Deserialization Resilience (models.py):
  
  Added explicit path attribute and dynamic **extra kwargs absorption to SearchResult dataclass, preventing deserialization errors during cross-module payload passing.
🛡️ Governance & Security Hardening
- Server-Side Asymmetric Constraints (mcp_server.py):
  
  Bound FastMCP instructions to server-side Law #1 Ruin Prevention, Epistemic Fidelity (Law #2 & #5 fact-grounding), write-time cross-repo memory scope declarations, and secrecy constraints.
  
  Prohibits unhedged survival risks and ungrounded factual assertions at the tool definition layer, ensuring negative constraints propagate reliably across calling LLMs and IDEs.
- Zero-Stdout IPC Modernization (mcp_server.py):
  
  Eliminated sys.stdout buffer hijacking in search and context tools via direct print_output=False payload returns.
  
  Integrated decision_screen tool for GTO numerical calculation evaluations and risk screening.
- CodeQL Security Remediation (Alert #47 / CWE-20):
  
  Resolved GitHub CodeQL CWE-20 (alert #47) incomplete URL substring sani
v10.0.4v10.0.4 — Operational OSINT, Local KV Cache Benchmark, & Gate Synchronization2026-10-05 · 2026-10-05 22:40 UTC
查看更新说明
Counterparty Reconnaissance & Due Diligence (Protocol 580)
- Operational OSINT Engine (operational-osint Skill): Added 5-layer counterparty intelligence stack for commercial entity vetting, paid-up capital vs senior floating charges forensics, review sentiment haircuts, and protective OPSEC audits.
- Protocol 580 (RSC-580): Codified 100-point counterparty risk audit across statutory standing, review integrity, financial posture, litigation cause books, and physical permanence with contract risk inversion mechanics.
- /osint Workflow: Added 3-tier cognitive intake funnel (Public Reality -> Exocortex Precedents -> Game-Theoretic Contract Terms) for counterparty screening.
Local Inference & Cache Benchmarking
- KV Cache Scaling Harness (benchmark_kv_cache.py): Added reproducible benchmark harness measuring TTFT, generation throughput (tok/s), and VRAM scaling from 2K to 32K context on local Ollama / llama.cpp engines.
- Unit & Contract Tests: Added tests/test_benchmark_kv_cache.py verifying CLI contracts, table generation, and zero-mutation guarantees.
- Inference Scaling Matrix: Documented empirical ~35x–50x TTFT speedups at 2K zero-touch boot depths across README and docs.
Governance & Verification Gates
- GTO Decision Receipts Gate: Integrated check_decision_receipts in .agent/scripts/hook_stop_verify.py and scripts/hook_stop_verify.py to intercept and verify model engine claims against .athena/decision_receipts.jsonl.
- Formatting & Release Verification: Purged stale static version badge in README and synchronized all declared surfaces to pass automated version sync gates.
v10.0.1v10.0.1 — Deliverable Audit Mode & Multi-Agent Launcher Hardening2026-09-28 · 2026-09-28 16:22 UTC
查看更新说明
Adversarial Review & Deliverable Verification
- Deliverable Audit Mode: Codified isolated fresh-context audit protocol for built deliverables (docx, PDF, reports, slides, code artifacts) against specifications and rubrics in red-team-review/deliverable-audit.md.
- Physical Isolation Packet: Structured pre-audit boundaries excluding answer keys, changelogs, prior audit notes, and author chat logs to eliminate circular confirmation bias.
- Executed Lenses L1–L6: Codified active execution verification (spec compliance, zip/XML inspection of compiled outputs, code rerun, data cross-checks, folder inventory reconciliation, and marker rubric simulation).
- Academic Delivery Pipeline Gate: Integrated Step 7.5 Deliverable Audit gate into academic-delivery skill to enforce compiled deliverable verification prior to sign-off.
Autonomous Runtime & Self-RSI Hardening
- Agent CLI Candidate Resolution: Upgraded scripts/daily_self_rsi.py with multi-agent binary detection across claude, agy, gemini, cursor, code, well-known system paths, and --agent flag override.
- Bounded Queue Backpressure: Calibrated Self-RSI ticket throttle to active 14-day window (<14d), isolating stale tickets (>14d) for archiving to prevent premature circuit breaker trips.
- SDK Typing & Quality: Added type annotations to src/athena/core/skill_telemetry.py.
v10.0.0v10.0.0 — Major Architectural Sync & Ledger-Backed Engine Release2026-09-27 · 2026-09-27 23:58 UTC
查看更新说明
Core Engine & Architecture Modernization
- Ledger-Backed Sync Architecture: Transitioned the public repository distribution from legacy tag-delta polling to an automated, ledger-tracked state machine with strict drift detection.
- Fail-Closed GTO Decision Screening: Upgraded src/athena/intelligence/gto_engine.py with violates_law1, derive_ruin_floors, and fail-closed candidate screening that enforces mandatory veto floors against ruinous actions.
- Protocol 509 Crisis Life-Safety Gate: Embedded hard-stop crisis triage into src/athena/core/lambda_scorer.py and governance checks with automated Singapore emergency hotline referral (SOS 1-767, IMH 6389 2222, 995) and colloquial idiom filtering.
- AgentGate Command Interception: Hardened src/athena/core/ruin_structured.py and src/athena/core/gate_cli.py to intercept destructive Git commands, subshell nesting, python one-liners, file truncation redirects, and data exfiltration attempts.
- AST Codebase Graph Engine: Ported src/athena/tools/ast_graph.py for bidirectional caller-callee resolution, symbol dependency tracking, and dead code detection.
- Local FTS5/BM25 Keyword Engine: Ported src/athena/tools/fts_search.py providing fast SQLite full-text search over markdown memory corpus.
- Evaluator Calibration: Un-flattered RAG evaluation in evaluator.py using strict exact stem matching to eliminate optimistic baseline inflation.
- Sentinel Governance Resilience: Patched unhandled urllib exceptions in .github/scripts/sentinel.py to ensure graceful fallback to rule-based triage on network or model latency.
Upstream Reconciliation & Layout Deduplication
- Adopted Public-Side Work: Reconciled 15 distributed modules into upstream private tracking (edge_node.py, sandbox.py, sessions_rpc.py, skill_nudge.py, skill_telemetry.py, athena_tui.py, athena_client.py).
- Deduplicated Script Layout: Cleaned up duplicated files between .agent/scripts/ and examples/scripts/.
- Test Suite Expansion: Added 13 new test suites across AST graph, FTS search, GTO engine, Lambda scoring, crisis gate, and AgentGate command security, bringing the green test suite to 43 test modules (590+ tests).

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

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.

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

Quickstart · How It Works · Structure · 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 & Wargaming: EEV, 1/3 Kelly, Ruin, MCDA, Wargame  │
│  └── 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)

Repository Structure

Following Protocol 543 standard repository scaffold:

Athena/
├── src/athena/          # Core runtime (Memory, Intelligence/GTO, Governance, Lifecycle, Tools)
├── tests/               # Comprehensive test suites (unit, integration, red-team)
├── scripts/             # Automation, synchronization, and verification harnesses
├── docs/                # Architecture, guides, API specs, and benchmarks
├── data/                # Active datasets and project assets (latest iteration only)
├── supabase/            # Database schemas, migrations, and vector functions
├── .agent/              # Agent workflows, skills, protocols, and configuration
├── .context/            # Persistent memory, case studies, canonical truths, and session logs
├── pyproject.toml       # Build configuration and dependency declarations
├── Makefile             # Standard task runner (test, lint, sync)
├── ARCHITECTURE.md      # Narrative system architecture and memory layout
├── CHANGELOG.md         # Release history and audit log
├── LICENSE              # MIT License
└── README.md            # Project front door

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`)
Adversarial Wargaming Engine	`intelligence/wargame.py` (`athena-wargame`)	Two-turn sequential Blue vs. Red game trees with intra-turn path-dependent trough ruin, Red best-response optimization, and tamper-evident run receipts (`.athena/wargame_runs.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 & wargaming — EEV, 1/3 Kelly, Ruin, MCDA, 2-turn game trees	✅ Shipped (`code-available`)	`gto_engine.py` & `wargame.py` emit 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, 428 active protocols, and 627 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

# Adjudicate a 2-turn adversarial wargame with path-dependent trough ruin screening
python -m athena.intelligence.wargame --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.

怎么上手

项目说明

核心能力

容易踩的坑

最近发版

⚖️ Decision Engine & Frame Ledger Control Plane

🏛️ Canonical Positioning & 4-Pillar Bionic Architecture

📊 Canonical System Metrics (CAPS.json Ground Truth)

🧠 Memory & Retrieval Substrate

🛡️ Governance & Security Hardening

Counterparty Reconnaissance & Due Diligence (Protocol 580)

Local Inference & Cache Benchmarking

Governance & Verification Gates

Adversarial Review & Deliverable Verification

Autonomous Runtime & Self-RSI Hardening

Core Engine & Architecture Modernization

Upstream Reconciliation & Layout Deduplication