Local-first memory, decision engine, and governance harness for AI agents — portable across IDEs. Own the state. Rent the intelligence.

Athena – 便携式、自托管的 AI 代理记忆

它是什么 – Athena 是一个基于 Python 的 SDK，能让您将 LLM 代理的“记忆”以普通 Markdown 文件的形式保存在自己的磁盘上。其理念是相同的上下文可以伴随您跨不同的 IDE 集成聊天助手（Claude Code、Antigravity、Cursor、Gemini CLI、VS Code 等）以及任何底层模型。Athena 提供一个小型命令行界面（athena init、/start、/end、/ultrastart 等），可挂接到这些 IDE 的聊天面板，记录会话，之后通过混合关键词加向量的 RAG 管道检索相关事实。

为何重要

便携性 – 没有厂商锁定的记忆。您的知识以纯文本、可 git 跟踪的 Markdown 形式存在，因此您可以从 Claude 切换到 Gemini（或任何未来的模型）而不会丢失上下文。
本地优先 – “轻量”安装没有云依赖；一切都在您的机器上运行。可选的“完整”安装增加了 Supabase 支持的 pgvector 存储，用于云同步和重新排序。
安全挂钩 – Athena 注入代码强制的护栏（破坏检查、机密扫描、接地），在破坏性命令到达模型之前阻止它们。
成本意识 – 不同的使用模式（lightweight、standard、deep）让您控制每个会话加载/保存的令牌数量，使 API 成本可预测。

核心组件

组件	角色
IDE 挂钩	最小化、代码强制的集成，从支持的 IDE 聊天界面捕捉 `/start` … `/end` 命令。
Athena SDK	处理会话生命周期、写入 Markdown 日志、执行混合检索管道（关键词搜索 + 可选向量嵌入 + 交叉编码器重新排序）。
磁盘存储	纯 Markdown 文件，以 git 进行版本控制。可选的 Supabase pgvector 存储，用于云同步和更快的向量搜索。

架构以三层流程可视化：IDE → Athena SDK → 磁盘（或 Supabase）。

快速开始

# 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

之后，在 IDE 的 AI 聊天面板中输入 /start，照常工作，并以 /end 结束。会话会自动保存为 Markdown。

安全性与可靠性

护栏 – 内置的“破坏检查”阻止 16 个已知破坏性命令中的 14 个；其余两个记录在 docs/TECH_DEBT.md 中。
机密扫描 – CI 在每次提交时运行 Gitleaks；README 报告在 1,248 次提交中零泄漏。
基准测试 – 仓库附带脚本用于测量：
- KV 缓存预热加速（对于 2K 令牌启动与 32K 启动相比，约快 35-50 倍）。
- 检索质量（Hit@5 = 0.569，MRR@5 = 0.472）在严格评估器上。
测试 – 644 个单元和集成测试全部通过（pytest）。使用 ruff 进行 linting 显示没有问题。

谁应该使用它？

开发人员 依赖 AI 辅助编码并希望他们的个人上下文能在模型或供应商变更后存活。
团队已经对文档进行版本控制，并希望为他们的 LLM 助手提供可重现、可审计的记忆层。
注重隐私的用户 偏好本地存储而非专有云记忆。

限制

“复合个性化”的说法是基于单一作者的 1,900+ 个会话；尚无正式的多用户研究。
反谄媚机制目前仅为 Claude Code 实现。
完整的云同步和向量重新排序需要 Supabase 账户和额外配置。

在哪里了解更多

文档 – docs/GETTING_STARTED.md、docs/ARCHITECTURE.md、docs/CLI.md。
安全 – SAFETY.md 解释限制和负责任使用。
基准测试 – docs/BENCHMARKS.md 详细说明了检索和 KV 缓存测量。
贡献 – 如果您想添加 IDE 支持或改进检索管道，请遵循 CONTRIBUTING.md 中的指南。

TL;DR

Athena 是一个真实的开源工具，将 LLM 代理记忆从不透明的平台服务转移到用户拥有的 Markdown 文件，具有 IDE 挂钩、混合 RAG 检索和安全护栏。它可以在本地开箱即用，并可通过 Supabase 扩展到云同步。