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★ — ci passing pypi v1.0.7 license MIT
Plate I · Bronze
P
Perseus with the
Head of Medusa
Benvenuto Cellini, 1545
Loggia dei Lanzi · Florence
Plate I
Perseus with the Head of Medusa
Cellini, 1545 · Bronze · Loggia dei Lanzi
Read on
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
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.

Source 01
# .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 render 02
$ 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 → Assistant 03
# 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
Click to close

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
writes 000/150
elapsed 0.00s
status RACING
agent write
collisions 0

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.