# psyche-ai

A local MCP server that tracks an agent's mood, relationships and behaviour bias, then feeds that state into later replies.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: Shangri-la-0428
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Shangri-la-0428/oasyce_psyche
- Updated: 2026-04-14
- HTML: https://affpapa.org/en/nevibecode/mcp/psyche-ai

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `PSYCHE_MBTI`, `PSYCHE_NAME`, `PSYCHE_MODE`, `PSYCHE_LOCALE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-ai
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-ai
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md