Context Intelligence Graph Agentic Runtime
Governed context, bounded agent authority, and replayable evidence for AI agent workflows.
CIGAR is an open protocol developed by HOL.
Local context graphs work without HOL services, an account, API keys, a daemon, or a database.
Use LocalContextGraph from Python's cigar_sdk or npm's @hol-org/cigar/context.
Both packages run a bundled Rust worker locally; their separate CigarClient
APIs connect to a caller-selected CIGAR server.
One local broker can serve independent Python and Node agent processes with host-issued, authenticated source scopes. The host controls evidence admission, reviewer verdicts and execution authority. Per-agent quotas, fair admission, source revision conflicts and expiring tickets bound shared work. Optional SQLite persistence restores admitted context with a fresh authority epoch after restart. Existing graphs, scoped views, source citations, budgets and 0.12 APIs remain.
The development load matrix passes 2,379,985 cycles at 1/5/12 processes; the fault matrix passes 3,879 checks. On the installed comparison host, compile latency is 6.48% lower than 0.12. Three startup costs are accepted exceptions: local API loading adds about 2.36 ms and worker hashing about 0.51 ms versus 0.12; hashing also exceeds the original limit versus alpha. All other compared guardrails pass. These are offline measurements, not a real-model hallucination claim.
Python and npm 0.14.0 are published, and the 24-hour twelve-agent soak passed. The run completed 1,036,800 cycles and 23 forced worker recoveries; independent replay confirmed the result. Node client RSS continued to grow within the 2 GiB aggregate cap; a memory plateau remains unproven. See the complete soak report. Seven-platform installed package checks pass. HUMIDOR adoption and broader Hiero/task evidence remain pending. Public archive readback passed for both registries. See the release notes, full comparison, release checklist, and broker guide.
The broker authenticates loopback clients; it is not an OS sandbox or encrypted multi-host service. A trusted host retains policy and review authority. HUMIDOR continues to own orchestration. Retrieval adapters remain optional: the independent SciFact comparison preserves default behavior and records a stronger flat BM25 control, added latency and precision trade-offs.
0.12 improvements · Local Python quickstart · Local npm quickstart · Why CIGAR? · Get started · How it works · 0.9.4 candidate · Candidate evidence · Release gates · Documentation · Security
Important
The separate runtime profile documented below is CIGAR Honey 0.9.4 candidate (0.9.4). Its Python
development distribution is hol-cigar==0.9.4. This is unsupported evaluation software: it is not
production-qualified, signed, or notarized. See current status and the exact
candidate release gates before evaluating it.
The Python release improves startup, integrity validation and worker cleanup while preserving the existing context ABI, valid canonical IDs and all 69 public Python exports. Compared with published 0.11.0:
| Measure | 0.11.0 | 0.12.0 |
|---|---|---|
| Python local API import, median | 59.06 ms | 6.50 ms (89% lower) |
| Python import plus first graph, median | 109.72 ms | 62.83 ms (43% lower) |
| Worker-hashing Python allocation | 7.29 MB | 1.18 MB (84% lower) |
| Ambiguous mapping keys in semantic integrity data | Could lose entries before hashing | Rejected before conversion |
| Protobuf requirement | Exactly 6.33.5 | Tested range >=6.33.5,<8 |
Worker shutdown now preserves primary errors, handles concurrent cleanup and
rejects inherited graph use after fork(). Package qualification adds Python
branch-coverage gates, API snapshots and dependency evidence derived from actual
installed artifacts. Native wheels work without HOL services or a Rust compiler.
Timings are from one macOS ARM64 host with Python 3.14.7, equal protobuf versions, warm filesystem/bytecode caches and 25 fresh-process samples per startup case. Steady-state compilation was essentially unchanged. Some native benchmark medians increased up to 7.4%, one microsecond-scale p95 increased 26%, and native process RSS increased up to 3.5%; passing the regression thresholds does not mean every metric improved. Offline answer-review outcomes were unchanged and do not establish a real-model hallucination reduction.
See the full comparison, tradeoffs and qualification scope
and Python changelog. The qualified npm 0.12.0 archive
also fixes canonical-CBOR union response decoding, including publishSpace;
its npm registry publication is separate from this Python release.
Use Python 3.14 on a supported native platform:
python3.14 -m pip install --upgrade 'hol-cigar==0.14.0'
python3.14 -m cigar_sdk.local_cli doctor
python3.14 -m cigar_sdk.local_cli demoThe Python guide covers ingestion, exact context budgets, citations, source updates and answer review. A normal wheel install bundles the worker; deliberate workerless source builds require explicit opt-in and a trusted matching worker path.
The npm package name is @hol-org/cigar. hol-cigar is the Python distribution name.
The current npm registry release is 0.14.0 and includes local graphs and the shared broker:
npm install --save-exact @hol-org/cigar@0.14.0Use Node.js >=24.10.0 <25 on macOS ARM64/x64, Linux ARM64/x64 with glibc or musl,
or Windows x64. Save this as
context.mjs and run node context.mjs:
import { LocalContextGraph } from "@hol-org/cigar/context";
const graph = await LocalContextGraph.create("my-project");
try {
await graph.replaceSource("docs/retries.md", [
{id: "retry-policy", source: "docs/retries.md", text: "Retry at most three times."},
]);
const result = await graph.compile({query: "retry", max_tokens: 512, reserve_tokens: 64});
console.log(result.rendered);
} finally {
await graph.close();
}Keep the graph open across requests in your application to reuse its indexes and token cache.
Supply document text yourself; source is a citation locator and does not open a file.
The published 0.11.0 package includes compact prompt citations and answer review. Use its versioned TypeScript guide. The 0.12.0 TypeScript guide describes the separately qualified npm archive, which is not yet the npm registry default.
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.
CIGAR is model-agnostic. It is not a model, hosted agent service, autonomous scheduler, or replacement for an application-specific orchestrator.
| Workflow | What CIGAR demonstrates |
|---|---|
| Governed context compilation | Observe filesystem or Git sources, apply policy and budgets, and produce a stable bundle with a manifest and provenance. |
| Two-agent collaboration | Fork private work, issue a signed and attenuated handoff, accept it once, and merge a typed result against an exact base. |
| Recoverable external actions | Record intent before dispatch, preserve UNKNOWN after ambiguous execution, then reconcile or compensate explicitly. |
| Replay and audit | Reconstruct declared inputs, verify retained evidence, or replay recorded observations without contacting a live provider. |
| Local agent integration | Use the CLI, embedded runtime, local daemon, MCP server, Claude Code adapter, or language SDKs. |
Choose the path that matches what you are trying to do:
| Goal | Start here |
|---|---|
| Create a local context graph from npm | Follow the local npm quickstart; no HOL services are required. |
| Create a local context graph from Python | Install hol-cigar==0.14.0 from PyPI; follow the Python quickstart. |
| Connect to an existing CIGAR server from TypeScript | Use the compatible remote client; inspect the @hol-org/cigar@0.9.4 release assessment for its exact scope and verification evidence. |
| Evaluate the private Honey 0.9.4 candidate | Install Honey, then run the offline context quickstart. |
| Understand the security model first | Read Honey security and limitations. |
| Try agent coordination | Follow the two-agent workflow. |
| Try MCP or Claude Code | Follow the MCP and Claude Code guide. |
| Build or contribute from source | Install the versions in support.toml, then use the commands below. |
cargo xtask bootstrap
cargo xtask test unitbootstrap validates required tools and generated artifacts. It does not install software or fetch
missing dependencies. Tests are expected to remain hermetic and offline.
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
- Observe sources. Filesystem and Git connectors discover content under explicit source identities, exclusions, lifecycle rules, and integrity metadata.
- Plan under policy. A context contract fixes purpose, principal, projects, consistency, trust constraints, token lanes, compiler profile, and catalog watermark.
- Compile deterministically. CIGAR sorts, deduplicates, filters, budgets, materializes, and hashes selected context into an immutable bundle and manifest.
- Coordinate bounded work. Context spaces preserve immutable bases, private overlays, checkpoints, signed handoffs, typed changes, and explicit conflicts.
- Handle actions as effects. External mutation is separated into intent, authorization,
dispatch, observation, reconciliation, and compensation. Ambiguous execution remains
UNKNOWN. - 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.
Version 0.11.0 shipped cigar-context, with
matching Python and TypeScript SDKs. It added a bounded answer-review contract:
current authorized evidence, exact claim/snapshot bindings, independently supplied
trusted verdicts, citation checks, distinct source groups and explicit counterevidence.
Unreviewed or unsupported claims cannot pass merely by reporting high confidence.
The host supplies and evaluates its semantic reviewer; CIGAR does not certify truth.
The measurement plan defines release gates. The answer-quality tools provide explicit factuality, citation, abstention, calibration and efficiency metrics. Synthetic contract tests do not establish live-model hallucination reduction.
Start with python3 scripts/dev.py context. See the
release notes,
Python guide, and TypeScript guide.
The distribution work introduced seven-platform
workers, installed diagnostics, a complete local workflow and agent instructions for
npm/PyPI. The Honey history below retains its original 0.9.4 identity.
Honey is the first bounded CIGAR profile intended for hands-on local evaluation. The private 0.9.4
candidate adds the explicit balanced_v4 profile: risk-aware ranking protects blocking and
effect-adjacent evidence, exact-token packing stops when marginal utility is exhausted, and dense
request-scoped state reduces repeated ranking and compiler work. During qualification, an omitted
profile still selects frozen balanced_v3; balanced_v1 remains selectable for exact 0.9.2 replay.
The candidate remains a developer preview, not a supported service or security certification.
- 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.
- Linux, Windows, and Intel macOS release support;
- remote multi-tenancy and shared PostgreSQL/S3 deployment;
- containers, Kubernetes, Homebrew, crates.io publication, and PyPI publication outside the
separately bounded
hol-cigarSDK profile; public npm remains separately approval-gated by the@hol-org/cigarprofile; - HTTPS effects, arbitrary extensions, live-provider replay, and remote OTLP;
- vector retrieval in the selected release profile;
- generalized model-provider completion or cross-workload performance 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.
The independent Hiero Pentest RC comparison ran five governed workflows with 50 measured trials per workflow and treatment: 250 observations for each of 0.9.2, 0.9.3, and 0.9.4, plus registered warmups. Treatments were release-built from immutable commits, interleaved in randomized blocks, and executed against a recorded provider under network denial.
| Metric | 0.9.2 / balanced_v1 |
0.9.3 / balanced_v3 |
0.9.4 / balanced_v4 |
|---|---|---|---|
| Valid completion and blocking/gold/citation coverage | 100% | 100% | 100% |
| Useful-selection precision | 27.1% | 50.0% | 100% |
| Semantic duplicate rate | 46.1% | 0% | 0% |
| Mean exact selected tokens | 2,251.05 | 1,251.78 | 625.40 |
| Internal CIGAR pipeline p50 | 2.049 ms | 1.852 ms | 0.738 ms |
| Internal CIGAR pipeline p95 | 7.658 ms | 3.268 ms | 1.216 ms |
All 44 evaluated claims passed. Relative to 0.9.3, 0.9.4 used 50.039% fewer exact tokens and reduced mean internal CIGAR pipeline latency by 59.627%; every workflow independently reduced mean tokens by approximately 50%. The separately evaluated 128/512 allocation gate is not inferred from this workflow cohort.
These are deterministic, source-bound measurements—not final installed-artifact, live-model,
security-certification, or universal performance claims. See the
full Hiero three-way report and
0.9.4 candidate release notes. The retained evidence ID is
ae0abda8daa92a00b1c5e1d75b947ee35d9abc75ef7364be0549558ad7b5c1e4.
The checked-in product authority currently declares:
| Property | Value |
|---|---|
| Project | HOL.org alpha project |
| Marketing name | CIGAR Honey 0.9.4 candidate |
| Version | 0.9.4 |
| Python distribution | hol-cigar==0.9.4 (import cigar_sdk) |
| TypeScript npm distribution | @hol-org/cigar@0.9.4 (published developer preview; intended alpha channel) |
| Context ABI | cigar.context.v1 |
| Release state | Alpha / developer-preview |
| Target | aarch64-apple-darwin |
| Publication | Not published |
| Support | Unsupported evaluation software |
| Production qualification | False |
| Signing and notarization | Not included |
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; andpackaging/honey/release-requirements.v1.json— mandatory gates and prohibited claims.packaging/pypi/release-profile.v1.json— the separatehol-cigar0.9.1 PyPI developer-preview identity and bounded qualification gates.packaging/npm/release-profile.v1.json— the separate@hol-org/cigarnpm identity, published canonical bytes, terminal 0.9.4 state, and future staged-publication controls.
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.
The candidate cut uses a scoped, fail-closed distribution gate. It establishes that the exact source and package bytes are internally consistent and installable; it does not establish production readiness or a conclusive efficiency or efficacy claim.
| Gate | Required result before release |
|---|---|
| Frozen source | One clean committed revision and tree, no Git replacement objects, consistent product/Honey authority, generated clients, contracts, and documentation. |
| Regression checks | Python SDK tests, lint, formatting, and strict typing; release-tool regression tests; documentation checks; Rust workspace tests and warnings-denied Clippy. |
| Exact artifacts | The closed 13-file Honey inventory is rebuilt from the frozen commit; every contract and checksum passes; the public verifier returns passed-artifact-integrity. |
| Python package | The hol_cigar-0.9.4 wheel and sdist pass strict metadata checks and clean Python 3.14 installs in the non-admin qualification environment. Imports, the 45-operation surface, shared fixture, and both entry points must pass. |
| TypeScript npm package | @hol-org/cigar@0.9.4 is published and matches the qualified archive byte-for-byte. Exact metadata and archive checks, two-pack reproducibility, strict types, runtime tests, clean packed consumers, live-registry install, and production audit passed. The registry unexpectedly also assigned latest; that tag-policy exception is recorded in the npm release assessment. |
| Publication control | The tag resolves to the frozen commit; GitHub prerelease downloads match the manifest; PyPI uses the protected pypi environment, Trusted Publishing, attestations, and explicit owner approval. A clean post-publication install and published hashes must match. |
Installed-artifact workflow qualification, upgrade and rollback rehearsal, final reproducibility,
long-running fuzz/sanitizer/soak campaigns, signing, and notarization remain separate work. No
candidate package may imply they passed. The public manifest must continue to report
supported=false and production_qualified=false.
| Path | Contents |
|---|---|
crates/ |
Rust protocol, catalog, compiler, policy, space, effects, replay, storage, API, daemon, CLI, MCP, and support crates. |
sdk/ |
Python, TypeScript, Rust, and Go SDK source and contract tests. Go is not selected for Honey packaging. |
adapters/, connectors/ |
Claude Code and source-system integrations. |
spec/, schemas/, proto/ |
Versioned operations, payloads, schemas, and transport contracts. |
conformance/ |
Conformance runners, vectors, and install qualification tools. |
demos/ |
Deterministic Honey context, handoff, effect, replay, and injection-defense scenarios. |
packaging/, scripts/release/ |
Product authority, artifact producers, verifiers, and qualification workflows. |
docs/ |
Guides, API reference, operations, troubleshooting, release verification, and design documentation. |
artifacts/, reports/ |
Implementation and test records; not automatically evidence for a later source revision. |
- Documentation index
- Core concepts
- Honey installation
- Honey offline quickstart
- Handoffs, effects, and replay
- SDK guides
- Operations
- Troubleshooting
- Release verification
@hol-org/cigar0.9.4 npm readiness- Artifact-oriented Honey README
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.
CIGAR is licensed under the terms in LICENSE.