Repolode
Submit
winstonkoh87

winstonkoh87/Athena-Public

A local-first memory and decision layer for AI agents that stores context as Markdown and JSONL files you own, usable across several IDEs and LLMs.

View on GitHubWebsite
Stars
620
Forks
84
Open issues
0
Last commit
18 hours ago

What is it?

Athena keeps an AI assistant's memory, problem framing, and decision records on your own disk as plain Markdown and JSONL files, so the context survives when you switch models or editors. It is installed as a Python package and exposes its functions through two MCP servers, one for retrieval and governance and one for DuckDB-based analytical queries.

The project covers several areas: hybrid search that combines BM25 full-text and pgvector results with an ONNX cross-encoder reranker, a problem-framing ledger with hypothesis pre-registration and Brier calibration scoring, and a decision screen that computes expected economic value, one-third Kelly sizing, ruin probability, and Monte Carlo results with SHA-256 receipts. Hooks also block certain destructive shell commands and scan for secrets.

Athena works with Claude Code, Antigravity, Cursor, Gemini CLI, VS Code, Kilo Code, and Roo Code through per-IDE config files. The README includes a table separating features enforced in code from those that depend on prompting, and reports retrieval Hit@5 of 0.569 on its own gold set.

Key features

  • 01Stores memory and context as plain Markdown and JSONL files on local disk.
  • 02Hybrid retrieval combining BM25 full-text search, pgvector, and ONNX cross-encoder reranking.
  • 03Problem-framing ledger with falsifiable hypotheses and Brier calibration scoring.
  • 04Quantitative decision screening for EEV, one-third Kelly, ruin, MCDA, and Monte Carlo, with SHA-256 receipts.
  • 05MCP servers for memory retrieval and DuckDB querying of CSV, JSON, and Parquet files.
  • 06Hooks that block certain destructive commands and scan for secrets.

Use cases

  • Keeping an AI coding assistant's project context consistent when switching between Claude Code, Cursor, or Gemini CLI.
  • Recording and reviewing structured decisions with explicit assumptions and falsifiers.
  • Querying large CSV or Parquet datasets from an LLM agent without loading them into the context window.
  • Adding local governance hooks to AI agent sessions.

Quick start

  1. 1

    Clone the repository and enter it

    git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
  2. 2

    Create and activate a Python virtual environment

    python3 -m venv .venv && source .venv/bin/activate
  3. 3

    Install the lightweight package

    pip install -e ".[local]"
  4. 4

    Initialize Athena for your IDE and run the health check

    athena init --ide claude && athena doctor

Things to know

  • Evidence for long-term personalization comes from a single author's usage (N=1), not a multi-user study.
  • Some anti-sycophancy protections are agent-discretion only in IDEs without lifecycle hooks.
  • Retrieval quality is modest, with a strict Hit@5 of 0.569 on the author's gold set.
  • Full install needs optional cloud services such as Supabase for sync.

In collections

Long-term memory for AI agentsOpen-source AI agent frameworks & appsMCP serversPrivacy & local-first tools

Topics

#ai-agents#memory#local-first#rag#mcp#llm#knowledge-management#semantic-search#ai#ai-assistant

FAQ

What is Athena-Public?
A local-first memory and decision layer for AI agents that stores context as Markdown and JSONL files you own, usable across several IDEs and LLMs. Athena keeps an AI assistant's memory, problem framing, and decision records on your own disk as plain Markdown and JSONL files, so the context survives when you switch models or editors. It is installed as a Python package and exposes its functions through two MCP servers, one for retrieval and governance and one for DuckDB-based analytical queries.
Is Athena-Public free to use? What license does it have?
Athena-Public is open source under the MIT license. Check the license terms before using it in commercial products.
Is Athena-Public still maintained?
Actively maintained. The last commit to Athena-Public was on Nov 6, 2026.
What can I use Athena-Public for?
Keeping an AI coding assistant's project context consistent when switching between Claude Code, Cursor, or Gemini CLI. Recording and reviewing structured decisions with explicit assumptions and falsifiers. Querying large CSV or Parquet datasets from an LLM agent without loading them into the context window. Adding local governance hooks to AI agent sessions.
How do I install Athena-Public?
Clone the repository and enter it: git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public Create and activate a Python virtual environment: python3 -m venv .venv && source .venv/bin/activate Install the lightweight package: pip install -e ".[local]" Initialize Athena for your IDE and run the health check: athena init --ide claude && athena doctor
Where can I get Athena-Public?
The source code and installation instructions are on GitHub: https://github.com/winstonkoh87/Athena-Public

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects