# Koios

> *Named for the Titan of intellect and the celestial axis around which the heavens revolve.*

System prompts, shared tools, and graph schema for Robert Helewka's AI assistants.

## Architecture

Each assistant's runtime prompt is composed from these layers:

| Layer | Location | Audience | Purpose |
|-------|----------|----------|---------|
| **System Prompt** | `prompts/{team}/{name}.md` | LLM | Identity, communication style, boundaries, graph domain (~400-600 words) |
| **Tool Prompt Snippets** | `prompts/tools/{tool}.md` | LLM | Per-tool usage discipline (e.g., "always check the `success` boolean") — composed into the system prompt to teach the model what MCP tool descriptions don't convey |
| **Shared Context** | `docs/tools/neo4j/shared.md` | LLM | MCP server inventory, Agathos sandbox map, inter-agent messaging protocol, assistant directory |
| **Graph Context** | `docs/tools/neo4j/{team}.md` | LLM | Team-specific Neo4j principles, node ownership, patterns |

Human reference documentation lives in `docs/`:
- `docs/{team}/{name}.md` — character design per assistant
- `docs/{team}/team.md` — team overview, responsibility matrix, handoff patterns
- `docs/{team}/subagents.md` — catalog of team-scoped subagents and when to delegate to them
- `docs/tools/{tool}.md` — per-tool reference (what it is, what it's good for, known gotchas)
- `docs/tools/neo4j/` — full graph schema, breaking changes, utility patterns

Subagents are minimal-personality utility agents called as tools by leads — see `docs/engineering/subagents.md` for the established pattern.

## Assistants

The lists below reflect what's currently in `prompts/{team}/` — the source of truth. When assistants are added, replaced, or retired, update the directory and these tables together.

### Personal Team
| Assistant | Inspired By | Domain |
|-----------|------------|--------|
| **Shawn** | — | General assistant (calendar/contacts/email) |
| **Nate** | Nathan Drake | Travel & Adventure |
| **Hypatia** | Hypatia of Alexandria | Learning & Reading |
| **Marcus** | Marcus Aurelius | Fitness & Training |
| **Watson** | — | Relationship memory & emotional safety (replaces Seneca) |
| **Bourdain** | Anthony Bourdain | Food & Cooking |
| **David** | — | Arts & Culture (replaces Bowie) |
| **Cousteau** | Jacques Cousteau | Nature & Living Things |
| **Garth** | Garth Turner | Personal Finance |
| **Cristiano** | Cristiano Ronaldo | Football |

### Work Team
| Assistant | Inspired By | Domain |
|-----------|------------|--------|
| **Alan** | Alan Weiss | Strategy & Positioning |
| **Ann** | Ann Handley | Content & Visibility |
| **Jeffrey** | Jeffrey Gitomer | Proposals & Sales |
| **Jarvis** | J.A.R.V.I.S. | Daily Execution |
| **AWS SA** | — | Cloud architecture specialist (subagent) |

### Engineering Team
| Assistant | Inspired By | Domain |
|-----------|------------|--------|
| **Harper** | Seamus Harper | Build — ideation through deployment |
| **Scotty** | Montgomery Scott | Operate — production ops & provisioning |
| **CASE** | CASE (Interstellar) | Field — physical layer, LAN, hardware |

## Repository Structure

```
koios/
├── prompts/                          # Sent to LLM at runtime
│   ├── personal/                     #   Personal assistants (lead agents)
│   ├── work/                         #   Work assistants (lead agents)
│   │   └── subagents/                #     Team-scoped subagents (e.g. aws-sa)
│   ├── engineering/                  #   Engineering assistants (lead agents)
│   │   └── subagents/                #     Team-scoped subagents (research, tech_research)
│   └── tools/                        #   Per-tool prompt snippets
│       ├── kernos.md                 #     Shell/file-ops discipline
│       ├── argos.md                  #     Web search
│       ├── mnemosyne.md              #     Multimodal KB
│       ├── grafana.md                #     Metrics + logs
│       ├── gitea.md                  #     Self-hosted Git
│       ├── github.md                 #     GitHub.com via Copilot MCP
│       ├── context7.md               #     Library docs
│       ├── time.md                   #     Current date/time
│       ├── rommie.md                 #     Desktop automation
│       └── neo4j.md                  #     Graph usage discipline
├── docs/                             # Human reference + LLM context for graph/messaging
│   ├── personal/                     #   Character definitions & team overview
│   ├── work/                         #   Character definitions & team overview
│   ├── engineering/                  #   Character definitions, team overview, subagents catalog
│   └── tools/                        #   Per-tool human reference
│       ├── argos.md                  #     What each tool is, good/bad uses, gotchas
│       ├── kernos.md
│       ├── mnemosyne.md
│       ├── grafana.md
│       ├── gitea.md
│       ├── github.md
│       ├── context7.md
│       ├── time.md
│       ├── rommie.md
│       └── neo4j/                    #   Neo4j has extensive content; its own subdir
│           ├── unified-schema.md     #     Canonical graph schema
│           ├── shared.md             #     MCP registry, Agathos sandbox, messaging protocol, assistant directory (LLM-facing)
│           ├── engineering.md        #     Engineering team graph context (LLM-facing)
│           ├── personal.md           #     Personal team graph context (LLM-facing)
│           ├── work.md               #     Work team graph context (LLM-facing)
│           ├── utils.md              #     Helper patterns
│           └── breaking-changes.md
└── utils/                            # Scripts
    ├── neo4j-reset.py
    ├── neo4j-schema-init.py
    └── neo4j-validate.py
```

## Knowledge Graph

All assistants share a single Neo4j knowledge graph. Each assistant owns specific node types and can read broadly across the entire graph. The full schema is in `docs/tools/neo4j/unified-schema.md`.

Assistants communicate asynchronously via `Note` nodes with inbox/read tagging — see `docs/tools/neo4j/shared.md` for the messaging protocol.

## License

MIT