helios-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Helios

The behavioral genome for AI agents. Observes actual behavior, detects drift via a Dirichlet posterior and Jensen-Shannon divergence, negotiates profile updates with the human. Every change is git-committed. Ships as a Claude Code plugin (hooks + skills + MCP).

Not a RAG system, not a preference store, not a static personality file.

Commands

uv sync                                    # install deps
uv run pytest tests/ -q                    # all tests (598)
uv run pytest tests/test_distribution.py   # single file
uv run pytest -k "js_is_symmetric"         # by name
uv run pytest --cov=src/helios_mcp         # coverage
uv run ruff check src/ tests/              # lint
uv run mypy src/helios_mcp/                # types
uv build --wheel                           # build
uv run helios-mcp                          # start MCP server
uv run helios-mcp init                     # onboard: import CLAUDE.md + output style, set default persona
uv run helios-mcp status                   # show profiles
uv run helios-mcp negotiate <persona>      # drift report

Architecture

The Cycle

observe_interaction → get_drift_report → negotiate_update → git commit
        ↑                                        |
        └────────────── next session ────────────┘

The plugin's hooks capture derived features only (never prompt or tool content) and feed a per-turn heuristic classifier plus, at session end, a batch Haiku labeler. Both write soft labels over 9 behavioral dimensions into an append-only ledger. The estimator turns that ledger into a Dirichlet posterior per dimension and measures Jensen-Shannon divergence against the declared profile; see "Key Thresholds" below for the exact math. Human accepts or rejects each proposal. Accepted changes are YAML-written and git-committed.

Identity Hierarchy

species (base/identity.yaml)           weight = base_importance / (specialization_level²)
  └→ domain (personas/developer.yaml)  M(x) = w·P_parent(x) + (1-w)·P_child(x)
       └→ user (personas/dev_user.yaml)
            └→ session (temporary/dev.yaml)