Namespaces

A namespace is the cache isolation boundary in Cachecore. Two requests can only share a cached response if they produce the same namespace hash. Namespaces are derived automatically from your JWT claims and request parameters.

Derivation

A namespace is a SHA-256 hash of five inputs:

namespace = SHA256(tenant_id ‖ policy_version ‖ system_prompt_fp ‖ toolset_fp ‖ permissions)

| Input | Source | Purpose | | :--- | :--- | :--- | | tenant_id | JWT claim | Isolates tenants | | policy_version | JWT claim | Enables rolling cache invalidation | | system_prompt_fp | SHA-256 of system message | Isolates by instruction context | | toolset_fp | SHA-256 of tool definitions | Isolates by function-calling config | | permissions | JWT claim | Isolates by access scope |

The hash is deterministic. Identical inputs always produce the same namespace.

Why namespaces matter

Tenant isolation. Two tenants with different tenant_id values can never share a cache entry, even with identical prompts. The namespace hash differs, so the Redis keys differ.

System prompt isolation. Two projects with different system prompts have different namespaces. A response cached under "You are a legal assistant" is never returned to a request with "You are a customer support agent."

Tool definition isolation. Changing the tool definitions in a function-calling request changes the namespace. Cached responses from a prior tool configuration are not returned.

Policy versioning. Incrementing policy_version in the JWT produces a new namespace. The old cache becomes unreachable. This is a zero-downtime mechanism for global cache invalidation.

Policy-version rollout

Every cache write automatically adds a cc:policy-version dependency with the current policy version. To force a full cache refresh:

curl -X POST https://api.cachecore.it/v1/invalidate \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -d '{"dep_id": "cc:policy-version", "new_hash": "v2"}'

Then issue new JWTs with policy_version: v2. Requests with the new token build a new namespace, and the cache starts fresh. No client code changes required.

Debugging

Enable debug headers on your project to see the first 12 characters of the namespace hash in the X-Cachecore-Namespace-Hint response header. This is useful for verifying that two requests produce the same namespace across environments.

Multi-tenant example

# Tenant A: tenant_id="acme" in JWT
cc_acme = CachecoreClient(
    gateway_url="https://api.cachecore.it",
    tenant_jwt=acme_token,
)

# Tenant B: tenant_id="globex" in JWT
cc_globex = CachecoreClient(
    gateway_url="https://api.cachecore.it",
    tenant_jwt=globex_token,
)

Same prompt, different tenant_id, different namespaces. Tenant A's cached responses are invisible to Tenant B.