ruvnet/ruflo · error · Error

dimension is required when creating a new memory file

Error message

dimension is required when creating a new memory file

What it means

Thrown by openWithLineage() when neither a lineage manifest nor the target `.rvf` file exists AND no integer `dimension` was supplied. Creating a fresh agenticow memory file requires a vector dimension (it sizes the HNSW/base index), so omitting it on a new file is ambiguous. When the file or manifest already exists, dimension is optional because it is read from the existing base.

Source

Thrown at v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts:110

  }
  return label;
}

/**
 * Open (or create) a memory file, restoring its COW chain from the lineage
 * manifest when one exists. When neither the `.rvf` nor the manifest exists,
 * `dimension` is required to create a fresh base.
 */
export async function openWithLineage(api: AgenticowApi, file: string, dimension?: number) {
  const manifest = manifestFor(file);
  if (existsSync(manifest)) {
    return (api.AgenticMemory as any).load(manifest);
  }
  const opts: any = {};
  if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {
    opts.dimension = dimension;
  } else if (!existsSync(file)) {
    throw new Error('dimension is required when creating a new memory file');
  }
  return api.open(file, opts);
}

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Pass an integer dimension when opening a path that may not exist yet: e.g. `dimension: 384` (all-MiniLM-L6-v2) or your model's dim.
2. If you expect the file to exist, ensure the path is correct and the manifest is present alongside the `.rvf`.
3. Validate dimension in your caller: `Number.isInteger(d) && d > 0` before open.

Example fix

// before — new file, no dimension
await openWithLineage(api, '.agenticow/m.rvf'); // throws
// after
await openWithLineage(api, '.agenticow/m.rvf', 384);

function requireDimensionForNewFile(file: string, dim?: number): number {
  if (Number.isInteger(dim) && (dim as number) > 0) return dim as number;
  if (!existsSync(file)) throw new Error('dimension is required to create a new memory file');
  return 0; // existing file — dimension read from base
}

const isPositiveInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v) && v > 0;

null

When it happens

Trigger: First-time open of a new memory path without passing dimension; passing dimension as undefined/0/a non-integer; passing dimension as a string; the manifest file was deleted but the data file was expected to exist.

Common situations: Integrator called open without dimension on a fresh install; a fixture that expects a pre-existing file but runs in a clean tmpdir; a refactor that stopped forwarding dimension.

Related errors

• label is required
• label may only contain [A-Za-z0-9_.\-:/@]
• Invalid embedding model name: ${embeddingModel}
• memory path is required
• at least one candidate is required

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/8c4e647b4edc97fe. Report an issue: GitHub.