affaan-m/ECC · error · Error

Memory document ${sourcePath} must start with --- frontmatte

Error message

Memory document ${sourcePath} must start with --- frontmatter.

What it means

Thrown by parseMemoryDocument() when the source does not begin with the opening frontmatter marker '---\n' (or '---\r\n'), or when source is not a string at all. The marker must be the very first bytes of the document — leading whitespace, a BOM, or a shebang will not match. The check uses /^---\r?\n/.

Source

Thrown at scripts/lib/memory-vault-format.js:248

    throw new Error(`Unknown memory frontmatter field in ${sourcePath}.`);
  }
  if (seen.has(objectKey)) {
    throw new Error(`Duplicate memory frontmatter field in ${sourcePath}.`);
  }
  const rawValue = line.slice(separator + 1).trim();
  try {
    return { objectKey, value: JSON.parse(rawValue) };
  } catch {
    throw new Error(`Memory frontmatter field in ${sourcePath} must use a JSON value.`);
  }
}

function parseMemoryDocument(source, sourcePath = '<memory>') {
  const openingMarker = typeof source === 'string'
    ? /^---\r?\n/.exec(source)
    : null;
  if (!openingMarker) {
    throw new Error(`Memory document ${sourcePath} must start with --- frontmatter.`);
  }
  if (Buffer.byteLength(source, 'utf8') > MAX_DOCUMENT_BYTES) {
    throw new Error(`Memory document ${sourcePath} is too large.`);
  }

  const frontmatterStart = openingMarker[0].length;
  const remainder = source.slice(frontmatterStart);
  const closingMarker = /\r?\n---(?=\r?\n|$)/.exec(remainder);
  if (!closingMarker) {
    throw new Error(`Memory document ${sourcePath} has no closing frontmatter marker.`);
  }

  const frontmatterSource = remainder.slice(0, closingMarker.index);
  const parsed = frontmatterSource.split(/\r?\n/).reduce((state, line) => {
    const next = parseFrontmatterLine(line, sourcePath, state.seen);
    return {
      values: { ...state.values, [next.objectKey]: next.value },
      seen: new Set([...state.seen, next.objectKey]),

View on GitHub (pinned to 01e15490f0)

Solutions

1. Confirm the file begins with exactly '---\n' as its first four bytes; use hexdump -C file | head -1.
2. Strip a leading BOM before parsing: source = source.replace(/^\uFEFF/, '').
3. If you called parseMemoryDocument(fs.readFileSync(path,'utf8')) and got this, check that the file is not empty.
4. Use saveMemory() to author files so the opening marker is always correct.

Example fix

// before
// file content:  \uFEFF---\ntitle: "x"\n---\nbody\n
const mem = parseMemoryDocument(source, path);

// after
const mem = parseMemoryDocument(source.replace(/^\uFEFF/, ''), path);

if (typeof source !== 'string' || !/^---\r?\n/.test(source.replace(/^\uFEFF/, ''))) {
  throw new Error('memory document must begin with ---\\n (BOM stripped if present)');
}

When it happens

Trigger: parseMemoryDocument('') on an empty file. parseMemoryDocument('title: x') where the opening marker was stripped. A file that starts with a UTF-8 BOM (\uFEFF). A file edited in Windows that begins with '\r\n---\r\n'. Passing a Buffer instead of a string. Calling parseMemoryDocument on a non-memory .md file.

Common situations: Vault directory got mixed with regular markdown files. Editor inserted a BOM on save. Network transfer that strips the first line. Bug in a wrapper that called .trim() on the source before parsing (removing leading '---' if it was followed by '\n' only at start).

Related errors

• Invalid memory frontmatter line in ${sourcePath}.
• Unknown memory frontmatter field in ${sourcePath}.
• Duplicate memory frontmatter field in ${sourcePath}.
• Memory frontmatter field in ${sourcePath} must use a JSON va
• Memory document ${sourcePath} has no closing frontmatter mar

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/b894bbf2d5fb73c7. Report an issue: GitHub.