Perseus Quickstart

August 27, 2026 · View on GitHub

30-Second Install

pip install perseus-ctx==1.0.26
cd your-project
perseus quickstart

That's it. Perseus scans your project, creates a context template, and verifies everything works. If you have an LLM key in your environment (Gemini, Groq, OpenAI, or DeepSeek), it is detected and can configure optional task suggestions and cited synthesis.

What Just Happened

Workspace detected — Perseus found your git repo root (or current directory)
Context template created — .perseus/context.md with @skills, @services, @query, and @session directives
Config written — .perseus/config.yaml with the balanced permission profile (safe for AI-agent workspaces)
First render verified — Perseus resolved your context. Note: the live shell @query directives (git status/log in Workspace State) are off by default for safety; quickstart prints how to enable them. Everything else renders live.
(Optional) LLM configured — if you chose a free backend during the prompt, Perseus is ready for perseus suggest and perseus synthesize

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.

Add Durable Memory (optional)

Cross-session durable memory is a separate, optional component: Perseus Vault. Perseus Context Engine resolves the active working context; Perseus Vault owns durable-memory persistence and recall. perseus quickstart writes the connector configuration. The command below installs the verified v2.23.2 x86_64 Linux release:

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"
perseus doctor

Use the v2.23.2 release page for macOS, Windows, other architectures, and provenance. Without Perseus Vault, Perseus Context Engine still works; Vault-backed recall returns no records.

Setting Up a Free LLM Backend

Optional task suggestions and cited synthesis need an LLM. Perseus supports several backends:

Option 1: Gemini Free Tier (recommended)

No credit card required. 15 requests per minute.

# 1. Get an API key at https://aistudio.google.com/apikey
# 2. Export it
export GEMINI_API_KEY="your-key-here"

# 3. Re-run quickstart — it auto-detects the key
perseus quickstart

Perseus adds to .perseus/config.yaml:

generation:
  enabled: true
  model: gemini-2.5-flash
  provider: openai-compat
llm:
  provider: openai-compat
  model: gemini-2.5-flash
  url: https://generativelanguage.googleapis.com/v1beta

Option 2: Groq Free Tier

No credit card. Very fast inference.

export GROQ_API_KEY="your-key-here"
perseus quickstart

Option 3: Local llama.cpp (fully offline)

No network. Fully private. Requires llama.cpp server running locally.

# Install llama.cpp
brew install llama.cpp                    # macOS
# or: apt install llama-cpp               # Linux

# Download a model
llama-cli download llama-3.2-3b

# Start the server (OpenAI-compatible API)
llama-server -m llama-3.2-3b.Q4_K_M.gguf --port 8080

# Configure Perseus
perseus quickstart                        # choose option [4]

Your config will be:

generation:
  enabled: true
  model: llama-3.2-3b
  provider: llamacpp
llm:
  provider: llamacpp
  model: llama-3.2-3b
  url: http://127.0.0.1:8080

Option 4: Skip and Configure Later

Edit .perseus/config.yaml manually, or re-run perseus quickstart later.

Next Steps

Command	What it does
`perseus render .perseus/context.md`	Refresh rendered context
`perseus serve --lsp --stdio`	Start LSP for your editor (Claude Code, Cursor, etc.)
`perseus watch`	Auto-refresh context when sources change
`perseus suggest "fix the login bug"`	Get ranked tool/skill suggestions
`perseus synthesize "What's the auth flow?" --source src/auth.py`	Draft cited synthesis claims
`perseus doctor`	Health check — config, LLM, cache, sessions, directives
`perseus checkpoint --task "my work" --status "in progress"`	Save a session checkpoint
`perseus memory update`	Update Perseus Vault project narrative
`perseus trust`	Show effective permission profile
`perseus --help`	Full command reference

Editor Integration

For full wiring instructions — MCP server, editor hooks, live auto-refresh, systemd timers, cron, context packs, and trust configuration — see WIRING.md.

Quick Editor Hooks

Claude Code / Cursor / Copilot / Gemini CLI

perseus install --target claude-code
# or: cursor, copilot, gemini-cli

This installs hooks so your AI assistant gets fresh Perseus context at session start.

MCP Server

For MCP configurations and scheduled jobs, use the stable launcher ~/.local/bin/perseus. It remains the same entry point across package upgrades, so background jobs do not pin a version-specific Python or Library path. Bare perseus remains fine for interactive shells; use command -v perseus to inspect the resolved installation when diagnosing a path problem.

~/.local/bin/perseus mcp config    # Print MCP client config for Claude Desktop, Cursor, etc.
~/.local/bin/perseus mcp serve     # Run as an MCP server over stdio

CI/CD Integration

Add to your CI pipeline (GitHub Actions, etc.):

- name: Refresh Perseus context
  run: ~/.local/bin/perseus render .perseus/context.md --output .hermes.md --strict

The --strict flag fails the build if any directive emits a warning.

Troubleshooting

# Check everything
perseus doctor

# Verify the local setup
perseus doctor

# Check permission profile
perseus trust

# Recover from last checkpoint
perseus recover

Advanced manual configuration (dangerous gates opt-in)

The example below deliberately enables shell, agent-shell, remote-health, and service-command operations. Do not use it as a default. Review each gate, keep unneeded operations false, and set PERSEUS_ALLOW_DANGEROUS=1 only for a workspace where the operator accepts those process-level permissions.

If you prefer to configure manually instead of using perseus quickstart:

perseus init                # Scaffold .perseus/context.md
# Edit .perseus/context.md  # Add your project-specific directives
perseus render .perseus/context.md  # Verify it works

Then create .perseus/config.yaml:

# ~/.perseus/config.yaml
# ⚠ CRITICAL: @query needs BOTH of these, by design (defense-in-depth):
#   1) render.allow_query_shell: true  (below), AND
#   2) export PERSEUS_ALLOW_DANGEROUS=1  in your shell.
# With only one set, @query renders a warning block instead of shell output.
# The trust section controls audit display only — NOT the render gate.
render:
  allow_query_shell: true        # ← required, but not sufficient alone (see above)
  allow_agent_shell: true
  allow_remote_services_health: true
  allow_services_command: true
  parallel_services: true
  services_timeout_s: 3

trust:
  allow_query_shell: true        # controls audit display only
  allow_outside_workspace: false
  redact_secrets: true

# Optional: LLM backend for task suggestions and cited synthesis
generation:
  enabled: true
  model: gemini-2.5-flash
llm:
  provider: openai-compat
  model: gemini-2.5-flash
  url: https://generativelanguage.googleapis.com/v1beta

See the full Setup & Configuration Guide for detailed config documentation, automation patterns, and troubleshooting.

Prefer a step-by-step walkthrough? See the detailed Quickstart — it walks through every step from zero to a live rendered context.