ruvnet/ruflo · error · Error

memory path is required

Error message

memory path is required

What it means

Thrown by resolveMemoryPath() in the agenticow MCP tool loader (agenticow-loader.ts:71), the shared entry guard for every agenticow_* tool that touches a memory file (agenticow_branch, agenticow_ingest, agenticow_query, agenticow_diff, agenticow_lineage, agenticow_checkpoint, agenticow_rollback, agenticow_promote, agenticow_speculate). It fires before any path resolution when the user-supplied path is falsy (undefined, null, empty string) or not a string. This prevents the tools from silently operating on an unintended or garbage location.

Solutions

1. Pass a non-empty relative path (resolved against the project cwd, e.g. 'memory/main.rvf') or an absolute path
2. Use the correct parameter name: 'path' for most agenticow_* tools, 'basePath' for agenticow_speculate
3. Check the value for ''/undefined immediately before the tool call and fail with your own clearer message

Example fix

// before
await callTool('agenticow_query', { path: '', vector: [0.1, 0.2] });
// throws: memory path is required

// after
await callTool('agenticow_query', { path: 'memory/main.rvf', vector: [0.1, 0.2] });

function assertMemoryPath(p: unknown): string {
  if (typeof p !== 'string' || p.trim() === '') {
    throw new TypeError('agenticow: path/basePath must be a non-empty string');
  }
  return p;
}
// run before the tool call
assertMemoryPath(args.path ?? args.basePath);

const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;

try {
  await callTool('agenticow_query', args);
} catch (e) {
  if (e instanceof Error && e.message === 'memory path is required') {
    return { error: 'bad_request', detail: 'path must be a non-empty relative or absolute path' };
  }
  throw e;
}

When it happens

Trigger: Calling any agenticow_* tool with path (or basePath for agenticow_speculate) set to an empty string, or calling resolveMemoryPath() programmatically with undefined/null. Note the MCP handlers wrap the value with String(), so a fully omitted path becomes the string 'undefined' and slips past this check — the empty string '' is what triggers it.

Common situations: Form or UI defaults that submit path:''; an optional variable that was never assigned before the tool call; a parameter-name typo — most tools take 'path' but agenticow_speculate takes 'basePath'; spreading an options object that lacks the key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

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

Appendix: source

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

  }
}

/** Reset the module-level load cache. Test-only seam. */
export function __resetAgenticowCache(): void {
  _agenticowMod = null;
  _loadAttempted = false;
}

export function degradedResult(reason: string): { success: true; degraded: true; reason: string } {
  return { success: true, degraded: true, reason };
}

/**
 * Resolve a user-supplied memory path against the project cwd, rejecting path
 * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
 */
export function resolveMemoryPath(path: string): string {
  if (!path || typeof path !== 'string') throw new Error('memory path is required');
  if (/\.\.[\\/]|\0/.test(path)) throw new Error('memory path contains disallowed characters');
  return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
}

/**
 * Lineage manifest companion path. agenticow persists the COW chain
 * (working → checkpoints → base) into `<file>.agenticow.json` next to the
 * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
 * disappear when the AgenticMemory handle closes.
 */
export function manifestFor(file: string): string {
  return `${file}.agenticow.json`;
}

/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
export function validateLabel(label: string): string {
  if (!label || typeof label !== 'string') throw new Error('label is required');
  if (label.length > 256) throw new Error('label exceeds 256 chars');

View on GitHub (pinned to fa13ee4ad6)