What causes "Unsupported memory schema." in affaan-m/ECC?

affaan-m/ECC · error · Error

Unsupported memory schema.

Error message

Unsupported memory schema.

What it means

Thrown by normalizeMemory() when memory.schema !== MEMORY_SCHEMA_VERSION ('ecc.memory.v1'). The schema field is the version pin for the on-disk document format; the library does no implicit migration. A mismatched value means the document was written by a different version (future or past) and the parser cannot safely interpret the surrounding fields.

Source

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

  return normalized;
}

function normalizeMemory(memory) {
  if (!memory || typeof memory !== 'object' || Array.isArray(memory)) {
    throw new Error('memory must be an object.');
  }

  const targetHarnesses = uniqueStrings(memory.targetHarnesses, {
    label: 'target harnesses',
    limit: MAX_TARGETS,
    validator: value => validateSlug(value, 'target harness'),
  });
  if (targetHarnesses.length === 0) {
    throw new Error('target harnesses must contain at least one harness or "all".');
  }

  if (memory.schema !== MEMORY_SCHEMA_VERSION) {
    throw new Error('Unsupported memory schema.');
  }

  return {
    schema: memory.schema,
    id: validateMemoryId(memory.id),
    title: asNonEmptyString(memory.title, 'memory title', MAX_TITLE_CHARS),
    kind: validateEnum(memory.kind, MEMORY_KINDS, 'memory kind'),
    scope: validateEnum(memory.scope, MEMORY_SCOPES, 'memory scope'),
    trust: validateEnum(memory.trust, MEMORY_TRUST_STATES, 'memory trust'),
    status: validateEnum(memory.status, MEMORY_STATUSES, 'memory status'),
    sourceHarness: validateSlug(memory.sourceHarness, 'source harness'),
    targetHarnesses,
    tags: uniqueStrings(memory.tags, {
      label: 'tags',
      limit: MAX_TAGS,
      validator: value => validateSlug(value, 'tag'),
    }),
    links: uniqueStrings(memory.links, {

View on GitHub (pinned to 01e15490f0)

Solutions

Always set schema via the exported constant: const { MEMORY_SCHEMA_VERSION } = require('./scripts/lib/memory-vault-format'); then schema: MEMORY_SCHEMA_VERSION.
Use saveMemory() which sets schema: MEMORY_SCHEMA_VERSION for you in normalizeSaveInput.
For documents on disk that legitimately use an older schema, write a one-shot converter that reads them with the old library and re-saves with the current one.
Do not invent a future schema string to 'opt in' to new behaviour — there is no v2.

Example fix

// before
saveMemory({ schema: 'ecc.memory.v2', title: 'x', body: '...' });

// after
const { MEMORY_SCHEMA_VERSION } = require('./scripts/lib/memory-vault-format');
saveMemory({ schema: MEMORY_SCHEMA_VERSION, title: 'x', body: '...' });
// or simply omit schema — saveMemory() fills it in.

Defensive patterns

Strategy: validation

Validate before calling

const { MEMORY_SCHEMA_VERSION } = require('./scripts/lib/memory-vault-format');
if (input.schema && input.schema !== MEMORY_SCHEMA_VERSION) {
  throw new Error(`schema ${input.schema} is unsupported; expected ${MEMORY_SCHEMA_VERSION}`);
}
saveMemory(input); // saveMemory fills schema automatically when omitted

Type guard

import { MEMORY_SCHEMA_VERSION } from './scripts/lib/memory-vault-format';
function isCurrentSchema(value): value is string {
  return value === MEMORY_SCHEMA_VERSION;
}

Prevention

Import MEMORY_SCHEMA_VERSION and use it instead of hard-coding the string.
Omit schema when calling saveMemory() — normalizeSaveInput() sets it for you.
For on-disk files written by an older version, write a one-shot migrator rather than editing schema in place.

When it happens

Trigger: saveMemory({schema: 'ecc.memory.v2', ...}) from a future-proofing attempt. parseMemoryDocument() on a file whose schema line reads 'ecc.memory.v0'. normalizeMemory() called with a hand-built object where schema was set to a typo like 'ecc.memory.V1'. Forwarding documents from a different tool that re-uses the format.

Common situations: Two installed versions of ECC (one writing v1, one expecting v1 but reading a file from a beta that wrote v0). User hand-edited a memory file and 'fixed' the schema string. Migration script that bumped the schema field before updating the parser.

Related errors

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