Perseus

Perseus™ 🪞 — One command. Zero orientation.

Published on PyPI · Official MCP Registry · Glama · Smithery · Lulu MCPs 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.

What you get

• Live context before the first turn — render verified workspace facts instead of making an assistant rediscover them.
• One source, any assistant — write .perseus/context.md once and render to .hermes.md, AGENTS.md, CLAUDE.md, .cursorrules, or another assistant context file.
• Local-first by default — the core renderer reads your workspace locally; no account or hosted service is required.
• MCP-native when you need it — expose the same live context as a stdio or SSE MCP server, with shell-executing tools opt-in.

Context, memory, and session terms

Perseus resolves and shapes the active working context; Perseus Vault owns durable-memory persistence and recall.

• 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.
• Durable memory is information intended to survive session boundaries. Perseus Vault owns its persistence and recall.
• 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.
• 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.

Fastest path

pip install perseus-ctx
cd your-project
perseus quickstart

That creates .perseus/context.md and a project config, detects common stacks, and verifies the first render. See the 5-minute quickstart for assistant profiles, refresh options, and security settings.

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 latest completed paired confirmation is 82.0% (410/500) on LongMemEval-S using the official-CoT answer prompt and evidence-structured candidate context, versus 83.2% (416/500) for the matched full-context control (-1.2 points). This is a company-run internal result: the preregistered success rule failed, so it is not a superiority, independent-holdout, or production-promotion claim. The historical official-CoT mean is 79.0% and the separately labeled plain-prompt result is 73.8%. On LOCOMO (run on Mem0's own harness), the same local evaluation reports Perseus Vault 87.9%, Mem0 Platform 82.2%, and Zep Cloud 33.8%. Local-first, air-gap ready, MIT.

🛡️ Platform

Perseus is one platform with three layers. Each layer has a distinct job; together they keep agent work oriented, durable, and reviewable.

The benchmarks desk is the proof surface for measured results. It is not a fourth product or a substitute for a customer evaluation.

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 a broad canonical MCP surface under perseus_vault_* names across structured entities, hybrid vector search, RAG, connectors, confidence decay, journal events, and state management. Representative tools include perseus_vault_remember, perseus_vault_recall, perseus_vault_context, perseus_vault_traverse, perseus_vault_decay, perseus_vault_stats, and perseus_vault_health.

📄 Product page → | ⭐ Vault on 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). 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.

Works with any MCP-compatible assistant.

Project history

The projects below are historical experiments and submissions, not current product lines:

• Rapid Agent — persistent agent memory across three sessions, with a backend swap from Elastic Cloud to Engram-rs. Devpost
• Qwen Memory — a memory-agent prototype exploring confidence decay and cross-session compounding.
• Blast Radius — a GitLab-native dependency-impact prototype using a knowledge graph.
• PR Pilot — an autonomous PR-review prototype with graduated review stages.

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.

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.

⚠️ 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
~/.local/bin/perseus mcp serve                          # stdio (Claude Desktop, Claude Code, Cursor, Codex)
~/.local/bin/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: /home/yourname/.local/bin/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, so the stable launcher above avoids relying on interactive-shell lookup.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "perseus": {
      "command": "/Users/yourname/.local/bin/perseus",
      "args": ["mcp", "serve", "--workspace", "/path/to/workspace"]
    }
  }
}

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

{
  "mcpServers": {
    "per

…