@sentry/junior-memory 0.197.0 → 0.199.0

package/src/api.ts

@@ -1,288 +0,0 @@
-/**
- * Authenticated REST access to memory.
- *
- * The signed-in User can read public memory and private memory that they own.
- */
-import { z } from "zod";
-import {
-  pluginApiRouteRequestContextSchema,
-  type PluginConversationEventStats,
-  type PluginRouteApp,
-  type User,
-} from "@sentry/junior-plugin-api";
-import type { MemoryDb } from "./store";
-import {
-  archiveMemory,
-  getMemory,
-  getMemoryStats,
-  getMemoryTimeline,
-  getMemoryTimelineHours,
-  InvalidMemoryCursorError,
-  listMemories,
-  MemoryNotFoundError,
-  type MemoryView,
-} from "./viewer";
-import { MEMORY_SOURCE_PLATFORMS } from "./types";
-
-export const memoryApiSchema = z
-  .object({
-    content: z.string().min(1),
-    createdAt: z.iso.datetime(),
-    expiresAt: z.iso.datetime().optional(),
-    id: z.string().min(1),
-    kind: z.enum(["preference", "procedure", "knowledge"]),
-    observedAt: z.iso.datetime(),
-    origin: z.enum(["automatic", "explicit", "other"]),
-    sourcePlatform: z.enum(MEMORY_SOURCE_PLATFORMS),
-    visibility: z.enum(["private", "public"]),
-  })
-  .strict();
-
-export const memoryListResponseSchema = z
-  .object({
-    memories: z.array(memoryApiSchema),
-    nextCursor: z.string().min(1).optional(),
-  })
-  .strict();
-
-const memoryBucketSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2})?$/);
-
-const memoryDashboardDaySchema = z
-  .object({
-    date: memoryBucketSchema,
-    personal: z.number().int().min(0),
-    public: z.number().int().min(0),
-  })
-  .strict();
-
-const memoryCostDaySchema = z
-  .object({
-    costUsd: z.number().finite().nonnegative(),
-    date: memoryBucketSchema,
-    events: z.number().int().min(0),
-  })
-  .strict();
-
-export const memoryDashboardResponseSchema = z
-  .object({
-    days: z.array(memoryDashboardDaySchema).length(90),
-    extractionDays: z.array(memoryCostDaySchema).length(90),
-    extractionHours: z.array(memoryCostDaySchema).min(24).optional(),
-    generatedAt: z.iso.datetime(),
-    hours: z.array(memoryDashboardDaySchema).min(24).optional(),
-    recallDays: z.array(memoryCostDaySchema).length(90),
-    recallHours: z.array(memoryCostDaySchema).min(24).optional(),
-    stats: z
-      .object({
-        active: z.number().int().min(0),
-        automatic: z.number().int().min(0),
-        createdThirtyDays: z.number().int().min(0),
-        embedded: z.number().int().min(0),
-        explicit: z.number().int().min(0),
-        knowledge: z.number().int().min(0),
-        personal: z.number().int().min(0),
-        preference: z.number().int().min(0),
-        procedure: z.number().int().min(0),
-        public: z.number().int().min(0),
-      })
-      .strict(),
-  })
-  .strict();
-
-export type MemoryApi = z.output<typeof memoryApiSchema>;
-export type MemoryDashboardResponse = z.output<
-  typeof memoryDashboardResponseSchema
->;
-export type MemoryListResponse = z.output<typeof memoryListResponseSchema>;
-
-const memoryListQuerySchema = z
-  .object({
-    cursor: z.string().min(1).max(1_000).optional(),
-    limit: z.coerce.number().int().min(1).max(50).default(25),
-    q: z.string().trim().max(200).optional(),
-  })
-  .strict();
-
-interface MemoryApiOptions {
-  db: MemoryDb;
-  eventStats: PluginConversationEventStats;
-  users: {
-    resolve(email: string): Promise<User | undefined>;
-  };
-}
-
-function json(body: unknown, status = 200): Response {
-  return Response.json(body, {
-    headers: { "cache-control": "no-store" },
-    status,
-  });
-}
-
-function apiMemory(memory: MemoryView): z.output<typeof memoryApiSchema> {
-  return {
-    content: memory.content,
-    createdAt: new Date(memory.createdAtMs).toISOString(),
-    ...(memory.expiresAtMs !== undefined
-      ? { expiresAt: new Date(memory.expiresAtMs).toISOString() }
-      : undefined),
-    id: memory.id,
-    kind: memory.kind,
-    observedAt: new Date(memory.observedAtMs).toISOString(),
-    origin: memory.origin,
-    sourcePlatform: memory.sourcePlatform,
-    visibility: memory.visibility,
-  };
-}
-
-function viewerEmail(context: unknown): string | undefined {
-  const parsed = pluginApiRouteRequestContextSchema.safeParse(context);
-  if (!parsed.success || parsed.data.auth.user.emailVerified !== true) {
-    return undefined;
-  }
-  return parsed.data.auth.user.email?.trim().toLowerCase() || undefined;
-}
-
-/** Create the authenticated memory REST app. */
-export function createMemoryApi(options: MemoryApiOptions): PluginRouteApp {
-  return {
-    async fetch(request, context) {
-      const email = viewerEmail(context);
-      if (!email) {
-        return json({ error: "Authentication required." }, 401);
-      }
-
-      const url = new URL(request.url);
-      const memoryPath = /^\/memories\/([^/]+)$/.exec(url.pathname);
-      const isCollection = url.pathname === "/memories";
-      const isDashboard = url.pathname === "/dashboard";
-      if (!isCollection && !isDashboard && !memoryPath) {
-        return json({ error: "Not found." }, 404);
-      }
-      const isRead = request.method === "GET" || request.method === "HEAD";
-      if (!isRead && !(memoryPath && request.method === "DELETE")) {
-        return json({ error: "Method not allowed." }, 405);
-      }
-
-      const viewer = await options.users.resolve(email);
-      if (!viewer) return json({ error: "Authentication required." }, 401);
-      const userId = viewer.id;
-
-      try {
-        if (isDashboard && isRead) {
-          const [
-            stats,
-            days,
-            hours,
-            extractionDays,
-            extractionHours,
-            recallDays,
-            recallHours,
-          ] = await Promise.all([
-            getMemoryStats(options.db, userId),
-            getMemoryTimeline(options.db, userId, 90),
-            getMemoryTimelineHours(options.db, userId, 7 * 24),
-            options.eventStats.costsByDay({
-              days: 90,
-              eventName: "memories_captured",
-            }),
-            options.eventStats.costsByHour({
-              eventName: "memories_captured",
-              hours: 7 * 24,
-            }),
-            options.eventStats.costsByDay({
-              days: 90,
-              eventName: "memories_recalled",
-            }),
-            options.eventStats.costsByHour({
-              eventName: "memories_recalled",
-              hours: 7 * 24,
-            }),
-          ]);
-          const { private: personal, ...dashboardStats } = stats;
-          const body = memoryDashboardResponseSchema.parse({
-            days: days.map(({ private: personal, ...day }) => ({
-              ...day,
-              personal,
-            })),
-            extractionDays,
-            extractionHours,
-            generatedAt: new Date().toISOString(),
-            hours: hours.map(({ private: personal, ...day }) => ({
-              ...day,
-              personal,
-            })),
-            recallDays,
-            recallHours,
-            stats: { ...dashboardStats, personal },
-          });
-          return request.method === "HEAD"
-            ? new Response(null, {
-                headers: { "cache-control": "no-store" },
-                status: 200,
-              })
-            : json(body);
-        }
-
-        if (isCollection && isRead) {
-          const query = memoryListQuerySchema.parse({
-            cursor: url.searchParams.get("cursor") ?? undefined,
-            limit: url.searchParams.get("limit") ?? undefined,
-            q: url.searchParams.get("q") ?? undefined,
-          });
-          const page = await listMemories(options.db, userId, {
-            cursor: query.cursor,
-            limit: query.limit,
-            ...(query.q ? { query: query.q } : undefined),
-          });
-          const body = memoryListResponseSchema.parse({
-            memories: page.memories.map(apiMemory),
-            ...(page.nextCursor ? { nextCursor: page.nextCursor } : undefined),
-          });
-          return request.method === "HEAD"
-            ? new Response(null, {
-                headers: { "cache-control": "no-store" },
-                status: 200,
-              })
-            : json(body);
-        }
-
-        if (memoryPath && isRead) {
-          const memory = await getMemory(
-            options.db,
-            userId,
-            decodeURIComponent(memoryPath[1]!),
-          );
-          const body = memoryApiSchema.parse(apiMemory(memory));
-          return request.method === "HEAD"
-            ? new Response(null, {
-                headers: { "cache-control": "no-store" },
-                status: 200,
-              })
-            : json(body);
-        }
-
-        if (memoryPath && request.method === "DELETE") {
-          const id = decodeURIComponent(memoryPath[1]!);
-          await archiveMemory(options.db, userId, id);
-          return new Response(null, {
-            headers: { "cache-control": "no-store" },
-            status: 204,
-          });
-        }
-      } catch (error) {
-        if (
-          error instanceof z.ZodError ||
-          error instanceof InvalidMemoryCursorError
-        ) {
-          return json({ error: "Invalid memory request." }, 400);
-        }
-        if (error instanceof MemoryNotFoundError) {
-          return json({ error: error.message }, 404);
-        }
-        throw error;
-      }
-
-      return json({ error: "Method not allowed." }, 405);
-    },
-  };
-}

package/src/cli/format.ts

@@ -1,30 +0,0 @@
-import type { juniorMemoryMemories } from "../db/schema";
-
-function formatDate(ms: number | null): string {
-  return ms === null ? "-" : new Date(ms).toISOString();
-}
-
-/** Format a memory row as an operator-safe CLI projection. */
-export function formatMemory(
-  row: typeof juniorMemoryMemories.$inferSelect,
-  args: {
-    showContent: boolean;
-  },
-): string {
-  const lines = [
-    `id=${row.id}`,
-    `scope=${row.scope}`,
-    `scope_key=${row.scopeKey}`,
-    `subject_type=${row.subjectType}`,
-    ...(row.subjectKey ? [`subject_key=${row.subjectKey}`] : []),
-    `kind=${row.kind}`,
-    `created_at=${formatDate(row.createdAtMs)}`,
-    `observed_at=${formatDate(row.observedAtMs)}`,
-    `expires_at=${formatDate(row.expiresAtMs)}`,
-    `archived_at=${formatDate(row.archivedAtMs)}`,
-  ];
-  if (args.showContent) {
-    lines.push(`content=${row.content}`);
-  }
-  return lines.join("\n");
-}

package/src/cli/index.ts

@@ -1,15 +0,0 @@
-import type { PluginCliCommandDefinition } from "@sentry/junior-plugin-api";
-import { configureMemorySearchCommand } from "./search";
-import { configureMemoryShowCommand } from "./show";
-
-/** Create the plugin-owned memory admin CLI command. */
-export function createMemoryCliCommand(): PluginCliCommandDefinition {
-  return {
-    name: "memory",
-    summary: "Inspect Junior memory state",
-    configure(command, junior) {
-      configureMemorySearchCommand(command, junior);
-      configureMemoryShowCommand(command, junior);
-    },
-  };
-}

package/src/cli/search.ts

@@ -1,119 +0,0 @@
-import { InvalidArgumentError, Option, type Command } from "commander";
-import { and, desc, eq, gt, ilike, isNull, or, type SQL } from "drizzle-orm";
-import type {
-  PluginCliActionContext,
-  PluginCliHost,
-} from "@sentry/junior-plugin-api";
-import { juniorMemoryMemories } from "../db/schema";
-import type { MemoryDb } from "../store";
-import { MEMORY_SCOPES, type MemoryScope } from "../types";
-import { formatMemory } from "./format";
-
-interface SearchOptions {
-  limit: number;
-  scope: MemoryScope;
-  scopeKey: string;
-  showContent?: boolean;
-}
-
-function parseLimit(value: string): number {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed)) {
-    throw new InvalidArgumentError("--limit must be a number");
-  }
-  return Math.min(100, Math.max(1, Math.floor(parsed)));
-}
-
-async function runSearch(
-  ctx: PluginCliActionContext,
-  queryParts: string[] | undefined,
-  options: SearchOptions,
-): Promise<number> {
-  const query = (queryParts ?? []).join(" ").trim();
-  const nowMs = Date.now();
-  const terms = [
-    ...new Set(
-      query
-        .toLowerCase()
-        .split(/[^a-z0-9_'-]+/)
-        .map((term) => term.trim())
-        .filter((term) => term.length >= 2),
-    ),
-  ];
-
-  const db = ctx.db as MemoryDb;
-  const activeExpirationPredicate = or(
-    isNull(juniorMemoryMemories.expiresAtMs),
-    gt(juniorMemoryMemories.expiresAtMs, nowMs),
-  );
-  const predicates: SQL[] = [
-    eq(juniorMemoryMemories.scope, options.scope),
-    eq(juniorMemoryMemories.scopeKey, options.scopeKey),
-    isNull(juniorMemoryMemories.archivedAtMs),
-    isNull(juniorMemoryMemories.supersededAtMs),
-    isNull(juniorMemoryMemories.supersededById),
-  ];
-  if (activeExpirationPredicate) {
-    predicates.push(activeExpirationPredicate);
-  }
-  if (terms.length > 0) {
-    const termPredicate = or(
-      ...terms.map((term) => ilike(juniorMemoryMemories.content, `%${term}%`)),
-    );
-    if (termPredicate) {
-      predicates.push(termPredicate);
-    }
-  }
-  const rows = await db
-    .select()
-    .from(juniorMemoryMemories)
-    .where(and(...predicates))
-    .orderBy(desc(juniorMemoryMemories.createdAtMs))
-    .limit(options.limit);
-
-  if (rows.length === 0) {
-    await ctx.io.writeOutput("No memories matched.\n");
-    return 0;
-  }
-
-  await ctx.io.writeOutput(
-    `${rows
-      .map((row) =>
-        formatMemory(row, { showContent: Boolean(options.showContent) }),
-      )
-      .join("\n\n")}\n`,
-  );
-  return 0;
-}
-
-/** Wire the memory search admin subcommand under the plugin namespace. */
-export function configureMemorySearchCommand(
-  parent: Command,
-  junior: PluginCliHost,
-): void {
-  parent
-    .command("search")
-    .description("Search visible memories")
-    .argument("[query...]", "Search query")
-    .addOption(
-      new Option("--scope <scope>", "Memory scope")
-        .choices([...MEMORY_SCOPES])
-        .makeOptionMandatory(),
-    )
-    .requiredOption("--scope-key <key>", "Scope key")
-    .addOption(
-      new Option("--limit <n>", "Maximum rows")
-        .argParser(parseLimit)
-        .default(20),
-    )
-    .option("--show-content", "Print raw memory content")
-    .action(
-      junior.action(async (ctx, queryParts, options) => {
-        return await runSearch(
-          ctx,
-          queryParts as string[] | undefined,
-          options as SearchOptions,
-        );
-      }),
-    );
-}

package/src/cli/show.ts

@@ -1,44 +0,0 @@
-import type { Command } from "commander";
-import type {
-  PluginCliActionContext,
-  PluginCliHost,
-} from "@sentry/junior-plugin-api";
-import { eq } from "drizzle-orm";
-import { juniorMemoryMemories } from "../db/schema";
-import type { MemoryDb } from "../store";
-import { formatMemory } from "./format";
-
-async function runShow(
-  ctx: PluginCliActionContext,
-  id: string,
-): Promise<number> {
-  const db = ctx.db as MemoryDb;
-  const rows = await db
-    .select()
-    .from(juniorMemoryMemories)
-    .where(eq(juniorMemoryMemories.id, id))
-    .limit(1);
-  if (!rows[0]) {
-    await ctx.io.writeError(`Memory not found: ${id}\n`);
-    return 1;
-  }
-
-  await ctx.io.writeOutput(`${formatMemory(rows[0], { showContent: true })}\n`);
-  return 0;
-}
-
-/** Wire the explicit raw-content memory inspection subcommand. */
-export function configureMemoryShowCommand(
-  parent: Command,
-  junior: PluginCliHost,
-): void {
-  parent
-    .command("show")
-    .description("Show one memory")
-    .argument("<id>", "Memory id")
-    .action(
-      junior.action(async (ctx, id) => {
-        return await runShow(ctx, id as string);
-      }),
-    );
-}

package/src/db/schema.ts

@@ -1,147 +0,0 @@
-/**
- * Drizzle source of truth for memory plugin SQL migrations.
- *
- * Update this schema first, then regenerate packaged migrations with
- * `pnpm --filter @sentry/junior-memory db:generate`.
- */
-import { sql } from "drizzle-orm";
-import {
-  bigint,
-  check,
-  customType,
-  index,
-  integer,
-  pgTable,
-  text,
-  uniqueIndex,
-  vector,
-} from "drizzle-orm/pg-core";
-import {
-  MEMORY_EMBEDDING_DIMENSIONS,
-  MEMORY_EMBEDDING_METRICS,
-  MEMORY_SCOPES,
-  MEMORY_SOURCE_PLATFORMS,
-  MEMORY_SUBJECT_TYPES,
-  MEMORY_KINDS,
-} from "../types";
-
-const tsvector = customType<{ data: string }>({
-  dataType() {
-    return "tsvector";
-  },
-});
-
-export const juniorMemoryMemories = pgTable(
-  "junior_memory_memories",
-  {
-    id: text("id").primaryKey(),
-    scope: text("scope", { enum: MEMORY_SCOPES }).notNull(),
-    scopeKey: text("scope_key").notNull(),
-    kind: text("type", { enum: MEMORY_KINDS }).notNull(),
-    subjectType: text("subject_type", { enum: MEMORY_SUBJECT_TYPES }).notNull(),
-    subjectKey: text("subject_key"),
-    content: text("content").notNull(),
-    searchVector: tsvector("search_vector").generatedAlwaysAs(
-      sql`to_tsvector('english', "content")`,
-    ),
-    sourcePlatform: text("source_platform", {
-      enum: MEMORY_SOURCE_PLATFORMS,
-    }).notNull(),
-    sourceKey: text("source_key").notNull(),
-    /** Location where Junior learned the memory, when known. */
-    locationId: text("location_id"),
-    idempotencyKey: text("idempotency_key"),
-    observedAtMs: bigint("observed_at_ms", { mode: "number" }).notNull(),
-    createdAtMs: bigint("created_at_ms", { mode: "number" }).notNull(),
-    expiresAtMs: bigint("expires_at_ms", { mode: "number" }),
-    supersededAtMs: bigint("superseded_at_ms", { mode: "number" }),
-    supersededById: text("superseded_by_id"),
-    archivedAtMs: bigint("archived_at_ms", { mode: "number" }),
-    archiveReason: text("archive_reason"),
-  },
-  (table) => [
-    index("junior_memory_memories_visible_idx")
-      .on(table.scope, table.scopeKey, table.createdAtMs.desc(), table.id)
-      .where(
-        sql`${table.archivedAtMs} IS NULL AND ${table.supersededAtMs} IS NULL AND ${table.supersededById} IS NULL`,
-      ),
-    index("junior_memory_memories_expiration_idx")
-      .on(table.expiresAtMs)
-      .where(
-        sql`${table.archivedAtMs} IS NULL AND ${table.expiresAtMs} IS NOT NULL`,
-      ),
-    index("junior_memory_memories_search_idx")
-      .using("gin", table.scope, table.scopeKey, table.searchVector)
-      .where(
-        sql`${table.archivedAtMs} IS NULL AND ${table.supersededAtMs} IS NULL AND ${table.supersededById} IS NULL`,
-      ),
-    uniqueIndex("junior_memory_memories_idempotency_idx")
-      .on(table.scope, table.scopeKey, table.idempotencyKey)
-      .where(
-        sql`${table.idempotencyKey} IS NOT NULL AND ${table.archivedAtMs} IS NULL AND ${table.supersededAtMs} IS NULL AND ${table.supersededById} IS NULL`,
-      ),
-    check(
-      "junior_memory_memories_scope_check",
-      sql`${table.scope} IN ('private', 'public')`,
-    ),
-    check(
-      "junior_memory_memories_kind_check",
-      sql`${table.kind} IN (
-        'preference',
-        'procedure',
-        'knowledge'
-      )`,
-    ),
-    check(
-      "junior_memory_memories_subject_type_check",
-      sql`${table.subjectType} IN ('user', 'conversation', 'general')`,
-    ),
-    check(
-      "junior_memory_memories_subject_key_check",
-      sql`(${table.subjectType} = 'general' AND ${table.subjectKey} IS NULL) OR (${table.subjectType} IN ('user', 'conversation') AND ${table.subjectKey} IS NOT NULL AND length(${table.subjectKey}) > 0)`,
-    ),
-    check(
-      "junior_memory_memories_source_platform_check",
-      sql`${table.sourcePlatform} IN ('slack', 'local', 'web')`,
-    ),
-  ],
-);
-
-export const juniorMemoryEmbeddings = pgTable(
-  "junior_memory_embeddings",
-  {
-    memoryId: text("memory_id")
-      .primaryKey()
-      .references(() => juniorMemoryMemories.id, { onDelete: "cascade" }),
-    provider: text("provider").notNull(),
-    model: text("model").notNull(),
-    dimensions: integer("dimensions").notNull(),
-    metric: text("metric", { enum: MEMORY_EMBEDDING_METRICS }).notNull(),
-    contentHash: text("content_hash").notNull(),
-    embedding: vector("embedding", {
-      dimensions: MEMORY_EMBEDDING_DIMENSIONS,
-    }).notNull(),
-    createdAtMs: bigint("created_at_ms", { mode: "number" }).notNull(),
-  },
-  (table) => [
-    index("junior_memory_embeddings_model_idx").on(
-      table.provider,
-      table.model,
-      table.dimensions,
-      table.metric,
-    ),
-    // Cosine ANN for vector recall/search. Ops must match cosineDistance (<=>).
-    // Keep this unfiltered so planners can use HNSW before scope/status joins.
-    index("junior_memory_embeddings_embedding_hnsw_idx")
-      .using("hnsw", table.embedding.op("vector_cosine_ops"))
-      .with({ m: 16, ef_construction: 64 }),
-    check(
-      "junior_memory_embeddings_metric_check",
-      sql`${table.metric} IN ('cosine')`,
-    ),
-    check(
-      "junior_memory_embeddings_dimensions_check",
-      sql`${table.dimensions} = ${sql.raw(String(MEMORY_EMBEDDING_DIMENSIONS))}`,
-    ),
-  ],
-);