Perseus™ 🪞 — One command. Zero orientation.

Published on PyPI · Official MCP Registry · Glama · Smithery · Lulu MCPs pip install perseus-ctx==1.0.26 && cd your-project && perseus quickstart

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

pip install perseus-ctx==1.0.26                       # 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. For the one-page product boundary and independent evaluation sequence, see the Evaluator Guide.

What you get

• Live context before the first turn — render current workspace values with their source and freshness boundaries 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==1.0.26
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 is the system around the model: current context, governed memory, and reviewable evidence for consequential agent work.

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

The current source-checked LongMemEval measurement is the fully offline, judge-free session-level recall lane in the Perseus Vault repository. On the public _s split (500 questions, 23,867 ingested sessions), the committed hybrid path reaches 83.2% recall@1, 96.6% recall@3, 98.8% recall@5, 99.8% recall@10, and 0.8949 MRR against answer_session_ids. This is a company-run retrieval measurement: it is retrieval-only, not end-to-end QA accuracy; not a customer result, production validation, independent holdout, or cross-model comparison; the committed report, harness, and methodology boundaries are public.

Deprecated answerer/judge experiments are not current product claims. Read the Evaluator Guide and canonical claim registry before reusing a measurement.

🛡️ 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 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.

📄 Product page → | 📚 Versioned MCP API reference → | ⭐ Vault on GitHub →

Install (v2.23.2, x86_64 Linux; verified before extraction):

set -euo pipefail
workdir="$(mktemp -d)"
trap 'rm -rf "$workdir"' EXIT
archive="$workdir/perseus-vault-x86_64-unknown-linux-gnu.tar.gz"
curl -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
printf '%s  %s\n' '7143709aa6c9c29128e5daae47c13ddcc6ec56b35c7a605726b51f635309998e' "$archive" | sha256sum -c -
tar -xzf "$archive" -C "$workdir"
test -f "$workdir/perseus-vault"
mkdir -p "$HOME/.local/bin"
install -m 0755 "$workdir/perseus-vault" "$HOME/.local/bin/perseus-vault"

Use the v2.23.2 release page for macOS, Windows, other architectures, and provenance. 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"]
    }
  }
}