r/koios
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
db59266527bcb49c744cad301c59b58d96ab8d0b
koios/README.md
Robert Helewka db59266527 feat(personal): Sophia replaces Bourdain and Cousteau 
Adds Sophia Petrillo (The Golden Girls) to the personal team and retires
Bourdain and Cousteau — a 2:1 merge, net -1 agent (10 -> 9 personal,
18 -> 17 total).

Why: the personal team casts fictional characters. Bourdain and Cousteau
are real people, one with significant baggage and one who died by suicide,
and neither had a dedicated MCP server or capability. Sophia is fictional,
plausibly owns both domains (an Italian grandmother knows food; tending
plants and the tank is housekeeping), and is the first personal agent to
actuate the house via the new Hecate MCP server.

Graph: Sophia inherits all 11 node types unchanged (Recipe, Restaurant,
Ingredient, Meal, Technique + Species, Plant, Tank, Garden, Ecosystem,
Observation). Uniqueness constraints are keyed on node label, not agent,
so there is no schema or data migration. Historical Note tags
(from:bourdain, to:cousteau) are deliberately left intact as an accurate
record. Schema bumped to 2.5.0.

Also:
- New docs/tools/hecate.md + prompts/tools/hecate.md, documenting the
  physical-actuation discipline (never guess a room or device slug) and
  stating plainly what Hecate cannot do yet: no sensor readings (Demeter
  is REST-only), no weather, and set_timer is routine-bound with no
  cancel — the conversational timer is coming to Daedalus.
- Shawn gains Periplus in the docs. The server was already wired in
  iolaus but never described in any prompt, so the model was handed a
  tool it was never told about — including the never-estimate-coordinates
  rule.
- Corrected stale counts (15/16/18 assistants -> 17) and the stale
  "Bowie's Domain" schema heading missed when David replaced Bowie.
- Removed utils/neo4j-schema-init.py.bak, a pre-Watson artifact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-26 19:24:16 -04:00

122 lines
6.7 KiB
Markdown
Raw Blame History

# 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) |
| **Sophia** | Sophia Petrillo | Home, Food & Living Things (replaces Bourdain and Cousteau) |
| **David** | — | Arts & Culture (replaces Bowie) |
| **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 |
| **Quentin** | Q (007 Quartermaster) | Solution architecture & demos |
Work subagents (called as tools, not lead agents): **AWS SA** (cloud architecture, Quentin's exclusive subagent) and **tech_research** (technical investigation). See [docs/work/subagents.md](docs/work/subagents.md).
### 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 (aws-sa, research, tech_research)
│ ├── 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
│ ├── hecate.md # Home 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
│ ├── hecate.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
Reference in New Issue View Git Blame Copy Permalink