Perseus

Perseus™ 🪞 — One command. Zero orientation.

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

Zero to rendered context in three lines — no config spelunking:

pip install perseus-ctx                       # 1. install
cd your-project && perseus quickstart         # 2. scaffold .perseus/context.md + config
perseus render .perseus/context.md -o AGENTS.md   # 3. write live context your agent reads

quickstart detects your stack, scaffolds .perseus/context.md, writes config, and verifies a render. Step 3 writes the file your assistant loads at session start (AGENTS.md, CLAUDE.md, .cursorrules, ...). Keep it live with perseus watch (or cron/systemd/launchd). Full walkthrough: QUICKSTART.md.

perseus.observer →

Perseus: the memory & context layer for AI agents. Load only the context they actually need.

Your agents re-read their whole notebook from page one on every call, and you're billed per word. Perseus hands them just the page they need: it resolves live workspace state into verified facts before the context window opens, and pairs with Perseus Vault for durable, encrypted memory. The result: 73.8% on LongMemEval (official harness), a 67% smaller tool schema, and 611× warmer renders. On LOCOMO (run on Mem0's own harness): Perseus Vault 87.9% vs Mem0 Platform 82.2% vs Zep Cloud 33.8%. Local-first, air-gap ready, MIT.

🛡️ Product Family

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

Perseus Vault — Persistent Memory (MCP)

Perseus Vault is the persistent memory backend for Perseus — a lightweight Rust MCP server with SQLite + FTS5. Zero network calls, no API keys. 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. Perseus Vault exposes 55+ MCP tools under canonical perseus_vault_* names across structured entities, hybrid vector search, RAG, connectors, confidence decay, journal events, and state management: perseus_vault_remember, perseus_vault_recall, perseus_vault_context, perseus_vault_traverse, perseus_vault_decay, perseus_vault_stats, perseus_vault_health, and more.

📄 Product page → | ⭐ GitHub →

Install (prebuilt binary — Linux / macOS):

curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

Windows / Intel-macOS (build from source): cargo install --git https://github.com/Perseus-Computing-LLC/perseus-vault. Then run perseus doctor to confirm Perseus can reach it.

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

mcp_servers:
  perseus_vault:
    command: "perseus-vault"
    args: ["serve"]

Claude Desktop / Cursor — add to your MCP settings:

{
  "mcpServers": {
    "perseus_vault": {
      "command": "perseus-vault",
      "args": ["serve"]
    }
  }
}

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

perseus_vault:
  enabled: true
  command: ["perseus-vault", "serve"]

The 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). Legacy mimir: configuration is still accepted for back-compat, so existing configs keep working. Then add @memory mode=search query="your terms" to .perseus/context.md and Perseus resolves live recall at render time.

Works with any MCP-compatible assistant.

🏆 Hackathons — 3 Entries Submitted

Google Cloud Rapid Agent (Elastic Partner Track)

Status: Submitted | Deadline: June 11, 2026 | Devpost: perseus-cmzeu9 📄 Product page →

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)

Status: Submitted | 📄 Product page →

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)

Status: Submitted | 📄 Product page →

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

Build with Gemini XPRIZE

Status: Submitted | 📄 Product page →

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.

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.

Claude Desktop (claude_desktop_config.json):

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

Claude Code (.mcp.json in your project root):

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

Cursor (.cursor/mcp.json):

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

Codex (~/.codex/config.toml or per-project .mcp.json):

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

Rovo Dev (.mcp.json in repo root):

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

Rovo Dev also reads AGENTS.md at session start — pair MCP tools with rendered context for a complete setup.

Docker

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

See Container Runtime for full Docker and compose deployment.

MCP Registry

Published as io.github.Perseus-Computing-LLC/perseus on the official MCP Registry (search "perseus"). Includes server.json for zero-config discovery.

MCP Tools

33 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).

…