JuliusBrussee/caveman · error · Error

cave_memory_provenance_unsupported: only "local" memory is s

Error message

cave_memory_provenance_unsupported: only "local" memory is supported

What it means

The durable memory store in this package implements only local, single-tenant memory, so memory() fails closed at construction when provenance is 'project' or 'external'. Passing anything other than the default 'local' throws rather than waiting until tool-call time, because a shared-backend contract the framework does not provide should be rejected before a model turn is spent discovering it.

Source

Thrown at packages/agent/src/primitives.ts:286

  if (!/^[a-z0-9][a-z0-9_-]{0,95}$/.test(options.namespace)) {
    throw new Error(`caveman agent: invalid memory namespace ${JSON.stringify(options.namespace)}`);
  }
  if (!Number.isSafeInteger(options.recallBudget) || options.recallBudget < 0) {
    throw new Error("caveman agent: memory recallBudget must be a non-negative integer");
  }
  try {
    memoryTTLMilliseconds(options.ttl);
  } catch {
    throw new Error("caveman agent: memory ttl must use positive m, h, or d duration");
  }
  // Fail closed at CONSTRUCTION, not at tool-call time: the durable
  // store implements only local, single-tenant memory. A `project`/`external`
  // provenance or a `project_shared` consent is a shared-backend contract this
  // package does not provide, so it is refused here rather than burning a model
  // turn to discover a config the framework already knew was unsupported.
  const provenance = options.provenance ?? "local";
  if (provenance !== "local") {
    throw new Error("cave_memory_provenance_unsupported: only \"local\" memory is supported");
  }
  const consent = options.consent ?? "local_only";
  if (consent !== "local_only") {
    throw new Error("cave_memory_consent_unsupported: only \"local_only\" consent is supported");
  }
  return Object.freeze({
    kind: "memory",
    namespace: options.namespace,
    provenance,
    ttl: options.ttl,
    recallBudget: options.recallBudget,
    consent,
  });
}

export type ContextKind =
  | "instruction"
  | "user_intent"

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Drop the provenance option (it defaults to 'local') or set it explicitly to 'local'
2. If you need shared/team memory, keep it out of this primitive — back it with your own tool or store until the framework supports it
3. Strip unsupported provenance values when loading config so a stale config key cannot break construction

Example fix

// before
memory({ namespace: 'notes', ttl: '7d', recallBudget: 10, provenance: 'project' });

// after
memory({ namespace: 'notes', ttl: '7d', recallBudget: 10, provenance: 'local' });

const SUPPORTED_PROVENANCE = new Set(['local']);
function checkProvenance(p: unknown): 'local' | undefined {
  if (p === undefined) return undefined;
  if (!SUPPORTED_PROVENANCE.has(p as string)) throw new Error('only provenance "local" is supported by this build');
  return 'local';
}

function isSupportedProvenance(value: unknown): value is 'local' { return value === 'local' || value === undefined; }

try { memory(opts); } catch (e) { if (e instanceof Error && e.message.startsWith('cave_memory_provenance_unsupported')) throw new ConfigError('shared memory provenance is not available; use local', { cause: e }); throw e; }

When it happens

Trigger: Calling memory({ provenance: 'project' }) or memory({ provenance: 'external' }). The option type admits the strings, but the only supported value (and the default when omitted) is 'local'.

Common situations: Copying a memory definition from a spec or another framework that supports project-shared or external provenance; writing config ahead of a feature that does not exist in this version; the type union inviting experimentation with 'project'.

Related errors

• cave_memory_consent_unsupported: only "local_only" consent i
• caveman build: dataResidency is not enforced yet; refusing t
• cave_budget_denomination_unavailable
• cave_claude_reasoning_capability_unknown:${model}
• cave_sandbox_conformance_failed

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/9d90b70f70e14f28. Report an issue: GitHub.