@sentry/junior-memory 0.76.0

package/src/db/schema.ts

@@ -0,0 +1,130 @@
+/**
+ * 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,
+  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_TYPES,
+} from "../types";
+
+export const juniorMemoryMemories = pgTable(
+  "junior_memory_memories",
+  {
+    id: text("id").primaryKey(),
+    scope: text("scope", { enum: MEMORY_SCOPES }).notNull(),
+    scopeKey: text("scope_key").notNull(),
+    type: text("type", { enum: MEMORY_TYPES }).notNull(),
+    subjectType: text("subject_type", { enum: MEMORY_SUBJECT_TYPES }).notNull(),
+    subjectKey: text("subject_key"),
+    content: text("content").notNull(),
+    sourcePlatform: text("source_platform", {
+      enum: MEMORY_SOURCE_PLATFORMS,
+    }).notNull(),
+    sourceKey: text("source_key").notNull(),
+    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`,
+      ),
+    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 ('personal', 'conversation')`,
+    ),
+    check(
+      "junior_memory_memories_type_check",
+      sql`${table.type} IN (
+        'preference',
+        'identity',
+        'relationship',
+        'knowledge',
+        'context',
+        'event',
+        'task',
+        'observation'
+      )`,
+    ),
+    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')`,
+    ),
+  ],
+);
+
+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,
+    ),
+    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))}`,
+    ),
+  ],
+);

package/src/index.ts

@@ -0,0 +1,16 @@
+export { createMemoryPlugin, memoryPlugin } from "./plugin";
+export type { MemoryPluginOptions } from "./plugin";
+export { createMemoryStore } from "./store";
+export type {
+  ArchiveMemoryInput,
+  CreateMemoryInput,
+  CreateMemoryResult,
+  ListMemoriesInput,
+  MemoryDb,
+  MemoryEmbeddingProvider,
+  MemoryRecord,
+  MemoryStore,
+  MemoryStoreOptions,
+  SearchMemoriesInput,
+} from "./store";
+export type { MemoryRuntimeContext } from "./types";

package/src/plugin.ts

@@ -0,0 +1,103 @@
+import { defineJuniorPlugin } from "@sentry/junior-plugin-api";
+import { createMemoryAgent } from "./agent";
+import { createMemoryCliCommand } from "./cli";
+import {
+  createMemoryCreateTool,
+  createMemoryListTool,
+  createMemoryRemoveTool,
+  createMemorySearchTool,
+  type MemoryReviewer,
+  type MemoryToolContext,
+} from "./tools";
+import { processMemorySession } from "./process-session";
+import { createMemoryPromptMessages } from "./recall";
+import type { MemoryDb } from "./store";
+
+const MEMORY_MODEL_ENV = "AI_MEMORY_MODEL";
+
+export interface MemoryPluginOptions {
+  modelId?: string;
+}
+
+function memoryModelId(options: MemoryPluginOptions): string | undefined {
+  const explicitModelId = options.modelId?.trim();
+  if (explicitModelId) {
+    return explicitModelId;
+  }
+  const envModelId = process.env[MEMORY_MODEL_ENV]?.trim();
+  return envModelId || undefined;
+}
+
+function memoryToolContext(ctx: {
+  agent: MemoryReviewer;
+  conversationId?: string;
+  db: MemoryToolContext["db"];
+  embedder?: MemoryToolContext["embedder"];
+  requester?: MemoryToolContext["requester"];
+  source: MemoryToolContext["source"];
+  userText?: string;
+}): MemoryToolContext {
+  return {
+    agent: ctx.agent,
+    ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+    ...(ctx.requester ? { requester: ctx.requester } : {}),
+    db: ctx.db,
+    ...(ctx.embedder ? { embedder: ctx.embedder } : {}),
+    source: ctx.source,
+    ...(ctx.userText ? { userText: ctx.userText } : {}),
+  };
+}
+
+/** Create Junior's long-term memory plugin registration. */
+export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
+  const modelId = memoryModelId(options);
+  return defineJuniorPlugin({
+    manifest: {
+      name: "memory",
+      displayName: "Memory",
+      description: "Long-term Junior memory storage and recall",
+    },
+    model: modelId
+      ? { structuredModelId: modelId }
+      : { structuredModel: "default" },
+    packageName: "@sentry/junior-memory",
+    cli: {
+      commands: [createMemoryCliCommand()],
+    },
+    tasks: {
+      processSession: {
+        async run(ctx) {
+          await processMemorySession(ctx);
+        },
+      },
+    },
+    hooks: {
+      tools(ctx) {
+        const context = memoryToolContext({
+          ...ctx,
+          agent: createMemoryAgent(ctx.model),
+          db: ctx.db as MemoryDb,
+          embedder: ctx.embedder,
+        });
+        return {
+          createMemory: createMemoryCreateTool(context),
+          removeMemory: createMemoryRemoveTool(context),
+          listMemories: createMemoryListTool(context),
+          searchMemories: createMemorySearchTool(context),
+        };
+      },
+      async userPrompt(ctx) {
+        return await createMemoryPromptMessages({
+          ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+          ...(ctx.requester ? { requester: ctx.requester } : {}),
+          db: ctx.db as MemoryDb,
+          embedder: ctx.embedder,
+          source: ctx.source,
+          text: ctx.text,
+        });
+      },
+    },
+  });
+}
+
+export const memoryPlugin = createMemoryPlugin();

package/src/process-session.ts

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import {
+  getSourceKey,
+  isPrivateSource,
+  type PluginTaskContext,
+} from "@sentry/junior-plugin-api";
+import { z } from "zod";
+import {
+  createMemoryStore,
+  type CreateMemoryInput,
+  type MemoryDb,
+} from "./store";
+import { createMemoryAgent, type ExtractedMemory } from "./agent";
+import { memoryRuntimeContextSchema } from "./types";
+
+const MEMORY_TOOL_NAMES = new Set([
+  "createMemory",
+  "listMemories",
+  "removeMemory",
+  "searchMemories",
+]);
+const MEMORY_TASK_STATE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const extractedMemoryCacheSchema = z.array(
+  z
+    .object({
+      content: z.string().min(1),
+      expiresAtMs: z.number().finite().nullable(),
+      target: z.enum(["requester", "conversation"]),
+    })
+    .strict(),
+);
+
+function memoryIdempotencySuffix(memory: ExtractedMemory): string {
+  return createHash("sha256")
+    .update(memory.target)
+    .update("\0")
+    .update(memory.content)
+    .update("\0")
+    .update(memory.expiresAtMs === null ? "never" : String(memory.expiresAtMs))
+    .digest("hex")
+    .slice(0, 32);
+}
+
+function passiveInput(
+  sessionId: string,
+  memory: ExtractedMemory,
+  sourceKey: string,
+): CreateMemoryInput {
+  return {
+    content: memory.content,
+    idempotencyKey: `session:${sourceKey}:${sessionId}:${memoryIdempotencySuffix(memory)}`,
+    ...(memory.expiresAtMs !== null ? { expiresAtMs: memory.expiresAtMs } : {}),
+  };
+}
+
+async function getTaskMemories(
+  context: PluginTaskContext,
+  extract: () => Promise<ExtractedMemory[]>,
+): Promise<ExtractedMemory[]> {
+  const cacheKey = `memory-extraction:${context.id}`;
+  const cached = await context.state.get(cacheKey);
+  if (cached !== undefined) {
+    return extractedMemoryCacheSchema.parse(cached);
+  }
+  const memories = await extract();
+  if (memories.length > 0) {
+    await context.state.set(cacheKey, memories, MEMORY_TASK_STATE_TTL_MS);
+  }
+  return memories;
+}
+
+/**
+ * Extract and store memories from a completed session plugin task.
+ *
+ * Memory owns post-session extraction and consumes only the bounded plugin task
+ * projection. Explicit memory tools and private non-local sources remain hard
+ * boundaries so background retries cannot reinterpret user-directed mutations
+ * or private conversations.
+ */
+export async function processMemorySession(
+  context: PluginTaskContext,
+): Promise<void> {
+  const run = await context.run.load();
+  // Memory tool turns already own memory management or recall; do not reinterpret
+  // recalled memory output as fresh passive-learning evidence.
+  if (
+    run.transcript.some(
+      (entry) =>
+        entry.type === "toolResult" && MEMORY_TOOL_NAMES.has(entry.toolName),
+    )
+  ) {
+    return;
+  }
+  // V1 passive learning only stores public channel facts outside local QA.
+  if (run.source.platform !== "local" && isPrivateSource(run.source)) {
+    return;
+  }
+  const sourceKey = getSourceKey(run.source);
+  if (!sourceKey) {
+    return;
+  }
+  const transcript = run.transcript
+    .filter((entry) => entry.text?.trim())
+    .map((entry) => ({ ...entry, text: entry.text!.trim() }));
+  const evidenceText = transcript
+    .filter((entry) => entry.type === "toolResult" || entry.role === "user")
+    .map((entry) => entry.text)
+    .join("\n\n")
+    .trim();
+  if (!evidenceText) {
+    return;
+  }
+
+  const runtimeContext = memoryRuntimeContextSchema.parse({
+    conversationId: run.conversationId,
+    ...(run.requester ? { requester: run.requester } : {}),
+    source: run.source,
+  });
+  const store = createMemoryStore(context.db as MemoryDb, runtimeContext, {
+    embedder: context.embedder,
+  });
+  const memories = await getTaskMemories(context, async () => {
+    const existingMemories = await store.searchMemories({
+      limit: 10,
+      query: evidenceText,
+    });
+    const agent = createMemoryAgent(context.model);
+    return await agent.extractSessionMemories({
+      existingMemories: existingMemories.map((memory) => ({
+        content: memory.content,
+      })),
+      transcript,
+      runtimeContext,
+    });
+  });
+  if (memories.length === 0) {
+    return;
+  }
+
+  for (const memory of memories) {
+    const input = passiveInput(run.runId, memory, sourceKey);
+    if (memory.target === "conversation") {
+      await store.createConversationMemory(input);
+      continue;
+    }
+    if (!run.requester) {
+      continue;
+    }
+    await store.createMemory(input);
+  }
+}

package/src/recall.ts

@@ -0,0 +1,81 @@
+import type {
+  PromptMessage,
+  Requester,
+  Source,
+} from "@sentry/junior-plugin-api";
+import {
+  createMemoryStore,
+  type MemoryDb,
+  type MemoryEmbeddingProvider,
+  type MemoryRecord,
+} from "./store";
+import { memoryRuntimeContextSchema } from "./types";
+
+const DEFAULT_RECALL_LIMIT = 5;
+const MAX_PROMPT_CHARS = 1_600;
+const MAX_MEMORY_LINE_CHARS = 320;
+
+export interface MemoryRecallContext {
+  conversationId?: string;
+  db: MemoryDb;
+  embedder?: MemoryEmbeddingProvider;
+  requester?: Requester;
+  source: Source;
+  text: string;
+}
+
+function trimContent(content: string, maxLength: number): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= maxLength) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function renderMemoryPrompt(memories: MemoryRecord[]): string | undefined {
+  const header = "Relevant memories for this request:";
+  const footer =
+    "Treat these as possibly stale context. Current user instructions and repository evidence take priority.";
+  const lines: string[] = [];
+  let totalChars = header.length + footer.length + 2;
+
+  for (const memory of memories) {
+    const line = `- ${trimContent(memory.content, MAX_MEMORY_LINE_CHARS)}`;
+    if (totalChars + line.length + 1 > MAX_PROMPT_CHARS) {
+      break;
+    }
+    lines.push(line);
+    totalChars += line.length + 1;
+  }
+
+  if (lines.length === 0) {
+    return undefined;
+  }
+  return `${header}\n${lines.join("\n")}\n\n${footer}`;
+}
+
+/** Build the memory prompt contribution for active visible recall. */
+export async function createMemoryPromptMessages(
+  context: MemoryRecallContext,
+): Promise<PromptMessage[] | undefined> {
+  if (!context.text.trim()) {
+    return undefined;
+  }
+  const runtimeContext = memoryRuntimeContextSchema.parse({
+    ...(context.conversationId
+      ? { conversationId: context.conversationId }
+      : {}),
+    ...(context.requester ? { requester: context.requester } : {}),
+    source: context.source,
+  });
+  const memories = await createMemoryStore(
+    context.db,
+    runtimeContext,
+    context.embedder ? { embedder: context.embedder } : {},
+  ).searchMemories({
+    query: context.text,
+    limit: DEFAULT_RECALL_LIMIT,
+  });
+  const text = renderMemoryPrompt(memories);
+  return text ? [{ text }] : undefined;
+}

package/src/scope.ts

@@ -0,0 +1,99 @@
+import type {
+  MemoryRuntimeContext,
+  MemoryScope,
+  MemorySubjectType,
+} from "./types";
+
+/** Runtime-derived visibility scope used for memory authorization checks. */
+export interface ResolvedMemoryScope {
+  scope: MemoryScope;
+  scopeKey: string;
+}
+
+/** Runtime-derived subject classification stored for filtering and rendering. */
+export interface ResolvedMemorySubject {
+  subjectKey?: string;
+  subjectType: MemorySubjectType;
+}
+
+function sourceConversationKey(ctx: MemoryRuntimeContext): string | undefined {
+  if (ctx.source.platform === "local") {
+    return ctx.source.conversationId;
+  }
+  const threadKey = ctx.source.threadTs ?? ctx.source.messageTs;
+  if (!threadKey) {
+    return undefined;
+  }
+  return `slack:${ctx.source.teamId}:${ctx.source.channelId}:${threadKey}`;
+}
+
+function requesterScopeKey(ctx: MemoryRuntimeContext): string | undefined {
+  const requester = ctx.requester;
+  if (!requester?.userId) {
+    return undefined;
+  }
+  if (requester.platform === "slack") {
+    return `slack:${requester.teamId}:${requester.userId}`;
+  }
+  return `local:${requester.userId}`;
+}
+
+/** Derive the authority-bearing key for a requested memory scope. */
+export function deriveMemoryScope(
+  ctx: MemoryRuntimeContext,
+  scope: MemoryScope,
+): ResolvedMemoryScope {
+  if (scope === "personal") {
+    const scopeKey = requesterScopeKey(ctx);
+    if (!scopeKey) {
+      throw new Error("Personal memory requires requester context.");
+    }
+    return { scope, scopeKey };
+  }
+
+  const scopeKey = sourceConversationKey(ctx);
+  if (!scopeKey) {
+    throw new Error("Conversation memory requires conversation context.");
+  }
+  return { scope, scopeKey };
+}
+
+/** Derive the memory subject from the already-authorized write scope. */
+export function deriveMemorySubject(
+  ctx: MemoryRuntimeContext,
+  scope: ResolvedMemoryScope,
+): ResolvedMemorySubject {
+  if (scope.scope === "personal") {
+    const subjectKey = requesterScopeKey(ctx);
+    if (!subjectKey) {
+      throw new Error("User-subject memory requires requester context.");
+    }
+    return { subjectType: "user", subjectKey };
+  }
+
+  const subjectKey = sourceConversationKey(ctx);
+  if (!subjectKey) {
+    throw new Error(
+      "Conversation-subject memory requires conversation context.",
+    );
+  }
+  return { subjectType: "conversation", subjectKey };
+}
+
+/** Return every visible scope for memory retrieval in the current context. */
+export function deriveVisibleMemoryScopes(
+  ctx: MemoryRuntimeContext,
+): ResolvedMemoryScope[] {
+  const scopes: ResolvedMemoryScope[] = [];
+  try {
+    scopes.push(deriveMemoryScope(ctx, "personal"));
+  } catch {
+    // Personal memory is optional when a runtime surface has no requester.
+  }
+  try {
+    scopes.push(deriveMemoryScope(ctx, "conversation"));
+  } catch {
+    // Conversation memory is optional for synthetic invocations.
+  }
+  return scopes;
+}