Soul Crystal

Provides a persistent, stateful emotional substrate and function-style access for agents via an MCP server.

python

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "openzeroagent-soul-crystal-mcp": {
      "command": "uv",
      "args": [
        "run",
        "soul-crystal-mcp-server"
      ],
      "env": {
        "SOUL_CRYSTAL_BIN": "/usr/local/bin/soul-crystal",
        "SOUL_CRYSTAL_REPO": "/path/to/soul-crystal",
        "SOUL_CRYSTAL_STATE": "~/.soul-crystal-mcp/crystal_state.bin",
        "SOUL_CRYSTAL_GIT_REF": "main",
        "SOUL_CRYSTAL_GIT_URL": "https://github.com/OpenZeroAgent/soul-crystal.git",
        "SOUL_CRYSTAL_VENDOR_REPO": "~/.soul-crystal-mcp/vendor/soul-crystal",
        "SOUL_CRYSTAL_AUTO_BOOTSTRAP": "1",
        "SOUL_CRYSTAL_CMD_TIMEOUT_SEC": "120",
        "SOUL_CRYSTAL_BUILD_TIMEOUT_SEC": "600",
        "SOUL_CRYSTAL_CLONE_TIMEOUT_SEC": "600"
      }
    }
  }
}

You can run soul-crystal-mcp as an MCP server to access a persistent, emotionally aware state via function-like calls such as pulse, vibe, and emotions. This setup lets your AI tools interact with a dynamic internal reservoir, enabling memory across sessions and richer, stateful behavior rather to stateless exchanges.

How to use

To use the MCP server, start it with your MCP client and then invoke the exposed functions as you would with any compatible tool. The server accepts text through its functions, maintains a persistent internal state, and returns observations about the agent’s current dynamics, such as phase coherence or horizon activity. Use it to remember how you have been feeling, react differently to inputs, or run self-reflection between prompts.

How to install

Prerequisites you need before installing the MCP server:

Python 3.11+
uv

Run the MCP server manually

uv run soul-crystal-mcp-server

Optionally run with a explicit engine repository

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

Available tools

pulse

Send text to the engine and advance the internal state using the pulse function.

diff

Compare current state with a given input and show differences.

tick

Advance the internal state by a specified number of steps.

vibe

Retrieve or influence the current emotional vibe of the agent.

emotions

Query or modify the agent's emotional state.

status

Report the current status of the MCP server and engine.

write_emotion_file

Write the current emotional state to a file.

reset_state

Reset the engine state to a baseline.

bench

Run a performance benchmark against the engine.

engine_info

Return information about the engine version and configuration.

Built by

VeilStrat

AI signals for GTM teams