affaan-m/ECC · error · Error
read requires exactly one memory ID.
Error message
read requires exactly one memory ID.
What it means
Thrown by runReadCommand in scripts/memory.js when the `read` subcommand does not receive exactly one positional argument (the memory ID). The read operation targets a single memory record, so zero IDs or multiple IDs are both rejected — passing two IDs does not read two memories.
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 01e15490f0)
Solutions
- Pass exactly one memory ID: `node scripts/memory.js read <id>`.
- To find an ID first, run `search` with a query, then `read` the returned ID.
- Quote shell variables (`"$ID"`) so an unset variable produces zero args you can detect, rather than silently shifting positionals.
Example fix
// before node scripts/memory.js read 2024-01-15-meeting 2024-01-16-notes // after node scripts/memory.js read 2024-01-15-meeting
Defensive patterns
Strategy: validation
Validate before calling
function assertSingleId(positionals) {
if (!Array.isArray(positionals) || positionals.length !== 1) {
throw new Error(`read expects exactly one memory ID, got ${positionals ? positionals.length : 0}`);
}
return positionals[0];
} Type guard
function isSingleId(positionals) {
return Array.isArray(positionals) && positionals.length === 1 && typeof positionals[0] === 'string' && positionals[0].length > 0;
} Prevention
- Quote shell variables holding an ID so word-splitting cannot turn one ID into zero or many positionals.
- Use `search` for lookups and reserve `read` for a single known ID.
- In batch tooling, loop over IDs and call read once each rather than passing a list.
When it happens
Trigger: Running `node scripts/memory.js read` with no ID, or `node scripts/memory.js read id1 id2`. The check is `positionals.length !== 1`, so any count other than one triggers it. Positionals are the non-flag trailing arguments after command parsing.
Common situations: Forgetting the ID when building a quick lookup; pasting a space-separated list of IDs expecting batch reads; a shell variable that expands to empty or to multiple words; confusing `read` (single ID) with `search` (free-text query from positionals).
Related errors
- --from is required for handoffs.
- At least one --target is required for handoffs.
- Unknown memory command: ${command}
- Unknown argument: ${arg}
- Unknown argument: ${arg}
AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13).
Data as JSON: /api/errors/6092b93aabf57078.
Report an issue: GitHub.