Skip to content
Python
17.1 KB
Raw Blame
import { randomUUID } from "node:crypto";
import type {
  MemoryAddReceipt,
  SdkMemoryPage,
  SdkMemoryRecord,
} from "@one-memory/contracts";
import {
  buildMemoryAddRequest,
  MemoryAddInputError,
  memoryAddStatusPath,
  parseMemoryAddReceipt,
} from "@one-memory/operations";
import { type CoreReader, RESERVED_MEMORY_SEGMENTS } from "./core-client.js";
import type { CoreOperations } from "./core-operations.js";
import { PRODUCT } from "./version.js";

/** A MemHub user id, the same shape Core accepts. `local` is the default. */
const USER_ID = /^[A-Za-z0-9._-]{1,64}$/;
export const DEFAULT_USER_ID = "local";

export function isUserId(value: string): boolean {
  return USER_ID.test(value);
}

/**
 * The `user_id` to send, or nothing. The default user is never named on the
 * wire, so a request without `--user-id` stays exactly what it was before
 * multi-user support and still works against an older Core.
 */
export function userIdParameters(userId?: string): { user_id?: string } {
  return userId === undefined || userId === DEFAULT_USER_ID
    ? {}
    : { user_id: userId };
}

/** Output budget: a long memory is shortened visibly, never dropped silently. */
const CONTENT_BUDGET = 240;

const MEMORY_ID_SHAPE = /^[A-Za-z0-9][\w.-]{0,127}$/;

/** Reserved segments are rejected here too, before a request is even built. */
export function isMemoryId(value: string): boolean {
  return (
    MEMORY_ID_SHAPE.test(value) &&
    !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(value)
  );
}

const CONTENT_MAX_CHARACTERS = 100_000;

/** A memory body read from `--content-file`: UTF-8, non-blank, bounded, and
 * free of control characters other than tab and newline. */
export function parseMemoryContent(bytes: Buffer): string | null {
  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
  let decoded: string;
  try {
    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch {
    return null;
  }
  const content = decoded.replace(/\r?\n$/, "");
  return content.trim().length > 0 &&
    [...content].length <= CONTENT_MAX_CHARACTERS &&
    ![...content].some((character) => {
      const code = character.charCodeAt(0);
      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
    })
    ? content
    : null;
}

export const MEMORY_SCENES = ["all", "chat", "working", "coding"] as const;
export type MemoryScene = (typeof MEMORY_SCENES)[number];
export const MEMORY_KINDS = ["chat", "experience", "fact"] as const;
export type MemoryKind = (typeof MEMORY_KINDS)[number];
export const MEMORY_VARIANTS = ["working", "coding"] as const;
export type MemoryVariant = (typeof MEMORY_VARIANTS)[number];

/** Which SDK namespace a memory lives in. A chat memory needs neither; a
 * working/coding experience or fact needs both so Core does not have to guess
 * (an id present in two namespaces is refused as ambiguous). */
export interface MemoryNamespace {
  kind?: MemoryKind;
  variant?: MemoryVariant;
}

export function namespaceParameters(
  namespace: MemoryNamespace,
): Record<string, string> {
  return {
    ...(namespace.kind === undefined ? {} : { kind: namespace.kind }),
    ...(namespace.variant === undefined ? {} : { variant: namespace.variant }),
  };
}

export interface MemoryQuery {
  query?: string;
  status?: string;
  source?: string;
  scene?: MemoryScene;
  offset: number;
  limit: number;
}

/** Every `memories` document is schema 2: list/show share it with
 * add/update/delete, and the v1-era `evidence`/`history` fields are gone. */
export interface MemoryPageDocument {
  schema_version: 2;
  product: string;
  page: Record<string, unknown>;
  memories: Record<string, unknown>[];
}

export interface MemoryDetailDocument {
  schema_version: 2;
  product: string;
  memory: Record<string, unknown>;
}

export async function readMemoryPage(
  reader: CoreReader,
  query: MemoryQuery,
  userId?: string,
): Promise<MemoryPageDocument> {
  const parameters: Record<string, string | number> = {
    offset: query.offset,
    limit: query.limit,
    ...userIdParameters(userId),
  };
  if (query.status !== undefined) parameters.statuses = query.status;
  if (query.source !== undefined) parameters.source = query.source;
  if (query.query !== undefined) parameters.query = query.query;
  if (query.scene !== undefined && query.scene !== "all") {
    parameters.scene = query.scene;
  }
  const outcome = await reader<unknown>("/api/v2/memory-library", parameters);
  if (outcome.state !== "ok") {
    return {
      schema_version: 2,
      product: PRODUCT,
      page: { state: outcome.state, code: outcome.code },
      memories: [],
    };
  }
  const page = sdkMemoryPage(outcome.data);
  if (page === null) {
    return {
      schema_version: 2,
      product: PRODUCT,
      page: { state: "invalid", code: "response_invalid" },
      memories: [],
    };
  }
  const items = page.memories;
  return {
    schema_version: 2,
    product: PRODUCT,
    page: {
      state: "ok",
      scene: query.scene ?? "all",
      ...(query.query === undefined ? {} : { query: query.query }),
      total: page.total,
      offset: page.offset,
      limit: page.limit,
      returned: items.length,
      has_more: page.offset + items.length < page.total,
      // A keyword search only looks among this many most relevant memories.
      ...(typeof page.search_window === "number"
        ? { search_window: page.search_window }
        : {}),
    },
    memories: items.map((item) => describeMemory(item)),
  };
}

export async function readMemoryDetail(
  reader: CoreReader,
  memoryId: string,
  namespace: MemoryNamespace = {},
  userId?: string,
): Promise<MemoryDetailDocument> {
  const parameters = {
    ...namespaceParameters(namespace),
    ...userIdParameters(userId),
  };
  const outcome = await reader<unknown>(
    `/api/v2/memories/${memoryId}`,
    Object.keys(parameters).length > 0 ? parameters : undefined,
  );
  if (outcome.state !== "ok") {
    return {
      schema_version: 2,
      product: PRODUCT,
      memory: { state: outcome.state, code: outcome.code },
    };
  }
  const memory = sdkMemory(outcome.data);
  if (memory === null || memory.memory_id !== memoryId) {
    return {
      schema_version: 2,
      product: PRODUCT,
      memory: { state: "invalid", code: "response_invalid" },
    };
  }
  return {
    schema_version: 2,
    product: PRODUCT,
    memory: { state: "ok", ...describeMemory(memory) },
  };
}

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
/** The same bound the app's 添加记忆 box applies. */
export const MEMORY_ADD_MAX_CHARACTERS = 12_000;

export interface MemoryAddDocument {
  schema_version: 2;
  product: string;
  command: "memories add" | "memories add-status";
  state: "accepted" | "rejected" | "unknown" | "not_found" | "invalid";
  request_id: string;
  code?: string;
  receipt?: Record<string, unknown>;
}

export function isRequestId(value: string): boolean {
  return UUID.test(value);
}

/** A memory text: non-blank, bounded, no control characters except tab and
 * newline. */
export function validMemoryText(text: string): boolean {
  return (
    text.trim().length > 0 &&
    [...text].length <= MEMORY_ADD_MAX_CHARACTERS &&
    ![...text].some((character) => {
      const code = character.charCodeAt(0);
      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
    })
  );
}

function addReceipt(receipt: MemoryAddReceipt): Record<string, unknown> {
  return {
    evidence_id: receipt.evidence_id,
    state: receipt.state,
    created_at: receipt.created_at,
    task_id: receipt.task_id,
    memory_ids: receipt.memory_ids,
    error: receipt.error,
  };
}

/**
 * Add one memory directly, the same request as the app's 添加记忆.
 *
 * `requestId` is Core's idempotency key: retrying with the same id and text
 * returns the first receipt; the same id with other text is refused.
 */
export async function addMemory(
  operations: CoreOperations,
  text: string,
  requestId: string = randomUUID(),
  userId?: string,
): Promise<MemoryAddDocument> {
  const base = {
    schema_version: 2 as const,
    product: PRODUCT,
    command: "memories add" as const,
    request_id: requestId,
  };
  if (!validMemoryText(text) || !UUID.test(requestId)) {
    return { ...base, state: "invalid", code: "memory_add_invalid" };
  }
  let request: ReturnType<typeof buildMemoryAddRequest>;
  try {
    request = buildMemoryAddRequest({
      request_id: requestId,
      text,
      scope: "all-apps",
    });
  } catch (error) {
    if (error instanceof MemoryAddInputError) {
      return { ...base, state: "invalid", code: "memory_add_invalid" };
    }
    throw error;
  }
  const result = await operations.post<unknown>(request.path, {
    ...request.body,
    ...userIdParameters(userId),
  });
  if (result.state !== "committed") {
    return { ...base, state: result.state, code: result.code };
  }
  const receipt = parseMemoryAddReceipt(result.data);
  return receipt === null
    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
}

/** Read how one addition is doing, by the request id it was submitted with. */
export async function readMemoryAddStatus(
  reader: CoreReader,
  requestId: string,
  userId?: string,
): Promise<MemoryAddDocument> {
  const base = {
    schema_version: 2 as const,
    product: PRODUCT,
    command: "memories add-status" as const,
    request_id: requestId,
  };
  if (!UUID.test(requestId)) {
    return { ...base, state: "invalid", code: "invalid_request_id" };
  }
  const user = userIdParameters(userId);
  const outcome =
    user.user_id === undefined
      ? await reader<unknown>(memoryAddStatusPath(requestId))
      : await reader<unknown>(memoryAddStatusPath(requestId), user);
  if (outcome.state === "not_found") {
    return { ...base, state: "not_found", code: "memory_add_not_found" };
  }
  if (outcome.state !== "ok") {
    return {
      ...base,
      state: outcome.state === "rejected" ? "rejected" : "unknown",
      code: outcome.code,
    };
  }
  const receipt = parseMemoryAddReceipt(outcome.data);
  return receipt === null
    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
}

export function memoryAddExitCode(document: MemoryAddDocument): number {
  return document.state === "accepted" ? 0 : 1;
}

export function renderMemoryAddText(document: MemoryAddDocument): string {
  if (document.state === "accepted" && document.receipt) {
    return [
      `request_id: ${document.request_id}`,
      `evidence_id: ${document.receipt.evidence_id}`,
      `state: ${document.receipt.state}`,
      ...((document.receipt.memory_ids as string[]).length > 0
        ? [`memory_ids: ${(document.receipt.memory_ids as string[]).join(",")}`]
        : []),
      document.command === "memories add"
        ? `查询进度:memhub memories add-status ${document.request_id};重试请带上同一个 --request-id,不会重复添加。`
        : "",
      "",
    ]
      .filter((line, index, all) => line !== "" || index === all.length - 1)
      .join("\n");
  }
  if (document.state === "not_found") {
    return `未找到该 request id:${document.request_id}\n`;
  }
  return [
    `添加记忆未完成:${document.state}(${document.code})`,
    document.state === "unknown"
      ? `结果未知;可以用同一个 --request-id ${document.request_id} 安全重试。`
      : "",
    "",
  ]
    .filter((line, index, all) => line !== "" || index === all.length - 1)
    .join("\n");
}

export function renderMemoryPageText(document: MemoryPageDocument): string {
  const page = document.page;
  if (page.state !== "ok") {
    if (page.state === "unavailable" && page.code === "embedding_unavailable") {
      return "向量服务不可用,无法检索;请检查向量模型配置。\n";
    }
    if (page.state === "unavailable") {
      return "后台正忙,记忆列表这次没查完,不代表没有记忆,请稍后再试\n";
    }
    if (page.state === "rejected") {
      return `记忆查询被拒绝(${page.code}),请检查参数。\n`;
    }
    return `记忆查询未完成:${page.state}(${page.code})\n`;
  }
  const lines = [
    `共 ${page.total} 条,本页 ${page.returned} 条(offset=${page.offset} limit=${page.limit})${
      page.has_more ? ",还有更多,请用 --offset 继续" : ""
    }`,
  ];
  if (typeof page.search_window === "number") {
    lines.push(`(搜索只在最相关的 ${page.search_window} 条里匹配关键词)`);
  }
  for (const memory of document.memories) {
    const namespace =
      memory.kind === "chat"
        ? ""
        : ` kind=${memory.kind} variant=${memory.variant}`;
    lines.push(
      `- ${memory.memory_id}  [${memory.scene}] ${memory.status}/${memory.layer}  source=${memory.source ?? "未知"}${namespace}`,
      `  ${memory.content}${memory.content_truncated ? ` …(共 ${memory.content_characters} 字)` : ""}`,
    );
  }
  if (document.memories.length === 0) lines.push("(没有符合条件的记忆)");
  lines.push("");
  return lines.join("\n");
}

export function renderMemoryDetailText(document: MemoryDetailDocument): string {
  const memory = document.memory;
  if (memory.state !== "ok") {
    if (memory.state === "unavailable") {
      return "后台正忙,记忆详情这次没查完,不代表没有这条记忆,请稍后再试\n";
    }
    if (memory.code === "memory_id_ambiguous") {
      return "这个 ID 同时存在于多个场景;请加 --kind(以及 --variant)指明是哪一条。\n";
    }
    return `记忆读取未完成:${memory.state}(${memory.code})\n`;
  }
  const lines = [
    `记忆 ${memory.memory_id}`,
    `场景:${memory.scene}  类型:${memory.kind}${memory.variant ? `(${memory.variant})` : ""}`,
    `状态:${memory.status}  层:${memory.layer}  来源:${memory.source ?? "未知"}`,
    `owner:${memory.owner ?? "未知"}  latest:${memory.is_latest}`,
    `raw IDs:${(memory.source_raw_ids as string[]).join(",") || "无"}`,
    "",
    String(memory.content),
    memory.content_truncated ? `…(共 ${memory.content_characters} 字)` : "",
    "",
    "SDK memory 数据不在 MemHub 中保留 Evidence/版本副本。",
  ];
  lines.push("");
  return lines.join("\n");
}

function describeMemory(memory: SdkMemoryRecord): Record<string, unknown> {
  const budgeted = budget(memory.content ?? "");
  return {
    memory_id: memory.memory_id,
    // Pre-2.0.6 Core listed chat memories only and named no scene.
    scene: memory.scene ?? "chat",
    kind: memory.kind ?? "chat",
    variant: memory.variant ?? null,
    status: memory.status,
    layer: memory.layer,
    is_latest: memory.is_latest,
    owner: memory.owner,
    source: memory.source,
    source_raw_ids: memory.source_raw_ids,
    supersedes: memory.supersedes,
    superseded_by: memory.superseded_by,
    tags: memory.tags ?? [],
    memory_at: memory.memory_at,
    gmt_created: memory.gmt_created,
    ...(memory.task === undefined || memory.task === null
      ? {}
      : { task: memory.task }),
    content: budgeted.text,
    content_truncated: budgeted.truncated,
    content_characters: budgeted.characters,
  };
}

function sdkMemoryPage(value: unknown): SdkMemoryPage | null {
  if (!record(value) || !Array.isArray(value.memories)) return null;
  const memories = value.memories.map(sdkMemory);
  if (memories.some((item) => item === null)) return null;
  if (!integer(value.total) || !integer(value.limit) || !integer(value.offset))
    return null;
  return {
    memories: memories as SdkMemoryRecord[],
    total: value.total,
    limit: value.limit,
    offset: value.offset,
    ...(integer(value.search_window)
      ? { search_window: value.search_window }
      : {}),
  };
}

function sdkMemory(value: unknown): SdkMemoryRecord | null {
  if (
    !record(value) ||
    !text(value.memory_id) ||
    typeof value.content !== "string" ||
    !text(value.layer) ||
    !text(value.status) ||
    typeof value.is_latest !== "boolean" ||
    !strings(value.supersedes) ||
    !strings(value.superseded_by) ||
    !strings(value.tags) ||
    !strings(value.source_raw_ids) ||
    // Working/coding memories may carry an empty user or agent id.
    typeof value.user_id !== "string" ||
    typeof value.agent_id !== "string"
  )
    return null;
  return value as unknown as SdkMemoryRecord;
}

function record(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function text(value: unknown): value is string {
  return typeof value === "string" && value.length > 0;
}

function strings(value: unknown): value is string[] {
  return (
    Array.isArray(value) && value.every((item) => typeof item === "string")
  );
}

function integer(value: unknown): value is number {
  return Number.isInteger(value) && Number(value) >= 0;
}

function budget(value: string): {
  text: string;
  truncated: boolean;
  characters: number;
} {
  const points = [...value];
  return points.length <= CONTENT_BUDGET
    ? { text: value, truncated: false, characters: points.length }
    : {
        text: points.slice(0, CONTENT_BUDGET).join(""),
        truncated: true,
        characters: points.length,
      };
}