Perseus

pip install perseus-ctx && cd your-project && perseus quickstart

perseus.observer →

<!-- mcp-name: io.github.Perseus-Computing-LLC/perseus -->

---

🛡️ Product Family

Perseus is the live context engine. Seven specialized products extend it:

| Product | Description | Page |
|---|---|---|
| Mimir | 48 MCP tools — persistent memory with FTS5, entities, layers, confidence decay | /mimir/ |
| MCTS | 31 security analyzers for MCP servers — tool poisoning, prompt injection, credential leaks | /mcts/ |
| PR Pilot | 5-agent autonomous PR review pipeline — graduated autonomy L1→L3 | /pr-pilot/ |
| Blast Radius | GitLab-native dependency impact analysis — 1 mention, instant risk report | /blast-radius/ |
| Rapid Agent | Dual-backend memory agent (Elastic ↔ Engram-rs) — Google Cloud Hackathon | /rapid-agent/ |
| Qwen Memory | Agent that gets smarter every session — Qwen Cloud Hackathon | /qwen-memory/ |
| CrewAI Memory | Persistent cross-session memory backend for CrewAI (54K stars) — community PR #6208 | /crewai/ |

---

Mimir — Persistent Memory (MCP)

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.7.0, 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.12.0 provides 48 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.

📄 Product page → | ⭐ GitHub →

Install:

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

Hermes Agent — add to ~/.hermes/config.yaml:

mcp_servers:

  mimir:

    command: "mimir"

    args: ["--db", "~/.mimir/data/mimir.db"]

Claude Desktop / Cursor — add to your MCP settings:

{

  "mcpServers": {

    "mimir": {

      "command": "mimir",

      "args": ["--db", "/home/YOU/.mimir/data/mimir.db"]

    }

  }

}

Perseus integration — add to .perseus/config.yaml:

mimir:

  enabled: true

  command: ["mimir", "serve", "--db", "~/.mimir/data/mimir.db"]

Works with any MCP-compatible assistant.

🏆 Hackathons — 3 Entries Submitted

Google Cloud Rapid Agent (Elastic Partner Track)

Perseus is entered in the Google Cloud Rapid Agent Hackathon (Elastic Partner Track).
The submission demonstrates persistent agent memory across three consecutive sessions,
with live backend swap from Elastic Cloud to Engram-rs (self-hosted).

Qwen Cloud Hackathon (MemoryAgent Track)

Agent that gets smarter every session. Persistent memory, confidence decay, cross-session compounding. Track requirements checklist with contradiction demo beat.

GitLab Transcend Hackathon (Showcase Track)

Blast Radius — GitLab-native dependency impact analysis via Orbit knowledge graph. One @mention, instant risk report.

Build with Gemini XPRIZE

PR Pilot — 5-agent autonomous PR review pipeline. Gemini API, Google Cloud Run, Stripe integration.

Wire Perseus to Your Assistant (MCP)

Perseus implements the Model Context Protocol (MCP), exposing tools over stdio or SSE transport. Every tool resolves live workspace state at invocation time — no stale cache, no pre-computed snapshots.

> ⚠️ Security Gate: Shell-executing directives (@query, @agent, @services command:) require export PERSEUS_ALLOW_DANGEROUS=1. Without it, shell directives are silently skipped.

Quick Start (MCP Server)

pip install perseus-ctx
perseus mcp serve                          # stdio (Claude Desktop, Claude Code, Cursor, Codex)
perseus mcp serve --transport sse --port 8420  # SSE (remote agents, multi-machine)

Assistant-Specific Wiring

Pick your assistant and add the config block shown:

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  perseus:
    command: perseus
    args: ["mcp", "serve", "--workspace", "/path/to/workspace"]

Then verify with hermes mcp test perseus. Tools appear as mcp_perseus_ in your session.

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve", "--workspace", "/path/to/workspace"]
    }
  }
}

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

docker build -t perseus .
docker run --rm -v /path/to/workspace:/workspace perseus mcp serve

<!-- test-count: 1552 — recount with: grep -rE "^\sdef test_" tests/ | wc -l -->
<!-- The table below is the exact default output of _get_all_mcp_tools({}) — 30 rows. Recount before editing. -->
30 MCP tools resolve live state at invocation time (including the legacy aliases perseus_get_context/perseus_get_health). Two additional sensitive tools — perseus_query (run a shell command) and perseus_agent (execute a local agent subprocess) — are not part of this default set: they require explicit mcp.tool_allowlist opt-in because they execute commands in the user's local shell (not sandboxed, full user permissions apply).

| Tool | Description |
|---|---|
| perseus_services | Health-check running services |
| perseus_read | Read file contents |
| perseus_list | List directory or structured data |
| perseus_tree | Tree view of directory |
| perseus_env | Read environment variables |
| perseus_date | Current date/time |
| perseus_waypoint | Latest checkpoint summary |
| perseus_session | Recent session digests |
| perseus_health | Context maintenance report |
| perseus_drift | Oracle drift report |
| perseus_memory | Mnēmē narrative memory (+ persistent store) |
| perseus_mimir | Recall persistent memories via BM25 (legacy name of perseus_mneme) |
| perseus_mneme | Recall persistent memories from the external Mneme server via BM25 |
| perseus_skills | List available skills with staleness flags |
| perseus_include | Include and render another file |
| perseus_agora | Task board from tasks/*.md |
| perseus_inbox | Agent message inbox |
| perseus_prompt | System prompt block |
| perseus_validate | Validate rendered block against schema |
| perseus_tool | Run allowlisted external tool |
| perseus_perseus | Fetch context from remote Perseus instance |
| perseus_auto_skill | Instruct the agent to load a specific skill before starting work |
| perseus_profile | Resolve a per-model context profile (context target + memory posture) |
| perseus_mason | Query the Mason code architecture concept map |
| perseus_research | Per-paper Methods/Results blocks from an external paper-search MCP server (external server is opt-in via config) |
| perseus_tokens | Embed token budget for rendered context |
| perseus_budget | Declare a token budget enforced by perseus prompt-size |
| perseus_tooltrim | Filtered toolset metadata and usage statistics |
| perseus_get_context | Full rendered workspace context (legacy alias) |
| perseus_get_health | Daedalus context-maintenance heuristics (legacy alias) |

Opt-in only (excluded from the default set until added to mcp.tool_allowlist):

| Tool | Description |
|---|---|
| perseus_query | Run a shell command and return stdout |
| perseus_agent | Execute local agent subprocess |

---

The Problem

Every 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.

Stale context isn't neutral. It's drag.

---

The Fix: Resolve Before Context

Perseus 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.

Without Perseus                     With Perseus
────────────────────────────────    ──────────────────────────────────
"Port is 3001 (check .env)"    →   Port: 3001
"47 tests (may be stale)"      →   Tests: all passing (run 8s ago)
"Check docker ps first"        →   mongo-dev: Up 4h 12m
"Where did we leave off?"      →   Checkpoint: webhook handler written,
                                              pending test run

Perseus 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.

---

Quick Start (30 Seconds to Live Context)

perseus quickstart          # auto-detects project, scaffolds context, renders

Smart init detects your stack and tailors the setup:
- Python → @memory queries for test patterns, type annotations
- Rust → trait bounds, lifetime annotations, cargo config
- Node.js/TS → npm scripts, ESLint config, component patterns
- Go, Java, C/C++, Docker — all detected automatically
- Falls back to a sensible generic query when unknown

The output file name is the only assistant-specific detail:

| Assistant | Output file |
|---|---|
| Claude Code | CLAUDE.md |
| Hermes Agent | .hermes.md (top priority) or AGENTS.md |
| Cursor | .cursorrules or .cursor/context.md |
| Codex | AGENTS.md |
| Rovo Dev | AGENTS.md |
| Any other | Whatever your assistant reads at session start |

> Hermes priority order: .hermes.md → AGENTS.md → CLAUDE.md. Render to .hermes.md for highest priority.

Keep it fresh with cron, launchd, systemd, or perseus watch:

```bash