HestAI-MCP

Governance and session management layer of the HestAI ecosystem — pre-release, B1 Foundation phase

Overview

HestAI-MCP is the governance and session management layer of the HestAI ecosystem — a five-system stack for AI-assisted software development. It is currently pre-release at B1 (Foundation phase): functional and in daily use, but still discovering its full scope.

Its role in the ecosystem: knows WHO agents are and HOW they should behave — provider-agnostic. It does not spawn CLIs or know which model runs underneath; that is the workbench's job.

What it does today:

• Injects system governance (.hestai-sys/) into projects at runtime — agent constitutions, skills, rules — without copy-pasting between projects
• Tracks sessions (clock_in/clock_out) and archives transcripts in OCTAVE format
• Bootstraps agent binding (bind)
• Posts structured review comments to GitHub PRs (submit_review)

What it's building toward: persistent memory across sessions (the context feedback loop requires context_update, planned Phase 4), Orchestra Map dependency tracking (ADR-0034 MVP validated, automation not yet built), and document routing (document_submit, Phase 4).

Where it fits: built on octave-mcp (document format foundation), works alongside odyssean-anchor-mcp (identity binding ceremony, merger planned), debate-hall-mcp (structured deliberation), and hestai-workbench (execution/UI layer).

Architecture

YOUR PROJECT (using HestAI)
├── .hestai-sys/              # TIER 1: SYSTEM (read-only, injected by MCP at runtime, gitignored)
│   ├── CONSTITUTION.md       # Immutable laws
│   ├── governance/           # Rules, North Stars
│   ├── library/
│   │   ├── agents/           # Agent definitions
│   │   ├── skills/           # Capability definitions
│   │   └── patterns/         # Reusable solution patterns
│   └── templates/            # Document templates
│
├── .hestai/                  # TIER 2: PROJECT GOVERNANCE (committed, PR-controlled)
│   ├── north-star/           # Project North Star
│   ├── decisions/            # Architectural Decision Records
│   ├── rules/                # Project-wide standards
│   └── state/ → .hestai-state/  # TIER 3: WORKING STATE (symlink, gitignored)
│       ├── context/          # Living context files (generated by clock_in)
│       ├── sessions/
│       │   ├── active/       # Current sessions
│       │   └── archive/      # Completed sessions (OCTAVE compressed)
│       └── reports/          # Generated reports
│
├── docs/                     # Developer documentation (ADRs, guides)
└── src/                      # Your code

Note for AI Agents: Even though .hestai-sys/ is gitignored, you can still read it! Use:

• Read .hestai-sys/README.md - Start here for governance overview
• Glob .hestai-sys/**/*.md - Discover all governance files

Key Principle: Single Writer

All .hestai/state/ writes go through MCP tools. No direct file creation.

Agent → MCP Tool (clock_in/clock_out/bind) → System Steward → Files

This prevents:

• Multi-agent conflicts
• Governance drift
• Inconsistent documentation

The Three Tiers

Tier	Location	Git	Mutability
1: System Governance	.hestai-sys/	Gitignored	Read-only (MCP-injected at runtime)
2: Project Governance	.hestai/north-star/, .hestai/decisions/	Committed	Human via PR
3: Working State	.hestai/state/ (symlinked)	Gitignored	Via MCP tools (clock_in/clock_out)

For detailed architecture, see docs/ARCHITECTURE.md.

MCP Tools

Tool	Purpose	Status
clock_in	Start session, create session dir, return context paths	Implemented
clock_out	End session, compress transcript to OCTAVE, archive	Implemented
bind	Lightweight agent binding bootstrap	Implemented
submit_review	Post structured review comments to GitHub PRs	Implemented
document_submit	Route docs to correct location	Planned (Phase 4)
context_update	Update context with conflict resolution	Planned (Phase 4)

Documentation Format

When to use OCTAVE (.oct.md)

• Agent constitutions
• Governance rules
• North Stars
• Context files (PROJECT-CONTEXT, etc)
• Session archives

When to use Markdown (.md)

• Developer guides
• ADRs
• READMEs
• Setup instructions

Decision: Primary audience AI agents? → .oct.md. Human developers? → .md

Quick Start

# Clone and install (uv recommended)
git clone https://github.com/elevanaltd/HestAI-MCP.git
cd hestai-mcp
uv sync --all-extras

# Run tests
.venv/bin/python -m pytest

# Check quality
.venv/bin/python -m ruff check src tests scripts && .venv/bin/python -m mypy src && .venv/bin/python -m black --check src tests scripts

MCP Configuration

Default behavior (simplest): .hestai-sys is created in the current working directory where the server runs:

{
  "mcpServers": {
    "hestai": {
      "command": "python",
      "args": ["-m", "hestai_mcp.mcp.server"]
    }
  }
}

Optional override: Control location via HESTAI_PROJECT_ROOT env var:

# .env file (optional - only if you want a custom location)
HESTAI_PROJECT_ROOT=/path/to/shared/location

Opt-in: Governance injection only runs if the project has a .hestai/ directory or HESTAI_GOVERNANCE_ENABLED=true in .env. New projects must opt in explicitly.

Design: Follows the debate-hall pattern - creates governance in CWD by default, just like ./debates/. Each project/worktree gets its own .hestai-sys unless explicitly configured otherwise.

Governance Rules

Documentation placement is governed by rules injected to .hestai-sys/governance/rules/ (source: src/hestai_mcp/_bundled_hub/governance/rules/):

Rule	Document	Purpose
Visibility	visibility-rules.oct.md	Where docs belong (product placement)
Hub Authoring	hub-authoring-rules.oct.md	What goes in system governance (.hestai-sys/)
Naming	naming-standard.oct.md	How to name files
Format	In visibility-rules	When to use OCTAVE vs Markdown

Development Status

• ✅ Phase 0-2: Foundation, porting, MCP server
• ✅ Phase 2.5: Hub architecture, bundled governance
• ✅ Odyssean Anchor: Agent identity binding (ADR-0036)
• ✅ Clock tools: Session lifecycle with AI synthesis
• ✅ Submit review: GitHub PR review comment tool
• 🚧 Phase 3: Single writer tools (document_submit, context_update)
• 🚧 Phase 5: Fractal refactor and modularization (ADR-0184)

Related

• docs/ARCHITECTURE.md - Detailed architecture

License

Apache License 2.0 - see LICENSE for details.

"Odyssean Anchor" is a registered trademark of Shaun Buswell - see docs/trademarks.md for usage guidelines.