perseus

<div align="center">
  <img src=".github/banner.png" alt="Perseus — Live Context Engine. One command. Zero orientation." width="100%">
</div>

# Perseus™ 🪞 — One command. Zero orientation.

[![smithery badge](https://smithery.ai/badge/Perseus-Computing-LLC/perseus)](https://smithery.ai/servers/Perseus-Computing-LLC/perseus)
**`pip install perseus-ctx && cd your-project && perseus quickstart`**

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

```bash
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](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/quickstart.md).

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

### Fastest path

```bash
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](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/quickstart.md)
for assistant profiles, refresh options, and security settings.


![Perseus demo — before/after cold-start](https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus/main/demo.gif)

[![CI](https://github.com/Perseus-Computing-LLC/perseus/actions/workflows/test.yml/badge.svg)](https://github.com/Perseus-Computing-LLC/perseus/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/perseus-ctx)](https://pypi.org/project/perseus-ctx/)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Perseus-Computing-LLC/perseus/blob/main/LICENSE)
[![Status: Patent Pending](https://img.shields.io/badge/status-patent_pending-blue)](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/ip/README.md)
[**perseus.observer →**](https://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](https://github.com/Perseus-Computing-LLC/perseus-vault) for durable, encrypted memory. The result: **79.0% on LongMemEval** with the official CoT answer prompt, a **67% smaller tool schema**, and **611× warmer renders**. The separately labeled plain-prompt LongMemEval result is **73.8%**. On LOCOMO (run on [Mem0's own harness](https://github.com/Perseus-Computing-LLC/memory-benchmarks)), the same local evaluation reports Perseus Vault **87.9%**, Mem0 Platform 82.2%, and Zep Cloud 33.8%. Local-first, air-gap ready, MIT.

<!-- mcp-name: io.github.Perseus-Computing-LLC/perseus -->

---

## 🛡️ Product Family

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

| Product | Description | Page |
|---|---|---|
| **Perseus Vault** | Persistent, encrypted memory for AI agents — FTS5, entities, layers, confidence decay. New integrations use `perseus_vault_*`; legacy aliases remain compatible. | [perseus.observer/perseus-vault](https://perseus.observer/perseus-vault/) |
| **MCTS** | 31 security analyzers for MCP servers — tool poisoning, prompt injection, credential leaks | [perseus.observer/mcts](https://perseus.observer/mcts/) |
| **PR Pilot** | 5-agent autonomous PR review pipeline — graduated autonomy L1→L3 | [perseus.observer/pr-pilot](https://perseus.observer/pr-pilot/) |
| **Blast Radius** | GitLab-native dependency impact analysis — 1 mention, instant risk report | [perseus.observer/blast-radius](https://perseus.observer/blast-radius/) |
| **Rapid Agent** | Dual-backend memory agent (Elastic ↔ Engram-rs) — Google Cloud Hackathon | [perseus.observer/rapid-agent](https://perseus.observer/rapid-agent/) |
| **Qwen Memory** | Agent that gets smarter every session — Qwen Cloud Hackathon | [perseus.observer/qwen-memory](https://perseus.observer/qwen-memory/) |
| **CrewAI Memory** | Persistent cross-session memory backend for CrewAI (54K stars) — community PR #6208 | [perseus.observer/crewai](https://perseus.observer/crewai/) |

---

### Perseus Vault — Persistent Memory (MCP)

[Perseus Vault](https://github.com/Perseus-Computing-LLC/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. Legacy `mimir_*` and `mneme_*` aliases remain callable for compatibility but are not counted as separate capabilities: `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 →](https://perseus.observer/perseus-vault/) | ⭐ [Vault on GitHub →](https://github.com/Perseus-Computing-LLC/perseus-vault)

**Install** (prebuilt binary — Linux / macOS):
```bash
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`:
```yaml
mcp_servers:
  perseus_vault:
    command: "perseus-vault"
    args: ["serve"]
```

**Claude Desktop / Cursor** — add to your MCP settings:
```json
{
  "mcpServers": {
    "perseus_vault": {
      "command": "perseus-vault",
      "args": ["serve"]
    }
  }
}
```

**Perseus integration** — add to `.perseus/config.yaml`:
```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](https://devpost.com/software/perseus-cmzeu9)
📄 [Product page →](https://perseus.observer/rapid-agent/)

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 →](https://perseus.observer/qwen-memory/)

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 →](https://perseus.observer/blast-radius/)

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

### Build with Gemini XPRIZE
**Status:** Submitted | 📄 [Product page →](https://perseus.observer/pr-pilot/)

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](https://modelcontextprotocol.io/) (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)

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

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