affaan-m/ECC · error · Error

read requires exactly one memory ID.

Error message

read requires exactly one memory ID.

What it means

runReadCommand reads a single memory entry by its ID, so it requires exactly one positional argument. It throws 'read requires exactly one memory ID.' when positionals.length !== 1 — zero IDs, or multiple IDs passed at once, both fail. IDs are not accepted via flags here; they must be positionals.

Solutions

1. Pass exactly one memory ID as a single positional: `node scripts/memory.js read <id>`.
2. Quote the ID variable: `memory read "$MEM_ID"` to prevent whitespace splitting; check it is non-empty first.
3. For multiple entries, loop over IDs invoking read once per ID (or use a list/search command if available).
4. Capture the ID from save output (printWrite with --json) instead of hand-copying, to avoid malformed IDs.

Example fix

// before
node scripts/memory.js read mem_001 mem_002
// after
node scripts/memory.js read mem_001
node scripts/memory.js read mem_002

const ids = positionals.filter((p) => typeof p === 'string' && p.trim() !== '');
if (ids.length !== 1) throw new Error('memory read takes exactly one quoted memory ID.');

const isSingleId = (args) => args.length === 1 && typeof args[0] === 'string' && args[0].trim() !== '';

try {
  runReadCommand(args);
} catch (err) {
  if (err.message === 'read requires exactly one memory ID.') {
    console.error('Usage: memory read <id> — one ID per invocation; loop for batches.');
  } else throw err;
}

When it happens

Trigger: Running `memory read` with no ID, with two or more IDs (`memory read id1 id2`), or putting the ID after a flag in a way the parser treats as a positional count mismatch. Raised at the top of runReadCommand.

Common situations: Assuming read accepts a list of IDs (batch reads are unsupported); losing the ID because a variable was empty (`memory read "$MEM_ID"` with unset MEM_ID); pasting an ID containing whitespace so it splits into two positionals.

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

• Agents directory not found
• --all-harnesses and --harness are mutually exclusive.
• all overlays must be readable local files
• all takes must be readable local files
• AMBIGUOUS_PLUGIN_SCOPES

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/6092b93aabf57078. Report an issue: GitHub.

Appendix: source

Thrown at scripts/memory.js:440

    saveMemory(saveInput(options, command === 'handoff' ? 'handoff' : null), { roots }),
    options.json
  );
}

function runSearchCommand({ options, positionals, roots }) {
  const query = positionals.join(' ');
  return printSearch(query, searchMemories(query, {
    roots,
    scopes: options.scopes,
    kinds: options.kinds,
    targetHarness: options.targetHarness,
    limit: options.limit,
  }), options.json);
}

function runReadCommand({ options, positionals, roots }) {
  if (positionals.length !== 1) {
    throw new Error('read requires exactly one memory ID.');
  }
  return printRead(readMemoryById(positionals[0], {
    roots,
    scopes: options.scopes,
  }), options.json);
}

function runDoctorCommand({ command, options, positionals, roots }) {
  requireNoPositionals(positionals, command);
  return printDoctor(doctorMemoryVault({
    roots,
    scopes: options.scopes,
  }), options.json);
}

const COMMAND_HANDLERS = Object.freeze({
  doctor: runDoctorCommand,
  handoff: runWriteCommand,

View on GitHub (pinned to 8321021c54)