Skip to main content
Monogram is Monolex’s code-intelligence engine. It turns a source tree into ranked locations, exact symbols, call and dependency graphs, cross-boundary coupling evidence, and deep semantic worklists. The goal is not to guess from a function name; it is to move from a symptom to bounded source evidence and then prove the owning path. Public OpenCLIs release: monogram 0.99.5, build 2026-08-27-024306, from clean source commit a39fb0d1cee1f1ecd94fd2f83836336109627371. Run monogram --version to identify the binary you are using. In an agent/non-TTY process, bare monogram prints the compact entry brief; use monogram docs initiate or monogram help --full for the complete embedded reference.

​
Quick start

In 0.99.5 the plain command is the automatic path. A fresh eligible linked worktree tries a validated main corpus from the active home and then the read-only fallback home; if neither is usable, the same command visibly falls back to a cold build. Add --no-seed-from-main only when cold work is the intended evidence. Seed reconciles worktree changes by content hash instead of extracting the whole tree from scratch.
On the exact older 86b33bc63 Monolex worktree, the 0.99.5 debug candidate measured the same fresh isolated command both ways:
This is a reproducible comparison witness, not a universal timing promise; repository size, changed files, storage, and build profile still affect the absolute duration. The installed, signed 0.99.5 release independently completed the plain automatic path against that older worktree in 10.78 seconds and returned a ready 3,564-file, 102,935-identifier worktree-owned corpus.

​
Upgrade and first linked worktree

Upgrade the installed CLI before relying on automatic recovery:
Then close the path in this order:
  1. In the main checkout, run monogram stats. If it has no usable corpus, build one structural receipt with monogram index . --no-workspace --no-deep.
  2. Enter the fresh linked worktree and run monogram stats again.
  3. Run monogram index . --no-workspace --no-deep. Monogram automatically reuses the first exact valid main corpus or visibly cold-falls back.
  4. Require a ready, nonzero worktree-owned corpus from monogram stats before drawing code conclusions.
  5. Only after selecting a semantic audit at a stable source boundary, inspect monogram semantic status and build with monogram index . --no-workspace --deep when needed.
For a brand-new isolated destination, the executable sequence is:
The isolated home remains the only write destination. Monogram may read an exact valid main corpus from the normal user home; set MONOGRAM_SEED_SOURCE_HOME=<dir> only to choose a different read-only source. monogram docs changelog carries the same upgrade order inside the installed artifact. Every investigation result includes executable [NEXT] guidance. A normal path is:

​
Agent entry and embedded docs

The 0.99.5 release retains the survivable agent entry introduced in 0.97.0 and keeps the full command manual available on demand:
The seven topics are audit-guide, changelog, flow-guide, ownership-ffi-guide, sequence, initiate, and skill. Human-readable stats, search, and region output routes through a mutation-aware three-state sequence entry gate:
  • A new recognized task file emits a runnable sequence start task --from <path> hint. Recognized cwd files are TASK.md, PLAN.md, BUG.md, .task.md, and .monobench-task-instruction.md; the historical /tmp Monobench instruction path remains supported.
  • An open current session initially emits one ORDER OPEN (<id>) line naming its connection-points.md path and the required final sequence finish verb, so a compacted agent can re-enter the binding order. Once a checked file in the saved scope has an mtime newer than the UTC session start, the line escalates to edits detected in its scope and the final-close form.
  • A finished session stays silent for the same task digest, while a different task file triggers the entry hint again. A virgin root with no recognized file retains the generic sequence start ... --from <task-or-bug.md> placeholder.
sequence start --from stores the task’s source_path and FNV-1a 64-bit identity source_digest in meta.json. The digest gates duplicate guidance; it is not a cryptographic integrity claim. This release does not add an MCP tool: monogram mcp-schema still reports exactly 50 investigation commands. Successful stats --json, search --json, and region --json payloads now include sequence_hint: it is the same state-aware edge as a string, or null when no edge applies. The MCP server forces those commands through JSON, so MCP clients receive the same field without a second state machine or schema command. The existing sequence tool retains its binding [IAW-SOP] ORDER chain and closing verb sequence finish. start and define expose that ordered contract in human and JSON output; status and resume re-emit the current phase after context loss. Run finish after the last Edit/Write: it re-presents the saved task contract and available Book knowledge, writes finish.json, changes the session phase to finished, and tells the agent to make no later source mutation. In 0.99.5, the installed external initiate.md and current release source are identical, with SHA-256 f218c4ba5038f28a66200573b726c22b78fe8a9691b1c66d3ad3c85c18d2ae12. The installed SKILL also matches source at d89eea41280257126a8f3ea600b58a9adda3d1b074aff3da56c890b35b63d0f0. The complete hook lifecycle is shipped in this release:
The hook preserves unrelated settings and hooks. Its carrier remains a fail-quiet, one-file core-index refresh; it does not build deep semantics, create a database, migrate a schema, or replace an ordinary index refresh. The release also carries forward the Windows-safe ASCII release gate, the synchronized NIIA standalone lock, and the lib-monosession optional SQLite boundary required by the all-CLI release gate. version --json is not a supported form; use monogram --version or monogram version for the executing identity. The 0.99.5 stable pointer and every platform row record clean source commit a39fb0d1cee1f1ecd94fd2f83836336109627371. This removes the previous cross-platform provenance split: the source, tag, five archive rows, and installed Darwin payload now have one reachable main-branch identity. For isolated CI, benchmark, or disposable-worktree runs, set MONOGRAM_HOME=<dir>. Core and semantic databases then live under <dir>/monogram/, while sequence sessions and their finish.json witnesses live under <dir>/problem-definitions/. Without the override, sequence state remains repo-local under .monogram/problem-definitions/. Version 0.98.2 closed the earlier leak where sequence artifacts could enter a benchmark Git patch even though the index databases were already isolated; 0.99.5 retains that isolation and the 0.98.3 per-task provenance inside the isolated session. The override also relocates the destination registry. For an eligible fresh linked worktree, automatic recovery checks that active registry first and then an exact valid main corpus in the normal user home. The fallback registry and database are read-only inputs: every new registry row and corpus write remains inside the isolated destination. A zero-file database is already an owned corpus and therefore stays on the ordinary incremental/cold path.

​
What Monogram owns

​
The evidence boundary

Monogram deliberately separates observation from conclusion:
  • Search and region scores rank likely source locations. They do not prove causality.
  • uncalled reports no inbound edge in the indexed graph. Dynamic, reflective, trait, external, and test callers may be invisible.
  • Deep semantic commands and possibility bands return candidates or complete review worklists. A row is not automatically a defect.
  • coupling --verify-callers reports inbound-edge facts for orphan definitions; public APIs and dynamically invoked handlers still require interpretation.
  • The stable proof loop is context the concrete row, follow it with chain or investigate, inspect the owning boundary, and rerun the same query after a change.

​
Public MCP surface: 50 tools

monogram mcp exposes 50 investigation tools over stdio JSON-RPC. monogram mcp-schema prints the exact wrapper schema used by the server.
The 50-tool surface includes locate, navigation, contract, coupling, quality, deep-semantic, and possibility-band commands. The complete inventory and purpose of every tool is in Monogram Reference. Index and terminal administration are intentionally separate from that 50-tool count. Commands such as index, reindex, prune, scope, docs, verify, hook claude, hook install/remove/status, and mcp manage local state or integration rather than serving as MCP investigation tools. In the sequence family, start, deepen, define, finish, and resume change repo-local session artifacts; only status and list are read-only. boot init also writes configuration. See the mutation boundaries on the companion pages.

​
Supported languages

The core index recognizes 24 language families: The basic index extracts search identifiers, symbols, references, calls, imports, and boundary keys where the language adapter supports them. The deep semantic companion is a separate evidence plane: verify it with monogram semantic status before relying on deep commands.

​
Project-scoped indexes

Each registered project root has its own database. Monogram resolves the deepest indexed ancestor of the current working directory, so your current directory is part of every query.
In a monorepo, cd into the intended indexed subtree before making an absence claim. Learn the registry, workspace expansion, schema-v17 corpus policy, selective recovery, and fail-closed deep-index rules in Scope & Index Management.

​
Installation and release identity

Monogram is distributed through OpenCLIs:
The installed binary, the OpenCLIs registry entry, and a development checkout can be at different versions. Public behavior should be claimed from the installed release and its live mcp-schema; source-only changes are not a shipped feature. The public registry guide includes the ordered sequence flow and relationships to NIIA, Monoflow, Work Wiki, Monograph, the Monogram companion tools, Kernel CLI, and MonoSurf. When command-specific wrapper guidance is useful, run for example OPENCLIS_NEXT=1 openclis monogram search "session reconnect"; the wrapper adds a bounded next step after the native Monogram result.
The live OpenCLIs registry is synchronized with the 0.99.5 source manifest. Its full initiate_md, ai_use, and wrapper_steps SHA-256 values are f218c4ba5038f28a66200573b726c22b78fe8a9691b1c66d3ad3c85c18d2ae12, 1cbaee3de9af2861a2ac285cebbbf35a1e54d7314ce82f3dd999a29a3d096a39, and 8d236a5fcf3b8fdce2d05d395e7b0db1df92e5be52f8f5d90e09a30a81222ed3 respectively. Registry synchronization, installed-artifact behavior, and source proof remain separate validation planes.
The 0.99.5 release has five platform artifacts. Each archive and extracted payload below was downloaded from build 2026-08-27-024306 and verified directly: The OpenCLIs-managed macOS payload reports 0.99.5, passes strict signature verification, exposes 50 MCP schema commands, and verifies 435 embedded Book files plus eight initiate-tree files. The CDN Windows x86_64 payload also ran version and verify successfully on the designated native Windows host. Archive integrity, executable signature, runtime behavior, and source-provenance metadata remain separate proofs even when every row records the same source commit. Intel macOS is not part of the stable five-platform matrix. Check cdn.openclis.com/monogram/latest.json and its referenced meta.json rather than inferring platform support from the Rust source.

​
Relationship to the Monolex tools

​
Keeping results fresh

index --no-deep is the routine structural path. -r remains an explicit incremental override, but it is not a fresh-worktree shortcut and can pay the default deep stage. reindex is a full rebuild. Monogram prints index identity and freshness before queries; do not silently treat stale results as current evidence.
Version 0.99.5 separates executable version from extraction compatibility. A different Monogram crate version may continue incremental writes when the stored corpus contract epoch is unchanged; an old contract epoch refuses the write and routes to a rebuild. This avoids needless full rebuilds while still preventing a new extractor from stamping old structural assumptions as current. Selective --files-from recovery may converge content or membership drift it observes during the paired core/deep pass. It does not silently accept a new or removed source outside the authoritative carrier: unresolved structural drift leaves semantic currentness closed and requires a broader index. After a successful crash-safe reindex, Monogram protects every live registry pointer, keeps the newest previously served generation as a rollback/in-flight-reader margin, and reclaims older superseded generations plus same-root crash orphans.

​
Where next