CIGAR: Context Intelligence Graph Agentic Runtime

	Give AI agents the right context—and only the authority they need. CIGAR is an open protocol for deterministic context compilation, bounded agent handoffs, governed effects, and replayable evidence. Visit the CIGAR website Install the Python SDK Read the documentation PyPI Package (hol-cigar) Report an Issue

CIGAR makes the decision environment around an AI agent explicit. It sits between source systems
and an agent or model runtime so applications can govern what context is disclosed, constrain
delegated authority, recover external actions, and reproduce the evidence behind a decision.

CIGAR is model-agnostic and developed by HOL. It is not a model, hosted agent
service, autonomous scheduler, or replacement for an application-specific orchestrator.

[!IMPORTANT]
This repository contains two bounded developer previews. The Python 3.14 SDK is published as
hol-cigar 0.9.1 on PyPI; its import package is
cigar_sdk. The broader CIGAR Honey v0.9 runtime (0.9.0-honey.1) remains an unpublished,
unsupported Apple-silicon preview and is not production-qualified, signed, or notarized. See
current status before evaluating either surface.

Install the Python SDK

python -m pip install "hol-cigar==0.9.1"

The SDK exposes all 45 frozen CIGAR v1 operations through synchronous and asynchronous clients.
It provides typed problems, bounded deadlines, safe retry, resumable streams, pagination, fixed
idempotency keys, and local semantic bundle and delta verification.

Python SDK guide ·
PyPI package ·
Package qualification and limitations ·
Security policy

Start here

For source development, bootstrap validates required tools and generated artifacts. It does not
install software or fetch missing dependencies. Tests are expected to remain hermetic and offline.

cargo xtask bootstrap
cargo xtask test unit

Why CIGAR?

Agent systems routinely assemble context, call tools, hand work to other agents, and retry after
partial failures. Without an explicit runtime contract, those operations are difficult to govern or
reproduce: source text can blur into instruction authority, prompt construction becomes invisible,
tool outcomes are mistaken for certainty, and audit logs omit the context that shaped a decision.

CIGAR makes that decision environment explicit. It sits between source systems and an agent or
model runtime and provides:

• deterministic, provenance-bearing context bundles instead of opaque prompt concatenation;
• policy enforcement before protected content is disclosed;
• recipient-bound handoffs with attenuated authority and typed result merging;
• durable effect intent, authorization, dispatch, reconciliation, and compensation;
• evidence reproduction and no-egress observational replay; and
• content-safe operational signals without storing hidden model reasoning.

What can you evaluate?

How it works

flowchart LR
    S["Filesystem and Git sources"] --> C["Versioned catalog"]
    C --> P["Policy and retrieval plan"]
    P --> B["Deterministic compiler"]
    B --> A["Bundle, manifest, provenance"]
    A --> M["Agent or model consumer"]
    M --> D["Decision and typed result"]
    D --> E["Evidence and replay"]
    X["Context spaces and handoffs"] --> B
    D --> F["Authorized effects and recovery"]
    F --> E

1. Observe sources. Filesystem and Git connectors discover content under explicit source
   identities, exclusions, lifecycle rules, and integrity metadata.
2. Plan under policy. A context contract fixes purpose, principal, projects, consistency,
   trust constraints, token lanes, compiler profile, and catalog watermark.
3. Compile deterministically. CIGAR sorts, deduplicates, filters, budgets, materializes, and
   hashes selected context into an immutable bundle and manifest.
4. Coordinate bounded work. Context spaces preserve immutable bases, private overlays,
   checkpoints, signed handoffs, typed changes, and explicit conflicts.
5. Handle actions as effects. External mutation is separated into intent, authorization,
   dispatch, observation, reconciliation, and compensation. Ambiguous execution remains UNKNOWN.
6. Retain observable evidence. Decisions bind inputs, policy, context, runtime fingerprints,
   outputs, effects, observations, and uncertainty without requesting hidden chain-of-thought.

The public protocol currently defines seven services covering catalog, context, spaces, handoffs,
effects, replay, and operations. See the public API reference for the
operation-level contract.

Honey v0.9 developer preview

Honey is the first bounded CIGAR profile intended for hands-on local evaluation.

Selected scope

• Apple-silicon macOS (aarch64-apple-darwin);
• embedded and local-sidecar deployment modes;
• one local operating-system user with explicit CIGAR agent principals;
• filesystem and Git ingestion;
• a local filesystem reference effect;
• CLI, local daemon, MCP, and Claude Code workflows;
• direct Python and TypeScript packages plus an offline Rust local-registry kit; and
• deterministic workflows that need neither a model provider nor network access.

Explicitly deferred

• Linux, Windows, and Intel macOS release support;
• remote multi-tenancy and shared PostgreSQL/S3 deployment;
• containers, Kubernetes, Homebrew, public npm and crates.io publication, and PyPI publication
  outside the separately bounded hol-cigar SDK profile;
• HTTPS effects, arbitrary extensions, live-provider replay, and remote OTLP;
• vector retrieval in the selected release profile;
• general benchmark or efficacy claims; and
• production support, Apple signing/notarization, long-duration qualification, and GA guarantees.

The repository contains implementation and design work beyond Honey. Code presence does not imply
that a surface is selected, packaged, qualified, published, or supported by this release profile.

Current status

The checked-in product authority currently declares:

The Honey artifact profile defines a closed 13-file candidate inventory with checksum and structural
verification. Final qualification evidence is not complete, so artifact integrity must not be
reported as production qualification.

Machine-readable authorities take precedence over prose:

• packaging/product-version.v1.json — version and publication state;
• packaging/honey/capability-profile.v1.json — selected capabilities and platform;
• packaging/honey/artifact-matrix.v1.json — exact artifact inventory; and
• packaging/honey/release-requirements.v1.json — mandatory gates and prohibited claims.
• packaging/pypi/release-profile.v1.json — the separate
  hol-cigar 0.9.1 PyPI developer-preview identity and bounded qualification gates.

Progress toward the broader CIGAR v1 design is tracked in
IMPLEMENTATION_STATUS.md against prd.md. Those planning
documents do not expand Honey's release claims.

Repository map

Documentation

• Documentation index
• Python SDK package on PyPI
• Python SDK guide
• Core concepts
• Honey installation
• Honey offline quickstart
• Handoffs, effects, and replay
• SDK guides
• Operations
• Troubleshooting
• Release verification
• Artifact-oriented Honey README

Security

Honey's authority, integrity, and traceability controls operate inside a single local-user trust
boundary. They are not process isolation between mutually hostile programs running as that user.
Review Honey security and limitations before using CIGAR
with sensitive material.

Report vulnerabilities through the private process in SECURITY.md. Do not publish
private source, prompts, credentials, handoff capsules, transcripts, or diagnostic archives.

Resources

• HOL
• HOL GitHub organization
• hol-cigar on PyPI
• CIGAR documentation
• GitHub Issues

License

CIGAR is licensed under the terms in LICENSE.