Skip to content
Python
6.8 KB
Raw Blame
import type {
  GovernedMemory,
  MemoryDetail,
  MemoryKind,
  MemoryLibraryPage,
  SdkMemoryPage,
  SdkMemoryRecord,
  SdkMemoryRef,
} from "@one-memory/contracts";

/** The SDK memory panel's page size (the API still accepts 1..500). */
export const SDK_MEMORY_PAGE_SIZE = 20;

/** Scene, kind and namespace of an SDK memory. Records from a Core before
 * the all-scene library carry none of these and were all chat. */
export function sdkMemoryRef(record: SdkMemoryRecord): SdkMemoryRef {
  const kind = record.kind ?? "chat";
  if (kind === "chat") return { scene: "chat", kind, variant: null };
  const variant =
    record.variant ?? (record.scene === "coding" ? "coding" : "working");
  return { scene: variant, kind, variant };
}

/** What get/update/delete name for a memory: nothing for chat, so a chat
 * memory is addressed exactly as before; kind+variant for the rest. */
export function sdkNamespace(
  ref: SdkMemoryRef | undefined,
):
  | { kind: SdkMemoryRef["kind"]; variant: SdkMemoryRef["variant"] }
  | undefined {
  return ref && ref.kind !== "chat"
    ? { kind: ref.kind, variant: ref.variant }
    : undefined;
}

/** The text an edit replaces: an experience's solution, otherwise content. */
export function sdkEditableText(record: SdkMemoryRecord): string {
  return record.kind === "experience" && typeof record.solution === "string"
    ? record.solution
    : record.content;
}

function kindOf(record: SdkMemoryRecord): MemoryKind {
  const scene = sdkMemoryRef(record).scene;
  if (scene !== "chat") return scene;
  const layer = record.layer;
  if (layer === "l6_schema") return "schema";
  if (layer === "l7_intention") return "intention";
  if (layer.startsWith("coding")) return "coding";
  if (layer.startsWith("working")) return "working";
  return "chat";
}

function stamp(seconds: number | null | undefined): string {
  return typeof seconds === "number" && Number.isFinite(seconds)
    ? new Date(seconds * 1_000).toISOString()
    : "";
}

const EARLIEST_PLAUSIBLE = Date.UTC(2000, 0, 1) / 1_000;

/** A conversation time that can be true: not before 2000, not tomorrow or later.
 *
 * A historical Cursor bug stored a file hash as the message time (years like
 * 2254). Such a value is not shown as when the conversation happened; the
 * import time, or "time unknown", says what is actually known.
 */
function plausible(seconds: number | null | undefined): number | null {
  return typeof seconds === "number" &&
    Number.isFinite(seconds) &&
    seconds >= EARLIEST_PLAUSIBLE &&
    seconds <= Date.now() / 1_000 + 86_400
    ? seconds
    : null;
}

/** The SDK writes "default" when no source was given; keep it as that bucket. */
function sourceOf(record: SdkMemoryRecord): string {
  return record.source || "default";
}

/** An SDK memory in the shape the memory map draws.
 *
 * The map groups and labels by id, content, kind, status and tags only, so the
 * governed-only fields are inert placeholders here. Opening, editing and
 * deleting still go through the SDK (v2) endpoints — `sdkDetail()` below wraps
 * the same projection for the map's inspector, which is why the inspector can
 * stay where the design put it instead of sending the reader to another view.
 */
export function sdkMapMemory(record: SdkMemoryRecord): GovernedMemory {
  const created = stamp(
    record.gmt_created ?? record.created_at ?? record.memory_at,
  );
  const updated = stamp(record.updated_at) || created;
  return {
    memory_id: record.memory_id,
    user_id: record.user_id,
    kind: kindOf(record),
    status:
      record.status === "active"
        ? "confirmed"
        : record.status === "superseded"
          ? "superseded"
          : "deleted",
    content: record.content,
    scopes: [],
    evidence_ids: [],
    origin: "extracted",
    tags: [...record.tags],
    supersedes: [...record.supersedes],
    superseded_by: [...record.superseded_by],
    // GovernedMemory still requires a revision for the shared map model. SDK
    // has no revision contract; the inspector recognises sdk_status and never
    // renders this placeholder.
    revision: 0,
    created_at: created,
    updated_at: updated,
    deleted_at: null,
  };
}

/** One SDK memory as the map's inspector reads it.
 *
 * The inspector was built for a governed detail. SDK-native memory has no
 * product revision or "original evidence" section; source_raw_ids remain an
 * internal SDK provenance relation and are deliberately not projected as UI
 * evidence.
 */
export function sdkDetail(record: SdkMemoryRecord): MemoryDetail {
  return {
    memory: sdkMapMemory(record),
    evidence: [],
    history: [],
    index_sync: null,
    sdk_status: record.status,
    source_id: sourceOf(record),
    sdk_memory_at: stamp(plausible(record.memory_at)) || null,
    sdk_created_at: stamp(record.gmt_created ?? record.created_at) || null,
    sdk_ref: sdkMemoryRef(record),
    sdk_task: record.kind === "experience" ? (record.task ?? null) : null,
    sdk_solution:
      record.kind === "experience" ? (record.solution ?? null) : null,
  };
}

/** One SDK page as the map's left list reads it.
 *
 * The list asks a library page for its rows, its total and — per row — when
 * the cited conversation happened. The SDK page carries the row itself, so the
 * time is taken from the memory: `memory_at` is the moment the conversation
 * happened, `gmt_created` only the moment it was imported. Naming which one it
 * is keeps "对话于" from silently becoming "沉淀于".
 */
export function sdkLibraryPage(page: SdkMemoryPage): MemoryLibraryPage {
  const sourceTime: Record<
    string,
    { at: string; basis: "conversation" | "import" | "write" }
  > = {};
  const sourceIds: Record<string, string[]> = {};
  const refs: Record<string, SdkMemoryRef> = {};
  for (const record of page.memories) {
    sourceIds[record.memory_id] = [sourceOf(record)];
    refs[record.memory_id] = sdkMemoryRef(record);
    // An experience or fact stored before hy-memory 2.0.7 has no
    // conversation time. It shows when it was written, labelled as such,
    // rather than calling its creation an import.
    const chat = refs[record.memory_id].kind === "chat";
    const conversation = plausible(record.memory_at);
    const at =
      conversation ?? plausible(chat ? record.gmt_created : record.created_at);
    if (at === null) continue;
    sourceTime[record.memory_id] = {
      at: new Date(at * 1_000).toISOString(),
      basis: conversation !== null ? "conversation" : chat ? "import" : "write",
    };
  }
  return {
    items: page.memories.map(sdkMapMemory),
    total: page.total,
    offset: page.offset,
    limit: page.limit,
    source_ids_by_memory: sourceIds,
    source_time_by_memory: sourceTime,
    search_window: page.search_window ?? null,
    window_id: page.window_id ?? null,
    window_reset: page.window_reset ?? false,
    sdk_memory_refs: refs,
  };
}