{"id":51181497,"url":"https://github.com/perseus-computing-llc/perseus","last_synced_at":"2026-06-27T07:03:19.701Z","repository":{"id":358667084,"uuid":"1242409019","full_name":"Perseus-Computing-LLC/perseus","owner":"Perseus-Computing-LLC","description":"Live context engine for AI assistants — resolve-before-context, session waypoints, and tool-selection intelligence for Hermes Agent","archived":false,"fork":false,"pushed_at":"2026-06-24T18:17:18.000Z","size":15863,"stargazers_count":20,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-24T18:22:36.145Z","etag":null,"topics":["ai-agents","claude-code","cli","context-engine","hermes","local-first","mcp","open-source","perseus","python","workspace-context"],"latest_commit_sha":null,"homepage":"http://perseus.observer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Perseus-Computing-LLC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["tcconnally"],"opencollective":"perseus"}},"created_at":"2026-05-18T11:59:16.000Z","updated_at":"2026-06-24T18:06:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Perseus-Computing-LLC/perseus","commit_stats":null,"previous_names":["tcconnally/perseus","perseus-computing-llc/perseus"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Perseus-Computing-LLC/perseus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Perseus-Computing-LLC","download_url":"https://codeload.github.com/Perseus-Computing-LLC/perseus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34844350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","cli","context-engine","hermes","local-first","mcp","open-source","perseus","python","workspace-context"],"created_at":"2026-06-27T07:03:15.861Z","updated_at":"2026-06-27T07:03:19.691Z","avatar_url":"https://github.com/Perseus-Computing-LLC.png","language":"Python","funding_links":["https://github.com/sponsors/tcconnally","perseus"],"categories":[],"sub_categories":[],"readme":"# Perseus™ 🪞 — One command. Zero orientation.\n\n[![smithery badge](https://smithery.ai/badge/Perseus-Computing-LLC/perseus)](https://smithery.ai/servers/Perseus-Computing-LLC/perseus)\n**`pip install perseus-ctx \u0026\u0026 cd your-project \u0026\u0026 perseus quickstart`**\n\n![Perseus demo — before/after cold-start](demo.gif)\n\n[![CI](https://github.com/Perseus-Computing-LLC/perseus/actions/workflows/test.yml/badge.svg)](https://github.com/Perseus-Computing-LLC/perseus/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/perseus-ctx)](https://pypi.org/project/perseus-ctx/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Status: Patent Pending](https://img.shields.io/badge/status-patent_pending-blue)](./docs/ip/README.md)\n[**perseus.observer →**](https://perseus.observer)\n\n\u003c!-- mcp-name: io.github.tcconnally/perseus --\u003e\n\n---\n\n## 🛡️ Product Family\n\nPerseus is the live context engine. Seven specialized products extend it:\n\n| Product | Description | Page |\n|---|---|---|\n| **Mimir** | 40 MCP tools — persistent memory with FTS5, entities, layers, confidence decay | [/mimir/](https://perseus.observer/mimir/) |\n| **MCTS** | 120 security analyzers for MCP servers — tool poisoning, prompt injection, credential leaks | [/mcts/](https://perseus.observer/mcts/) |\n| **PR Pilot** | 5-agent autonomous PR review pipeline — graduated autonomy L1→L3 | [/pr-pilot/](https://perseus.observer/pr-pilot/) |\n| **Blast Radius** | GitLab-native dependency impact analysis — 1 mention, instant risk report | [/blast-radius/](https://perseus.observer/blast-radius/) |\n| **Rapid Agent** | Dual-backend memory agent (Elastic ↔ Engram-rs) — Google Cloud Hackathon | [/rapid-agent/](https://perseus.observer/rapid-agent/) |\n| **Qwen Memory** | Agent that gets smarter every session — Qwen Cloud Hackathon | [/qwen-memory/](https://perseus.observer/qwen-memory/) |\n| **CrewAI Memory** | Persistent cross-session memory backend for CrewAI (54K stars) — community PR #6208 | [/crewai/](https://perseus.observer/crewai/) |\n\n---\n\n### Mimir — Persistent Memory (MCP)\n\n[Mimir](https://github.com/Perseus-Computing-LLC/mimir) is the persistent memory backend for Perseus — a lightweight Rust MCP server with SQLite + FTS5. Zero network calls, no API keys. As of **v2.2**, offline dense/hybrid embeddings are **bundled by default** (the model is compiled into the binary), so semantic recall works zero-config with no external model download. v2.2 provides **40 MCP tools** across structured entities, hybrid vector search, RAG, connectors, confidence decay, journal events, and state management: `mimir_remember`, `mimir_recall`, `mimir_context`, `mimir_traverse`, `mimir_decay`, `mimir_stats`, `mimir_health`, and more.\n\n📄 [Product page →](https://perseus.observer/mimir/) | ⭐ [GitHub →](https://github.com/Perseus-Computing-LLC/mimir)\n\n**Install:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/Perseus-Computing-LLC/mimir/main/scripts/bootstrap.sh | bash\n```\n\n**Hermes Agent** — add to `~/.hermes/config.yaml`:\n```yaml\nmcp_servers:\n  mimir:\n    command: \"mimir\"\n    args: [\"--db\", \"~/.mimir/data/mimir.db\"]\n```\n\n**Claude Desktop / Cursor** — add to your MCP settings:\n```json\n{\n  \"mcpServers\": {\n    \"mimir\": {\n      \"command\": \"mimir\",\n      \"args\": [\"--db\", \"/home/YOU/.mimir/data/mimir.db\"]\n    }\n  }\n}\n```\n\n**Perseus integration** — add to `.perseus/config.yaml`:\n```yaml\nmimir:\n  enabled: true\n  command: [\"mimir\", \"--db\", \"~/.mimir/data/mimir.db\"]\n```\nThen add `@memory mode=search query=\"your terms\"` to `.perseus/context.md` and Perseus resolves live recall at render time.\n\nWorks with any MCP-compatible assistant.\n\n## 🏆 Hackathons — 3 Entries Submitted\n\n### Google Cloud Rapid Agent (Elastic Partner Track)\n**Status:** Submitted | **Deadline:** June 11, 2026 | **Devpost:** [perseus-cmzeu9](https://devpost.com/software/perseus-cmzeu9)\n📄 [Product page →](https://perseus.observer/rapid-agent/)\n\nPerseus is entered in the Google Cloud Rapid Agent Hackathon (Elastic Partner Track).\nThe submission demonstrates persistent agent memory across three consecutive sessions,\nwith live backend swap from Elastic Cloud to Engram-rs (self-hosted).\n\n### Qwen Cloud Hackathon (MemoryAgent Track)\n**Status:** Submitted | 📄 [Product page →](https://perseus.observer/qwen-memory/)\n\nAgent that gets smarter every session. Persistent memory, confidence decay, cross-session compounding. Track requirements checklist with contradiction demo beat.\n\n### GitLab Transcend Hackathon (Showcase Track)\n**Status:** Submitted | 📄 [Product page →](https://perseus.observer/blast-radius/)\n\nBlast Radius — GitLab-native dependency impact analysis via Orbit knowledge graph. One @mention, instant risk report.\n\n### Build with Gemini XPRIZE\n**Status:** Submitted | 📄 [Product page →](https://perseus.observer/pr-pilot/)\n\nPR Pilot — 5-agent autonomous PR review pipeline. Gemini API, Google Cloud Run, Stripe integration.\n\n## Wire Perseus to Your Assistant (MCP)\n\nPerseus implements the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), exposing tools over stdio or SSE transport. Every tool resolves live workspace state at invocation time — no stale cache, no pre-computed snapshots.\n\n\u003e **⚠️ Security Gate:** Shell-executing directives (`@query`, `@agent`, `@services command:`) require `export PERSEUS_ALLOW_DANGEROUS=1`. Without it, shell directives are silently skipped.\n\n### Quick Start (MCP Server)\n\n```bash\npip install perseus-ctx\nperseus mcp serve                          # stdio (Claude Desktop, Claude Code, Cursor, Codex)\nperseus mcp serve --transport sse --port 8420  # SSE (remote agents, multi-machine)\n```\n\n### Assistant-Specific Wiring\n\nPick your assistant and add the config block shown:\n\n**Hermes Agent** (`~/.hermes/config.yaml`):\n\n```yaml\nmcp_servers:\n  perseus:\n    command: perseus\n    args: [\"mcp\", \"serve\", \"--workspace\", \"/path/to/workspace\"]\n```\n\nThen verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in your session.\n\n\u003e Use an absolute path for `--workspace`. Perseus's non-interactive shell context has a limited PATH — a bare `perseus` command works in the Hermes MCP config because Hermes resolves it from the user's environment, but the workspace path must be absolute.\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus\": {\n      \"command\": \"perseus\",\n      \"args\": [\"mcp\", \"serve\", \"--workspace\", \"/path/to/workspace\"]\n    }\n  }\n}\n```\n\n**Claude Code** (`.mcp.json` in your project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus\": {\n      \"command\": \"perseus\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus\": {\n      \"command\": \"perseus\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Codex** (`~/.codex/config.toml` or per-project `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus\": {\n      \"command\": \"perseus\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Rovo Dev** (`.mcp.json` in repo root):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus\": {\n      \"command\": \"perseus\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\nRovo Dev also reads `AGENTS.md` at session start — pair MCP tools with rendered context for a complete setup.\n\n### Docker\n\n```bash\ndocker build -t perseus .\ndocker run --rm -v /path/to/workspace:/workspace perseus mcp serve\n```\n\nSee [Container Runtime](./docs/CONTAINER.md) for full Docker and compose deployment.\n\n### MCP Registry\n\nPublished as [`io.github.Perseus-Computing-LLC/perseus`](https://registry.modelcontextprotocol.io/) on the official MCP Registry (search \\\"perseus\\\"). Includes `server.json` for zero-config discovery.\n\n---\n\n### MCP Tools\n\n\u003c!-- test-count: 1032 --\u003e\n24 MCP tools resolve live state at invocation time. Two sensitive tools (`perseus_query` and `perseus_agent`) require explicit `mcp.tool_allowlist` opt-in because they execute commands in the user's local shell — **not sandboxed, full user permissions apply**:\n\n| Tool | Description |\n|---|---|\n| `perseus_services` | Health-check running services |\n| `perseus_query` | Run a shell command and return stdout |\n| `perseus_read` | Read file contents |\n| `perseus_list` | List directory or structured data |\n| `perseus_tree` | Tree view of directory |\n| `perseus_env` | Read environment variables |\n| `perseus_date` | Current date/time |\n| `perseus_waypoint` | Latest checkpoint summary |\n| `perseus_session` | Recent session digests |\n| `perseus_health` | Context maintenance report |\n| `perseus_drift` | Oracle drift report |\n| `perseus_memory` | Mnēmē narrative memory (+ Mimir persistent store) |\n| `perseus_mimir` | Recall persistent memories via Mimir BM25 |\n| `perseus_skills` | List available skills with staleness flags |\n| `perseus_include` | Include and render another file |\n| `perseus_agent` | Execute local agent subprocess |\n| `perseus_agora` | Task board from tasks/*.md |\n| `perseus_inbox` | Agent message inbox |\n| `perseus_prompt` | System prompt block |\n| `perseus_validate` | Validate rendered block against schema |\n| `perseus_tool` | Run allowlisted external tool |\n| `perseus_perseus` | Fetch context from remote Perseus instance |\n| `perseus_get_context` | Full rendered workspace context |\n| `perseus_get_health` | Daedalus context-maintenance heuristics |\n\n---\n\n## The Problem\n\nEvery AI assistant session starts cold. Before useful work begins, the assistant burns turns on orientation — checking which services are running, reading stale config files, rediscovering where you left off. Static markdown files (`.cursorrules`, `CLAUDE.md`) rot immediately. The port you wrote down has changed. The container that was \"always running\" hasn't been started since Tuesday.\n\n**Stale context isn't neutral. It's drag.**\n\n---\n\n## The Fix: Resolve Before Context\n\nPerseus is a pre-processor. You write directives in a source document — `@query`, `@services`, `@waypoint` — and Perseus resolves them at render time, then outputs plain markdown. The assistant reads **verified facts**, not instructions to go find facts.\n\n```\nWithout Perseus                     With Perseus\n────────────────────────────────    ──────────────────────────────────\n\"Port is 3001 (check .env)\"    →   Port: 3001\n\"47 tests (may be stale)\"      →   Tests: all passing (run 8s ago)\n\"Check docker ps first\"        →   mongo-dev: Up 4h 12m\n\"Where did we leave off?\"      →   Checkpoint: webhook handler written,\n                                              pending test run\n```\n\nPerseus replaces your assistant's context file — `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `.hermes.md` — with rendered live context. **If you already have a hand-written context file, migrate its static content into `.perseus/context.md` first.** Perseus overwrites the output file on every render. Add `@perseus` to line 1 of your source and it becomes live. The assistant never sees directive syntax. It sees a document that was already true.\n\n---\n\n## Quick Start (30 Seconds to Live Context)\n\n```bash\nperseus quickstart          # auto-detects project, scaffolds context, renders\n```\n\nSmart init detects your stack and tailors the setup:\n- **Python** → `@memory` queries for test patterns, type annotations\n- **Rust** → trait bounds, lifetime annotations, cargo config\n- **Node.js/TS** → npm scripts, ESLint config, component patterns\n- **Go, Java, C/C++, Docker** — all detected automatically\n- Falls back to a sensible generic query when unknown\n\nThe output file name is the only assistant-specific detail:\n\n| Assistant | Output file |\n|---|---|\n| Claude Code | `CLAUDE.md` |\n| Hermes Agent | `.hermes.md` (top priority) or `AGENTS.md` |\n| Cursor | `.cursorrules` or `.cursor/context.md` |\n| Codex | `AGENTS.md` |\n| Rovo Dev | `AGENTS.md` |\n| Any other | Whatever your assistant reads at session start |\n\n\u003e **Hermes priority order:** `.hermes.md` → `AGENTS.md` → `CLAUDE.md`. Render to `.hermes.md` for highest priority.\n\nKeep it fresh with cron, launchd, systemd, or `perseus watch`:\n\n```bash\n# Linux systemd (auto-refresh every 5 minutes)\nperseus systemd .perseus/context.md --output AGENTS.md --interval 5m --install --enable\n\n# macOS launchd\nperseus launchd .perseus/context.md --output AGENTS.md\n\n# Cron (any POSIX host)\nperseus cron .perseus/context.md --output AGENTS.md --every 5 --install\n```\n\nSee the [Integration Guide](./docs/HERMES_INTEGRATION.md) for Hermes-specific auto-refresh setups and [spec/integration.md](./spec/integration.md) for full adapter patterns.\n\n---\n\n## Why Perseus? (Proof, Hardening, and Enterprise Value)\n\nPerseus delivers verified, up-to-date context, eliminating the need for AI assistants to spend turns orienting themselves. Here's how it stands up:\n\n### Performance \u0026 Efficiency\n\n- **1,190× cold→warm gap** — Real-world scenario using the Perseus repo itself as the benchmark target. At the 1,408 directive scale, the cold render took **578.7s**, while the warm render took **0.486s**. [Raw data →](benchmark/real_deltas.json)\n- **Mnēmē persistent memory** — In-process BM25 recall, zero daemon. **37ms search P50 at 10,000 docs**, flat across all scales. Perseus `@mimir` renders: **51× cold→warm speedup** with @cache. **2,700 docs/sec** write throughput, **0.4ms P50** saves. v1.0.7 adds **Mimir** (Project Synapse) — MCP-based remote memory with Ebbinghaus time-decay and FTS5 + LIKE hybrid search, circuit-breaker protected. Local Mnēmē remains the default. [Full results →](benchmark/mneme_hardcore.json)\n- **94% token reduction, 0ms overhead** — live 200-request A/B harness: 488 → 27 avg prompt tokens per request. P99 latency overhead: **0ms** — Perseus adds nothing to response time. [Full harness results →](benchmark/ultimate_suite_results.json)\n- **Enterprise Ready** — Cost analysis shows that for a 500-developer team, Perseus can save significant token costs per year. [Cost analysis →](benchmark/titan_cost.json)\n- **Extreme Enterprise Benchmark** — 10-phase suite (reps=10, 50 devs, 250 concurrent agents): **10/10 hard gates · 6/6 soft gates · 0 errors at 250 concurrent · 90% enterprise ROI · fleet P99 1,169ms**. The benchmark is designed to surface regressions, not hide them. [Full methodology →](benchmark/README_EXTREME.md) · [Raw results →](benchmark/extreme_enterprise_results_full.json)\n\n![Perseus v1.0.6 — Performance Benchmarks](https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus/main/benchmark/infographic/perseus-benchmarks.svg)\n\n### Reliability \u0026 Security\n\nPerseus is tested against edge cases that challenge the \"resolve before context\" claim. **v1.0.6** completed a deep-dive architectural review (O(n²)→O(n), regex parser, shell hardening, retry classification) and a full security review against the MCP transport and foreign resolver surface (Phase 26):\n\n- **MCP SSE bearer-token auth** — `POST /message` requires Bearer token via `mcp.sse_bearer_token` config key (falls back to `serve.auth_token` for backward compat). Unauthenticated requests receive 401.\n- **Platform-portable MCP timeout** — `_call_tool()` uses `ThreadPoolExecutor` + `Future.result(timeout=...)` instead of Unix-only SIGALRM. Works on Windows, macOS, and Linux.\n\n**Platform support:** Perseus is developed and CI-tested on Linux (Ubuntu, Python 3.10–3.12). macOS is supported but not in CI. Windows is supported with caveats: the MCP transport and core render pipeline work cross-platform, but approximately 8% of the test suite currently fails on Windows due to POSIX-specific shell assumptions, path handling differences, and missing `select` support in the LSP module. Native Windows scheduling (Task Scheduler) is deferred — use WSL cron or invoke `perseus render` from your own scheduler. Windows improvements are tracked but not the primary target.\n- **Foreign resolver SSRF protection** — URL allowlist via `foreign_resolver.url_allowlist`, private-IP blocking (`block_private_ips`, default true), HMAC signature verification (`verify_signatures` now defaults to true, minimum 32-char secret). Redirects re-check destination IPs. Localhost (127.0.0.1, ::1) explicitly allowed for local testing.\n\n- **16/16 hard gates passed — Gauntlet v2: 100.0/100** — Full 10-phase enterprise torture test on Perseus v1.0.8: cold/warm renders, memory retrieval, single/multi-agent tasks, 5-day enterprise week, 12 adversarial scenarios, 2-hour sustained torture, and token efficiency. All 16 gates passed with zero failures. [Full results →](benchmark/gauntlet/v2/gauntlet_v2_report.md)\n- **Semantic Equivalence: 1.0** — A live Gemini 2.5 Flash judge found 20/20 A/B test pairs to be semantically equivalent, confirming that Perseus changes what the assistant *knows*, not what it says.\n- **Workspace boundaries** — Symlink escapes (direct, relative, chained, to `/etc`) are all blocked. The trust-gate resolves symlinks to their real target before checking boundaries.\n- **Context overflow protection** — `@read` and `@include` warn and truncate when files exceed `max_read_bytes` / `max_include_bytes` (512 KB default, `None` for unlimited).\n- **Transitive resolution** — `@include` on `.md` files recursively renders directives up to `max_include_depth` (default 5), with cycle detection.\n- **Integrity drift** — Optional `integrity_check` captures file mtimes before render and warns if any file changed mid-resolution.\n- **Plugin sandboxing** — Plugin directives with `executes_shell=True` are gated behind `allow_query_shell`, same as built-ins. Plugin errors are caught and surfaced as inline warnings — a broken plugin never breaks a render.\n\n[Edge-case tests](tests/test_edge_cases.py) cover circular dependencies, race conditions, symlink escapes, and context overflow. These four config knobs live under `render:` in `~/.perseus/config.yaml`.\n\nPerseus reads from a live filesystem — there is no snapshot isolation unless you enable `integrity_check`. Files can change between directive resolutions. The render output reflects whatever was on disk at the moment each directive resolved, **not** a single atomic point-in-time. This is the right tradeoff for a zero-dependency pre-processor (zero overhead by default, check when it matters), but it is not a database transaction.\n\nThe `O_CREAT | O_EXCL` checkpoint locking is atomic on local POSIX filesystems. Network filesystems (**NFS** \u003c v4, **SMB**, cloud mounts) may not honor these semantics — if you run a multi-agent relay across machines, use a local disk or a filesystem with verified atomic-create support.\n\n`perseus.py` is a compiled build artifact produced by `scripts/build.py` from the modular `src/perseus/` tree. It is not hand-maintained as a single file. The source modules are the canonical form.\n\n---\n\n## How Perseus Works\n\nYou write this:\n\n```markdown\n@perseus v1.0.8\n\n# Context — @date format=\"YYYY-MM-DD HH:mm z\"\n\n## What's Running\n@query \"docker ps --format 'table {{.Names}}\\t{{.Status}}'\"\n\n## Last Session\n@waypoint ttl=86400\n\n## Ports\n@read .env key=\"API_PORT\" fallback=\"3001\"\n\n## Active Tasks\n@agora status=open,in_progress\n\n## Skills Available\n@skills flag_stale=true category=devops,github\n\n## Project Memory\n@memory focus=\"recent\"\n```\n\nPerseus renders this:\n\n```markdown\n# Context — 2026-05-27 08:33 CDT\n\n## What's Running\nmongo-dev    Up 4 hours\nredis-dev    Up 4 hours\n\n## Last Session\nCheckpoint written: 2026-05-27T08:28\nTask: webhook handler — written, pending test run\nNext: run pytest tests/test_webhook.py\n\n## Ports\n3001\n\n## Active Tasks\n| ID | Title | Status | Scope |\n|---|---|---|---|\n| task-08 | List and Tree Directives | Complete | medium |\n| task-12 | Mnēmē Narrative Memory | Complete | large |\n\n## Skills Available\n| Skill | Category | Updated |\n|---|---|---|\n| hermes-agent | autonomous-ai-agents | 2026-05-20 |\n| github-pr-workflow | github | 2026-05-15 |\n| docker-stack-auditing ⚠ | devops | 2026-03-01 |\n| documentation-audit | software-development | 2026-05-26 |\n\n## Project Memory\n### Recent\n- 2026-06-05: Deep-dive code review — O(n²)→O(n) macro expansion, regex parser, webhook retry classification, shell injection hardening. Test suite at 894 tests (Linux, Python 3.10–3.12), all passing.\n- 2026-05-27: Shipped MCP deep integration (Phase 25). 24 directives exposed as MCP tools by default.\n- 2026-05-26: Deployed Perseus v1.0.6 to PyPI. Test suite at 894 tests — all passing (Linux, Python 3.10–3.12).\n- 2026-05-24: Completed Hephaestus extensibility — plugin directives, macros, hooks, pipes.\n```\n\nThe assistant never sees a directive. It sees a document that was already true — including which skills are available, which tasks are open, and what decisions were recently made.\n\n### Extensibility in Practice\n\nMacros reduce repetition. Pipes compose. Aliases keep things short:\n\n```markdown\n@macro health-check %service%\n@query \"curl -s http://%service%:8080/health\"\n@services\n  - name: %service%\n    url: http://%service%:8080/health\n@endmacro\n\n@q \"git log --oneline -5\" | @cache ttl=300\n@health-check my-api\n```\n\nThe assistant sees resolved output — never a directive.\n\nFull directive reference: [`docs/DIRECTIVES.md`](./docs/DIRECTIVES.md).\n\n---\n\n## Session Waypoints\n\nIf an agent session crashes or a connection drops, Waypoints preserve the execution state.\n\n```bash\nperseus checkpoint \\\n  --task \"Implementing webhook integration\" \\\n  --status \"handler written, pending test run\" \\\n  --next \"run pytest tests/test_webhook.py\" \\\n  --workspace /workspace/myproject\n```\n\nThe next session recovers immediately with `perseus recover` — workspace-aware, freshness-gated, no re-orientation.\n\n---\n\n## Multi-Agent Coordination\n\n![120-agent swarm demo — 120 agents claiming tasks via atomic sidecar locks, zero collisions](demo-swarm.gif)\n\nBecause Perseus outputs flat files and writes checkpoints to disk, downstream systems can build coordination on top of it without Perseus itself being an orchestration platform. The checkpoint store is namespaced and lock-protected — agents read each other's latest state from the filesystem rather than a message bus. Teams have extended this pattern to multi-agent relay, shared inboxes, and agora task boards.\n\n```\ndev-01: [architect → implementer → reviewer → tester]  ─┐\ndev-02: [architect → implementer → reviewer → tester]  ─┤\n...                                                      ├─ shared checkpoint store\ndev-30: [architect → implementer → reviewer → tester]  ─┘     (namespaced + lock-protected)\n```\n\nProven at enterprise scale — see [Multi-Agent Relay](./docs/EXAMPLES.md#subagent-handover-zero-tax-orientation).\n\n---\n\n## Architecture\n\n```\n  Plugins:  ~/.perseus/plugins/        ─┐  Discovered at render time.\n            ~/.perseus/validators/       │  Macros, hooks, webhooks,\n            ~/.perseus/formats/          ┘  and aliases load from config.\n\nSource document (.perseus/context.md)\n  @perseus v1.0.8\n  @query \"git log --oneline -5\"          ┐\n  @read .env key=\"PORT\"                  │  Directives resolved\n  @waypoint ttl=86400                    │  before context window.\n  @services                              │  Cache layer avoids\n    - name: My App                       │  re-running slow queries.\n      url: http://localhost:3001/health  ┘\n          │\n          ▼ perseus render\n  Resolved markdown (facts, not instructions)\n          │\n          ▼\n  .hermes.md  ←── cron watchdog keeps this ≤5 min fresh\n          │\n          ▼\n  AI context window — complete, accurate, zero pre-flight tax\n\n  Waypoints: ~/.perseus/checkpoints/\n  Plugins:   ~/.perseus/plugins/\n  Validators:~/.perseus/validators/\n  Formats:   ~/.perseus/formats/\n  Cache:     ~/.perseus/cache/\n  Config:    ~/.perseus/config.yaml\n```\n\n---\n\n## Extensibility (Hephaestus)\n\nPerseus is extensible without source patching. Drop Python files into\n`~/.perseus/` and the renderer discovers them at startup.\n\n### Plugins\n\n```python\n# ~/.perseus/plugins/my_plugin.py\nfrom perseus.registry import DirectiveSpec\n\ndef _resolve_service_status(args, cfg, workspace):\n    import urllib.request\n    try:\n        resp = urllib.request.urlopen(args.strip(), timeout=5)\n        return f\"Status: {resp}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\nREGISTER = {\n    \"@service-status\": DirectiveSpec(\n        name=\"@service-status\",\n        resolver=_resolve_service_status,\n        args=[\"url\"],\n        kind=\"inline\",\n        call_sig=\"acw\",\n        executes_shell=False,\n        safe_for_hover=True,\n        cacheable=True,\n        summary=\"Check HTTP status of a URL\",\n    )\n}\n```\n\nUse it in context files: `@service-status https://api.example.com/health`\n\nBuilt-in directives always win collisions. Plugins respect the same permission\nprofile as built-ins (`executes_shell` gates behind `allow_query_shell`).\n\n### Macros\n\nReusable directive compositions — no Python needed:\n\n```markdown\n@macro deploy %env% %version%\n@query \"kubectl rollout status deploy/app -n %env%\"\n@services\n  - name: app-%env%\n    url: https://%env%.example.com/health\n@endmacro\n\n@deploy production 2.3.1\n```\n\nMacros expand before directive resolution. Chaining supported up to depth 5 with\ncycle detection. Define them in your context file or at `.perseus/macros.md`.\n\n### Render Pipeline Hooks\n\nShell scripts or Python callbacks fire at render lifecycle points —\n`on_render_start`, `on_directive_resolved`, `on_cache_hit`, `on_cache_miss`,\n`on_render_complete`, `on_directive_error`:\n\n```yaml\n# ~/.perseus/config.yaml\nhooks:\n  enabled: true\n  on_render_complete:\n    - cmd: \"notify-send 'Context refreshed'\"\n  on_directive_error:\n    - plugin: \"my_error_handler\"\n```\n\n### Pipe Syntax\n\nChain directives with `|` for lightweight composition (max 3 stages):\n\n```markdown\n@query \"ls services/\" | @cache ttl=300\n@read config.yaml path=\"endpoints\" | @validate schema=\"endpoint-list\"\n```\n\nOutput of each stage becomes the first positional argument to the next.\n\n### Tiered Context (Progressive Disclosure)\n\nNot every question needs the full environment injected. A \"what's 2+2?\" shouldn't pull in Docker health checks, skill listings, and session digests. Perseus now ships tiered context rendering — the agent *is* the RAG.\n\n```bash\nperseus render .perseus/context.md --tier 1    # core context (~12 directives, lean)\nperseus render .perseus/context.md --tier 2    # + services, skills, sessions\nperseus render .perseus/context.md              # everything (backward compatible)\n```\n\nThree tiers, assigned per directive in the registry:\n\n| Tier | Name | What goes here |\n|------|------|---------------|\n| **1** | Always | Core context — lightweight, always needed (`@date`, `@memory`, `@waypoint`, `@health`, `@env`) |\n| **2** | Conditional | Task-specific, heavier (`@services`, `@skills`, `@session`, `@agora`, `@inbox`) |\n| **3** | On-Demand | Bulky/expensive — the agent pulls it if needed (`@query`, `@read`, `@include`, `@tree`, `@list`) |\n\nDirectives above the tier limit are skipped and reported in a **Context Manifest**:\n\n```\n\u003e 📋 Context Manifest — Tier limit: 1\n\u003e\n\u003e • @services (Tier 2 / Conditional) — Health-check listed services\n\u003e • @skills (Tier 2 / Conditional) — List available skills\n\u003e • @query (Tier 3 / On-Demand) — Run a shell command and embed stdout\n\u003e\n\u003e Re-run with `perseus render --tier 2` for conditional context,\n\u003e or `--tier 3` for full context on demand.\n```\n\nTemplate authors can override per-instance with `@tier:N`:\n\n```markdown\n@services @tier:1    # Always resolve this block, even though @services defaults to Tier 2\ndocker\nnginx\n@end\n```\n\nSet `render.default_tier: 1` in `~/.perseus/config.yaml` to make lean context the default for all renders. No embedding model, no LLM routing — one integer comparison per directive gates resolution. The agent sees what's available and can pull it on demand.\n\n### Directive Aliases\n\nConfig-driven shorthand — single-pass, no recursive expansion:\n\n```yaml\n# ~/.perseus/config.yaml\ndirectives:\n  aliases:\n    \"@q\": \"@query\"\n    \"@svc\": \"@services\"\n    \"@stale-skills\": \"@skills flag_stale=true category=all\"\n```\n\nPre-defined aliases: `@q→@query`, `@r→@read`, `@svc→@services`, `@mb→@memory`,\n`@ag→@agora`, `@wp→@waypoint`, `@sess→@session`. Config aliases override them.\n\n### Custom Schema Validators\n\nPlugin validators for domain-specific schemas:\n\n```markdown\n@query \"cat endpoints.yaml\" schema=\"plugin:endpoint_list\"\n```\n\nValidator modules in `~/.perseus/validators/` export a `validate(value, schema_def)`\nfunction returning `(valid: bool, message: str)`.\n\n### Event Webhooks\n\nPOST render lifecycle events to an external URL with optional HMAC-SHA256 signing:\n\n```yaml\nwebhooks:\n  enabled: true\n  url: \"https://hooks.example.com/perseus-events\"\n  secret: \"your-hmac-key\"\n  events:\n    - on_render_start\n    - on_render_complete\n    - on_directive_error\n```\n\n---\n\n## Project Memory (Mnēmē)\n\nMnēmē (Μνήμη) is Perseus's narrative project memory. It distills checkpoints and Pythia recommendations into a per-workspace narrative — so your assistant knows not just what's running, but *how you got here*.\n\n```bash\n# Update the narrative from latest checkpoints\nperseus memory update\n\n# Query the narrative\nperseus memory query \"what was the auth decision?\"\n\n# Render it inline\nperseus render .perseus/context.md --output CLAUDE.md\n```\n\nIn your context file:\n\n```markdown\n@memory                    # full narrative\n@memory focus=\"decisions\"  # decisions section only\n@memory focus=\"recent\"     # recent activity\n```\n\nMnēmē is LLM-optional: deterministic assembly works zero-dependency; an optional `memory.llm_provider` enables richer distillation. Full docs: [spec/components.md](./spec/components.md) § 4.\n\n---\n\n## Full Documentation\n\n| Document | What it covers |\n|---|---|\n| [**CLI Reference**](./docs/CLI.md) | Every command and flag |\n| [**Setup \u0026 Config Guide**](./SETUP-GUIDE.md) | The definitive setup, config, automation, and troubleshooting guide |\n| [**Directives Reference**](./docs/DIRECTIVES.md) | All directives with modifiers and examples |\n| [**Integration Guide**](./docs/HERMES_INTEGRATION.md) | Wire Perseus to Hermes via LLM routing |\n| [**Adapter Patterns**](./spec/integration.md) | Wire Perseus to any AI assistant |\n| [**Container Runtime**](./docs/CONTAINER.md) | Docker and compose deployment |\n| [**Quickstart**](./docs/quickstart.md) | 5-minute setup walkthrough |\n| [**Product Contract**](./docs/PRODUCT_CONTRACT.md) | Guarantees, trust model, permissions |\n| [**Contributing**](./docs/CONTRIBUTING.md) | Dev setup, test suite, commit conventions |\n| [**Examples**](./docs/EXAMPLES.md) | End-to-end workflow recipes |\n| [**Use Cases**](./docs/use-cases.md) | Real-world usage patterns |\n| [**Performance**](./docs/PERFORMANCE.md) | Benchmark methodology and results |\n| [**Agent Surfaces**](./docs/AGENT_SURFACES.md) | JSON contracts for agent consumption |\n| [**Deployment**](./docs/DEPLOYMENT.md) | Systemd, launchd, cron, Docker, CI |\n| [**Security**](./SECURITY.md) | Trust model, workspace boundaries, secrets |\n| [**Roadmap**](./ROADMAP.md) | Living roadmap (live `@perseus` source) |\n\n---\n\n## Government \u0026 Federal Procurement\n\nPerseus is built for government deployment from the ground up.\n\n| Capability | Status |\n|---|---|\n| **License** | MIT — no copyleft, no GPL/AGPL |\n| **SBOM** | [Published](./docs/SBOM.md) — NTIA minimum elements |\n| **Air-gapped** | Zero cloud dependencies |\n| **Encryption** | N/A (read-only context engine) |\n| **Telemetry** | None — no phoning home, no tracking |\n| **Supply chain** | SLSA attestation in progress |\n\n**For federal buyers:** See [docs/federal-buyers.md](./docs/federal-buyers.md) for\nprocurement information, compliance status, and deployment models (air-gapped,\non-premises, classified environments).\n\nPerseus Computing LLC is a US-owned small business. SAM.gov registration in progress.\nNAICS: 541715, 541511, 541512.\n\n---\n\n## IP \u0026 Legal\n\n**Patent Pending.** A provisional patent application covering Perseus's\nresolve-before-context pipeline architecture is on file with the USPTO.\nSee **[docs/ip/](docs/ip/)** for the public IP portfolio, including\ntechnical disclosures and evidence exhibits.\n\n**PERSEUS™** is a trademark of Thomas Connally. Internal subsystem names\n(Pythia, Daedalus, Agora, Mnēmē) are not independently trademarked and\nare covered under the PERSEUS mark.\n\n**License:** MIT — see [LICENSE](./LICENSE). This license does not include\na patent grant; patent rights are reserved separately.\n\n**Third-party notices:** see [NOTICE](./NOTICE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperseus-computing-llc%2Fperseus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperseus-computing-llc%2Fperseus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperseus-computing-llc%2Fperseus/lists"}