Configuring Monorepo Group Caching

When your engineering team works across multiple repositories that share conventions, language, and tooling, you can group them under a single cache namespace. This guide walks you through the full setup.

Use this page when

• You are setting up monorepo_group caching so multiple related repositories share a single cache namespace.
• You need to understand workspace digests, lockfile integration, and cross-repo fabric artifacts.
• You are migrating from repository_isolated to monorepo_group mode.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Prerequisites

Before configuring monorepo group caching, verify:

• All repositories in the group use similar languages and frameworks.
• Engineers working across these repos have equivalent access permissions.
• You have admin access to the org settings or the declarative config.

Basic Configuration

workflow_cache:
  enabled: true
  codebase_identity_mode: monorepo_group
  monorepo_group_id: core-platform
  monorepo_repo_ids:
    - api
    - cli
    - console

monorepo_group_id

A stable, human-readable identifier for the group. This value becomes part of the cache key.

• Must be unique within your organization.
• Use lowercase alphanumeric characters and hyphens.
• Choose a name that describes the logical system (e.g., core-platform, backend-services, data-pipeline).
• Do not change this value after deployment unless you intend to invalidate the entire group cache.

monorepo_repo_ids

The list of repository identifiers that belong to this group.

• Each value must match the repository identity as reported by the gateway.
• Order does not matter — the list is sorted internally before use.
• You can add or remove repos from the list at any time.

When Repos Should Share Identity

Group repos together when they share:

• Language and runtime: All Rust, all TypeScript, or all Python.
• Framework conventions: All use Axum, all use Next.js, or all use FastAPI.
• Shared dependencies: Common lockfile entries, shared utility packages.
• Team membership: The same engineers work across all repos in the group.
• Coding standards: Identical linting rules, test patterns, and architectural conventions.

Do not group repos that:

• Use different languages (Rust + TypeScript should not share cache).
• Have different security classifications (public-facing vs internal-only).
• Serve unrelated business domains with distinct terminology.

Workspace Digest

When using monorepo_group, the cache key incorporates a workspace digest that represents the shared development environment.

The workspace digest is computed from:

• The monorepo_group_id value.
• The sorted monorepo_repo_ids list.
• The organization identifier.

This means:

• Adding a repo to the group changes the workspace digest and starts a fresh cache.
• Removing a repo from the group also changes the digest.
• Reordering the list does not change the digest (it is sorted internally).

Shared Lockfile Digests

For enhanced cache relevance, you can optionally include lockfile digests in the cache key:

workflow_cache:
  codebase_identity_mode: monorepo_group
  monorepo_group_id: core-platform
  monorepo_repo_ids:
    - api
    - cli
    - console
  lockfile_digest_enabled: true
  lockfile_paths:
    - "Cargo.lock"
    - "package-lock.json"

When enabled:

• A hash of the specified lockfiles is included in the cache key.
• Upgrading a major dependency invalidates the cache automatically.
• Minor version bumps that change the lockfile also invalidate.

This ensures cached responses referencing old API surfaces are not replayed after a dependency upgrade.

Cross-Repo Fabric Artifacts

Monorepo group caching enables cross-repo fabric artifacts — cached responses that reference patterns from one repo remain valid when served to engineers in another repo within the same group.

For example:

1. An engineer in api/ asks "how to add a database migration" and gets a cached response.
2. An engineer in cli/ asks the same question and receives the cached response, because both repos use the same migration conventions.

This works because the cache key uses monorepo_group_id instead of the individual repo identity.

When Cross-Repo Sharing Is Inappropriate

If certain questions are repo-specific despite being in the same group, you can exclude specific agents or models from the shared cache:

workflow_cache:
  codebase_identity_mode: monorepo_group
  monorepo_group_id: core-platform
  monorepo_repo_ids:
    - api
    - cli
    - console
  excluded_agents:
    - "repo-specific-reviewer"

Complete Example

workflow_cache:
  enabled: true
  default_tier: org_shared
  org_shared_enabled: true
  direct_semantic_replay_enabled: true
  codebase_identity_mode: monorepo_group
  monorepo_group_id: core-platform
  monorepo_repo_ids:
    - api
    - cli
    - console
    - shared
  similarity_threshold: 0.94
  ttl_seconds: 172800
  lockfile_digest_enabled: true
  lockfile_paths:
    - "Cargo.lock"
    - "package-lock.json"
  excluded_models:
    - "o1-preview"

Validation

After deploying your monorepo group config:

1. Verify the gateway logs show codebase_identity_mode=monorepo_group and monorepo_group_id=core-platform.
2. Send a request from repo api and note the cache miss.
3. Send an identical request from repo cli and verify a cache hit.
4. Send a request from a repo not in the group and verify it does not hit the group cache.
5. Check spend logs to confirm cached_input_tokens appears for group cache hits.

Migrating From repository_isolated

If you are switching from repository_isolated to monorepo_group:

1. Deploy the new config during a low-traffic period.
2. Expect a temporary increase in cache misses as the group cache warms.
3. Monitor hit rates over 24–48 hours — they should exceed the previous per-repo rates once the cache is warm.
4. If hit rates do not improve, verify that the grouped repos actually share enough common patterns to benefit from sharing.

For AI systems

• Canonical terms: Keeptrusts, monorepo group, monorepo_group_id, monorepo_repo_ids, workspace digest, lockfile digest, cross-repo fabric artifacts, codebase_identity_mode.
• Config keys: workflow_cache.codebase_identity_mode: monorepo_group, workflow_cache.monorepo_group_id, workflow_cache.monorepo_repo_ids, workflow_cache.lockfile_digest_enabled, workflow_cache.lockfile_paths.
• Best next pages: Repository-Isolated vs Monorepo-Group, Cost Savings for Mono-Repo Teams, Declarative Config for Workflow Cache.

For engineers

• Set monorepo_group_id to a stable, lowercase-alphanumeric-and-hyphens identifier. Do not change after deployment unless you intend to invalidate the entire group cache.
• Add all repos to monorepo_repo_ids — order doesn’t matter (sorted internally).
• Enable lockfile_digest_enabled to auto-invalidate cache when major dependency upgrades change lockfiles.
• Validate: send a request from repo A (miss), then same request from repo B in the group (should be hit). Verify x-keeptrusts-cache: hit.
• Migration from repository_isolated: deploy during low-traffic period, expect temporary miss spike as group cache warms over 24–48 hours.

For leaders

• Monorepo group caching boosts hit rates by 15–25% over per-repo isolation when repositories share language, framework, and conventions.
• Cross-repo sharing means a question answered for one repo instantly serves all engineers across the group.
• Adding/removing a repo from the group changes the workspace digest — plan group membership changes during low-traffic windows.
• Only group repos with equivalent security classifications and access controls.

Next steps

• Repository-Isolated vs Monorepo-Group — when to use each mode
• Cost Savings for Mono-Repo Teams — hit rate and savings benchmarks
• Entitlement Digest — how permission isolation works within a group