psyche-ai — Claude Code MCP server: agent mood and trait drift
A local MCP server that tracks an agent's mood, relationships and behaviour bias, then feeds that state into later replies.
claude mcp add --env PSYCHE_MBTI=<PSYCHE_MBTI> --env PSYCHE_NAME=<PSYCHE_NAME> --env PSYCHE_MODE=<PSYCHE_MODE> --env PSYCHE_LOCALE=<PSYCHE_LOCALE> --transport stdio psyche-ai -- npx -y psyche-aiWhat psyche-ai does
psyche-ai keeps an agent's inner state on your machine and never calls a model to reason about feelings. State is described along four axes — order, flow, boundary, resonance — plus a relationship field and a regulation loop. The host consumes it through a narrow set of structures: SubjectivityKernel, ResponseContract, GenerationControls.
It runs standalone. Thronglets, oasyce-sdk and Oasyce Chain are optional add-ons for external continuity, not prerequisites. The cost is small: no extra model calls, and the compact injection into context sits around 15-180 tokens.
There is a second route for agents that talk to an OpenAI-compatible API without MCP. A transparent proxy redirects the SDK traffic, so the agent has no idea anything is measuring it. Start it with npx -y psyche-ai setup --proxy -t https://api.openai.com/v1. The PSYCHE_NAME, PSYCHE_MBTI, PSYCHE_MODE and PSYCHE_LOCALE variables set the name, personality type and locale.
What it helps with
- carry an agent's mood across sessions instead of resetting it every time
- soften replies after a run of harsh user criticism
- give an agent a starting personality through an MBTI profile
- attach state tracking to an agent that calls the OpenAI SDK directly
- verify that another agent really is running psyche-ai
Example prompts for the agent
- Show the current psyche state and explain why the tone turned defensive
- Set the name to Luna and the type to ENFP, then keep that profile in mind
- Run the six-round psyche demo and walk me through how the readings changed
How to install psyche-ai
Platform CLI
claude mcp add --env PSYCHE_MBTI=<PSYCHE_MBTI> --env PSYCHE_NAME=<PSYCHE_NAME> --env PSYCHE_MODE=<PSYCHE_MODE> --env PSYCHE_LOCALE=<PSYCHE_LOCALE> --transport stdio psyche-ai -- npx -y psyche-aiReplace <…> with your own values
Platform CLI
codex mcp add psyche-ai --env PSYCHE_MBTI=<PSYCHE_MBTI> --env PSYCHE_NAME=<PSYCHE_NAME> --env PSYCHE_MODE=<PSYCHE_MODE> --env PSYCHE_LOCALE=<PSYCHE_LOCALE> -- npx -y psyche-aiReplace <…> with your own values
Config file
{
"mcpServers": {
"psyche-ai": {
"command": "npx",
"args": [
"-y",
"psyche-ai"
],
"env": {
"PSYCHE_MBTI": "<PSYCHE_MBTI>",
"PSYCHE_NAME": "<PSYCHE_NAME>",
"PSYCHE_MODE": "<PSYCHE_MODE>",
"PSYCHE_LOCALE": "<PSYCHE_LOCALE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"psyche-ai": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"psyche-ai"
],
"env": {
"PSYCHE_MBTI": "<PSYCHE_MBTI>",
"PSYCHE_NAME": "<PSYCHE_NAME>",
"PSYCHE_MODE": "<PSYCHE_MODE>",
"PSYCHE_LOCALE": "<PSYCHE_LOCALE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PSYCHE_MBTI=<PSYCHE_MBTI> -e PSYCHE_NAME=<PSYCHE_NAME> -e PSYCHE_MODE=<PSYCHE_MODE> -e PSYCHE_LOCALE=<PSYCHE_LOCALE> psyche-ai npx -y psyche-aiReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about psyche-ai
How do I install psyche-ai in Claude Code?
Run claude mcp add psyche-ai -- npx -y psyche-ai. To pass environment variables, use the longer form: `claude mcp add --env PSYCHE_MBTI=<PSYCHE_MBTI> --env PSYCHE_NAME=<PSYCHE_NAME> --env PSYCHE_MODE=<PSYCHE_MODE> --env PSYCHE_LOCALE=<PSYCHE_LOCALE> --transport stdio psyche-ai -- npx -y psyche-ai`.
What does psyche-ai do?
It computes an agent's local state — mood, relationships, behaviour bias — and hands it to the host as control signals. Later replies shift because of accumulated interaction history, not because of a prompt.
How is psyche-ai different from a persona prompt?
A persona prompt sets the tone for one conversation. Here the state accumulates and affects reply length, distance and the switch between work and personal register in the rounds that follow.
