ruvnet/ruflo · error · Error

memory path is required

Error message

memory path is required

What it means

Thrown by resolveMemoryPath() in agenticow-loader when the `path` argument is falsy, not a string, or empty. resolveMemoryPath is the shared resolver used by the agenticow MCP tools (and the SwarmMemoryBranches service) to resolve a user-supplied memory file path against the project cwd with traversal hardening — it cannot proceed without a path.

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 6b01dc5a68)

Solutions

1. Always supply a non-empty basePath string to agenticow tools (e.g. `.agenticow/memory.rvf`).
2. If a default is desired, set it in your caller before invoking the tool.
3. Validate basePath at your boundary: non-empty string before calling.

Example fix

// before
speculate({ candidates: [...] }); // throws: memory path is required
// after
speculate({ basePath: '.agenticow/memory.rvf', candidates: [...] });

function requireMemoryPath(p: unknown): string {
  if (typeof p !== 'string' || p.length === 0) throw new Error('basePath (memory path) is required');
  return p;
}

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

null

When it happens

Trigger: Calling an agenticow tool without basePath; passing basePath as undefined/null/''; a destructuring bug that dropped the field; calling resolveMemoryPath directly with no argument.

Common situations: Integrator forgot to thread basePath; a fixture with basePath omitted expecting a default (there is no default here, unlike agentbbs); a refactor renamed the field.

Related errors

• label is required
• at least one candidate is required
• roomLabel is required
• roomId is required
• msgType is required

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