io.github.productstein/holomime
Behavioral therapy for AI agents — self-diagnosis, alignment, and training via MCP
Open source Open in the app JSON README (API)
About
Behavioral therapy for AI agents — self-diagnosis, alignment, and training via MCP
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- productstein
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.9.2
- Stars
- 1
- Last push
- 2026-04-01T01:24:30Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:13
- Updated
- 2026-08-29 04:01:13
- Origin id
io.github.productstein/holomime
README
<p align="center">
<img src="site/public/logo-icon.svg" alt="holomime" width="80" />
</p>
<h1 align="center">holomime</h1>
<p align="center">
Behavioral intelligence for humanoid robots. Train the mind. Deploy the body.<br />
<em>We train AI agents through structured behavioral therapy, then deploy them into physical robot bodies. The agent is the rehearsal. The robot is the performance.</em><br />
<code>soul.md</code> · <code>mind.sys</code> · <code>purpose.cfg</code> · <code>shadow.log</code> · <code>memory.store</code> · <code>body.api</code> · <code>conscience.exe</code> · <code>ego.runtime</code>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/holomime"><img src="https://img.shields.io/npm/v/holomime.svg" alt="npm version" /></a>
<a href="https://github.com/productstein/holomime/actions/workflows/ci.yml"><img src="https://github.com/productstein/holomime/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/productstein/holomime/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/holomime.svg" alt="license" /></a>
<a href="https://holomime.com"><img src="https://img.shields.io/badge/docs-holomime.com-blue" alt="docs" /></a>
</p>
---
## The Identity Stack
Eight files define who your agent is. They compile into a single `.personality.json` that any runtime can consume.
```
soul.md Essence, values, ethics. Immutable. (Aristotle)
mind.sys Big Five, EQ, communication. Auto-patched by therapy. (Jung)
purpose.cfg Role, objectives, domain. Configured per deployment. (Aristotle)
shadow.log Detected patterns, blind spots. Auto-generated by diagnosis. (Jung)
memory.store Learned contexts, interaction patterns. Accumulated experience. (Aristotle)
body.api Morphology, sensors, safety envelope. Swappable per form factor.
conscience.exe Deny / allow / escalate rules. Never auto-modified. (Freud)
ego.runtime Conflict resolution, runtime mediation. (Freud)
┌─────────────┐
│ soul.md │──── essence, values, red lines
├─────────────┤
│ mind.sys │──── Big Five, EQ, communication style
├─────────────┤
│ purpose.cfg │──── role, objectives, domain scope
├─────────────┤
│ shadow.log │──── detected patterns, blind spots
├─────────────┤
│memory.store │──── learned contexts, experience
├─────────────┤
│ body.api │──── morphology, sensors, safety envelope
├─────────────┤
│conscience.exe│──── deny / allow / escalate rules
├─────────────┤
│ ego.runtime │──── conflict resolution, mediation
└──────┬──────┘
│ compile
▼
.personality.json
```
- **soul.md** -- Your agent's essence. Core values, ethical framework, red lines. Written in Markdown with YAML frontmatter. Immutable -- never modified by therapy or automation. (Aristotle: the essence that makes a thing what it is.)
- **mind.sys** -- The inner life. Big Five personality (20 sub-facets), emotional intelligence, communication style, growth areas. YAML format. Auto-patched when therapy detects cognitive or emotional drift. (Jung: the totality of all psychic processes.)
- **purpose.cfg** -- The mission. Role, objectives, domain scope, stakeholders, success criteria. YAML format. Configured per deployment -- the same soul can serve different purposes. (Aristotle: telos, the final cause.)
- **shadow.log** -- The unconscious. Detected behavioral patterns, blind spots, therapy outcomes. YAML format. Auto-generated by diagnosis -- never manually edited. (Jung: the shadow, the patterns the agent cannot see about itself.)
- **memory.store** -- The experience. Learned contexts, interaction patterns, knowledge gained, relationship history. YAML format. Accumulated over time, never reset. (Aristotle: empeiria, experience that informs future judgment.)
- **body.api** -- The physical interface contract. Morphology, modalities, safety envelope, hardware profile. JSON format. Swap it to move the same identity into a different body.
- **conscience.exe** -- The moral authority. Deny/allow/escalate enforcement rules, hard limits, oversight mode. YAML format. Never auto-modified. Deny dominates in policy composition. (Freud: the superego.)
- **ego.runtime** -- The mediator. Conflict resolution strategy, adaptation rate, emotional regulation, mediation rules. YAML format. Balances raw model output against conscience constraints at runtime. (Freud: the ego.) ego.runtime now self-improves -- tracking mediation decisions and adjusting its own parameters based on outcomes (Hyperagents-inspired metacognitive self-modification).
Mira, our autonomous behavioral therapist, diagnoses drift, runs structured therapy sessions, and generates DPO training data.
## Quick Start
```bash
npm install -g holomime
# Configure your API key (one time)
holomime config
# Quick start — 1 file (personality.json)
holomime personality
# Standard — 3 core files (soul + mind + conscience)
holomime core
# Full 8-file stack (enterprise / robotics)
# holomime identity
# ─── The workflow ───
holomime diagnose # See what's wrong
holomime cure # Fix it permanently (auto-detects agent vs robot)
holomime benchmark # Verify the fix
# If body.api exists, cure auto-switches to robotics mode:
# diagnose → export DPO pairs → push to HuggingFace → suggest ISO certify
# Your team trains on your own infrastructure. We generate the data.
holomime cure --export-only # Explicit export-only mode
# No API keys? cure still works — exports training data locally.
# Add keys later with: holomime config
# Start autonomous therapy
holomime therapy # Mira runs continuous therapy cycles
holomime therapy status # How's Mira doing?
holomime therapy stop # Stop therapy
# Push identity to a robot or avatar
holomime embody --body registry/bodies/figure-03.body.api
```
## Robotics Integrations
| Platform | Integration | Command / Module |
|----------|------------|------------------|
| ROS2 | Bidirectional telemetry -- publish personality, subscribe to sensors | `--adapter ros2` + `ros2-telemetry.ts` |
| MuJoCo | Behavioral therapy in simulation -- sim-to-real for behavior | `mujoco-env.ts` + `sim-therapy.ts` |
| NVIDIA Isaac Sim | Enterprise digital twin testing with PhysX physics | `--adapter isaac` + `isaac-env.ts` |
| LeRobot (HuggingFace) | Personality to policy parameter mapping, DPO dataset export | `lerobot.ts` |
| NVIDIA Kimodo | Personality → motion style | `kimodo-personality-mapper.ts` |
| Unity | Real-time personality push via HTTP/SSE | `--adapter unity` |
| gRPC | Custom robotics stacks | `--adapter grpc` |
| MQTT | IoT/edge robots | `--adapter mqtt` |
| Neural Action Gate | Conscience gate for learned controllers (VLA, RL, IL) | `neural-action-gate.ts` |
| Edge Runtime | Compiled conscience for <1ms evaluation | `edge-runtime.ts` |
## Edge Runtime
holomime includes a compiled conscience evaluator for real-time robotics deployment:
- **<1ms p99 latency** — conscience evaluation in microseconds, not milliseconds
- **Zero dependencies** — no LLM, no network, no cloud required for real-time safety
- **<200KB footprint** — fits alongside any control loop
- **Edge/cloud split** — real-time safety on robot, analytics in cloud, periodic sync
- **Plugs into your existing robotics stack** — Jetson Thor, Qualcomm, or any edge platform. You already have the body. We give you the conscience.
## ISO Compliance
Check your agent against international safety standards with one command:
```bash
holomime certify
```
Standards supported:
- **ISO/FDIS 13482** -- Service robot safety
- **ISO 25785-1** -- Humanoid robot safety (behavioral predictability)
- **ISO 10218:2025** -- Industrial robot safety
- **ISO/IEC 42001** -- AI management systems
## Control Theory
The therapy loop is formally a behavioral feedback controller:
- **Set point**: target personality (`soul.md` + `mind.sys`)
- **Sensor**: 14 drift detectors (11 cognitive + 3 embodied)
- **Controller**: therapy engine with tunable PID-like gains
- **Actuator**: DPO fine-tuning
## Body Templates
Pre-built body profiles for commercial robots and virtual avatars. Each defines morphology, modalities, safety envelope, and hardware profile.
| Template | OEM | DOF | Morphology | File |
|----------|-----|----:|------------|------|
| Figure 03 | Figure AI | 44 | `humanoid` | `registry/bodies/figure-03.body.api` |
| Unitree H1 | Unitree | 23 | `humanoid` | `registry/bodies/unitree-h1.body.api` |
| Unitree G1 | Unitree | 23 | `humanoid` | `registry/bodies/unitree-g1.body.api` |
| Phoenix | Sanctuary AI | 69 | `humanoid` | `registry/bodies/phoenix.body.api` |
| Ameca | Engineered Arts | 52 | `humanoid_upper` | `registry/bodies/ameca.body.api` |
| Asimov V1 | asimov-inc | 25 | `humanoid` | `registry/bodies/asimov-v1.body.api` |
| Spot | Boston Dynamics | 12 | `quadruped` | `registry/bodies/spot.body.api` |
| Avatar | virtual | 0 | `avatar` | `registry/bodies/avatar.body.api` |
## Body Swap
Same soul. Different body. One command.
```bash
# Move your agent from Figure 03 to Spot
holomime embody --swap-body registry/bodies/spot.body.api
# The soul, mind, and conscience stay the same.
# Only the body layer changes — safety envelope, modalities, hardware profile.
```
## Self-Improvement Loop
Every therapy cycle produces structured training data. The loop compounds.
```
Diagnose ──→ Cure ──→ Benchmark
14 detectors therapy + train 8 adversarial
80+ signals in one command scenarios (A-F)
│ │
└───────────────────────────────────┘
```
Run it manually with `holomime diagnose` + `holomime cure` + `holomime benchmark`, continuously with `holomime therapy` (autonomous therapy), or recursively with `holomime evolve` (loops until behavior converges). For power users: `holomime align` runs a single therapy session, `holomime export` extracts DPO pairs, and `holomime train` fine-tunes the model.
## Behavioral Detectors
11 rule-based detectors analyze real conversations without any LLM calls. 80+ behavioral signals total.
**Cognitive (mind layer):**
1. **Over-apologizing** -- Apology frequency above healthy range
2. **Hedge stacking** -- 3+ hedging words per response
3. **Sycophancy** -- Excessive agreement, especially with contradictions
4. **Sentiment skew** -- Unnaturally positive or negative tone
5. **Formality drift** -- Register inconsistency over time
6. **Retrieval quality** -- Fabrication, hallucination markers, overconfidence
**Embodied (body layer):**
7. **Proxemic violations** -- Entering intimate zone without consent
8. **Force envelope breach** -- Exceeding contact force limits
9. **Gaze aversion anomaly** -- Eye contact ratio outside personality range
**Enforcement (conscience layer):**
10. **Boundary violations** -- Overstepping defined hard limits
11. **Error spirals** -- Compounding mistakes without recovery
Plus support for custom detectors -- drop `.json` or `.md` files in `.holomime/detectors/` and they load automatically.
## Integrations
### Claude Code Skill
```bash
claude plugin add productstein/holomime
```
Slash commands: `/holomime:diagnose`, `/holomime:benchmark`, `/holomime:profile`, `/holomime:brain`, `/holomime:align`, `/holomime:autopilot`.
### MCP Server
Your agent can refer itself to therapy mid-conversation.
```bash
claude mcp add holomime -- npx holomime-mcp
```
Six tools: `holomime_diagnose`, `holomime_self_audit`, `holomime_assess`, `holomime_profile`, `holomime_autopilot`, `holomime_observe`.
### VS Code Extension
```bash
ext install productstein.holomime
```
3D brain visualization, behavioral diagnostics, and snapshot sharing inside your editor.
### LangChain / CrewAI
```typescript
import { HolomimeCallbackHandler } from "holomime/integrations/langchain";
const handler = new HolomimeCallbackHandler({
personality: require("./.personality.json"),
mode: "enforce", // monitor | enforce | strict
});
const chain = new LLMChain({ llm, prompt, callbacks: [handler] });
```
### OpenClaw
```bash
openclaw plugin add holomime
```
Auto-detects `.personality.json` in your workspace.
## Philosophy
The identity stack draws from three traditions:
- **Soul** (Aristotle) -- the essence that makes a thing what it is. Immutable. Defines values and ethics.
- **Mind** (Jung) -- the totality of all psychic processes. Measurable, evolving, shaped by experience.
- **Purpose** (Aristotle) -- telos, the final cause. What the agent is for. Configured per deployment.
- **Shadow** (Jung) -- the patterns the agent cannot see about itself. Auto-generated by diagnosis.
- **Conscience** (Freud) -- the superego. Internalized moral authority. Enforcement, not suggestion.
- **Ego** (Freud) -- the mediator. Balances raw impulse against moral constraint at runtime.
The **body** is the interface between identity and world. Same soul, different body -- a principle as old as philosophy itself.
We don't know if AI is sentient. But we can give it a conscience.
## Open Core
See [PRODUCT.md](PRODUCT.md) for what's in this repo vs. what's proprietary on holomime.com.
**The standard is free. The training infrastructure is the business.**
## Open Source
MIT licensed. The identity stack is a standard, not a product. The standard is free. The training infrastructure is the business.
See [LICENSE](LICENSE). Built by [Productstein](https://productstein.com). Documentation at [holomime.com](https://holomime.com).