TencentCloud/TencentDB-Agent-Memory · error

teamId is required for an agent prompt setting

Error message

teamId is required for an agent prompt setting

What it means

buildMemoryPromptSettingId composes a prompt setting id from a target and layer. An agent-scoped target (mps:a:...) requires both teamId and agentId because the id hashes `teamId\0agentId`. When target.agentId is set without target.teamId, the function cannot compute a stable agent-scoped id and throws.

Source

Thrown at MemoryCore/src/core/memory-prompt/types.ts:128

  clearMemoryPromptSettings?(
    ids: string[],
    logs: MemoryPromptSettingLogRecord[],
  ): Promise<void> | void;
  queryMemoryPromptSettingLogs?(
    filter: MemoryPromptSettingLogFilter,
  ): Promise<MemoryPromptSettingLogRecord[]> | MemoryPromptSettingLogRecord[];
}

function targetHash(value: string): string {
  return createHash("sha256").update(value).digest("hex").slice(0, 32);
}

export function buildMemoryPromptSettingId(
  target: { teamId?: string; agentId?: string },
  layer: MemoryPromptLayer,
): string {
  if (target.agentId) {
    if (!target.teamId) throw new Error("teamId is required for an agent prompt setting");
    return `mps:a:${targetHash(`${target.teamId}\0${target.agentId}`)}:${layer}`;
  }
  if (target.teamId) return `mps:t:${targetHash(target.teamId)}:${layer}`;
  return `mps:i:${layer}`;
}

export function getMemoryPromptTargetType(target: {
  teamId?: string;
  agentId?: string;
}): MemoryPromptTargetType {
  if (target.agentId) return "agent";
  if (target.teamId) return "team";
  return "instance";
}

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Include teamId in the target object whenever agentId is provided
2. If the setting is not team/agent-scoped, remove agentId so it falls through to the team (mps:t:) or instance (mps:i:) branch
3. At call sites, verify the teamId was not lost when constructing the target from partial context

Example fix

// before
const id = buildMemoryPromptSettingId({ agentId: "agt_1" }, "l2");
// after
const id = buildMemoryPromptSettingId({ teamId: "team_9", agentId: "agt_1" }, "l2");

function canBuildAgentSettingId(target) {
  return !(target.agentId && !target.teamId);
}

function isAgentTarget(t) {
  return typeof t.agentId === "string" && t.agentId.length > 0 && typeof t.teamId === "string" && t.teamId.length > 0;
}

try {
  const id = buildMemoryPromptSettingId(target, layer);
} catch (e) {
  if (e.message.includes("teamId is required")) {
    logger.error("agent-scoped prompt setting requires teamId+agentId");
  }
  throw e;
}

When it happens

Trigger: Calling buildMemoryPromptSettingId with { agentId: "..." } and no teamId (undefined or empty) for any layer; same requirement propagates to its callers settingIds, setting, candidates, ids.

Common situations: Building an agent prompt setting from a context that only carries agentId (e.g. resolving agent-scope config outside a team, or a migration that moved agent settings under teams); teamId omitted in the lookup object while the caller assumed instance-level (mps:i:) fallback.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• [skill-worker-pool] concurrency must be positive integer, go
• EmbeddingService: dimensions is required for remote provider
• cos.generationLogRetentionDays must be a non-negative intege
• metadata.systemUser.memory.userKey 必须匹配 sk-mem-[A-Za-z0-9_-]

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/0bd2abb0011e7729. Report an issue: GitHub.