Top-level entity parameters [${invalidKeys.join(", ")}] are

Error message

Top-level entity parameters [${invalidKeys.join(", ")}] are not supported in ${methodName}(). Use filters: { userId: "..." } instead.

What it means

Thrown by Memory's parameter validation when a caller passes entity identifiers (user_id/agent_id/run_id in snake_case or camelCase) as top-level keys of the options object instead of nested under filters. The OSS TS SDK requires scoping entities via filters: { userId: '...' } so it rejects the flatter Python-style or older-TS-style shape with an error naming the offending keys and the method.

Source

Thrown at mem0-ts/src/oss/src/memory/index.ts:145

}

// Batch size for deleteAll pagination. Larger than most vector store default
// page limits (~100) to minimize roundtrips while bounded to avoid memory pressure.
const DELETE_ALL_BATCH_SIZE = 1000;

/**
 * Validates that no top-level entity parameters are passed in config.
 * @throws Error if entity params are found at top level
 */
function rejectTopLevelEntityParams(
  config: Record<string, any>,
  methodName: string,
): void {
  const invalidKeys = Object.keys(config).filter((k) =>
    ENTITY_PARAMS.includes(k),
  );
  if (invalidKeys.length > 0) {
    throw new Error(
      `Top-level entity parameters [${invalidKeys.join(", ")}] are not supported in ${methodName}(). ` +
        `Use filters: { userId: "..." } instead.`,
    );
  }
}

/**
 * Validates and normalizes an entity ID.
 * - Coerces non-string ids (e.g. numeric database keys) to string
 * - Trims leading/trailing whitespace
 * - Rejects empty or whitespace-only strings
 * - Rejects strings containing internal whitespace
 * @returns The trimmed entity ID, or undefined if input is undefined/null
 * @throws Error if entity ID is invalid
 */
function validateAndTrimEntityId(
  value: string | number | undefined | null,
  name: string,

View on GitHub (pinned to 001c235229)

Solutions

Move entity ids into filters: memory.add(messages, { filters: { userId: 'u1' } }).
Audit call sites for user_id/agent_id/run_id (both casings) in the options object — the error message lists exactly which keys offended.
If porting from Python, mechanically translate every top-level id kwarg into the filters object.
Update to current docs/examples for the TS SDK shape.

Example fix

// before
await memory.add('user prefers dark mode', { user_id: 'u1', agent_id: 'a1' }); // throws

// after
await memory.add('user prefers dark mode', {
  filters: { userId: 'u1', agentId: 'a1' },
});

Defensive patterns

Strategy: validation

Validate before calling

const ENTITY_KEYS = ['user_id', 'agent_id', 'run_id', 'userId', 'agentId', 'runId'];
function assertNoTopLevelEntityParams(options: Record<string, unknown>, method: string) {
  const bad = Object.keys(options ?? {}).filter((k) => ENTITY_KEYS.includes(k));
  if (bad.length > 0) {
    throw new TypeError(`${method}(): pass ${bad.join(', ')} inside filters, not at top level`);
  }
}

Type guard

function isFiltersShaped(options: Record<string, any> | undefined): boolean {
  if (!options) return true;
  return !Object.keys(options).some((k) =>
    ['user_id', 'agent_id', 'run_id', 'userId', 'agentId', 'runId'].includes(k),
  );
}

Try / catch

try {
  await memory.add(messages, options as any);
} catch (err) {
  if (err instanceof Error && /Top-level entity parameters/.test(err.message)) {
    const { user_id, agent_id, run_id, ...rest } = options as any;
    await memory.add(messages, { ...rest, filters: { userId: user_id, agentId: agent_id, runId: run_id } });
    return;
  }
  throw err;
}

Prevention

Type your call sites with AddMemoryOptions/SearchOptions so top-level ids fail at compile time.
Never port Python kwargs verbatim — translate entity ids into filters in the TS port.
Add a lint/unit rule rejecting user_id/agent_id/run_id keys in Memory option objects.

When it happens

Trigger: Calling memory.add(msgs, { user_id: 'u1' }) or memory.search(q, { agentId: 'a1' }) — any *_id key at the top level of the config argument. Also triggered by code ported from the Python SDK or from older mem0-ts versions that accepted top-level entity params.

Common situations: Migrating Python mem0 code to mem0-ts and copying kwargs verbatim; upgrading from an older mem0ai npm version that tolerated top-level ids; AI-generated examples using the Python shape; passing a merged object that accidentally includes user_id from upstream data.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/1e4871e69a7ead86. Report an issue: GitHub.