@sentry/junior-memory 0.180.0 → 0.181.0

package/src/user-pages.ts

@@ -1,7 +1,6 @@
-/** Project viewer-visible memories into Junior's core-rendered user page. */
+/** Render memory in Junior's User page format. */
 import type { PluginUserPageDefinition } from "@sentry/junior-plugin-api";
-import { createViewerMemories } from "./personal";
-import type { MemoryVisibility, PersonalMemoryRecord } from "./personal-store";
+import { listMemories, type MemoryVisibility, type MemoryView } from "./viewer";
 import type { MemoryDb } from "./store";
 
 function titleCase(value: string): string {
@@ -16,7 +15,7 @@ function rememberedDate(createdAtMs: number): string {
   }).format(new Date(createdAtMs));
 }
 
-function originLabel(origin: PersonalMemoryRecord["origin"]): string {
+function originLabel(origin: MemoryView["origin"]): string {
   if (origin === "automatic") return "Automatic";
   if (origin === "explicit") return "Explicit";
   return "Other";
@@ -50,8 +49,7 @@ export function createMemoryUserPage(): PluginUserPageDefinition {
     description:
       "Personal and public memories Junior can use across conversations.",
     async read(ctx, input) {
-      const memories = createViewerMemories(ctx.db as MemoryDb, ctx.viewer);
-      const page = await memories.list({
+      const page = await listMemories(ctx.db as MemoryDb, ctx.viewer.id, {
         cursor: input.cursor,
         ...pageFilter(input.filter),
         limit: input.limit,

package/src/viewer.ts

@@ -0,0 +1,393 @@
+/**
+ * Memory access for an authenticated User.
+ *
+ * Every User can read public memory and private memory that they own.
+ */
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  gt,
+  ilike,
+  isNull,
+  like,
+  lt,
+  or,
+  sql,
+} from "drizzle-orm";
+import { z } from "zod";
+import { juniorMemoryEmbeddings, juniorMemoryMemories } from "./db/schema";
+import { publicMemoryScope } from "./scope";
+import { parseMemoryRow, type MemoryDb, type MemoryRecord } from "./store";
+import { MEMORY_KINDS, type MemorySourcePlatform } from "./types";
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const nonEmptyStringSchema = z.string().min(1);
+const memoryVisibilitySchema = z.enum(["private", "public"]);
+const cursorSchema = z
+  .object({
+    createdAtMs: z.number().finite(),
+    id: nonEmptyStringSchema,
+    kind: z.enum(MEMORY_KINDS).optional(),
+    origin: z.enum(["automatic", "explicit"]).optional(),
+    query: z.string().max(200).optional(),
+    version: z.literal(1),
+    visibility: memoryVisibilitySchema.optional(),
+  })
+  .strict();
+const pageInputSchema = z
+  .object({
+    cursor: z.string().min(1).max(1_000).optional(),
+    kind: z.enum(MEMORY_KINDS).optional(),
+    limit: z.number().int().min(1).max(50),
+    origin: z.enum(["automatic", "explicit"]).optional(),
+    query: z.string().max(200).optional(),
+    visibility: memoryVisibilitySchema.optional(),
+  })
+  .strict();
+const timelineDaysSchema = z.number().int().min(1).max(365);
+
+/** Access label returned by dashboard and REST memory views. */
+export type MemoryVisibility = z.output<typeof memoryVisibilitySchema>;
+
+/** Memory fields returned to an authenticated User. */
+export type MemoryView = MemoryRecord & {
+  origin: "automatic" | "explicit" | "other";
+  sourcePlatform: MemorySourcePlatform;
+  visibility: MemoryVisibility;
+};
+
+interface MemoryPage {
+  memories: MemoryView[];
+  nextCursor?: string;
+}
+
+type MemoryPageInput = z.output<typeof pageInputSchema>;
+
+/** Expected error for a malformed or mismatched page cursor. */
+export class InvalidMemoryCursorError extends Error {
+  constructor() {
+    super("Memory cursor is invalid.");
+    this.name = "InvalidMemoryCursorError";
+  }
+}
+
+/** Expected error when the current User cannot access a memory. */
+export class MemoryNotFoundError extends Error {
+  constructor() {
+    super("Memory was not found for this user.");
+    this.name = "MemoryNotFoundError";
+  }
+}
+
+function publicScopePredicate() {
+  return and(
+    eq(juniorMemoryMemories.scope, publicMemoryScope.scope),
+    eq(juniorMemoryMemories.scopeKey, publicMemoryScope.scopeKey),
+  );
+}
+
+function privateScopePredicate(userId: string) {
+  return and(
+    eq(juniorMemoryMemories.scope, "private"),
+    eq(juniorMemoryMemories.scopeKey, userId),
+  );
+}
+
+function visibleScopePredicate(userId: string, visibility?: MemoryVisibility) {
+  if (visibility === "public") return publicScopePredicate();
+  if (visibility === "private") return privateScopePredicate(userId);
+  return or(publicScopePredicate(), privateScopePredicate(userId));
+}
+
+function activeMemoryPredicate(
+  userId: string,
+  nowMs: number,
+  visibility?: MemoryVisibility,
+) {
+  return and(
+    visibleScopePredicate(userId, visibility),
+    isNull(juniorMemoryMemories.archivedAtMs),
+    isNull(juniorMemoryMemories.supersededAtMs),
+    isNull(juniorMemoryMemories.supersededById),
+    or(
+      isNull(juniorMemoryMemories.expiresAtMs),
+      gt(juniorMemoryMemories.expiresAtMs, nowMs),
+    ),
+  );
+}
+
+function utcDate(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function searchTerms(query: string): string[] {
+  return [
+    ...new Set(
+      query
+        .toLowerCase()
+        .split(/[^a-z0-9_'-]+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2),
+    ),
+  ];
+}
+
+function memoryOrigin(idempotencyKey: string | null): MemoryView["origin"] {
+  if (idempotencyKey?.startsWith("session:")) return "automatic";
+  if (idempotencyKey?.startsWith("tool:")) return "explicit";
+  return "other";
+}
+
+function toMemoryView(
+  row: typeof juniorMemoryMemories.$inferSelect,
+): MemoryView {
+  const memory = parseMemoryRow(row);
+  return {
+    ...memory,
+    origin: memoryOrigin(row.idempotencyKey),
+    sourcePlatform: row.sourcePlatform,
+    visibility: memory.scope,
+  };
+}
+
+function cursorFilters(input: MemoryPageInput) {
+  return {
+    kind: input.kind,
+    origin: input.origin,
+    query: input.query?.trim() || undefined,
+    visibility: input.visibility,
+  };
+}
+
+function decodeCursor(
+  value: string | undefined,
+  filters: ReturnType<typeof cursorFilters>,
+) {
+  if (!value) return undefined;
+  try {
+    const parsed = cursorSchema.parse(
+      JSON.parse(Buffer.from(value, "base64url").toString("utf8")),
+    );
+    if (
+      parsed.query !== filters.query ||
+      parsed.kind !== filters.kind ||
+      parsed.origin !== filters.origin ||
+      parsed.visibility !== filters.visibility
+    ) {
+      throw new InvalidMemoryCursorError();
+    }
+    return { createdAtMs: parsed.createdAtMs, id: parsed.id };
+  } catch {
+    throw new InvalidMemoryCursorError();
+  }
+}
+
+function encodeCursor(
+  createdBefore: { createdAtMs: number; id: string },
+  filters: ReturnType<typeof cursorFilters>,
+): string {
+  return Buffer.from(
+    JSON.stringify({ ...createdBefore, ...filters, version: 1 }),
+    "utf8",
+  ).toString("base64url");
+}
+
+/** Archive one active private memory owned by the authenticated User. */
+export async function archiveMemory(db: MemoryDb, userId: string, id: string) {
+  const memoryId = nonEmptyStringSchema.parse(id);
+  const nowMs = Date.now();
+  const updated = await db
+    .update(juniorMemoryMemories)
+    .set({
+      archivedAtMs: nowMs,
+      archiveReason: "user_removed",
+    })
+    .where(
+      and(
+        activeMemoryPredicate(userId, nowMs, "private"),
+        eq(juniorMemoryMemories.id, memoryId),
+      ),
+    )
+    .returning();
+  if (!updated[0]) throw new MemoryNotFoundError();
+  await db
+    .delete(juniorMemoryEmbeddings)
+    .where(eq(juniorMemoryEmbeddings.memoryId, memoryId));
+  return parseMemoryRow(updated[0]);
+}
+
+/** Read one active memory visible to the authenticated User. */
+export async function getMemory(
+  db: MemoryDb,
+  userId: string,
+  id: string,
+): Promise<MemoryView> {
+  const memoryId = nonEmptyStringSchema.parse(id);
+  const nowMs = Date.now();
+  const rows = await db
+    .select()
+    .from(juniorMemoryMemories)
+    .where(
+      and(
+        activeMemoryPredicate(userId, nowMs),
+        eq(juniorMemoryMemories.id, memoryId),
+      ),
+    )
+    .limit(1);
+  if (!rows[0]) throw new MemoryNotFoundError();
+  return toMemoryView(rows[0]);
+}
+
+/** List one stable page of active memory visible to the authenticated User. */
+export async function listMemories(
+  db: MemoryDb,
+  userId: string,
+  input: MemoryPageInput,
+): Promise<MemoryPage> {
+  input = pageInputSchema.parse(input);
+  const filters = cursorFilters(input);
+  const cursor = decodeCursor(input.cursor, filters);
+  const active = activeMemoryPredicate(userId, Date.now(), input.visibility);
+  const createdBefore = cursor
+    ? or(
+        lt(juniorMemoryMemories.createdAtMs, cursor.createdAtMs),
+        and(
+          eq(juniorMemoryMemories.createdAtMs, cursor.createdAtMs),
+          gt(juniorMemoryMemories.id, cursor.id),
+        ),
+      )
+    : undefined;
+  const terms = input.query ? searchTerms(input.query) : [];
+  const search =
+    input.query === undefined
+      ? undefined
+      : terms.length === 0
+        ? sql`false`
+        : or(
+            ...terms.map((term) =>
+              ilike(juniorMemoryMemories.content, `%${term}%`),
+            ),
+          );
+  const kind = input.kind
+    ? eq(juniorMemoryMemories.kind, input.kind)
+    : undefined;
+  const origin =
+    input.origin === "automatic"
+      ? like(juniorMemoryMemories.idempotencyKey, "session:%")
+      : input.origin === "explicit"
+        ? like(juniorMemoryMemories.idempotencyKey, "tool:%")
+        : undefined;
+  const rows = await db
+    .select()
+    .from(juniorMemoryMemories)
+    .where(and(active, createdBefore, search, kind, origin))
+    .orderBy(
+      desc(juniorMemoryMemories.createdAtMs),
+      asc(juniorMemoryMemories.id),
+    )
+    .limit(input.limit + 1);
+  const memories = rows.slice(0, input.limit).map(toMemoryView);
+  const last = memories.at(-1);
+  if (rows.length <= input.limit || !last) return { memories };
+  const next = { createdAtMs: last.createdAtMs, id: last.id };
+  return { memories, nextCursor: encodeCursor(next, filters) };
+}
+
+/** Summarize active memory visible to the authenticated User. */
+export async function getMemoryStats(db: MemoryDb, userId: string) {
+  const nowMs = Date.now();
+  const [counts] = await db
+    .select({
+      active: sql<number>`count(*)`.mapWith(Number),
+      automatic:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.idempotencyKey} like 'session:%')`.mapWith(
+          Number,
+        ),
+      createdThirtyDays:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.createdAtMs} >= ${nowMs - 30 * DAY_MS})`.mapWith(
+          Number,
+        ),
+      embedded: sql<number>`count(${juniorMemoryEmbeddings.memoryId})`.mapWith(
+        Number,
+      ),
+      explicit:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.idempotencyKey} like 'tool:%')`.mapWith(
+          Number,
+        ),
+      knowledge:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.kind} = 'knowledge')`.mapWith(
+          Number,
+        ),
+      private:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.scope} = 'private')`.mapWith(
+          Number,
+        ),
+      preference:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.kind} = 'preference')`.mapWith(
+          Number,
+        ),
+      procedure:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.kind} = 'procedure')`.mapWith(
+          Number,
+        ),
+      public:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.scope} = 'public')`.mapWith(
+          Number,
+        ),
+    })
+    .from(juniorMemoryMemories)
+    .leftJoin(
+      juniorMemoryEmbeddings,
+      eq(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id),
+    )
+    .where(activeMemoryPredicate(userId, nowMs));
+  if (!counts) throw new Error("Memory stats query returned no row.");
+  return counts;
+}
+
+/** Read daily memory creation totals visible to the authenticated User in UTC. */
+export async function getMemoryTimeline(
+  db: MemoryDb,
+  userId: string,
+  days: number,
+) {
+  days = timelineDaysSchema.parse(days);
+  const todayMs = Date.parse(`${utcDate(Date.now())}T00:00:00.000Z`);
+  const startMs = todayMs - (days - 1) * DAY_MS;
+  const rows = await db
+    .select({
+      date: sql<string>`to_char(to_timestamp(${juniorMemoryMemories.createdAtMs} / 1000.0) AT TIME ZONE 'UTC', 'YYYY-MM-DD')`.as(
+        "date",
+      ),
+      private:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.scope} = 'private')`.mapWith(
+          Number,
+        ),
+      public:
+        sql<number>`count(*) filter (where ${juniorMemoryMemories.scope} = 'public')`.mapWith(
+          Number,
+        ),
+    })
+    .from(juniorMemoryMemories)
+    .where(
+      and(
+        visibleScopePredicate(userId),
+        gt(juniorMemoryMemories.createdAtMs, startMs - 1),
+      ),
+    )
+    .groupBy(
+      sql`to_char(to_timestamp(${juniorMemoryMemories.createdAtMs} / 1000.0) AT TIME ZONE 'UTC', 'YYYY-MM-DD')`,
+    );
+  const byDate = new Map(rows.map((row) => [row.date, row]));
+  return Array.from({ length: days }, (_, index) => {
+    const date = utcDate(startMs + index * DAY_MS);
+    const row = byDate.get(date);
+    return {
+      date,
+      private: row?.private ?? 0,
+      public: row?.public ?? 0,
+    };
+  });
+}

package/dist/personal-store.d.ts

@@ -1,92 +0,0 @@
-import { z } from "zod";
-import type { ResolvedMemoryScope } from "./scope";
-import { type MemoryDb, type MemoryRecord } from "./store";
-import { type MemorySourcePlatform } from "./types";
-declare const memoryVisibilitySchema: z.ZodEnum<{
-    public: "public";
-    private: "private";
-}>;
-declare const personalMemoryCursorSchema: z.ZodObject<{
-    createdAtMs: z.ZodNumber;
-    id: z.ZodString;
-}, z.core.$strict>;
-declare const personalMemoryPageInputSchema: z.ZodObject<{
-    cursor: z.ZodOptional<z.ZodObject<{
-        createdAtMs: z.ZodNumber;
-        id: z.ZodString;
-    }, z.core.$strict>>;
-    kind: z.ZodOptional<z.ZodEnum<{
-        preference: "preference";
-        procedure: "procedure";
-        knowledge: "knowledge";
-    }>>;
-    limit: z.ZodNumber;
-    origin: z.ZodOptional<z.ZodEnum<{
-        automatic: "automatic";
-        explicit: "explicit";
-    }>>;
-    query: z.ZodOptional<z.ZodString>;
-    visibility: z.ZodOptional<z.ZodEnum<{
-        public: "public";
-        private: "private";
-    }>>;
-}, z.core.$strict>;
-export type PersonalMemoryCursor = z.output<typeof personalMemoryCursorSchema>;
-export type PersonalMemoryPageInput = z.output<typeof personalMemoryPageInputSchema>;
-export type MemoryVisibility = z.output<typeof memoryVisibilitySchema>;
-export interface PersonalMemoryPage {
-    memories: PersonalMemoryRecord[];
-    nextCursor?: PersonalMemoryCursor;
-}
-/** Safe provenance attached to one viewer-visible memory. */
-export type PersonalMemoryRecord = MemoryRecord & {
-    origin: "automatic" | "explicit" | "other";
-    sourcePlatform: MemorySourcePlatform;
-    visibility: MemoryVisibility;
-};
-/** Viewer-scoped active memory totals used by the dashboard. */
-export interface PersonalMemoryStats {
-    active: number;
-    automatic: number;
-    createdThirtyDays: number;
-    embedded: number;
-    explicit: number;
-    knowledge: number;
-    personal: number;
-    preference: number;
-    procedure: number;
-    public: number;
-}
-/** Viewer-scoped memory creation totals for one UTC calendar day. */
-export interface PersonalMemoryDay {
-    date: string;
-    personal: number;
-    public: number;
-}
-/** Expected failure when a viewer does not own the requested memory. */
-export declare class PersonalMemoryNotFoundError extends Error {
-    constructor();
-}
-/** Viewer-scoped memory operations shared by dashboard and REST. */
-export interface PersonalMemoryCollection {
-    /** Archive one exact personal memory owned by a linked identity. */
-    archive(id: string): Promise<MemoryRecord>;
-    /** Read one exact memory visible to a linked identity. */
-    get(id: string): Promise<PersonalMemoryRecord>;
-    /** List one stable page across every authorized viewer scope. */
-    list(input: PersonalMemoryPageInput): Promise<PersonalMemoryPage>;
-    /** Summarize active memories across every authorized viewer scope. */
-    stats(): Promise<PersonalMemoryStats>;
-    /** Read memory creation history across every authorized viewer scope. */
-    timeline(input: {
-        days: number;
-    }): Promise<PersonalMemoryDay[]>;
-}
-/** Build storage operations for every memory scope linked to one viewer. */
-export declare function createPersonalMemoryCollection(db: MemoryDb, scopes: {
-    privateScopes: ResolvedMemoryScope[];
-    publicScopes: ResolvedMemoryScope[];
-}, options?: {
-    now?: () => number;
-}): PersonalMemoryCollection;
-export {};

package/dist/personal.d.ts

@@ -1,31 +0,0 @@
-import type { User } from "@sentry/junior-plugin-api";
-import { type MemoryVisibility, type PersonalMemoryRecord } from "./personal-store";
-import type { MemoryDb, MemoryRecord } from "./store";
-import type { MemoryKind } from "./types";
-export interface ViewerMemoryPage {
-    memories: PersonalMemoryRecord[];
-    nextCursor?: string;
-}
-export interface ViewerMemoryPageInput {
-    cursor?: string;
-    kind?: MemoryKind;
-    limit: number;
-    origin?: "automatic" | "explicit";
-    query?: string;
-    visibility?: MemoryVisibility;
-}
-export declare class InvalidMemoryCursorError extends Error {
-    constructor();
-}
-export { PersonalMemoryNotFoundError } from "./personal-store";
-export type { MemoryVisibility, PersonalMemoryRecord } from "./personal-store";
-/** Build viewer memory operations authorized by a user's linked identities. */
-export declare function createViewerMemories(db: MemoryDb, user: User): {
-    archive(id: string): Promise<MemoryRecord>;
-    get(id: string): Promise<PersonalMemoryRecord>;
-    list(input: ViewerMemoryPageInput): Promise<ViewerMemoryPage>;
-    stats(): Promise<import("./personal-store").PersonalMemoryStats>;
-    timeline(input: {
-        days: number;
-    }): Promise<import("./personal-store").PersonalMemoryDay[]>;
-};