Skip to main content
Every Monogram query is answered by one registered project database. Correct output therefore depends on three separate facts: which root owns the query, whether the core index is current, and whether the optional semantic companion is verified for the same corpus policy. Documents the public OpenCLIs release monogram 0.99.5.

​
One project, one database

By default, project databases and the registry live under:
MONOGRAM_HOME=<dir> relocates the core/semantic database estate under <dir>/monogram/. Since 0.98.2 it also relocates sequence sessions under <dir>/problem-definitions/; without the override those sessions remain under the workspace’s .monogram/problem-definitions/. This keeps isolated CI, benchmark, and disposable-worktree patches free of Monogram state while still allowing portable prepared indexes.
stats is the current-query authority: it shows the selected database path, registered root, schema/corpus identity, builder state, failure cache, and optional deep status.

​
Linked-worktree recovery

Version 0.99.5 applies seeded recovery automatically when an ordinary index targets a fresh linked worktree. Monogram first checks the active MONOGRAM_HOME, then a read-only fallback source in the normal user home. Set MONOGRAM_SEED_SOURCE_HOME=<dir> only when that fallback source lives elsewhere. The destination registry and databases always remain inside the active MONOGRAM_HOME. Start with:
Then run the ordinary structural command unless you intentionally need a cold comparison:
MONOGRAM_HOME is always the sole write destination. Automatic recovery may read a validated main corpus from the fallback home, but it never repairs, updates, or relocates that source. Use --no-seed-from-main when a truly cold build is the intended evidence.
Human stats, stats --json, missing-index search --json, and MCP now share the same executable plain-index recovery. JSON places it in next_hint.commands; human output explains whether Monogram can automatically reuse a main corpus or will visibly cold-fall back. Both seed controls belong to index. --seed-from-main remains an explicit compatibility/force spelling, while --no-seed-from-main is the cold opt-out. reindex rejects both because a full rebuild does not reuse a main snapshot. Automatic seed is also disabled for custom extension/add/file-list modes, --no-gc, and an already-owned corpus. Seed copies a consistent corpus, then the content-hash tier re-extracts only changed worktree files.

​
Which database answers?

Monogram resolves the deepest registered ancestor of the current working directory. It searches upward, not downward.
Consequences:
  1. A nested registered project wins while your current directory is inside it.
  2. A query from /repo cannot automatically use a richer database registered at /repo/apps/web.
  3. A miss from the outer root is not proof that a symbol is absent from nested projects.
Monogram prints a descendant-index hint when a more specific registered project may own a miss. Follow it and rerun from that subtree.

​
Inspect the index estate

covered is based on row overlap, not path nesting alone.

​
Incremental index and full rebuild

Despite the shared spelling, the query flag -r is incremental; the standalone reindex command is a full rebuild.

​
Schema-v17 corpus policy

A successful full index records the corpus policy required to reproduce the database:
  • extensions and language selection;
  • workspace expansion;
  • scope and nested-project exclusions;
  • explicit --add roots;
  • Wasm/format participation where applicable;
  • whether the semantic companion is part of the effective policy.
The build writes a durable catch-up marker before mutation, publishes the root/database registry mapping, and reconciles the exact corpus. If a process stops mid-update, the pending marker remains evidence that the two planes may not agree.

​
Extraction contract, not executable version

Monogram stores an extraction-contract epoch separately from the binary’s SemVer. Incremental writes remain valid when a newer or differently labeled binary implements the same corpus contract. If the stored epoch differs, the writer refuses to stamp current provenance and requires a full rebuild.
This gate tracks the shape and meaning of extracted data. A release-number change alone is neither evidence that a rebuild is needed nor permission to reuse an incompatible corpus.

​
Deep policy and fail-closed reads

The normal monogram index . includes the semantic companion. A successful deep build must be rebuilt and verified before the pending marker can clear. If core or semantic reconciliation fails:
  • the command exits non-zero;
  • pending/invalid state remains visible;
  • official deep readers fail closed instead of treating stale semantic data as current.
A deliberate full --no-deep index establishes an own-index-only policy and can clear against that policy. It is not a way to downgrade a previously pending deep recovery through --files-from; selective recovery must honor the stored policy.

​
Index options

Automatic deleted-file GC refuses a suspicious blast radius when both thresholds are crossed: more than 20 candidate rows and more than 50% of the corpus. Inspect with monogram prune --dry-run; override only after proving the registered root is correct.

​
Selective --files-from recovery

monogram index --files-from is the event-carrier path used by watchers and recovery workflows. It replays the stored schema-v17 policy instead of inventing a smaller one.
Input records are exact newline paths. Existing files are force-reread even when mtime/failure caches would normally skip them. Directory records reconcile the exact subtree. Missing paths, symlinks, and special-file witnesses remove stale rows or subtrees. The semantic companion is marked invalid before core mutation. Existing-file events may refresh only those files when the companion is already current. During the paired pass, Monogram can run bounded scoped refresh rounds for content or corpus-membership drift it actually observes. A new or removed source outside the authoritative carrier is not silently accepted: unresolved structural drift keeps the semantic generation invalid and requires a broader index. A missing or stale companion also widens semantic reconciliation to the project root. Any incomplete core or deep pass leaves readers fail-closed. monogram reindex rejects --files-from: a full rebuild owns the entire corpus by definition. NIIA’s dirty-index workflow uses this carrier and can recover a durable catch-up marker left by a stopped run. The watcher subscription and explicit --add roots must intersect; otherwise use an explicit carrier or a full index.

​
Exclusions and explicit scope

Two root-relative surfaces are unioned:
  1. .monogramignore — one directory/prefix per line, with # comments.
  2. .monogram/scope.json — managed by monogram scope.
Both core and deep walkers honor the effective union.
scope exclude changes future policy. scope apply removes already-indexed rows under the excluded prefixes from Monogram’s own databases. It does not delete source, but the database mutation is immediate; preview it first. Hidden entries remain excluded even when --add is used. Use a narrow dependency root such as --add node_modules/@tauri-apps/api, not an entire generated/vendor estate, when you need one external type surface.

​
Workspace behavior

Indexing a member of a Cargo or npm workspace can expand to the workspace root so cross-package edges resolve. Use:
  • --no-workspace when the supplied subtree is intentionally the full corpus;
  • --workspace when expansion is required but auto-detection is ambiguous;
  • --exclude-nested at a large monorepo root when separately registered subprojects should not be duplicated.
Always verify the resulting root with monogram stats rather than inferring it from the command argument.

​
Freshness disclosure

Before investigations, Monogram compares the registered index to the filesystem and reports fresh, stale, or fresh (sampled) for very large corpora. Results are still from the current database snapshot; the banner does not silently refresh them.
Use full when exact checking matters. Use off only when an external controller already owns freshness and the snapshot boundary is explicit.

​
Pruning the current database

Current-database prune removes vanished source rows and stale deleted-file failure-cache entries. It is not bounded by the automatic GC blast-radius refusal, so the preview is important.

​
Registry and database cleanup

Registry mode plans stale, orphan, dangling, and optionally covered database cleanup. It synchronizes a root tombstone before recorded-generation deletion so interrupted cleanup can rediscover residue on retry. Without --force, treat the result as a plan.

​
Reindex generation retention

A crash-safe reindex publishes a new database generation only after validation. Version 0.99.5 retains the bounded retention rule:
The sweep checks recorded root provenance before removal. It does not delete a generation owned by another registered project, and it preserves one recently served generation so an in-flight reader or immediate rollback is not cut off.

​
Prepared-index guard

Set MONOGRAM_PREPARED_INDEX=1 when a benchmark or CI harness must hold an immutable prepared index. It blocks local mutators including:
  • monogram index and monogram reindex;
  • query-time -r refresh;
  • monogram prune;
  • monogram boot init.
Read-only query and MCP surfaces remain available against the prepared snapshot.

​
Claude hook boundary

monogram hook claude is an optional fail-quiet PostToolUse carrier. It updates at most one supported core-index file only when the database is registered, current schema/builder/root policy matches, and the event is well formed. It does not create or migrate databases, run the deep pass, perform GC, or bypass locks/prepared-index guards. If the hook skips an event, use monogram index . --no-workspace --no-deep to reconcile the structural corpus.

​
Shipped hook lifecycle

The public 0.99.5 binary exposes the lifecycle commands directly: The carrier keeps the same guarded single-file core refresh. While a sequence is open, it additionally emits Claude PostToolUse additionalContext reminding the agent to run sequence finish after the final Edit/Write. The reminder is throttled to 300 seconds by default; MONOGRAM_HOOK_REMINDER_SECS overrides that interval. status is read-only; install and remove write the selected Claude settings file.

​
Verification checklist

Keep these proof layers separate:
  1. list --health proves registry/database estate state.
  2. stats --deep proves the database selected for this working directory.
  3. semantic status proves whether deep evidence is current and usable.
  4. verify proves the installed binary’s embedded guide/Book build consistency, not the freshness of a project index.