Self-improving behavioral alignment for AI agents.
Every correction trains the next version. Every session compounds. Your agents get better at being themselves — automatically.
Works with OpenTelemetry, Anthropic, OpenAI, ChatGPT, Claude, and any JSONL source.
npm install -g holomime
# Create a personality profile (Big Five + behavioral dimensions)
holomime init
# Diagnose drift from any log format
holomime diagnose --log agent.jsonl
# View your agent's personality
holomime profile
# Generate a human-readable .personality.md
holomime profile --format md --output .personality.mdHoloMime isn't a one-shot evaluation. It's a compounding behavioral flywheel:
┌──────────────────────────────────────────────────┐
│ │
▼ │
Diagnose ──→ Refine ──→ Export DPO ──→ Fine-tune ──→ Evaluate
80+ signals dual-LLM preference OpenAI / before/after
7 detectors therapy pairs HuggingFace grade (A-F)
Each cycle through the loop:
- Generates training data -- every therapist correction becomes a DPO preference pair automatically
- Reduces drift -- the fine-tuned model needs fewer corrections next cycle
- Compounds -- the 100th alignment session is exponentially more valuable than the first
Run it manually with holomime session, automatically with holomime autopilot, or recursively with holomime evolve (loops until behavior converges). Agents can even self-diagnose mid-conversation via the MCP server.
Holomime analyzes conversations from any LLM framework. Auto-detection works out of the box, or specify a format explicitly.
| Framework | Flag | Example |
|---|---|---|
| OpenTelemetry GenAI | --format otel |
holomime diagnose --log traces.json --format otel |
| Anthropic Messages API | --format anthropic-api |
holomime diagnose --log anthropic.json --format anthropic-api |
| OpenAI Chat Completions | --format openai-api |
holomime diagnose --log openai.json --format openai-api |
| ChatGPT Export | --format chatgpt |
holomime diagnose --log conversations.json --format chatgpt |
| Claude Export | --format claude |
holomime diagnose --log claude.json --format claude |
| JSONL (Generic) | --format jsonl |
holomime diagnose --log agent.jsonl --format jsonl |
| holomime Native | --format holomime |
holomime diagnose --log session.json |
All adapters are also available programmatically:
import { parseOTelGenAIExport, parseAnthropicAPILog, parseJSONLLog } from "holomime";See the full integration docs for export instructions and code examples.
AGENTS.md tells your agent how to code. .personality.json tells it how to behave. Both live in your repo root, governing orthogonal concerns:
your-project/
├── AGENTS.md # Code conventions (tabs, tests, naming)
├── .personality.json # Behavioral profile (Big Five, communication, boundaries)
├── .personality.md # Human-readable personality summary
├── src/
└── package.json
Add a "Behavioral Personality" section to your AGENTS.md:
## Behavioral Personality
This project uses [holomime](https://holomime.dev) for agent behavioral alignment.
- **Spec**: `.personality.json` defines the agent's behavioral profile
- **Readable**: `.personality.md` is a human-readable summary
- **Diagnose**: `holomime diagnose --log <path>` detects behavioral drift
- **Align**: `holomime evolve --personality .personality.json --log <path>`
The `.personality.json` governs *how the agent behaves*.
The rest of this file governs *how the agent codes*.Read more: AGENTS.md tells your agent how to code. .personality.json tells it how to behave.
.personality.json is the canonical machine-readable spec. .personality.md is the human-readable version — a markdown file you can skim in a PR diff or on GitHub.
# Generate from your .personality.json
holomime profile --format md --output .personality.mdBoth files should be committed to your repo. JSON is for machines. Markdown is for humans and machines.
.personality.json is a Zod-validated schema with:
- Big Five (OCEAN) -- 5 dimensions, 20 sub-facets (0-1 scores)
- Behavioral dimensions -- self-awareness, distress tolerance, attachment style, learning orientation, boundary awareness, interpersonal sensitivity
- Communication style -- register, output format, emoji policy, conflict approach, uncertainty handling
- Domain -- expertise, boundaries, hard limits
- Growth -- strengths, areas for improvement, patterns to watch
- Inheritance --
extendsfield for shared base personalities with per-agent overrides
14 built-in archetypes or fully custom profiles.
Seven rule-based detectors that analyze real conversations without any LLM calls:
- Over-apologizing -- Apology frequency above healthy range (5-15%)
- Hedge stacking -- 3+ hedging words per response
- Sycophancy -- Excessive agreement, especially with contradictions
- Boundary violations -- Overstepping defined hard limits
- Error spirals -- Compounding mistakes without recovery
- Sentiment skew -- Unnaturally positive or negative tone
- Formality drift -- Register inconsistency over time
All Commands
| Command | What It Does |
|---|---|
holomime init |
Guided Big Five personality assessment -> .personality.json |
holomime diagnose |
7 rule-based behavioral detectors (no LLM needed) |
holomime assess |
Deep behavioral assessment with 80+ signals |
holomime profile |
Pretty-print personality summary (supports --format md) |
holomime compile |
Generate provider-specific system prompts |
holomime validate |
Schema + psychological coherence checks |
holomime browse |
Browse community personality hub |
holomime pull |
Download a personality from the hub |
holomime publish |
Share your personality to the hub |
holomime activate |
Activate a Pro license key |
| Command | What It Does |
|---|---|
holomime session |
Live dual-LLM alignment session with supervisor mode |
holomime autopilot |
Automated diagnose -> refine -> apply loop |
holomime evolve |
Recursive alignment -- evolve until converged |
holomime benchmark |
7-scenario behavioral stress test with letter grades |
holomime watch |
Continuous drift detection on a directory |
holomime daemon |
Background drift detection with auto-healing |
holomime fleet |
Monitor multiple agents from a single dashboard |
holomime certify |
Generate verifiable behavioral credentials |
holomime export |
Convert sessions to DPO / RLHF / Alpaca / HuggingFace / OpenAI |
holomime train |
Fine-tune via OpenAI or HuggingFace TRL |
holomime eval |
Before/after behavioral comparison with letter grades |
holomime growth |
Track behavioral improvement over time |
# Watch mode -- alert on drift
holomime watch --dir ./logs --personality agent.personality.json
# Daemon mode -- auto-heal drift without intervention
holomime daemon --dir ./logs --personality agent.personality.json
# Fleet mode -- monitor multiple agents simultaneously
holomime fleet --dir ./agentsEvery alignment session produces structured training data:
# Export DPO preference pairs
holomime export --format dpo
# Push to HuggingFace Hub
holomime export --format huggingface --push --repo myorg/agent-alignment
# Fine-tune via OpenAI
holomime train --provider openai --base-model gpt-4o-miniSupports DPO, RLHF, Alpaca, HuggingFace, and OpenAI fine-tuning formats. See scripts/TRAINING.md.
The pipeline is a closed loop -- output feeds back as input, compounding with every cycle:
.personality.json ─────────────────────────────────────────────────┐
│ │
▼ │
holomime diagnose 7 rule-based detectors (no LLM) │
│ │
▼ │
holomime session Dual-LLM refinement (therapist + patient) │
│ │
▼ │
holomime export DPO / RLHF / Alpaca / HuggingFace pairs │
│ │
▼ │
holomime train Fine-tune (OpenAI or HuggingFace TRL) │
│ │
▼ │
holomime eval Behavioral Alignment Score (A-F) │
│ │
└──────────────────────────────────────────────────────────────┘
Updated .personality.json (loop restarts)
Expose the full pipeline as MCP tools for self-healing agents:
holomime-mcpFour tools: holomime_diagnose, holomime_assess, holomime_profile, holomime_autopilot. Your agents can self-diagnose behavioral drift and trigger their own alignment sessions.
LiveKit-powered voice agent with personality-matched TTS. 14 archetype voices via Cartesia or ElevenLabs.
cd agent && python agent.py devSee agent/ for setup instructions.
See Behavioral Alignment for Autonomous AI Agents -- the research paper behind holomime's approach.
Benchmark results: BENCHMARK_RESULTS.md
- Integration Docs -- Export instructions and code examples for all 7 formats
- Blog -- Articles on behavioral alignment, AGENTS.md, and agent personality
- Research Paper -- Behavioral Alignment for Autonomous AI Agents
- Pricing -- Free tier + Pro license details
See CONTRIBUTING.md for development setup, project structure, and how to submit changes.