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

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

uv run soul-crystal-mcp-server

Use SOUL_CRYSTAL_REPO only if you want an explicit local engine:

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

Register In Codex

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:

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

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