@sentry/junior-memory 0.118.0 → 0.120.0

package/src/api.ts

@@ -0,0 +1,168 @@
+/**
+ * Authenticated REST resources for personal memories.
+ *
+ * HTTP identity is one verified viewer. Linked platform actors are resolved
+ * behind the route boundary and used only to authorize personal scopes.
+ */
+import { z } from "zod";
+import {
+  pluginApiRouteRequestContextSchema,
+  type PluginApiRouteRequestContext,
+  type PluginRouteApp,
+  type PluginUserPageActor,
+} from "@sentry/junior-plugin-api";
+import type { MemoryDb, MemoryRecord } from "./store";
+import {
+  createViewerMemories,
+  InvalidMemoryCursorError,
+  PersonalMemoryNotFoundError,
+} from "./personal";
+
+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(),
+  })
+  .strict();
+
+export const memoryListResponseSchema = z
+  .object({
+    memories: z.array(memoryApiSchema),
+    nextCursor: z.string().min(1).optional(),
+  })
+  .strict();
+
+export type MemoryApi = z.output<typeof memoryApiSchema>;
+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 {
+  actors(email: string): Promise<PluginUserPageActor[]>;
+  db: MemoryDb;
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, {
+    headers: { "cache-control": "no-store" },
+    status,
+  });
+}
+
+function apiMemory(memory: MemoryRecord): z.output<typeof memoryApiSchema> {
+  return {
+    content: memory.content,
+    createdAt: new Date(memory.createdAtMs).toISOString(),
+    ...(memory.expiresAtMs !== undefined
+      ? { expiresAt: new Date(memory.expiresAtMs).toISOString() }
+      : {}),
+    id: memory.id,
+    kind: memory.kind,
+    observedAt: new Date(memory.observedAtMs).toISOString(),
+  };
+}
+
+function viewerEmail(
+  context: PluginApiRouteRequestContext | undefined,
+): 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 personal-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";
+      if (!isCollection && !memoryPath) {
+        return json({ error: "Not found." }, 404);
+      }
+
+      const actors = await options.actors(email);
+      const memories = createViewerMemories(options.db, actors);
+      try {
+        if (
+          isCollection &&
+          (request.method === "GET" || request.method === "HEAD")
+        ) {
+          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 memories.list({
+            cursor: query.cursor,
+            limit: query.limit,
+            ...(query.q ? { query: query.q } : {}),
+          });
+          const body = memoryListResponseSchema.parse({
+            memories: page.memories.map(apiMemory),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+          });
+          return request.method === "HEAD"
+            ? new Response(null, {
+                headers: { "cache-control": "no-store" },
+                status: 200,
+              })
+            : json(body);
+        }
+
+        if (
+          memoryPath &&
+          (request.method === "GET" || request.method === "HEAD")
+        ) {
+          const memory = memoryApiSchema.parse(
+            apiMemory(await memories.get(decodeURIComponent(memoryPath[1]!))),
+          );
+          return request.method === "HEAD"
+            ? new Response(null, {
+                headers: { "cache-control": "no-store" },
+                status: 200,
+              })
+            : json(memory);
+        }
+
+        if (memoryPath && request.method === "DELETE") {
+          await memories.archive(decodeURIComponent(memoryPath[1]!));
+          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 PersonalMemoryNotFoundError) {
+          return json({ error: error.message }, 404);
+        }
+        throw error;
+      }
+
+      return json({ error: "Method not allowed." }, 405);
+    },
+  };
+}

package/src/db/schema.ts

@@ -58,6 +58,11 @@ export const juniorMemoryMemories = pgTable(
       .where(
         sql`${table.archivedAtMs} IS NULL AND ${table.expiresAtMs} IS NOT NULL`,
       ),
+    index("junior_memory_memories_search_idx")
+      .using("gin", sql`to_tsvector('english', ${table.content})`)
+      .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(

package/src/index.ts

@@ -1,4 +1,10 @@
-export { createMemoryPlugin, memoryPlugin } from "./plugin";
+export { memoryPlugin } from "./plugin";
+export {
+  memoryApiSchema,
+  memoryListResponseSchema,
+  type MemoryApi,
+  type MemoryListResponse,
+} from "./api";
 export type { MemoryPluginOptions } from "./plugin";
 export { createMemoryStore } from "./store";
 export type {

package/src/personal-store.ts

@@ -0,0 +1,195 @@
+/**
+ * SQL operations over personal memories owned by one authenticated viewer.
+ *
+ * A viewer may resolve to several runtime actors. This store combines their
+ * personal scopes without treating one actor as the canonical identity.
+ */
+import { and, asc, desc, eq, gt, ilike, lt, or, sql } from "drizzle-orm";
+import { z } from "zod";
+import { juniorMemoryEmbeddings, juniorMemoryMemories } from "./db/schema";
+import { deriveMemoryScope, type ResolvedMemoryScope } from "./scope";
+import {
+  activeVisiblePredicate,
+  archiveExpiredMemoryBatch,
+  parseMemoryRow,
+  type MemoryDb,
+  type MemoryRecord,
+} from "./store";
+import type { MemoryRuntimeContext } from "./types";
+
+const nonEmptyStringSchema = z.string().min(1);
+const personalMemoryCursorSchema = z
+  .object({
+    createdAtMs: z.number().finite(),
+    id: nonEmptyStringSchema,
+  })
+  .strict();
+const personalMemoryPageInputSchema = z
+  .object({
+    cursor: personalMemoryCursorSchema.optional(),
+    limit: z.number().int().min(1).max(50),
+    query: z.string().max(200).optional(),
+  })
+  .strict();
+
+export type PersonalMemoryCursor = z.output<typeof personalMemoryCursorSchema>;
+
+export type PersonalMemoryPageInput = z.output<
+  typeof personalMemoryPageInputSchema
+>;
+
+export interface PersonalMemoryPage {
+  memories: MemoryRecord[];
+  nextCursor?: PersonalMemoryCursor;
+}
+
+/** Expected failure when a viewer does not own the requested memory. */
+export class PersonalMemoryNotFoundError extends Error {
+  constructor() {
+    super("Memory was not found for the authenticated viewer.");
+    this.name = "PersonalMemoryNotFoundError";
+  }
+}
+
+/** Viewer-scoped personal memory operations shared by dashboard and REST. */
+export interface PersonalMemoryCollection {
+  /** Archive one exact personal memory owned by a linked actor. */
+  archive(id: string): Promise<MemoryRecord>;
+  /** Read one exact personal memory owned by a linked actor. */
+  get(id: string): Promise<MemoryRecord>;
+  /** List one stable page across every linked personal scope. */
+  list(input: PersonalMemoryPageInput): Promise<PersonalMemoryPage>;
+}
+
+function personalScopes(
+  runtimeContexts: MemoryRuntimeContext[],
+): ResolvedMemoryScope[] {
+  return [
+    ...new Map(
+      runtimeContexts.map((context) => {
+        const scope = deriveMemoryScope(context, "personal");
+        return [`${scope.scope}:${scope.scopeKey}`, scope] as const;
+      }),
+    ).values(),
+  ];
+}
+
+function searchTerms(query: string): string[] {
+  return [
+    ...new Set(
+      query
+        .toLowerCase()
+        .split(/[^a-z0-9_'-]+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2),
+    ),
+  ];
+}
+
+/** Build storage operations for every personal scope linked to one viewer. */
+export function createPersonalMemoryCollection(
+  db: MemoryDb,
+  runtimeContexts: MemoryRuntimeContext[],
+  options: { now?: () => number } = {},
+): PersonalMemoryCollection {
+  const scopes = personalScopes(runtimeContexts);
+  const getNowMs = () => options.now?.() ?? Date.now();
+
+  return {
+    async archive(id) {
+      const memoryId = nonEmptyStringSchema.parse(id);
+      const nowMs = getNowMs();
+      const predicate = activeVisiblePredicate({ nowMs, scopes });
+      if (!predicate) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      const updated = await db
+        .update(juniorMemoryMemories)
+        .set({
+          archivedAtMs: nowMs,
+          archiveReason: "user_removed",
+        })
+        .where(and(predicate, eq(juniorMemoryMemories.id, memoryId)))
+        .returning();
+      if (!updated[0]) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      await db
+        .delete(juniorMemoryEmbeddings)
+        .where(eq(juniorMemoryEmbeddings.memoryId, memoryId));
+      return parseMemoryRow(updated[0]);
+    },
+
+    async get(id) {
+      const memoryId = nonEmptyStringSchema.parse(id);
+      const nowMs = getNowMs();
+      const predicate = activeVisiblePredicate({ nowMs, scopes });
+      if (!predicate) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      const rows = await db
+        .select()
+        .from(juniorMemoryMemories)
+        .where(and(predicate, eq(juniorMemoryMemories.id, memoryId)))
+        .limit(1);
+      if (!rows[0]) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      return parseMemoryRow(rows[0]);
+    },
+
+    async list(input) {
+      input = personalMemoryPageInputSchema.parse(input);
+      const nowMs = getNowMs();
+      await archiveExpiredMemoryBatch({ db, nowMs, scopes });
+      const active = activeVisiblePredicate({ nowMs, scopes });
+      if (!active) {
+        return { memories: [] };
+      }
+
+      const cursor = input.cursor
+        ? or(
+            lt(juniorMemoryMemories.createdAtMs, input.cursor.createdAtMs),
+            and(
+              eq(juniorMemoryMemories.createdAtMs, input.cursor.createdAtMs),
+              gt(juniorMemoryMemories.id, input.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 rows = await db
+        .select()
+        .from(juniorMemoryMemories)
+        .where(and(active, cursor, search))
+        .orderBy(
+          desc(juniorMemoryMemories.createdAtMs),
+          asc(juniorMemoryMemories.id),
+        )
+        .limit(input.limit + 1);
+      const hasNextPage = rows.length > input.limit;
+      const memories = rows.slice(0, input.limit).map(parseMemoryRow);
+      const last = memories.at(-1);
+      return {
+        memories,
+        ...(hasNextPage && last
+          ? {
+              nextCursor: {
+                createdAtMs: last.createdAtMs,
+                id: last.id,
+              },
+            }
+          : {}),
+      };
+    },
+  };
+}

package/src/personal.ts

@@ -0,0 +1,120 @@
+/**
+ * Authenticated-viewer memory access shared by REST and dashboard projections.
+ *
+ * Viewer identity may resolve to multiple platform actors. This module keeps
+ * that federation behind one personal-memory collection.
+ */
+import { z } from "zod";
+import type { PluginUserPageActor } from "@sentry/junior-plugin-api";
+import { createPersonalMemoryCollection } from "./personal-store";
+import type { MemoryDb, MemoryRecord } from "./store";
+import type { MemoryRuntimeContext } from "./types";
+
+const cursorSchema = z
+  .object({
+    createdAtMs: z.number().finite(),
+    id: z.string().min(1),
+    query: z.string().max(200).optional(),
+    version: z.literal(1),
+  })
+  .strict();
+
+export interface ViewerMemoryPage {
+  memories: MemoryRecord[];
+  nextCursor?: string;
+}
+
+export interface ViewerMemoryPageInput {
+  cursor?: string;
+  limit: number;
+  query?: string;
+}
+
+export class InvalidMemoryCursorError extends Error {
+  constructor() {
+    super("Memory cursor is invalid.");
+    this.name = "InvalidMemoryCursorError";
+  }
+}
+
+export { PersonalMemoryNotFoundError } from "./personal-store";
+
+function runtimeContext(actor: PluginUserPageActor): MemoryRuntimeContext {
+  if (actor.platform === "slack") {
+    return {
+      actor,
+      source: {
+        platform: "slack",
+        type: "priv",
+        teamId: actor.teamId,
+        channelId: "DDASHBOARD",
+      },
+    };
+  }
+  return {
+    actor,
+    source: {
+      platform: "local",
+      type: "priv",
+      conversationId: "local:dashboard:memories",
+    },
+  };
+}
+
+function decodeCursor(value: string | undefined, query: string | undefined) {
+  if (!value) return undefined;
+  try {
+    const parsed = cursorSchema.parse(
+      JSON.parse(Buffer.from(value, "base64url").toString("utf8")),
+    );
+    if (parsed.query !== query) {
+      throw new InvalidMemoryCursorError();
+    }
+    return { createdAtMs: parsed.createdAtMs, id: parsed.id };
+  } catch {
+    throw new InvalidMemoryCursorError();
+  }
+}
+
+function encodeCursor(
+  cursor: { createdAtMs: number; id: string },
+  query: string | undefined,
+): string {
+  return Buffer.from(
+    JSON.stringify({ ...cursor, ...(query ? { query } : {}), version: 1 }),
+    "utf8",
+  ).toString("base64url");
+}
+
+/** Build personal-memory operations authorized by a viewer's linked actors. */
+export function createViewerMemories(
+  db: MemoryDb,
+  actors: PluginUserPageActor[],
+) {
+  const collection = createPersonalMemoryCollection(
+    db,
+    actors.map(runtimeContext),
+  );
+  return {
+    async archive(id: string): Promise<MemoryRecord> {
+      return await collection.archive(id);
+    },
+    async get(id: string): Promise<MemoryRecord> {
+      return await collection.get(id);
+    },
+    async list(input: ViewerMemoryPageInput): Promise<ViewerMemoryPage> {
+      const query = input.query?.trim() || undefined;
+      const page = await collection.list({
+        cursor: decodeCursor(input.cursor, query),
+        limit: input.limit,
+        ...(query ? { query } : {}),
+      });
+      return {
+        memories: page.memories,
+        ...(page.nextCursor
+          ? { nextCursor: encodeCursor(page.nextCursor, query) }
+          : {}),
+      };
+    },
+  };
+}

package/src/plugin.ts

@@ -1,5 +1,6 @@
 import { defineJuniorPlugin } from "@sentry/junior-plugin-api";
 import { createMemoryAgent } from "./agent";
+import { createMemoryApi } from "./api";
 import { createMemoryCliCommand } from "./cli";
 import {
   createMemoryCreateTool,
@@ -85,8 +86,8 @@ function memoryCreateToolContext(ctx: {
   };
 }
 
-/** Create Junior's long-term memory plugin registration. */
-export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
+/** Register Junior's long-term memory plugin. */
+export function memoryPlugin(options: MemoryPluginOptions = {}) {
   const modelId = memoryModelId(options);
   return defineJuniorPlugin({
     manifest: {
@@ -110,6 +111,12 @@ export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
     },
     userPages: [createMemoryUserPage()],
     hooks: {
+      apiRoutes(ctx) {
+        return createMemoryApi({
+          actors: ctx.viewer.actors,
+          db: ctx.db as MemoryDb,
+        });
+      },
       tools(ctx) {
         const agent = createMemoryAgent(ctx.model);
         const context = memoryToolContext({
@@ -135,10 +142,12 @@ export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
       },
       async userPrompt(ctx) {
         return await createMemoryPromptContributions({
+          agent: createMemoryAgent(ctx.model),
           ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
           ...(ctx.actor ? { actor: ctx.actor } : {}),
           db: ctx.db as MemoryDb,
           embedder: ctx.embedder,
+          log: ctx.log,
           maxVectorDistance: recallMaxVectorDistance(options),
           source: ctx.source,
           text: ctx.text,
@@ -147,5 +156,3 @@ export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
     },
   });
 }
-
-export const memoryPlugin = createMemoryPlugin();

package/src/ranking.ts

@@ -0,0 +1,98 @@
+import type { MemoryRecord } from "./store";
+
+const RECIPROCAL_RANK_FUSION_K = 60;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+export interface MemoryMatch {
+  exactIdentifier: boolean;
+  lexical?: {
+    rank: number;
+  };
+  memory: MemoryRecord;
+  sourceKey: string;
+  vector?: {
+    rank: number;
+  };
+}
+
+function reciprocalRank(rank: number): number {
+  return 1 / (RECIPROCAL_RANK_FUSION_K + rank);
+}
+
+function matchScore(match: MemoryMatch): number {
+  return (
+    (match.vector ? reciprocalRank(match.vector.rank) : 0) +
+    (match.lexical ? reciprocalRank(match.lexical.rank) : 0)
+  );
+}
+
+function currentChannel(
+  match: Pick<MemoryMatch, "sourceKey">,
+  channelPrefix: string | undefined,
+): boolean {
+  return channelPrefix ? match.sourceKey.startsWith(channelPrefix) : false;
+}
+
+function observedAgeRank(memory: MemoryRecord, nowMs: number): number {
+  const ageMs = Math.max(0, nowMs - memory.observedAtMs);
+  if (ageMs <= 7 * ONE_DAY_MS) {
+    return 3;
+  }
+  if (ageMs <= 30 * ONE_DAY_MS) {
+    return 2;
+  }
+  if (ageMs <= 90 * ONE_DAY_MS) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Keep exact structured-identifier matches in the strongest relevance tier,
+ * then fuse lexical and vector ranks without comparing provider raw scores.
+ */
+export function rankMemoryMatches(
+  matches: MemoryMatch[],
+  options: {
+    channelPrefix?: string;
+    nowMs: number;
+  },
+): MemoryMatch[] {
+  const byId = new Map<string, MemoryMatch>();
+  for (const match of matches) {
+    const existing = byId.get(match.memory.id);
+    if (!existing) {
+      byId.set(match.memory.id, match);
+      continue;
+    }
+    byId.set(match.memory.id, {
+      ...existing,
+      exactIdentifier: existing.exactIdentifier || match.exactIdentifier,
+      ...(match.lexical ? { lexical: match.lexical } : {}),
+      ...(match.vector ? { vector: match.vector } : {}),
+    });
+  }
+  return [...byId.values()].sort((left, right) => {
+    const identifierDelta =
+      Number(right.exactIdentifier) - Number(left.exactIdentifier);
+    if (identifierDelta !== 0) {
+      return identifierDelta;
+    }
+    const scoreDelta = matchScore(right) - matchScore(left);
+    if (scoreDelta !== 0) {
+      return scoreDelta;
+    }
+    const channelDelta =
+      Number(currentChannel(right, options.channelPrefix)) -
+      Number(currentChannel(left, options.channelPrefix));
+    if (channelDelta !== 0) {
+      return channelDelta;
+    }
+    return (
+      observedAgeRank(right.memory, options.nowMs) -
+        observedAgeRank(left.memory, options.nowMs) ||
+      right.memory.observedAtMs - left.memory.observedAtMs ||
+      left.memory.id.localeCompare(right.memory.id)
+    );
+  });
+}