affaan-m/ECC · error · Error

Unknown memory frontmatter field in ${sourcePath}.

Error message

Unknown memory frontmatter field in ${sourcePath}.

What it means

Thrown by parseFrontmatterLine() when the key before the ':' is not one of the 13 known serialized keys (schema, id, title, kind, scope, trust, status, source_harness, target_harnesses, tags, links, created_at, updated_at). Unknown keys are rejected rather than ignored to surface typos and schema drift — otherwise a misspelled 'tittle:' would silently drop the title.

Source

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

}

function decodeUtf8(buffer, label = 'text') {
  try {
    return FATAL_UTF8_DECODER.decode(buffer);
  } catch {
    throw new Error(`${label} must contain valid UTF-8 text.`);
  }
}

function parseFrontmatterLine(line, sourcePath, seen) {
  const separator = line.indexOf(':');
  if (separator <= 0) {
    throw new Error(`Invalid memory frontmatter line in ${sourcePath}.`);
  }
  const serializedKey = line.slice(0, separator).trim();
  const objectKey = FRONTMATTER_KEYS.get(serializedKey);
  if (!objectKey) {
    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.`);

View on GitHub (pinned to 01e15490f0)

Solutions

1. Cross-check the offending key against FRONTMATTER_FIELDS in memory-vault-format.js.
2. Use snake_case for serialized keys: source_harness, target_harnesses, created_at, updated_at.
3. Regenerate the document with serializeMemoryDocument() to get the canonical keys.
4. If you intended to extend the schema, that requires changing MEMORY_SCHEMA_VERSION and updating the parser — do not add fields unilaterally.

Example fix

// before
---
sourceHarness: "claude"
createdAt: "2024-08-12T00:00:00.000Z"
---

// after
---
source_harness: "claude"
created_at: "2024-08-12T00:00:00.000Z"
---

const { FRONTMATTER_FIELDS } = require('./scripts/lib/memory-vault-format'); // if exported
const KNOWN = new Set(['schema','id','title','kind','scope','trust','status','source_harness','target_harnesses','tags','links','created_at','updated_at']);
Object.keys(parsed).forEach(k => {
  if (!KNOWN.has(k)) throw new Error(`unknown frontmatter field: ${k}`);
});

const KNOWN = new Set(['schema','id','title','kind','scope','trust','status','source_harness','target_harnesses','tags','links','created_at','updated_at']);
function isKnownFrontmatterKey(key): key is string {
  return KNOWN.has(key);
}

When it happens

Trigger: A memory file with 'author: ...' (no such field), 'title_text: "x"', 'created: "..."' instead of 'created_at:', 'sourceHarness: "x"' using the camelCase object key instead of the snake_case serialized key, or 'source-harness:' with a hyphen instead of underscore.

Common situations: Hand-edited file where the user guessed the field name. AI agent wrote the camelCase key from the JS object instead of the snake_case wire key. Documentation example that used a slightly different field name. Future field added by a newer version that this parser does not know about.

Related errors

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

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