Live Context Engine for Professional Developers v1.0.7 · MIT

One command. Zero orientation.
Your assistant opens knowing exactly what’s running.

A live context engine for AI coding assistants. Perseus resolves your environment before the context window opens — directives like @query "git log -5" are rendered to facts at build time, so the assistant reads a document that was already true. Works with any tool that reads a file.

Works with any assistant that reads a file — Claude Code, Cursor, Codex, Rovo Dev, Hermes, or your own. No plugin. No SDK. Drop a rendered markdown file where your assistant already looks.

pip install perseus-ctx && perseus quickstart

That's the whole install. Perseus auto-detects your project language, scaffolds context-appropriate memory queries, and renders live state — one command, zero orientation.

github★ — cipassing pypiv1.0.7 licenseMIT

Plate I

Perseus with the Head of Medusa

Cellini, 1545 · Bronze · Loggia dei Lanzi

I — The Mirror

Don’t meet the Gorgon’s gaze. Reflect it.

Without Stale facts. Wasted turns.

The assistant guesses.

# session opens, CLAUDE.md last edited 11 days ago
you   deploy the api service to staging.
ai   running `make deploy-staging`...
ai   Makefile target removed in #482. Let me check
         the current scripts.
ai   Which branch are you on? Is the helm chart
         still at v0.3? What’s the staging cluster name?
# 4 orientation turns. 11k tokens. 0 progress.

Sessions start cold. Tooling drifts. Docs lie politely. Every conversation pays an orientation tax before the real work begins — and the assistant is staring straight at the Gorgon.

With Resolved at render time.

The assistant already knows.

# CLAUDE.md rendered 38s ago by `perseus render`
you   deploy the api service to staging.
ai   You’re on feat/billing-v2, helm chart
         v0.4.1, staging = eu-west-2/stg-a.
ai   Running `./scripts/deploy.sh staging api`.
ai   ✓ Image pushed. ✓ Helm upgrade applied.
# 1 turn. The branch, chart version, cluster: all true.

Perseus renders directives to live facts before the assistant reads the file. No guessing, no probing, no trusting yesterday’s notes. The mirror, polished.

Watch it happen — cold-start eliminated

Perseus demo: without Perseus (cold start, 36 discovery calls) vs with Perseus (install, render, 0 discovery calls, warm cache 0.28s)

Overhead

~1,600tokens

One-time context injection at session start. 5 directives pre-resolve everything the LLM would otherwise discover through tool calls.

Breakeven

~5turns

The upfront investment pays for itself by turn 5. Every turn after that is net positive — the LLM never wastes a turn on orientation.

Deep work

+7,500tokens

In a 30-turn session, Perseus saves over 7,500 tokens by eliminating discovery tool calls. The longer the session, the bigger the win.

II — The Render

A document that was already true.

Source01

# .perseus/context.md ## Project This is @query "jq -r .name package.json". ## Current state Branch: @query "git branch --show-current" @cache ttl=300 @query "git log --oneline -5" ## Dependencies @read pyproject.toml

Directives. Authored once.

Perseus render02

$ perseus render \ .perseus/context.md \ --output CLAUDE.md resolve query → 3 directives (1 cached) resolve read → 1 directive ✓ 4 directives in 31ms ✓ wrote CLAUDE.md (3.2 KB)

Parallel. Cached. Idempotent.

Output → Assistant03

# CLAUDE.md ## Project This is perseus-ctx. ## Current state Branch: feat/billing-v2 a3f1b9c fix: drift on tag walk 8c2e4d7 feat: add @file lines= d019f80 bench: 1M directive run …

Plain markdown. No directives left.

The principle The assistant never sees a directive. It sees a document that was already true.

III — The Triad

Three tools. One mirror.

The Renderer

The polished shield.

Resolves @query, @read, @waypoint, @services and friends before the assistant sees them. The output is plain markdown. No directives left for the model to chase. --tier 1|2|3 for progressive context disclosure.

perseus render .perseus/context.md

Session Waypoints

Pick up where the thread snapped.

Write a checkpoint at any natural pause; perseus recover finds the right one for your workspace; perseus diff shows what changed between two pauses. Continuity, without re-orientation.

perseus checkpoint --task ... --next ...

Pythia · Tool Oracle

Ranked paths, with a reason.

Given a task and the current environment, Pythia surfaces the highest-utility skill or tool and tells you why. No extra model required. The loop closes inside the same context window.

perseus suggest "deploy the staging container"

IV — The Blueprint

How the pieces fit together.

Click to expand

One file · one render · every assistant reads the same live truth

V — Persistent Memory

Mimir: one vault, every device.

Single file

One mimir.db — SQLite with FTS5. Drop it on Syncthing, Dropbox, or a NAS. Every Hermes instance on every machine reads from the same vault.

Sub-millisecond recall

BM25 over FTS5 with porter stemming. 0.09ms cold, 0.12ms warm query P50 at 75 records — flat across scale. No embedding model, no API calls, no cloud.

Multi-device sync

MCP-native. Run mimir as a sidecar, point all your agents at it. Same memories, same projects, same context — regardless of which machine you're on.

Install and run

curl -sSL https://raw.githubusercontent.com/tcconnally/mimir/main/scripts/bootstrap.sh | bash

# Start the MCP server
mimir --db ~/.mimir/data/mimir.db

# In your Perseus config:
# memory:
#   mimir_command: mimir
#   mimir_db: ~/.mimir/data/mimir.db

Perseus renders the context. Mimir remembers it.

Explore Mimir Server → Mimir on GitHub ↗

VI — The Receipts

Numbers from the bench, not the pitch deck.

Concurrent writers

120agents

30 developers × 4 agents each. 150 concurrent checkpoint writes in 9.7s on local NVMe with atomic O_CREAT | O_EXCL locking. Writes hit the task board (tasks/*.md) with zero failures, zero collisions — protocol tested across edge cases: crash recovery, stale claims, TTL expiry.

0 failures 0 collisions 9.7s wall edge cases

Perseus v1.0.7 — Performance Benchmarks: 450× speedup, 1,190× cache, 301× vs LLM, 94% compression, 0 failures, 1,032 tests

450× cold→warm · 1,190× cache punch · 301× vs LLM · 94% token compression · 0 failures at 150 concurrent · 1,032 tests all green · full benchmark suite ↗

Hardened

Symlink escapes blocked — direct, relative, chained, to /etc.

Workspace Boundaries

NVMe local lock is atomic. NFS v4+ for cross-machine; SMB requires careful config.

Overflow Guard

Context overflow protection on @read and @include.

Drift Detect

Optional integrity_check warns when a file changes mid-render.

14/14 + 10/10 Gates

Swarm chaos at 10/50/100 agents, cache thrash T1–T5, adversarial C1–C5. Plus: 10/10 hard gates in the Extreme Enterprise Benchmark at 250 concurrent agents.

0 Collisions @ 100 Agents

Zero hash collisions. Zero determinism violations. Adversarial-neighbor slowdown: 1.06×.

Semantic Equiv 1.0

Gemini 2.5 Flash judge, 20 A/B pairs. Perseus changes what the assistant knows. Not what it says.

Audit & Redaction

Every directive resolution is logged. Secrets auto-redacted with two-layer gating. Full audit trail, opt-out supported.

Deep-Dive v1.0.7

Architectural hardening pass: O(n²)→O(n) macro expansion, character parser→compiled regex, shell=True→explicit /bin/sh -c, webhook retry classification. Pythia log pruning prevents unbounded growth.

VIII — The Compatible

Resolves to a file. Yours, already.

CLAUDE.md

Claude Code

.cursorrules

Cursor

AGENTS.md

Codex · Rovo Dev

.hermes.md

Hermes

CONTEXT.md

Your own

Perseus outputs plain markdown. Point the output at whatever file your assistant opens at session start — no plugin, no SDK, no migration. The next session opens warm.

VII — The Arsenal

Every directive, every verb, every adapter.

Core Directives The Language

Render-time macros resolved to static facts before the context window opens.

@query Shell execution. Captures command stdout, cached via @cache ttl=N. For git branch, clusters, and versions.

@read File inclusion. Inlines file ranges securely with token-overflow guard rails.

@services Service checking. Discovers container health, endpoints, or exit checks in parallel.

@waypoint Session state. Inserts what you're working on and next actions. Swap contexts in one turn.

@memory Project memory. Distills checkpoint narrative journals. Federates across folders.

@agora Task board. Auto-renders `tasks/*.md` markdown files as a unified live task matrix.

CLI Verbs The Interface

The standalone binary commands you and your cron watchdogs run.

perseus quickstart Scaffolds, detects your assistant target, and renders warm context in 30 seconds.

perseus render Resolves all directives in parallel. --tier 1|2|3 filters prompt injection size.

perseus checkpoint Saves waypoints at pausing points. recover and diff restore and compare states.

perseus doctor System diagnostic. Verifies configuration paths, credentials, and render dependencies.

perseus suggest Tool recommend. Triggers Pythia Oracle to output high-utility skills and rationale.

perseus mcp serve Launches the standard stdio or SSE Model Context Protocol server exposing all tools.

Adapters The Integrations

Bridge triggers that automate context rendering in your native tools.

VS Code / Cursor Extension Auto-renders context files on save, displays status, and adds live directive hover-previews.

Claude Code Hook Triggers automatic rendering on terminal launch. Claude opens with 0-turn orientation.

GitHub Action Push & cron schedule action that commits rendered files back, briefing teammates for free.

MCP Server Sidecar Registers Perseus on the official MCP Registry, giving agents direct tool call capabilities.

30 CLI verbs · 25 directives · 24 MCP tools — see the full catalog on GitHub ↗

IX — The Start

Thirty seconds from cold to warm.

One command. Or hand the guide to your AI.

perseus quickstart detects your assistant, scaffolds a workspace, and renders live context in a single command. Or give your AI our LLM-tuned setup guide and say “set up Perseus for me.” Your assistant opens its next session already briefed.

01 $ pip install perseus-ctx

or ~ uv tool install perseus-ctx

02 $ perseus quickstart

or ~ perseus init --profile hermes /workspace/myproject

03 $ perseus doctor

⌘

LLM-Tuned Guides — Perseus ships with documentation written for AI assistants to read and execute. Drop SETUP-GUIDE.md or SKILL.md into any AI coding assistant and say “set up Perseus for this workspace.” Config, auto-refresh, permissions, MCP wiring, troubleshooting — the guide covers it all. Your AI reads it, then types the commands. You watch.

After setup → perseus doctor verifies everything is wired correctly.

One command. Zero orientation. Your assistant opens knowing exactly what’s running.