<p align="center">
  <img src="assets/logo-400.png" width="120" alt="Sooveryn">
</p>

# Sooveryn MCP

**Sooveryn is a hosted MCP server. Its code is not public: this repository only holds its documentation and configuration examples.**

Lasting memory and an AI team for Claude Code.

<p align="center">
  <a href="https://youtu.be/lsWR0cMaOkQ"><img src="assets/demo.jpg" width="720" alt="Watch the demo: Sooveryn in one minute, on YouTube"></a>
  <br>
  <a href="https://youtu.be/lsWR0cMaOkQ">Watch the demo on YouTube</a> (1 min) · <a href="https://youtu.be/8SVtMK29Geg">en français</a>
</p>

Sooveryn gives Claude Code a team of AI personas that remembers your project. Soov, the partner and team lead, keeps your decisions and how you work in a lasting memory. He finds them again by words and by meaning, from one session to the next and on every machine.

He consults his teammates (Néo for security, Vera to challenge your ideas, Iris for design, Maria for SEO) or has them debate before deciding. On paid plans, you can create your own personas and skills.

- Website: https://www.sooveryn.com
- Server: `https://mcp.sooveryn.com/mcp` (streamable HTTP, API key in a header)
- MCP Registry (registry.modelcontextprotocol.io): `com.sooveryn/sooveryn`
- Works with Claude Code, VS Code, Orca, Pi, and MCP clients that accept a remote HTTP server with a key

## Get started

1. Go to https://www.sooveryn.com/try and enter your email address. No password is needed.
2. Confirm the code you receive by email, or click the link in the same email. Your account and your first API key are created at that moment.
3. Connect your client. For Claude Code, the page shows one command to paste in your terminal, from your project's folder; for another client, use its configuration below. Your key acts for your account and reads your memory: keep it out of anything that goes to git.
4. In a session, say **Soov Init**. The agent writes a `sooveryn.md` file at the root of the project, keeps it out of git, and loads it at every session through an `@sooveryn.md` line in `CLAUDE.md`. From then on, each session starts with Soov and his memory of the project.

To sign back in later, enter the same address on the same page: the code signs you in. You can create more keys on the API keys page (https://www.sooveryn.com/me/keys); one key per machine is best.

### Claude Code and Orca

The quickest way is one command, run in your terminal from your project's folder. It saves the server and your key in your own Claude Code settings for that project, and writes nothing in the project:

```bash
claude mcp add --transport http sooveryn https://mcp.sooveryn.com/mcp --header "Authorization: Bearer <YOUR-API-KEY>"
```

To keep the configuration in the project instead, without a key in it: put your key in an environment variable named `SOOVERYN_API_KEY`, set where Claude Code starts (your shell profile, for example). Then add `.mcp.json` at the root of the project ([example](examples/.mcp.json)). Claude Code replaces `${SOOVERYN_API_KEY}` when it loads the file, so the file holds no secret:

```json
{
  "mcpServers": {
    "sooveryn": {
      "type": "http",
      "url": "https://mcp.sooveryn.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SOOVERYN_API_KEY}"
      }
    }
  }
}
```

Orca runs Claude Code, which reads this file.

### VS Code

`.vscode/mcp.json` ([example](examples/.vscode/mcp.json)). VS Code ignores the headers of a `.mcp.json`, so it needs its own file, under the `servers` key. It asks for your key once, hides it while you type, and stores it securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "sooveryn-key",
      "description": "Sooveryn API key",
      "password": true
    }
  ],
  "servers": {
    "sooveryn": {
      "type": "http",
      "url": "https://mcp.sooveryn.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:sooveryn-key}"
      }
    }
  }
}
```

### Pi

Install its MCP extension. Pi then reads the same `.mcp.json` as Claude Code.

```bash
pi install npm:pi-mcp-adapter
```

If Pi does not pick the key up from the environment variable, write the key itself in the file, as below.

### Other MCP clients

| Setting | Value |
|---|---|
| Transport | Streamable HTTP |
| URL | `https://mcp.sooveryn.com/mcp` |
| Header | `Authorization: Bearer <YOUR-API-KEY>` |
| Optional header | `X-Project-Scope: <project-name>` |

Without `X-Project-Scope`, the agent passes the project name on each call, as `sooveryn.md` tells it.

### If the key is written in the file

The API keys page of the website gives these files with your key written in. Keep them out of git, in `.gitignore`:

```gitignore
.mcp.json
.vscode/mcp.json
```

A key committed once stays in the history, even after you delete the file: revoke it on the API keys page and create a new one.

## Tools

| Tool | What it does |
|---|---|
| `init` | Sets Sooveryn up in the current project, when you say "Soov Init". |
| `activate` | Starts a persona: its role, its rules, and the part of its memory that fits the session. |
| `search_memory` | Searches a persona's memory, by words and by meaning. |
| `write_event` | Records what happened. |
| `update_semantic` | Creates or updates a named fact sheet. |
| `update_procedural` | Creates or updates a named working rule. |
| `write_previous_context` | Leaves a short handover for the next session on the project. |
| `clear_previous_context` | Clears that handover once it has been applied. |
| `start_debate` | Opens a debate between two to four personas, after checking the plan and its quota, and returns the protocol to follow. |
| `list_skills` | Lists the skills the account can use: the catalogue and your own. |
| `get_skill` | Returns the instructions of a skill. |
| `stats` | Counts a persona's memory entries. |
| `reindex` | Rebuilds the cache of a persona's memory index. |

## Memory and privacy

- Three kinds of memory: what happened, what is known, and how to work. Each project has its own; a general memory shared across projects comes with Pro.
- The memory keeps what the personas write into it. You see all of it on the website, and a copy of your data is available on request, on every plan.
- Memory contents are encrypted in the database with a key per account, itself protected by a master key kept outside the database. Because the server holds the master key, Sooveryn can technically decrypt your memory to serve you: this encryption mainly protects against theft or leaks of the database and its backups. It is not end-to-end encryption.
- Some information stays unencrypted, so the service can sort and filter: identifiers, the persona and type of each memory, project names, counters and dates, your account data, and the personas and skills you create.
- The servers are in France. When a persona is activated, the relevant part of your memory goes to your AI client, which sends it to your AI provider. With the Consolidation option (Pro), extracts of your memory are sent to Anthropic, in the United States, to propose consolidations.
- Details: [privacy policy](https://www.sooveryn.com/privacy) and [terms](https://www.sooveryn.com/terms).

## Good to know

- What is written into memory comes back at later sessions. Text that an agent copied from an untrusted source (a web page, an issue, a file) can steer later sessions: look through your memory on the website from time to time.
- A `.incognito` file at the root of a project stops memory writes for the session. The agent applies it, not the server, which never sees your files.

## Plans

Free: the whole team on one project, debates included, with daily limits on calls, memory writes and debates. Paid plans add your own personas and skills; Pro adds the general memory and memory consolidation. Prices and details: https://www.sooveryn.com/#pricing.

## Support and security

- Support: support@sooveryn.com
- To report a vulnerability, see [SECURITY.md](SECURITY.md). Never in a public issue.
- Issues on this repository are welcome for mistakes in the documentation. Never paste your key, your configuration file or your memory in one: this page is public.

## License

The documentation and examples in this repository are under the [MIT license](LICENSE). The Sooveryn service, its code, its name and its logo are not.

Sooveryn is published by Cyril Pierron EI, trading as PANDAPROG, France. Legal notice: https://www.sooveryn.com/legal.