Repository-Isolated vs Monorepo-Group Identity

The codebase_identity_mode setting determines how the cache groups requests by codebase context. Your choice affects cache hit rates, security boundaries, and cross-repository sharing.

Use this page when

• You are deciding between repository_isolated and monorepo_group identity modes for your cache.
• You need to understand the security, performance, and sharing implications of each mode.
• You are verifying which mode is currently active in your gateway configuration.

Primary audience

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

The Two Modes

repository_isolated (Default)

Each repository gets its own cache namespace. Requests from api/ never share cache entries with requests from console/, even within the same organization.

workflow_cache:
  codebase_identity_mode: repository_isolated

Cache key includes: org_id + repo_identity + entitlement_digest + semantic_hash

monorepo_group

Multiple repositories share a single cache namespace under a named group. Requests from any repo in the group can hit cache entries created by another repo in the same group.

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

Cache key includes: org_id + monorepo_group_id + entitlement_digest + semantic_hash

When to Use repository_isolated

Use repository_isolated when:

• Your repositories have distinct codebases with different languages, frameworks, or conventions.
• Teams working on different repos should not see each other's cached responses.
• You need strict isolation between microservices or independent projects.
• Your organization has compliance requirements that mandate per-repo data boundaries.
• You are unsure which mode to pick — this is the safer default.

Example scenario: A company with separate billing-service (Go), web-app (TypeScript), and ml-pipeline (Python) repos. Code patterns and conventions differ enough that cross-repo cache hits would be irrelevant or misleading.

When to Use monorepo_group

Use monorepo_group when:

• Multiple repos share the same language, framework, and coding conventions.
• Teams frequently work across repo boundaries on the same logical system.
• You want to maximize cache hit rates for similar engineering patterns.
• Your repos are logically part of one product and share dependencies.

Example scenario: A platform team maintains api/, cli/, and shared/ as separate repos but they all use Rust, share the same Cargo workspace patterns, and follow identical conventions. A cache entry from an api/ developer asking "how to add an Axum handler" is equally valid for a cli/ developer asking the same.

Security Implications

repository_isolated

• Cache entries are strictly scoped to one repository.
• No risk of cross-repo information leakage through cache.
• A compromised repo identity cannot access another repo's cached data.

monorepo_group

• All repos in the group share one cache namespace.
• A user with access to any repo in the group can receive cached responses originally generated for another repo in the group.
• You must ensure all repos in the group have equivalent access controls.
• The entitlement digest still enforces permission-level isolation — users with different permissions never share cache even within the same group.

Performance Implications

repository_isolated

• Lower cache hit rates for organizations with many small repos doing similar work.
• Cache warms up independently per repo — new repos start cold.
• No cross-pollination of common patterns.

monorepo_group

• Higher cache hit rates for shared patterns and conventions.
• Cache warms faster because all repos in the group contribute entries.
• Common questions ("how to write a test", "how to add a migration") benefit all group members.
• Larger effective cache pool means better utilization of cache capacity.

Configuration Examples

Single Repo (Default)

workflow_cache:
  enabled: true
  codebase_identity_mode: repository_isolated

No additional fields required. Each repo is automatically identified by its repository identity.

Two Repos Sharing a Group

workflow_cache:
  enabled: true
  codebase_identity_mode: monorepo_group
  monorepo_group_id: backend-services
  monorepo_repo_ids:
    - user-service
    - order-service

Large Monorepo Group

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

Changing Modes

You can switch between modes at any time. When you change:

• isolated → group: Existing per-repo cache entries become inaccessible under the new group key. The group cache starts cold.
• group → isolated: Existing group cache entries become inaccessible. Each repo's cache starts cold.

No data is deleted — entries expire naturally via TTL. The mode change only affects how new cache keys are constructed.

Verifying Your Configuration

After setting the identity mode, confirm it is working:

1. Check gateway logs for codebase_identity_mode=monorepo_group (or repository_isolated) in the startup config dump.
2. Send a request from one repo in the group.
3. Send the same request from another repo in the group.
4. With monorepo_group, the second request should show x-keeptrusts-cache: hit.
5. With repository_isolated, the second request should show x-keeptrusts-cache: miss.

For AI systems

• Canonical terms: Keeptrusts, codebase_identity_mode, repository_isolated, monorepo_group, cache key, cache isolation, cross-repository sharing.
• Config keys: workflow_cache.codebase_identity_mode, workflow_cache.monorepo_group_id, workflow_cache.monorepo_repo_ids.
• Best next pages: Configuring Monorepo Group Caching, Cost Savings for Mono-Repo Teams, Cost Savings for Multi-Repo Teams.

For engineers

• Default is repository_isolated — no additional config needed, each repo gets its own cache namespace.
• Switch to monorepo_group when repos share language, framework, conventions, and team membership.
• Changing modes makes existing entries inaccessible under the new key; they expire via TTL naturally.
• Verify: send same request from two repos in the group. With monorepo_group, second request shows x-keeptrusts-cache: hit; with repository_isolated, it shows miss.
• You can mix modes across your org — some repos isolated, others grouped.

For leaders

• repository_isolated provides maximum security boundaries at the cost of lower cross-repo hit rates.
• monorepo_group boosts hit rates significantly for teams sharing conventions, but requires equivalent access controls across grouped repos.
• No data is deleted when switching modes — entries expire naturally. Mode changes only affect new cache key construction.
• The entitlement digest still enforces permission-level isolation within either mode.

Next steps

• Configuring Monorepo Group Caching — detailed setup for group mode
• Cost Savings for Mono-Repo Teams — expected hit rates and savings
• Cost Savings for Multi-Repo Teams — per-repo isolation economics