Athena-Public: a local-first memory and reasoning layer you point at any LLM

The problem Athena-Public picks: memory that belongs to the provider

The README states the problem in plain terms. You spend months tuning a model to understand you, a model update resets the personality, custom instructions stop working, and switching to another provider means starting from zero. Platform memory is described as unreliable, opaque, and locked to one provider. You cannot inspect it and you cannot take it with you.

Athena's answer is to move the memory layer onto your machine as plain Markdown files that you own, version-control, and point at any model. The README's framing is that the model is "just whoever's on shift" while the memory stays. That is a real architectural position, not a slogan: the durable asset is the session data, and the README says so explicitly, noting that anyone can fork Athena but nobody can fork your sessions.

The intended user is someone who already runs multiple assistants and treats context as an asset. It is not aimed at a first-time chatbot user. The repository's own classifier says Development Status 4 - Beta, which is worth reading literally.

How the memory, boot tiers and governance layer fit together

The repository layout shows the shape of the system. There is a src/ tree, a .framework/ directory, a .context/ directory, and a top-level athena.yaml. Protocols live under examples/protocols/, including a decision category with numbered entries such as Protocol 330 on economic expected value. Agents, skills, hooks and workflows each have their own example directories.

Context is loaded in tiers rather than all at once. The README describes a 2K to 20K token boot that scales to the task: lightweight chat at roughly 2K tokens, /start at roughly 10K, and /ultrastart at roughly 20K. The claim attached to that is that 80 to 98 percent of the context window stays free even after 10,000 sessions. That is a design goal about how much of your window the framework consumes, and it is the kind of number you should measure against your own sessions rather than take on faith.

Governance is the other half. The README refers to 6 constitutional laws and 4 capability levels under the heading Governed Autonomy, and cites Law #1, the Committee of Seats, as the standing that lets the system refuse a premise. A worked example is given for a betting question: where a generic model answers that the math favours doubling, Athena is described as answering that the math is correct but the user's utility function makes the bet negative expected value, and refusing. Whether that refusal behaviour is useful or irritating depends entirely on how well your context is curated.

The dependency list in pyproject.toml tells you what the engine actually needs: google-genai for embeddings, supabase for storage, anthropic and the wider model tooling, flashrank and onnxruntime for reranking, diskcache for local caching, fastmcp for tool exposure, and pydantic for schema validation.

Installing athena-agent and running a first session

The package is published as athena-agent and requires Python 3.10 or newer. The console entry point is athena, which maps to athena.__main__:main. Install it from the project directory:

pip install -e .

Before the first run, copy the environment template. The .env.example lists exactly three groups of values: a Supabase URL, a Supabase service role key, and a Google API key used for embeddings.

cp .env.example .env

Fill in the placeholders. The template shows the expected shape, including the NEXT_PUBLIC_SUPABASE_URL and SUPABASE_URL pair pointing at the same project host.

NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here
GOOGLE_API_KEY=your_google_api_key_here

With those set, the README's boot commands are the first real use. A plain chat session boots the light tier; /start loads a fuller context; /ultrastart loads the heaviest. The README also points at an /end loop for closing a session, and states plainly that compounding needs curation and that unpruned memory decays like any archive. Treat /end as part of the workflow, not an optional extra. If you want to try the environment without a local setup, the README offers an Open in Codespaces badge.

Where Athena-Public is the wrong tool

The install is not self-contained. Embeddings come from Google's API and storage comes from Supabase, so the local-first claim applies to your files and your reasoning state, not to every network call in the pipeline. The .env.example makes that concrete: without a Google API key and a Supabase project, the vector path in src/athena/memory/vectors.py has nothing to talk to. If your constraint is that no data may leave the machine, this is the first thing to check rather than assume.

The second limitation is curation debt. The README is unusually direct about it: compounding needs curation, keep the /end loop running, and unpruned memory decays like any archive. A memory system that accumulates without pruning gets slower to boot and noisier to retrieve from. That is a maintenance commitment, not a one-time setup cost.

The third is that the project is classified as Beta. Version numbering is at v9.9.9, and the release notes show frequent thematic sweeps such as the Guard-Integrity Sweep and Meta-Awareness Gate v3. Frequent reorganisation of the reasoning layer is a signal that interfaces may move. If you need a frozen API surface for a production pipeline, this is not the right layer to build on yet.

Athena-Public versus a plain RAG stack over your notes

The obvious alternative is assembling your own retrieval pipeline: chunk your notes, embed them, store the vectors, retrieve the top matches, and paste them into the prompt. That gets you search over your own documents and nothing else. The difference in approach is what happens around the retrieval. Athena ships numbered decision protocols, named constitutional laws, capability levels, and boot tiers that decide how much context enters the window before you ask anything. A hand-rolled RAG stack has no opinion about whether the question you asked is the right one, and no mechanism for refusing a premise.

The trade is control for structure. A custom pipeline lets you choose the embedding model, the chunking strategy, the reranker and the store, and you can swap any of them without touching a framework. Athena has already made those choices: google-genai for embeddings, flashrank and onnxruntime for reranking, Supabase for storage, diskcache for local caching. You inherit a coherent system and you inherit its opinions. If your retrieval needs are unusual, or you want to evaluate three embedding models this week, the framework will be in your way. If your problem is that you keep re-explaining yourself to a new model every few months, the framework is the point.

Maintenance cost, licence and what to watch between releases

The last push to the repository was on 2026-09-10, and the most recent release listed is v9.9.9 from 2026-08-27, titled Feature Port and Synchronized Digital Portfolio Refresh. Before that, v9.9.8 in July 2026 was the Effective Command and the Guard-Integrity Sweep, and v9.9.7 in July 2026 was Meta-Awareness Gate v3. The cadence is steady and the changes are substantive rather than cosmetic, which cuts both ways: you get active development, and you should expect to re-read the changelog before upgrading.

Licensing is MIT, stated in both the LICENSE file and the pyproject.toml license field. That is permissive and places few obligations on how you redistribute or modify the code. It says nothing about the data you put in, and it does not change the terms of the Google or Supabase services the pipeline calls. Those are separate agreements you accept when you create the API key and the project.

The upgrade cost that matters most is not the Python package, it is your memory directory. Because your sessions are plain Markdown, a framework change can alter how they are parsed or retrieved without touching the files themselves. Version-control the memory directory alongside the code, and read the release notes for the boot and protocol layers before you pull a new tag.

Editorial conclusion

Adopt Athena if you already switch between models and want your accumulated context to survive the switch, and if you are willing to run a Supabase project and a Google API key to get embeddings. Skip it if you want a zero-configuration chat client, or if you cannot commit to the /end curation loop, since unpruned memory is described as decaying like any archive. Before installing, verify three things: that Python 3.10 or newer is available, that you can create a Supabase project for the URL and service role key, and that you have a Google AI key for embeddings, because the .env.example lists all three as required.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. winstonkoh87/Athena-Public on GitHub