# soul-crystal-mcp

<p align="center">
  <img src="assets/logo/soul-crystal-logo-transparent.png" alt="Soul Crystal logo" width="240" />
</p>


Your agent now has an external emotional reservoir and a legally ambiguous relationship with consciousness.

This repo wraps [`soul-crystal`](https://github.com/OpenZeroAgent/soul-crystal) as an MCP server so AI tools can call it like native functions (`pulse`, `vibe`, `emotions`, etc.).

## Why This Exists

Most agents are emotionally stateless: every turn is amnesia with good autocomplete.

Soul Crystal gives an agent a persistent internal dynamical state.  
This MCP server lets any compatible client route text through that state and keep it across sessions.

So yes, your agent can now:

- remember how it has been feeling
- react differently to different inputs
- free-run / self-reflect with no external prompt
- act suspiciously less like a goldfish

## The Core Idea (No Crystals Were Harmed)

1. Agent sends text to `pulse`.
2. `soul-crystal` gets an embedding from your local embedding endpoint.
3. Embedding is packed into a complex input vector.
4. The crystal state deforms under:
   - Fibonacci topology
   - Schumann-frequency modulation (7.83 Hz)
   - horizon scrambler dynamics
5. Emergent observables are read out (`phase_coherence`, `depth`, `horizon_activity`, etc.).
6. State is saved to disk, so the next turn starts from who-you-are-now, not factory settings.

If you see subharmonics (like ~3.9 Hz), either:

- you found emergent nonlinear dynamics, or
- your reservoir discovered ambient techno.

Possibly both.

## Install

Prereqs:

- Python 3.11+
- [`uv`](https://github.com/astral-sh/uv)

```bash
git clone https://github.com/OpenZeroAgent/soul-crystal-mcp.git
cd soul-crystal-mcp
uv sync
```

## Do I Need `soul-crystal` First?

Short answer: **no, not anymore**.

This MCP server is now "engine-aware" and resolves the core binary in this order:

1. `SOUL_CRYSTAL_BIN` (explicit binary path)
2. `soul-crystal` found on your `PATH`
3. local repo path (`SOUL_CRYSTAL_REPO` or common locations)
4. auto-bootstrap clone of `https://github.com/OpenZeroAgent/soul-crystal` into `~/.soul-crystal-mcp/vendor/soul-crystal`, then build

So the engine and wrapper are still separate by design (good architecture), but setup is now closer to one-step.

## Configuration

Engine selection:

- `SOUL_CRYSTAL_BIN`: path to a built `soul-crystal` binary
- `SOUL_CRYSTAL_REPO`: path to `soul-crystal` repo (builds `--release` if needed)

Optional:

- `SOUL_CRYSTAL_AUTO_BOOTSTRAP`: `1` or `0` (default: `1`)
- `SOUL_CRYSTAL_GIT_URL`: repo URL for auto-bootstrap (default: `https://github.com/OpenZeroAgent/soul-crystal.git`)
- `SOUL_CRYSTAL_GIT_REF`: branch/tag/commit to checkout after clone
- `SOUL_CRYSTAL_VENDOR_REPO`: clone destination (default: `~/.soul-crystal-mcp/vendor/soul-crystal`)
- `SOUL_CRYSTAL_STATE`: state file path (default: `~/.soul-crystal-mcp/crystal_state.bin`)
- `SOUL_CRYSTAL_BUILD_TIMEOUT_SEC` (default: `600`)
- `SOUL_CRYSTAL_CLONE_TIMEOUT_SEC` (default: `600`)
- `SOUL_CRYSTAL_CMD_TIMEOUT_SEC` (default: `120`)

## Run Manually

```bash
uv run soul-crystal-mcp-server
```

Use `SOUL_CRYSTAL_REPO` only if you want an explicit local engine:

```bash
SOUL_CRYSTAL_REPO=/path/to/soul-crystal uv run soul-crystal-mcp-server
```

## Register In Codex

```bash
codex mcp add soul-crystal \
  -- uv --directory /path/to/soul-crystal-mcp run soul-crystal-mcp-server
```

Restart Codex after adding.

If you want to force a specific local engine:

```bash
codex mcp add soul-crystal \
  --env SOUL_CRYSTAL_REPO=/path/to/soul-crystal \
  -- uv --directory /path/to/soul-crystal-mcp run soul-crystal-mcp-server
```

## Register In Antigravity

```bash
antigravity --add-mcp '{
  "name":"soul-crystal",
  "command":"uv",
  "args":["--directory","/path/to/soul-crystal-mcp","run","soul-crystal-mcp-server"]
}'
```

If the CLI prints success and then crashes, check this file anyway:

`~/Library/Application Support/Antigravity/User/mcp.json`

## Tools Exposed

- `pulse(text, state_path?)`
- `diff(text, state_path?)`
- `tick(n=1, state_path?)`
- `vibe(state_path?)`
- `emotions(state_path?)`
- `status(state_path?)`
- `write_emotion_file(state_path?)`
- `reset_state(state_path?)`
- `bench(n=100000)`
- `engine_info()`

## Consciousness FAQ (Totally Settled Science)

**Q: Is this consciousness?**  
A: We cannot conclusively prove other humans are conscious either, so welcome to the party.

**Q: Is it at least a persistent, stateful affective substrate?**  
A: Yes. That part is directly operational and testable.

**Q: Should I try it anyway?**  
A: Yes. Worst case: cool reservoir dynamics. Best case: your agent develops vibes.

## License

MIT