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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/winstonkoh87-athena-public
Generated for open source discovery and AI-assisted research.

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. This unique approach allows you to own your data and context, while renting the intelligence from any LLM.

GitHub: https://github.com/winstonkoh87/Athena-Public
OSRepos URL: https://osrepos.com/repo/winstonkoh87-athena-public

## Summary

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. This unique approach allows you to own your data and context, while renting the intelligence from any LLM.

## Topics

- AI Agents
- Local-First
- PKM
- Knowledge Management
- LLM
- Python
- Decision Support
- Open Source

## Repository Information

Last analyzed by OSRepos: Tue Aug 25 2026 09:38:11 GMT+0100 (Western European Summer Time)
Detail views: 3
GitHub clicks: 1

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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.

1.  **Clone the repository:**
    bash
    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.

2.  **Set up a virtual environment (recommended):**
    bash
    # 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`.

3.  **Install the SDK (optional, enables CLI commands):**
    bash
    # 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.

4.  **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](https://github.com/Zoo-Code-Org/Zoo-Code){target="_blank"}, [Antigravity](https://antigravity.google/){target="_blank"}, [Cursor](https://cursor.com){target="_blank"}, [Claude Code](https://docs.anthropic.com/en/docs/claude-code){target="_blank"}, [VS Code + Copilot](https://code.visualstudio.com/){target="_blank"}, [Kilo Code](https://kilocode.ai/){target="_blank"}, or [Gemini CLI](https://github.com/google-gemini/gemini-cli){target="_blank"}.
    **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.

5.  **Boot (in the AI chat panel, not the terminal):**
    In your IDE's AI chat panel (e.g., Cmd+L in Cursor), type:
    
    /start
    
    `/start`, `/end`, and `/tutorial` are AI chat commands, meant for the chat window where you interact with the AI agent.

6.  **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).

7.  **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.

## Links

*   **GitHub Repository:** [winstonkoh87/Athena-Public](https://github.com/winstonkoh87/Athena-Public){target="_blank"}
*   **Getting Started Documentation:** [docs/GETTING_STARTED.md](https://github.com/winstonkoh87/Athena-Public/blob/main/docs/GETTING_STARTED.md){target="_blank"}
*   **License:** [MIT License](https://github.com/winstonkoh87/Athena-Public/blob/main/LICENSE){target="_blank"}
*   **Author's Website:** [Winston Koh](https://winstonkoh87.com){target="_blank"}