Jiminy

A coherence control plane for multi-agent systems: one versioned source of truth for your system's mission and principles (its constitution), served over MCP so every agent can act on the direction in force right now — even when that direction changes mid-flight.

The name is the point: a small conscience the rest of the system consults.

Why

When a multi-agent system's goals change, agents holding a stale copy of the old direction keep producing work for it — and worse, quality checks against the stale copy actively push work back toward the obsolete goal. Jiminy removes the stale copy: direction lives in one versioned store, agents pull the current version at each step boundary, and subscribers are notified the moment it changes.

Quick start

pip install .             # from a clone; CLI: jiminy
jiminy init-db
jiminy set --mission "Ship a lending product people trust" \
           --note "initial constitution"
jiminy current
jiminy serve --transport stdio    # or --transport http

A constitution is a mission (the overarching purpose — the tie-breaker when principles conflict) plus ordered principles. Every change appends a new immutable version with a plain-language change note; nothing is edited in place, so "what was the direction when agent X acted" is always answerable.

The contract

Three operations, over MCP or Python:

• get_constitution — the direction in force now (mission, principles, version).
• get_changes_since(known_version) — the pull an agent makes before a step: the full current direction plus the change notes since the version it last saw. A missed notification is harmless — the next pull is self-describing.
• set_direction(mission?, principles?, change_note) — append the next version. Omitted fields carry forward. On HTTP this requires the bearer token.

Clients may also subscribe to the jiminy://constitution/current resource and receive a standard MCP resources/updated notification on every version bump.

Multiple constitutions

One Jiminy can hold several constitutions side by side — say one per product line or per jurisdiction. Every operation takes an optional constitution name, over MCP and on the CLI (--constitution eu), and defaults to "default", so a single-constitution setup never has to mention it. Each name has its own version sequence: bumping eu to v2 leaves default at whatever version it was. A name you have never written to reads as the same version-0 empty state an untouched store does. The subscribable resource is the default constitution's; agents on another one pull it by name with get_changes_since.

Storage

SQLite out of the box; PostgreSQL for production via JIMINY_DATABASE_URL. Storage is pluggable: hand SqlConstitutionStore your own SQLAlchemy Engine to live inside an existing database, or implement the small store protocol to bring your own persistence entirely. Concurrent writers are safe — versions are serialized by a unique index and a retry, never lost or duplicated.

Reads never fail on an empty store: before any direction is set, consumers get a version-0 empty state, so integrating Jiminy ahead of adopting it costs nothing.

Auth

• stdio: open. A process that can spawn the server already owns the database file under it; a token there would be ceremony, not a boundary.
• HTTP: a shared bearer token (JIMINY_TOKEN) gates every request. The server refuses to start tokenless over HTTP unless you explicitly opt in (JIMINY_ALLOW_INSECURE_HTTP, local experimentation only — it warns).

Testing

python -m pytest -q                      # SQLite, no network
JIMINY_TEST_POSTGRES_URL=postgresql+psycopg://… python -m pytest -q   # + Postgres

Sibling project: Canon tests whether your system's outputs actually cohere with the constitution Jiminy serves.

See CONTRIBUTING.md for style and test expectations.