io.github.productstein/holomime

Install

Config snippet generator goes here (5 client tabs)

README

<p align="center">
  <img src="https://holomime.dev/logo-icon.svg" alt="holomime" width="80" />
</p>

<h1 align="center">holomime</h1>

<p align="center">
  Behavioral alignment for AI agents. From diagnosis to cure.<br />
  <em>Diagnose behavioral drift. Run structured therapy. Export training data. The fix is permanent.</em><br />
  <code>soul.md</code> &middot; <code>psyche.sys</code> &middot; <code>body.api</code> &middot; <code>conscience.exe</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.dev"><img src="https://img.shields.io/badge/docs-holomime.dev-blue" alt="docs" /></a>
</p>

---

## The Identity Stack

Four files define who your agent is. They compile into a single `.personality.json` that any runtime can consume.

```
  soul.md          Values, ethics, purpose. Immutable.
  psyche.sys       Big Five, EQ, communication. Auto-patched by therapy.
  body.api         Morphology, sensors, safety envelope. Swappable per form factor.
  conscience.exe   Deny / allow / escalate rules. Never auto-modified.

        ┌─────────────┐
        │   soul.md    │──── values, red lines, purpose
        ├─────────────┤
        │ psyche.sys   │──── Big Five, EQ, communication style
        ├─────────────┤
        │  body.api    │──── morphology, sensors, safety envelope
        ├─────────────┤
        │conscience.exe│──── deny / allow / escalate rules
        └──────┬──────┘
               │ 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.
- **psyche.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.
- **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.

## Quick Start

```bash
npm install -g holomime

# Initialize the 4-file identity stack
holomime init-stack

# Compile into .personality.json
holomime compile-stack

# Diagnose behavioral drift (no LLM needed)
holomime diagnose --log agent.jsonl

# Benchmark alignment (8 adversarial scenarios, grade A-F)
holomime benchmark --personality .personality.json

# Push identity to a robot or avatar
holomime embody --body registry/bodies/figure-02.body.api
```

## Self-Improvement Loop

Every therapy session produces structured training data. The loop compounds.

```
Diagnose ──→ Therapy ──→ Export DPO ──→ Fine-tune ──→ Evaluate
  11 detectors   dual-LLM     preference     OpenAI /     before/after
  80+ signals    session       pairs        HuggingFace   grade (A-F)
       │                                                      │
       └──────────────────────────────────────────────────────┘
```

Run it manually with `holomime session`, automatically with `holomime autopilot`, or recursively with `holomime evolve` (loops until behavior converges).

## Behavioral Detectors

11 rule-based detectors analyze real conversations without any LLM calls. 80+ behavioral signals total.

**Cognitive (psyche 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.

## Embodiment (Enterprise)

When you're ready for physical AI, the same identity stack powers humanoid robots.

### Body Templates

Pre-built body profiles for commercial robots and v