# Perseus — Fact Sheet

**Last updated:** 2026-05-25

## Project

| Field | Value |
|---|---|
| Name | Perseus |
| Tagline | Live context engine for AI assistants |
| License | MIT |
| Language | Python 3.10+ |
| Dependencies | `pyyaml` (only) |
| First public release | 2025 |
| Current version | 1.0.3 |
| Tests | 596 passing, 1 skipped |
| Repo | https://github.com/tcconnally/perseus |
| Site | https://perseus.observer |
| PyPI | https://pypi.org/project/perseus-ctx/ |
| MCP Registry | listed (search "perseus" at registry.modelcontextprotocol.io) |
| Anthropic Skills marketplace | PR open: https://github.com/anthropics/skills/pull/1193 |

## Compatible assistants

Claude Code, Cursor, GitHub Copilot, OpenAI Codex CLI, Google Gemini CLI, Atlassian Rovo Dev, Hermes Agent (by Nous Research), and any agent that reads a markdown file at session start.

## What Perseus does

Resolves directives (`@query`, `@services`, `@waypoint`, `@agora`, etc.) inside a source markdown file and writes plain markdown into whichever context file an AI assistant reads at session start. Replaces stale hand-edited `CLAUDE.md` / `.cursorrules` files with freshly-true documents.

## Architectural position

Compile-before-context, as opposed to the runtime tool-call pattern (MCP, function calling). For static environment state (services, ports, recent commits, prior session state) the pre-processor approach is structurally faster and cheaper.

## Headline benchmarks

- **450× cold→warm gap:** 50,000 directives in 1.36s warm with `@cache` (612.6s cold). Local-disk JSON cache, SHA-256 keyed, one file per directive. Warm time stays flat regardless of scale.
- **301× faster than equivalent LLM tool calls:** 500-developer simulation, 5-day workweek, 16,250 context renders in 961s wall clock. Equivalent runtime tool calls: ~83 hours. Estimated token savings on Claude Opus: ~$295K/year.
- **1,000,000 directives in 22 seconds:** 22 μs per directive. 31 MB output file, 3M output lines, zero crashes. Ceiling is file I/O.
- **120-agent swarm, 0 collisions:** 30 developers × 4 agents each, 150 concurrent checkpoint writes in 9.7s on local NVMe. Uses atomic `O_CREAT | O_EXCL` locking.

## Components

| Component | Purpose | Greek/myth name |
|---|---|---|
| Renderer | Resolves `@directive` blocks before context | (core) |
| Checkpoints | Crash-recovery session snapshots | Waypoints |
| Tool oracle | Ranks approaches given task + live env | Pythia |
| Async agent coordination | Task queue + `@agora` directive | Agora |
| Context maintenance heuristics | Daily-driver health checks | Daedalus |
| Narrative project memory | Distills checkpoints into per-workspace narrative | Mnēmē |
| Cross-workspace memory aggregation | Federated narrative manifest | Federation |
| Plugin system | User-defined directives without source patching | Hephaestus |

## Founder

**Thomas Connally** (GitHub: [@tcconnally](https://github.com/tcconnally))

- Based in Austin, Texas
- Built Perseus solo over six months
- Runs a small homelab Majordomo agent project where Perseus was incubated
- Background: 20+ years in software, systems, and security engineering. Former ISSM/ISSO. Currently Support Account Manager at Atlassian.

## Distinctive design choices

- **Single-file build artifact** (`perseus.py`, ~12,750 lines) generated by `scripts/build.py` from a modular `src/perseus/` tree. The single file is the install target; the modular tree is canonical.
- **Zero dependencies beyond `pyyaml`.** No `requests`, no `click`, no `rich`. argparse + stdlib only.
- **Plugin discovery without source patching.** Drop a Python file into `~/.perseus/plugins/` and your custom directive is registered at render time.
- **Assistant-agnostic by design.** Same `.perseus/context.md` source compiles to `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.hermes.md`, or `copilot-instructions.md` via `perseus render --format <target>`.
- **Filesystem-locked checkpoints, no server.** Multi-agent coordination uses `O_CREAT | O_EXCL` atomic create on local disk. NFS < v4 and SMB caveats documented.

## Hardening / edge cases tested

- Symlink escapes (direct, relative, chained, to `/etc`) — blocked by trust gate
- Circular `@include` dependencies — detected up to `max_include_depth` (default 5)
- Context overflow — `@read` / `@include` truncate at configurable size caps
- Integrity drift — optional mtime check warns if files change mid-resolution
- Plugin sandboxing — `executes_shell=True` directives gated behind `allow_query_shell`
- Race conditions in checkpoint locks — atomic on local POSIX filesystems
- Network filesystem caveats (NFS < v4, SMB, cloud mounts) — explicitly documented

## What Perseus is NOT

- Not a runtime MCP server (though it has an MCP server façade for compatibility)
- Not an agent framework like CrewAI or AutoGen (it's the layer underneath)
- Not a hosted SaaS (single-file install, runs locally)
- Not snapshot-isolated (the live filesystem can change between directive resolutions unless `integrity_check` is enabled)
