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() (agenticow-loader.ts:110) when none of the three ways to size a memory file is available: no <file>.agenticow.json lineage manifest exists, the .rvf data file itself does not exist, and the dimension argument is not a positive integer. A fresh agenticow HNSW store cannot be created without knowing its vector dimension, so creation is refused rather than guessed.

Solutions

1. Create the file first with agenticow_ingest and an explicit positive integer dimension matching your embedding model (e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small)
2. Double-check the path spelling — a wrong path is indistinguishable from a new file and triggers this on query
3. Pass dimension as a JSON integer, not a string or float

Example fix

// before: query on a not-yet-created file
await callTool('agenticow_query', { path: 'memory/main.rvf', vector: v });
// throws: dimension is required when creating a new memory file

// after: create with explicit dimension first
await callTool('agenticow_ingest', { path: 'memory/main.rvf', dimension: 384, records: [{ vector: v, text: 'seed' }] });
await callTool('agenticow_query', { path: 'memory/main.rvf', vector: q });

import { existsSync } from 'node:fs';
const dim = 384; // your embedding model's dimension
// safe to omit dimension only when the file already exists
const needsDim = !existsSync(file) && !existsSync(`${file}.agenticow.json`);
if (needsDim && !(Number.isInteger(dim) && dim > 0)) {
  throw new Error('pass a positive integer dimension to create the store');
}

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

try {
  await callTool('agenticow_query', { path, vector });
} catch (e) {
  if (e instanceof Error && e.message.includes('dimension is required')) {
    // wrong path or uninitialized store: create it explicitly first
    await callTool('agenticow_ingest', { path, dimension: 384, records: seed });
    return callTool('agenticow_query', { path, vector });
  }
  throw e;
}

When it happens

Trigger: agenticow_query against a path that was never created — the query tool calls openWithLineage(api, path) with NO dimension, so any mistyped or missing path always looks like a new file and hits this. Also agenticow_ingest on a fresh path with dimension omitted, 0, negative, non-integer (384.5), or passed as a string ('384') — the guard requires typeof number && Number.isInteger && > 0.

Common situations: Querying before the first ingest; a path typo so the tool looks for a file that does not exist; dimension sent as a string through a generic JSON pipeline; assuming the store auto-detects dimension from the first vector when dimension is actually required up front.

Related errors

• label exceeds 256 chars
• label is required
• label may only contain [A-Za-z0-9_.\\-:/@]
• memory path is required
• records must be a non-empty array of

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

Appendix: 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 fa13ee4ad6)