Perseus

What is Perseus?

Perseus is a live context engine that pre‑processes dynamic directives into plain markdown, resolving real‑time workspace state before an AI assistant session starts. It replaces static context files (e.g., CLAUDE.md, .cursorrules, AGENTS.md) with verified facts, eliminating cold‑start orientation overhead.

How to use Perseus?

Install the Python package (pip install perseus-ctx) and run perseus mcp serve to start the MCP server over stdio or SSE transport. Wire it to any MCP‑compatible assistant by adding the appropriate config block (Claude Desktop, Claude Code, Cursor, Codex, Hermes, Rovo Dev). Shell‑executing directives require the environment variable PERSEUS_ALLOW_DANGEROUS=1.

Key features of Perseus

• Resolves live workspace state at invocation time – no stale cache
• 30 default MCP tools (services, files, environment, checkpoints, etc.)
• Two opt‑in shell‑execution tools (perseus_query, perseus_agent)
• Integrates with persistent memory backend Mimir (optional)
• Works with any MCP‑compatible assistant (Claude, Cursor, Codex, Hermes, Rovo Dev)
• SSE transport support for remote agents and multi‑machine setups

Use cases of Perseus

• Replace static assistant context files with live, verified workspace state
• Get real‑time service health, directory trees, and environment variables
• Recall persistent memories across sessions via Mimir integration
• Retrieve checkpoint and session digests without manual logging
• Declare token budgets and render context profiles per model

FAQ from Perseus

What dependencies does Perseus require?

Perseus is a Python package installed via pip install perseus-ctx. No external databases or API keys are required. The optional Mimir memory backend is a standalone Rust MCP server.

Can Perseus be used with any MCP‑compatible assistant?

Yes. Configurations are provided for Claude Desktop, Claude Code, Cursor, Codex, Hermes Agent, and Rovo Dev. Any MCP‑compatible client can connect via stdio or SSE.

What are the two sensitive tools and how do I enable them?

perseus_query (run a shell command) and perseus_agent (execute a local agent subprocess) are excluded from the default toolset. They must be explicitly added to mcp.tool_allowlist because they run commands with full user permissions.

Is there a security gate for shell commands?

Yes. Shell‑executing directives (@query, @agent, @services command:) require the environment variable PERSEUS_ALLOW_DANGEROUS=1; otherwise they are silently skipped.

Where does persistent memory data live?

When using the Mimir backend, data is stored in a local SQLite file (default: ~/.mimir/data/mimir.db). No external network calls or API keys are involved.