# Perseus Quickstart

## 30-Second Install

```bash
pip install perseus-ctx
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's auto-detected and configured for Pythia suggestions
and Synthesis.

## What Just Happened

1. **Workspace detected** — Perseus found your git repo root (or current directory)
2. **Context template created** — `.perseus/context.md` with `@skills`, `@services`,
   `@query`, and `@session` directives
3. **Config written** — `.perseus/config.yaml` with the `balanced` permission
   profile (safe for AI-agent workspaces)
4. **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.
5. **(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 — the **Perseus Vault**
MCP server. Perseus resolves and shapes the active working context; Perseus Vault
owns durable-memory persistence and recall. `perseus quickstart` already wires the
connector in your config; to install the engine (prebuilt binary, Linux/macOS):

```bash
curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh
perseus doctor    # confirms Perseus can reach the vault
```

Windows / Intel-macOS: `cargo install --git https://github.com/Perseus-Computing-LLC/perseus-vault`.
Without it, Perseus works fine — memory recall simply returns nothing.

## Setting Up a Free LLM Backend

Pythia (task suggestions) and Synthesis (cited claims from source files) need an
LLM. Perseus supports several free options:

### Option 1: Gemini Free Tier (recommended)

No credit card required. 15 requests per minute.

```bash
# 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`:
```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.

```bash
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.

```bash
# 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:
```yaml
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` | 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](./WIRING.md)**.

### Quick Editor Hooks

### Claude Code / Cursor / Copilot / Gemini CLI

```bash
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.

```bash
~/.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.):

```yaml
- 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

```bash
# Check everything
perseus doctor

# Verify LLM
perseus llm ping

# Check permission profile
perseus trust

# Recover from last checkpoint
perseus recover
```

## Manual Config

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

```bash
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`:

```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 Pythia suggestions & 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](./SETUP-GUIDE.md) for detailed config documentation, automation patterns, and troubleshooting.**
>
> **Prefer a step-by-step walkthrough?** See the [detailed Quickstart](./docs/quickstart.md) — it walks through every step from zero to a live rendered context.