Athena-Public: Your Local-First Agentic PKM for Smarter AI Decisions

Introduction

Athena-Public is a powerful local-first agentic Personal Knowledge Management (PKM) system designed to enhance your decision-making. It provides persistent memory, structured reasoning, and governed AI agents that operate across various Large Language Models (LLMs). The core philosophy behind Athena is "Own the state. Rent the intelligence," ensuring your data and context remain yours, regardless of the AI model you choose. Unlike typical assistants that aim to agree with you, Athena is built to remember you well enough to challenge your assumptions and offer truly personalized, critical insights.

This project addresses the common problem of platform memory being unreliable, opaque, and locked to a single provider. Athena moves the memory layer to your local machine, using plain Markdown files that you own, version-control, and can point at any LLM, from ChatGPT to Claude or Gemini. This approach ensures your accumulated knowledge compounds over time, providing a unique continuity advantage.

Installation

Getting started with Athena-Public is straightforward and works across macOS, Windows, and Linux.

Clone the repository:
```
git clone https://github.com/winstonkoh87/Athena-Public.git
cd Athena-Public
```
Clone this folder anywhere you keep projects. This directory will be your Athena workspace, housing your memory, protocols, and configuration.

Set up a virtual environment (recommended):

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows

This step prevents potential installation issues related to externally-managed-environment.

Install the SDK (optional, enables CLI commands):
```
# Lightweight install (~30 seconds, no ML dependencies)
pip install -e .

# Full install (~5–10 min, enables vector search and reranking)
pip install -e ".[full]"
```
Important: Do not pip install athena-cli, as it is a different, unrelated package. Always install from inside the cloned repository.
Open the folder in an AI-enabled IDE:

Open the Athena-Public/ directory as your workspace root in a compatible editor such as Zoo Code, Antigravity, Cursor, Claude Code, VS Code + Copilot, Kilo Code, or Gemini CLI. Crucially, Athena does NOT work through web interfaces like ChatGPT.com, Claude.ai, or Gemini web. You need an application that can read files directly from your disk.
Boot (in the AI chat panel, not the terminal):
```
/start
```
/start, /end, and /tutorial are AI chat commands, meant for the chat window where you interact with the AI agent.
First time? Take the guided tour:
```
/tutorial
```
This guided tour explains Athena, how it works, helps build your profile, and demonstrates its tools (approximately 20 minutes).
When you're done:
```
/end
```
No API keys or database setup are required. The folder itself is the product.

Examples

Athena excels at providing deeply personalized and context-aware guidance, moving beyond generic LLM responses.

Here's how Athena approaches various problem types:

Problem Type	What Athena Does	Example
Solvable	Solves it	"What's the Kelly fraction for this bet?" ? calculates, answers
Optimisable	Optimises within your chosen path	"I've decided to freelance, help me price it" ? constraint optimization
Unsolvable	Maps every option, prices every trade-off, hands the choice back to you	A closeted husband with children weighing whether to stay married or come out, Athena ensures full information.
Ruin-path	Vetoes before you walk off the cliff	"This bet risks everything" ? Law #1 override, regardless of your preference

Athena's capabilities extend to various real-world use cases:

Life Management: Manage health, career, relationships, finances, and client work in one unified system. Athena learns your patterns and can offer cross-domain advice, like prioritizing sleep debt over a client deadline.
Problem Solving: For complex personal challenges, Athena can conduct structured schema interviews, map internal protective parts (using IFS methodology), and connect patterns to your documented history, offering insights akin to a therapist.
Decision Making: When faced with significant choices, Athena cross-references your risk profile, financial runway, career history, and regret patterns from similar past decisions to provide highly specific recommendations that a generic LLM cannot.

Why Use Athena?

Athena offers a fundamental shift in how you interact with AI, prioritizing your ownership and personalized growth:

Your Memory, Your Machine: All your data resides on your local disk as plain Markdown files. You own them, can read and edit them, and even version-control them with Git. This eliminates vendor lock-in and ensures full transparency.
Switch Models Freely: Athena acts as a portable memory and governance layer. Whether you use Claude today, Gemini tomorrow, or GPT next week, your accumulated context remains consistent and accessible. The model is simply the "intelligence" you rent.
It Compounds: With each session, Athena extracts decisions, patterns, and learnings into your memory bank. Subsequent sessions load this accumulated intelligence, leading to increasingly sharper and more relevant outputs. The durable asset is your data, not the AI's code.
Meta-Game Reasoning: Generic LLMs optimize within the game you're playing. Athena, armed with your context, can question whether you should be playing that game at all, offering a higher level of strategic insight.
Governed Autonomy: Built with six constitutional laws and four capability levels, Athena provides bounded agency, ensuring that AI actions are aligned with your principles and prevent irreversible ruin.
Human Augmentation Thesis: Athena's core design principle is to augment human cognition, not replace it. It leverages your context not just to agree with you, but to reason differently and, crucially, to tell you when your own documented patterns suggest you might be wrong. This personalization makes disagreement credible and constructive.

Unlike cloud-based platform memories that are opaque and locked to a single provider, Athena gives you full control, inspectability, and portability of your personal AI context.