{ "markdown": "
\n \"Perseus\n
\n\n# Perseusβ„’ πŸͺž β€” One command. Zero orientation.\n\n[![Test Suite](https://img.shields.io/github/actions/workflow/status/Perseus-Computing-LLC/perseus/test.yml)](https://github.com/Perseus-Computing-LLC/perseus/actions/workflows/test.yml)\n[![PyPI version](https://img.shields.io/pypi/v/perseus-ctx)](https://pypi.org/project/perseus-ctx/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/perseus-ctx)](https://pypi.org/project/perseus-ctx/)\n[![License: MIT](https://img.shields.io/github/license/Perseus-Computing-LLC/perseus)](https://github.com/Perseus-Computing-LLC/perseus/blob/main/LICENSE)\n[![Glama](https://glama.ai/mcp/servers/Perseus-Computing-LLC/perseus/badge)](https://glama.ai/mcp/servers/Perseus-Computing-LLC/perseus)\n[![MCP Marketplace](https://img.shields.io/badge/MCP%20Marketplace-Indexed-blueviolet)](https://getlulu.dev/mcps/perseus-faa880)\n\n**Published on** [PyPI](https://pypi.org/project/perseus-ctx/) Β· [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Perseus-Computing-LLC/perseus) Β· [Glama](https://glama.ai/mcp/servers/Perseus-Computing-LLC/perseus) Β· [Smithery](https://smithery.ai/servers/tcconnally/perseus) Β· [Lulu MCPs](https://getlulu.dev/mcps/perseus-faa880)\n**`pip install perseus-ctx==1.0.26 && cd your-project && perseus quickstart`**\n\nZero to rendered context in three lines β€” no config spelunking:\n\n```bash\npip install perseus-ctx==1.0.26 # 1. install\ncd your-project && perseus quickstart # 2. scaffold .perseus/context.md + config\nperseus render .perseus/context.md -o AGENTS.md # 3. write live context your agent reads\n```\n\n`quickstart` detects your stack, scaffolds `.perseus/context.md`, writes config,\nand verifies a render. Step 3 writes the file your assistant loads at session\nstart (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, ...). Keep it live with\n`perseus watch` (or cron/systemd/launchd). Full walkthrough:\n[Quickstart](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/quickstart.md).\nFor the one-page product boundary and independent evaluation sequence, see the\n[Evaluator Guide](docs/EVALUATOR_GUIDE.md).\n\n### What you get\n\n- **Live context before the first turn** β€” render current workspace values with their source and freshness boundaries instead of making an assistant rediscover them.\n- **One source, any assistant** β€” write `.perseus/context.md` once and render to `.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or another assistant context file.\n- **Local-first by default** β€” the core renderer reads your workspace locally; no account or hosted service is required.\n- **MCP-native when you need it** β€” expose the same live context as a stdio or SSE MCP server, with shell-executing tools opt-in.\n\n### Context, memory, and session terms\n\nPerseus resolves and shapes the active working context; Perseus Vault owns durable-memory persistence and recall.\n\n- **Active working context** is the current, task-relevant workspace state β€” files, services, tasks, and other facts that can change. Perseus resolves and shapes it at render time before the assistant sees it.\n- **Durable memory** is information intended to survive session boundaries. Perseus Vault owns its persistence and recall.\n- **Recalled memory** is the subset of durable memory returned for a query and shaped into the rendered context. The public `@memory` directive remains the compatibility API name for Vault-backed recall; existing MCP compatibility names remain unchanged.\n- **Session history** is Perseus's recent checkpoint and session-digest record. `@waypoint` and `@session` expose it; it is distinct from durable memory. An explicit capture may persist a checkpoint in Perseus Vault as durable memory.\n\n### Fastest path\n\n```bash\npip install perseus-ctx==1.0.26\ncd your-project\nperseus quickstart\n```\n\nThat creates `.perseus/context.md` and a project config, detects common stacks,\nand verifies the first render. See the [5-minute quickstart](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/quickstart.md)\nfor assistant profiles, refresh options, and security settings.\n\n\n![Perseus demo β€” before/after cold-start](https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus/main/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)](https://github.com/Perseus-Computing-LLC/perseus/blob/main/LICENSE)\n[![Status: Patent Pending](https://img.shields.io/badge/status-patent_pending-blue)](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/ip/README.md)\n[**perseus.observer β†’**](https://perseus.observer)\n\n**Perseus is the system around the model: current context, governed memory, and reviewable evidence for consequential agent work.**\n\nPerseus Context Engine resolves live workspace state before execution. Perseus Vault carries selected, time-valid memory across sessions. Perseus Ledger records supplied events and evidence references for later review. The operator still chooses the model, keys, data path, deployment, and execution authority.\n\nThe current source-checked LongMemEval measurement is the fully offline, judge-free\n**session-level recall** lane in the Perseus Vault repository. On the public `_s`\nsplit (500 questions, 23,867 ingested sessions), the committed hybrid path reaches\n**83.2% recall@1, 96.6% recall@3, 98.8% recall@5, 99.8% recall@10, and 0.8949 MRR**\nagainst `answer_session_ids`. This is a company-run retrieval measurement: it is\nretrieval-only, not end-to-end QA accuracy; not a customer result, production\nvalidation, independent holdout, or cross-model comparison; the [committed report](https://github.com/Perseus-Computing-LLC/perseus-vault/blob/main/benchmark/longmemeval/report-currentmain-2026-08-16.json),\n[harness](https://github.com/Perseus-Computing-LLC/perseus-vault/tree/main/benchmark/longmemeval),\nand methodology boundaries are public.\n\nDeprecated answerer/judge experiments are not current product claims. Read the\n[Evaluator Guide](docs/EVALUATOR_GUIDE.md) and [canonical claim registry](claims.json)\nbefore reusing a measurement.\n\n\n\n---\n\n## πŸ›‘οΈ Platform\n\nPerseus is one platform with three layers. Each layer has a distinct job; together they keep agent work oriented, durable, and reviewable.\n\n| Layer | What it does | Page |\n|---|---|---|\n| **Perseus Context Engine** | Resolves configured workspace state into a bounded briefing with source and configuration boundaries before the model runs. | [perseus.observer/context-engine](https://perseus.observer/context-engine/) |\n| **Perseus Vault** | Persists governed memory across sessions with local-first storage, retrieval, and confidence-aware records. | [perseus.observer/vault](https://perseus.observer/vault/) |\n| **Perseus Ledger** | Records hash-chained events and evidence so consequential work can be reconstructed and reviewed. | [perseus.observer/ledger](https://perseus.observer/ledger/) |\n\nThe [benchmarks desk](https://perseus.observer/benchmarks/) is the proof surface for measured results. It is not a fourth product or a substitute for a customer evaluation.\n\n---\n\n### Perseus Vault β€” Persistent Memory (MCP)\n\n[Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) is the governed-memory component for Perseus. Its default local stdio path uses SQLite and FTS5 and does not require a Perseus-hosted service or API key. The release binary includes the default local embedding model. Optional connectors and network transports change that boundary and remain under operator configuration. Representative MCP tools include `perseus_vault_remember`, `perseus_vault_recall`, `perseus_vault_context`, `perseus_vault_traverse`, `perseus_vault_decay`, `perseus_vault_stats`, and `perseus_vault_health`.\n\nπŸ“„ [Product page β†’](https://perseus.observer/vault/) | πŸ“š [Versioned MCP API reference β†’](https://perseus.observer/vault/mcp-reference/) | ⭐ [Vault on GitHub β†’](https://github.com/Perseus-Computing-LLC/perseus-vault)\n\n**Install** (v2.23.2, x86_64 Linux; verified before extraction):\n```bash\nset -euo pipefail\nworkdir=\"$(mktemp -d)\"\ntrap 'rm -rf \"$workdir\"' EXIT\narchive=\"$workdir/perseus-vault-x86_64-unknown-linux-gnu.tar.gz\"\ncurl -fSL -o \"$archive\" https://github.com/Perseus-Computing-LLC/perseus-vault/releases/download/v2.23.2/perseus-vault-x86_64-unknown-linux-gnu.tar.gz\nprintf '%s %s\\n' '7143709aa6c9c29128e5daae47c13ddcc6ec56b35c7a605726b51f635309998e' \"$archive\" | sha256sum -c -\ntar -xzf \"$archive\" -C \"$workdir\"\ntest -f \"$workdir/perseus-vault\"\nmkdir -p \"$HOME/.local/bin\"\ninstall -m 0755 \"$workdir/perseus-vault\" \"$HOME/.local/bin/perseus-vault\"\n```\nUse the [v2.23.2 release page](https://github.com/Perseus-Computing-LLC/perseus-vault/releases/tag/v2.23.2) for macOS, Windows, other architectures, and provenance. Then run `perseus doctor` to confirm Perseus can reach it.\n\n**Hermes Agent** β€” add to `~/.hermes/config.yaml`:\n```yaml\nmcp_servers:\n perseus_vault:\n command: \"perseus-vault\"\n args: [\"serve\"]\n```\n\n**Claude Desktop / Cursor** β€” add to your MCP settings:\n```json\n{\n \"mcpServers\": {\n \"perseus_vault\": {\n \"command\": \"perseus-vault\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\n**Perseus integration** β€” add to `.perseus/config.yaml`:\n```yaml\nperseus_vault:\n enabled: true\n command: [\"perseus-vault\", \"serve\"]\n```\nThe `perseus-vault` binary self-resolves its canonical default DB path, so no `--db` argument is needed (its default is `~/.perseus-vault/data/perseus-vault.db`). The `perseus_vault:` configuration block is the sole supported memory configuration. Then 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## Wire Perseus to Your Assistant (MCP)\n\nPerseus implements the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), exposing tools over stdio or SSE transport. Most tools resolve workspace state when invoked, but freshness is tool-specific: the remote Perseus compatibility tool can cache results, waypoint data has a TTL, and explicit cache-enabled paths follow their configured policies.\n\n> **Stable launcher for MCP and schedulers:** Use `~/.local/bin/perseus` in shell commands. In JSON/YAML MCP `command` fields, replace `~` with your home directory because exec-style clients do not perform shell expansion. This install-managed launcher stays stable across package upgrades instead of baking a version-specific Python or Library path into background configuration. Interactive shell commands may still use `perseus`; verify the resolved entry point with `command -v perseus` when diagnosing an installation.\n\n> **⚠️ 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==1.0.26\n~/.local/bin/perseus mcp serve # stdio (Claude Desktop, Claude Code, Cursor, Codex)\n```\n\nFor the loopback-only SSE listener, set a bearer token in the protected Perseus config before launch. The server binds to `127.0.0.1`, rejects non-loopback Host headers, and refuses an unauthenticated bind unless the operator explicitly overrides that safeguard. Multi-machine deployments need a separately reviewed authenticated proxy or tunnel:\n\n```yaml\nmcp:\n sse_bearer_token: \"\"\n```\n\n```bash\n~/.local/bin/perseus mcp serve --transport sse --port 8420\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: /home/yourname/.local/bin/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> Use an absolute path for `--workspace`. Perseus's non-interactive shell context has a limited PATH, so the stable launcher above avoids relying on interactive-shell lookup.\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"perseus\": {\n \"command\": \"/Users/yourname/.local/bin/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\": \"/Users/yourname/.local/bin/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\": \"/Users/yourname/.local/bin/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\": \"/Users/yourname/.local/bin/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\": \"/Users/yourname/.local/bin/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](https://github.com/Perseus-Computing-LLC/perseus/blob/main/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### Current MCP interface\n\n\n\nPerseus Context Engine exposes workspace-context operations over MCP. The current public interface centers on rendering and inspecting context, checking health, reading explicitly allowed workspace sources, and connecting to Perseus Vault for durable memory. Code-level compatibility identifiers are not separate Perseus products.\n\nSensitive operations that execute a shell command or local agent process are excluded from the default tool set. They require an explicit `mcp.tool_allowlist` entry and the applicable dangerous-operation gate. They run with the current user's permissions and are not sandboxed.\n\nUse the [technical setup guide](SETUP-GUIDE.md) for host configuration. The [Context Engine MCP compatibility reference](docs/context-engine-mcp-tools.md) isolates code-level identifiers from the public product summary. Use the [versioned Perseus Vault MCP reference](https://perseus.observer/vault/mcp-reference/) for the release-bound Vault tool surface.\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 receives the rendered values together with the source and configuration boundaries that produced them.\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 rendered snapshot whose freshness depends on the source, configuration, and runtime availability.\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> **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)\n~/.local/bin/perseus systemd create .perseus/context.md --output AGENTS.md --interval 5m --install --enable\n\n# macOS launchd\n~/.local/bin/perseus launchd create .perseus/context.md --output AGENTS.md\n\n# Cron (any POSIX host)\n~/.local/bin/perseus cron create .perseus/context.md --output AGENTS.md --every 5 --install\n```\n\nSee the [file-based Hermes integration guide](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/HERMES_INTEGRATION.md) for generated context-file setup and [adapter patterns](https://github.com/Perseus-Computing-LLC/perseus/blob/main/spec/integration.md) for full integration details.\n\n---\n\n## Why Perseus? (Proof, Hardening, and Enterprise Value)\n\nPerseus delivers context rendered from configured sources, with freshness limits made visible, so AI assistants spend fewer turns orienting themselves. Here's how it stands up:\n\n### Performance & efficiency\n\nCurrent public measurements belong in the [methods desk](https://perseus.observer/benchmarks/) and [claims registry](claims.json). Each reusable figure must keep its method, dataset, denominator, control, and limitation attached.\n\n### Reliability & Security\n\nPerseus is tested against edge cases that challenge the resolve-before-context contract. The current security boundary and documented posture live in [SECURITY.md](SECURITY.md) and on the [public security page](https://perseus.observer/security/):\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. macOS is supported but not in CI. Windows core rendering, MCP transport, and Task Scheduler integration work with known POSIX-specific shell, path, and LSP caveats.\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- **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 permission gating** β€” Plugin directives with `executes_shell=True` are gated behind `allow_query_shell`, like built-ins. This is a permission gate, not a sandbox: enabled plugin code runs with the current user's permissions. Plugin errors are caught and surfaced as inline warnings.\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 documented tradeoff for a local pre-processor (low 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** < 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## Research references\n\nThe architecture draws on published work about context contracts, governed selection, structured context, and protocol security. Those papers motivate design questions; they do not validate Perseus products or supply reusable Perseus benchmark claims.\n\n- [Protocol-Driven Development](https://arxiv.org/abs/2605.12981)\n- [ContextNest](https://arxiv.org/abs/2607.02116)\n- [HiSkill](https://arxiv.org/abs/2607.25853)\n- [Breaking the Protocol](https://arxiv.org/abs/2601.17549)\n\nUse the [public methods desk](https://perseus.observer/benchmarks/) and [`claims.json`](claims.json) for current Perseus measurements, controls, denominators, and limitations.\n\n---\n\n## How Perseus Works\n\nThe first line in this **illustrative syntax sample** is the directive protocol marker, not the installed package version. Dates, task names, and rendered values below are examples, not current release or test evidence:\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 | Perseus Vault 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- [Illustrative] Reviewed a retry classification and shell-input hardening change.\n- [Illustrative] Added an MCP integration path for a project workspace.\n- [Illustrative] Published an earlier package release.\n- [Illustrative] Added plugin directives, macros, hooks, and pipes.\n```\n\nThe assistant never sees a directive. It sees a rendered snapshot of which skills are available, which tasks are open, and what decisions were recently made; those values should be checked against their source and freshness limits.\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## Composition boundary\n\nPerseus Context Engine writes bounded context artifacts and workspace checkpoints. Other systems can read those files to coordinate work, but the Context Engine is not an orchestration platform and the repository does not claim an enterprise deployment from that composition pattern.\n\n---\n\n## Architecture\n\n```text\noperator-authored context source\n |\n v\nPerseus Context Engine\n - validates enabled directives\n - resolves allowed local sources\n - gates optional shell and network operations\n - emits bounded markdown plus diagnostics\n |\n +--> compatible assistant host\n +--> optional Perseus Vault recall\n +--> optional Perseus Ledger evidence record\n```\n\nPerseus Vault and Perseus Ledger remain separate components. Extensions, hooks, custom directives, and external service checks execute only when the operator configures them; they inherit the current user's permissions and can change the local-only data boundary.\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> πŸ“‹ Context Manifest β€” Tier limit: 1\n>\n> β€’ @services (Tier 2 / Conditional) β€” Health-check listed services\n> β€’ @skills (Tier 2 / Conditional) β€” List available skills\n> β€’ @query (Tier 3 / On-Demand) β€” Run a shell command and embed stdout\n>\n> Re-run with `perseus render --tier 2` for conditional context,\n> 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### Prompt-Size Forensics (`perseus prompt-size` + `@budget`)\n\nContext is the scarcest resource in agent systems β€” and it's usually spent blind. `perseus prompt-size` renders a context and shows exactly where every byte went, attributed **per directive**, with a static-vs-dynamic split:\n\n```bash\nperseus prompt-size .perseus/context.md # human table, largest offenders first\nperseus prompt-size .perseus/context.md --json # stable, deterministic JSON for CI diffing\nperseus prompt-size .perseus/context.md --since HEAD~5 # per-directive budget delta vs a git ref\n```\n\n```\nperseus prompt-size: context.md (tier 3)\ntotal: 5950 bytes, 2270 tokens [tiktoken:cl100k_base β€” exact]\nsplit: static 43 B / cacheable 45 B / volatile 5862 B (attributed 5907 + static 43 = 5950 β€” exact)\n\nPer directive (largest first):\n 5862 B 2249 tok 98.52% [ volatile] @env PATH line 7\n 45 B 9 tok 0.76% [cacheable] @include \"sub.md\" line 8\n```\n\n- **Byte-exact accounting** β€” per-directive bytes + static template bytes sum to the rendered total with no unattributed remainder (the `accounting.exact` field asserts this in `--json`).\n- **Tokenizer-aware** β€” real BPE counts via `tiktoken` (cl100k_base) when it happens to be installed (labeled `exact`); otherwise a deterministic offline heuristic clearly labeled `estimate`. Never a network call.\n- **Static vs. dynamic split** β€” see how much of the render is a cacheable prefix vs. per-render volatility (`@env`, `@date`, `@query`).\n- **`--since ` diff mode** β€” renders the file's content at the ref (via `git show`, offline) and reports which directive's contribution grew, so \"someone added an `@include` that doubled the prompt\" is caught in review.\n\nPair it with a **`@budget`** declaration in the source to gate context bloat in CI:\n\n```markdown\n@perseus\n@budget max=8000 strict forensic\n...\n```\n\n`perseus prompt-size` checks every `@budget` after the render: under budget passes silently; over budget warns with the per-directive offender breakdown β€” or exits non-zero when the declaration says `strict` (or the CLI is invoked with `--strict`). `forensic` expands the overflow report to the full per-directive table plus the static/cacheable/volatile split. The directive itself renders as empty text, so it costs nothing in the context it guards.\n\nScope contract: `@budget` declarations are read from the top-level source text before conditionals are evaluated β€” **top-level only**. A `@budget` inside an `@include`'d file is not enforced (`prompt-size` warns and reports it under `included_budgets` in `--json`); a `@budget` inside a false `@if` branch is still enforced, because the scan is text-level. In `--json` output, `static.tokens` is derived (total βˆ’ Ξ£ per-directive tokens, clamped at 0 and flagged `tokens_derived`) β€” the byte accounting is the measured, exact invariant.\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### Speculative Prefetch (`@speculate`)\n\nSpeculative execution for context assembly (#607): a transparent Markov /\nfrequency predictor over your recorded waypoint (checkpoint) transitions\npredicts the next task, and Perseus pre-warms that task's context **after the\ncurrent render completes** β€” so the first render of the next turn is already\nhot. No ML dependencies; the predictor interface is pluggable for a future\nLLM backend.\n\n**Off by default.** Enable it in config and opt a source in with the pragma:\n\n```yaml\n# ~/.perseus/config.yaml\nspeculate:\n enabled: true # master gate β€” default false (zero behavior change)\n k: 3 # top-k predicted next intents to consider\n budget_tokens: 2000 # cumulative token budget per speculation pass\n confidence_threshold: 0.30 # only warm predictions at/above this probability\n intents: # intent pattern (fnmatch) β†’ prefetch directive line(s)\n \"deploy*\":\n - '@read \"runbook.md\" @cache ttl=300'\n \"review*\":\n - '@query \"git log --oneline -10\" @cache ttl=120'\n```\n\n```markdown\n@perseus v1\n\nYour context here...\n@speculate k=3 budget=2000\n```\n\nThe `@speculate` pragma never appears in rendered output; `k=` / `budget=`\noverride the config for that source. Speculation is synchronous-after-render:\nit can never delay or interleave with the live render, and a failure inside\nspeculation never breaks a render.\n\n**Cache safety:** speculative warms run through the same prefetch executor and\nuse the exact key derivation the renderer reads (workspace-scoped base key +\ndependency fingerprint), so a speculative entry is just an *early* warm β€” it\ncan never shadow or poison real reads. On the real turn the renderer\nre-derives the fingerprint and TTL as usual, so a wrong prediction costs\nnothing.\n\n**Observability:**\n\n```console\n$ perseus explain --speculate\nSpeculate: enabled=true backend=markov k=3 threshold=0.30\nHistory: 42 intent(s); current: review PR\nPredicted next intents:\n 1. deploy staging p=0.67 [1 candidate(s), 1 warm]\n - warm: @read \"runbook.md\" @cache ttl=300\nPast speculation: hits=12 misses=4 hit_rate=0.75 (settled=16)\n```\n\nPrediction outcomes (hit/miss per settled prediction, budget spend, warm\nresults) persist to a workspace-keyed stats file\n(`/speculate_stats-.json`, atomic writes) with a\ndocumented shape β€” a future `@bandit` ledger integration can consume it as a\nvalue signal.\n\n---\n\n## Context profiles and durable-memory boundary\n\nPerseus Context Engine resolves and shapes the active working context. Perseus Vault owns durable-memory persistence and recall. The default `on_demand` profile adds a retrieval pointer instead of preloading a memory dump; `relevant` and legacy `always` modes require explicit configuration.\n\n```yaml\nprofiles:\n default: { context_target: 200000, memory: on_demand }\n```\n\nAn explicit `@memory` directive is a code-level compatibility interface for requesting recalled memory. It is not a separate product. Recalled material can be stale or incomplete, so live workspace state and operator policy remain authoritative.\n\nTo disable automatic recall pointers, set `perseus_vault.auto_inject: false`. See the [setup guide](SETUP-GUIDE.md) and the [versioned Vault API reference](https://perseus.observer/vault/mcp-reference/) for the current boundary.\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 & 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| [**File-based Hermes integration**](./docs/HERMES_INTEGRATION.md) | Generate context files for Hermes |\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) | Current deployment guidance with pinned versions |\n| [**Security**](./SECURITY.md) | Trust model, workspace boundaries, secrets |\n| [**Roadmap**](./ROADMAP.md) | Living roadmap (live `@perseus` source) |\n\n---\n\n## Defense and Government\n\nPerseus Computing LLC can contribute current context, governed memory, and reviewable evidence around a prime-led or program-owned workflow. It does not replace the mission system, qualified integrator, approving authority, or accreditation process.\n\n| Record | Current public scope |\n|---|---|\n| **Company identifiers** | UEI `PJS2LW7HAK35`; CAGE `22JC5`. Verify current SAM status before proposal, subcontract, or award use. |\n| **Assessment evidence** | Owner-held NIST SP 800-171 Basic and CMMC Level 2 self-assessments scored 110 for their recorded enclave scope. These are company self-assessments, not independent assessments or C3PAO certification. |\n| **JCP / DD2345** | Certification `0092893`, approved 2026-08-18 through 2031-08-18, supports requests for unclassified export-controlled military technical data. It does not grant data access, classified access, facility clearance, an ATO, or cross-domain approval. |\n| **Software publication** | MIT-licensed source, SBOM, and security materials are published. Publication does not create Government approval or accreditation. |\n| **Deployment boundary** | Local CLI and stdio paths do not require a Perseus-hosted service. A program or integrator remains responsible for packaging, hardening, keys, networks, data handling, testing, and authorization. |\n\nReview the bounded [Defense and Government page](https://perseus.observer/government/) or contact **Perseus Computing LLC** at [perseus@perseus.observer](mailto:perseus@perseus.observer).\n\n---\n\n## IP & 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β„’** identifies software published by Perseus Computing LLC. Internal subsystem names are compatibility identifiers, not separate public product lines.\n\n## Privacy Policy\n\nPerseus Context Engine has a local default render path. Authored network directives, optional transports, and external integrations change that boundary.\n\n### Data Collection\n- The default local renderer does not send Perseus telemetry or require a Perseus-hosted service.\n- Operators choose the sources, output paths, network directives, and integrations they enable.\n\n### Data Usage & Storage\n- Perseus reads project files, git state, and environment variables to resolve context directives.\n- On the default local path, project data remains in the operator environment. Authored HTTP directives or external integrations can send operator-selected data to their configured destination.\n- When paired with Perseus Vault for persistent memory, memory data is stored locally per the Perseus Vault privacy policy.\n\n### Third-Party Sharing\n- The local default path does not share project data with Perseus Computing LLC.\n- Optional MCP servers, HTTP directives, package registries, and other external services apply their own data and transport policies when the operator enables them.\n\n### Data Retention\n- Perseus does not retain data independently. Rendered context is ephemeral and regenerated on each invocation.\n- For persistent memory, see [Perseus Vault's privacy policy](https://github.com/Perseus-Computing-LLC/perseus-vault#privacy-policy).\n\n### Contact\n- **Email:** perseus@perseus.observer\n- **GitHub:** [Perseus-Computing-LLC/perseus](https://github.com/Perseus-Computing-LLC/perseus)\n\n## License\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", "bytes": 41339, "sha": "da58433e9d79a27fa360c0ebe3b4a39689832e15551068d8a8d298b41b2b9b9e", "repo_slug": "perseus-computing-llc/perseus", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_perseus_computing_llc_perseus_a4d810f2/readme" }