{"record":{"id":"b894bbf2d5fb73c7","repo":"affaan-m/ECC","slug":"memory-document-sourcepath-must-start-with","errorCode":null,"errorMessage":"Memory document ${sourcePath} must start with --- frontmatter.","messagePattern":"Memory document (.+?) must start with --- frontmatter\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/memory-vault-format.js","lineNumber":248,"sourceCode":"    throw new Error(`Unknown memory frontmatter field in ${sourcePath}.`);\n  }\n  if (seen.has(objectKey)) {\n    throw new Error(`Duplicate memory frontmatter field in ${sourcePath}.`);\n  }\n  const rawValue = line.slice(separator + 1).trim();\n  try {\n    return { objectKey, value: JSON.parse(rawValue) };\n  } catch {\n    throw new Error(`Memory frontmatter field in ${sourcePath} must use a JSON value.`);\n  }\n}\n\nfunction parseMemoryDocument(source, sourcePath = '<memory>') {\n  const openingMarker = typeof source === 'string'\n    ? /^---\\r?\\n/.exec(source)\n    : null;\n  if (!openingMarker) {\n    throw new Error(`Memory document ${sourcePath} must start with --- frontmatter.`);\n  }\n  if (Buffer.byteLength(source, 'utf8') > MAX_DOCUMENT_BYTES) {\n    throw new Error(`Memory document ${sourcePath} is too large.`);\n  }\n\n  const frontmatterStart = openingMarker[0].length;\n  const remainder = source.slice(frontmatterStart);\n  const closingMarker = /\\r?\\n---(?=\\r?\\n|$)/.exec(remainder);\n  if (!closingMarker) {\n    throw new Error(`Memory document ${sourcePath} has no closing frontmatter marker.`);\n  }\n\n  const frontmatterSource = remainder.slice(0, closingMarker.index);\n  const parsed = frontmatterSource.split(/\\r?\\n/).reduce((state, line) => {\n    const next = parseFrontmatterLine(line, sourcePath, state.seen);\n    return {\n      values: { ...state.values, [next.objectKey]: next.value },\n      seen: new Set([...state.seen, next.objectKey]),","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/memory-vault-format.js#L230-L266","documentation":"parseMemoryDocument() requires a memory document to begin with the `---` frontmatter opening marker (for string sources; buffer sources bypass this check). The frontmatter-delimited format is the document's structural contract, so a file missing the opening fence is rejected before any field parsing.","triggerScenarios":"Loading a memory file that starts with blank lines, a BOM, prose/markdown text, a different fence style (e.g. `--- ` with trailing content on the same line, `---\\r` handled ok but `----` not), or a completely empty file; passing a string that was stripped of frontmatter.","commonSituations":"Creating a memory file by hand and forgetting the --- fences; a formatter or linter stripping/altering the leading fence; writing notes without frontmatter into the vault directory and expecting them to load; file begins with a UTF-8 BOM that breaks the ^--- regex match.","solutions":["Start the document with `---` on the very first line, followed by frontmatter and a closing `---`.","Remove any leading blank lines, BOM, or preamble text before the opening fence.","Ensure the fence is exactly three dashes on its own line (no leading spaces, no extra characters).","If the file isn't a memory document, move it out of the memory vault / don't pass it to parseMemoryDocument."],"exampleFix":"// before (missing fences)\nid: \"notes\"\ntitle: \"Deploy notes\"\n\n// after\n---\nid: \"notes\"\ntitle: \"Deploy notes\"\n---\nBody text here.","handlingStrategy":"validation","validationCode":"const src = fs.readFileSync(path, 'utf8').replace(/^\\uFEFF/, '');\nif (!/^---(\\r?\\n|$)/.test(src)) throw new Error(`${path} is missing the opening --- frontmatter fence`);","typeGuard":"const hasFrontmatter = (s) => typeof s === 'string' && /^---\\r?\\n/.test(s.replace(/^\\uFEFF/, ''));","tryCatchPattern":"try {\n  parseMemoryDocument(source, path);\n} catch (err) {\n  if (err.message.includes('must start with --- frontmatter')) {\n    console.error('%s lacks the leading --- fence; add frontmatter or move the file out of the vault.', path);\n  } else throw err;\n}","preventionTips":["Every memory file must begin with `---` as the very first line.","Strip BOMs and leading blank lines when generating files programmatically.","Keep notes and non-memory files out of the memory vault directory."],"tags":["parsing","frontmatter","format"],"backgroundTag":"invalid-argument-format","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}