@sentry/junior-memory 0.197.0 → 0.199.0

package/src/process-session.ts

@@ -1,311 +0,0 @@
-import { createHash } from "node:crypto";
-import {
-  getSourceKey,
-  type PluginRunContext,
-  type PluginRunTranscriptEntry,
-  type PluginTaskContext,
-} from "@sentry/junior-plugin-api";
-import { z } from "zod";
-import {
-  createMemoryStore,
-  type CreateMemoryInput,
-  type CreateMemoryResult,
-  type MemoryDb,
-} from "./store";
-import {
-  createMemoryAgent,
-  parseExtractedMemory,
-  type ExtractedMemory,
-  type MemoryExtractionResult,
-} from "./agent";
-import { MEMORY_KINDS, memoryRuntimeContextSchema } from "./types";
-import { capturedMemory, memoriesCapturedEvent } from "./events";
-
-const MEMORY_TOOL_NAMES = new Set([
-  "createMemory",
-  "listMemories",
-  "removeMemory",
-  "searchMemories",
-]);
-const MEMORY_TASK_STATE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-const extractedMemorySchema = z
-  .object({
-    content: z.string().min(1),
-    expiresAtMs: z.number().finite().nullable(),
-    kind: z.enum(MEMORY_KINDS),
-    evidenceMessageIndices: z
-      .array(z.number().int().nonnegative())
-      .min(1)
-      .max(10),
-  })
-  .strict()
-  .transform(parseExtractedMemory);
-const extractedMemoryCacheSchema = z.union([
-  z
-    .object({
-      costUsd: z.number().finite().nonnegative().optional(),
-      memories: z.array(extractedMemorySchema).max(5),
-    })
-    .strict(),
-  z
-    .array(extractedMemorySchema)
-    .max(5)
-    .transform((memories) => ({ memories })),
-]);
-
-/** Subject for a passively extracted memory, or drop when unproven. */
-type MemorySubjectTarget = "drop" | "user" | "conversation";
-
-function recordCapturedMemory(
-  captured: ReturnType<typeof capturedMemory>[],
-  result: CreateMemoryResult,
-): void {
-  const supersededIds = new Set(result.supersededIds ?? []);
-  for (let index = captured.length - 1; index >= 0; index -= 1) {
-    if (supersededIds.has(captured[index]!.id)) {
-      captured.splice(index, 1);
-    }
-  }
-  if (result.created || result.idempotent) {
-    captured.push(capturedMemory(result.memory));
-  }
-}
-
-/** A cited entry is a run-actor durable instruction evidence entry. */
-function isRunActorInstruction(entry: PluginRunTranscriptEntry): boolean {
-  return (
-    entry.type === "message" &&
-    entry.role === "user" &&
-    entry.provenance?.authority === "instruction" &&
-    entry.isRunActor === true
-  );
-}
-
-/** A cited entry is valid public conversation evidence for shared knowledge. */
-function isConversationEvidence(entry: PluginRunTranscriptEntry): boolean {
-  if (entry.type === "toolResult") {
-    return entry.isError === false && Boolean(entry.text?.trim());
-  }
-  if (
-    entry.type === "message" &&
-    entry.role === "user" &&
-    entry.provenance?.authority === "instruction" &&
-    entry.isRunActor === false
-  ) {
-    return Boolean(entry.provenance.actor);
-  }
-  return (
-    entry.type === "message" &&
-    entry.role === "user" &&
-    entry.provenance?.authority === "context"
-  );
-}
-
-/** Resolve the deduplicated cited transcript entries, failing on bad indices. */
-function citedEntries(
-  indices: number[],
-  transcript: PluginRunTranscriptEntry[],
-): { valid: boolean; entries: PluginRunTranscriptEntry[] } {
-  const seen = new Set<number>();
-  const entries: PluginRunTranscriptEntry[] = [];
-  for (const index of indices) {
-    if (seen.has(index)) {
-      continue;
-    }
-    seen.add(index);
-    const entry = transcript[index];
-    if (!entry) {
-      return { valid: false, entries: [] };
-    }
-    entries.push(entry);
-  }
-  return { valid: entries.length > 0, entries };
-}
-
-/**
- * Verify an extracted memory against runtime-owned provenance on its cited
- * evidence. This is a deterministic authority boundary, not a model decision:
- * personal preferences require a single-actor run whose citations are all
- * run-actor instructions, conversation knowledge requires run-actor instruction
- * or valid public conversation evidence, and anything unproven (including
- * missing provenance) is dropped. Multi-actor runs interleave first-person
- * statements from different people, so they never store a preference regardless
- * of citations; a personal preference can wait for a single-actor run.
- */
-function routeExtractedMemory(
-  memory: ExtractedMemory,
-  transcript: PluginRunTranscriptEntry[],
-  run: Pick<PluginRunContext, "actor" | "actors" | "actorUserId">,
-): MemorySubjectTarget {
-  const cited = citedEntries(memory.evidenceMessageIndices, transcript);
-  if (!cited.valid) {
-    return "drop";
-  }
-  if (memory.kind === "preference") {
-    // Only a run attributed to exactly one human run actor may store a preference.
-    const exactlyOneHumanRunActor =
-      run.actorUserId !== undefined &&
-      run.actor !== undefined &&
-      run.actor.platform !== "system" &&
-      run.actors.length === 1 &&
-      run.actors[0]?.platform !== "system";
-    if (!exactlyOneHumanRunActor) {
-      return "drop";
-    }
-    // Never downgrade an unproven first-person preference to conversation subject.
-    return cited.entries.every(isRunActorInstruction) ? "user" : "drop";
-  }
-  return cited.entries.every(
-    (entry) => isRunActorInstruction(entry) || isConversationEvidence(entry),
-  )
-    ? "conversation"
-    : "drop";
-}
-
-function memoryIdempotencySuffix(
-  memory: ExtractedMemory,
-  target: MemorySubjectTarget,
-): string {
-  return createHash("sha256")
-    .update(target)
-    .update("\0")
-    .update(memory.kind)
-    .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,
-  target: MemorySubjectTarget,
-): CreateMemoryInput {
-  return {
-    content: memory.content,
-    idempotencyKey: `session:${sourceKey}:${sessionId}:${memoryIdempotencySuffix(memory, target)}`,
-    kind: memory.kind,
-    ...(memory.expiresAtMs !== null
-      ? { expiresAtMs: memory.expiresAtMs }
-      : undefined),
-  };
-}
-
-async function getTaskExtraction(
-  context: PluginTaskContext,
-  extract: () => Promise<MemoryExtractionResult>,
-): Promise<MemoryExtractionResult> {
-  const cacheKey = `memory-extraction:${context.id}`;
-  const cached = await context.state.get(cacheKey);
-  if (cached !== undefined) {
-    const parsed = extractedMemoryCacheSchema.safeParse(cached);
-    if (parsed.success) {
-      return parsed.data;
-    }
-    await context.state.delete(cacheKey);
-  }
-  const extraction = await extract();
-  await context.state.set(cacheKey, extraction, MEMORY_TASK_STATE_TTL_MS);
-  return extraction;
-}
-
-/**
- * Extract and store memories from a completed session plugin task.
- *
- * Memory owns learning after a run and reads only the plugin run data.
- * Explicit memory tools stay separate so retries do not reinterpret user
- * requests.
- */
-export async function processMemorySession(
-  context: PluginTaskContext,
-): Promise<void> {
-  const run = await context.run.load();
-  // TODO(dcramer): Replace this hardcoded Source check when a plugin Run can
-  // state whether passive memory extraction should run.
-  if (run.source.kind !== "slack" && run.source.kind !== "web") {
-    return;
-  }
-  // 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;
-  }
-  const sourceKey = getSourceKey(run.source);
-  if (!sourceKey || (run.source.visibility === "private" && !run.actorUserId)) {
-    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.locationId ? { locationId: run.locationId } : undefined),
-    ...(run.actor ? { actor: run.actor } : undefined),
-    source: run.source,
-    ...(run.actorUserId ? { userId: run.actorUserId } : undefined),
-  });
-  const agent = createMemoryAgent(context.model);
-  const store = createMemoryStore(context.db as MemoryDb, runtimeContext, {
-    embedder: context.embedder,
-    supersessionDecider: agent,
-  });
-  await store.archiveExpiredMemories();
-  const extraction = await getTaskExtraction(context, async () => {
-    const existingMemories = await store.searchMemories({
-      limit: 10,
-      query: evidenceText,
-    });
-    return await agent.extractSessionMemories({
-      existingMemories: existingMemories.map((memory) => ({
-        content: memory.content,
-      })),
-      actors: run.actors,
-      transcript,
-      runtimeContext,
-    });
-  });
-
-  const captured: ReturnType<typeof capturedMemory>[] = [];
-  for (const memory of extraction.memories) {
-    // The routing gate stays even though extraction is also actor-gated:
-    // getTaskExtraction caches extraction output for 7 days, so a retry can replay
-    // preference proposals cached before this gate existed.
-    const target = routeExtractedMemory(memory, transcript, run);
-    if (target === "drop") {
-      continue;
-    }
-    const input = passiveInput(run.runId, memory, sourceKey, target);
-    if (target === "conversation") {
-      const result = await store.createConversationMemory(input);
-      recordCapturedMemory(captured, result);
-      continue;
-    }
-    const result = await store.createMemory(input);
-    recordCapturedMemory(captured, result);
-  }
-  await context.events.emit(
-    memoriesCapturedEvent({
-      memories: captured,
-      ...(extraction.costUsd !== undefined
-        ? { costUsd: extraction.costUsd }
-        : undefined),
-    }),
-  );
-}

package/src/ranking.ts

@@ -1,107 +0,0 @@
-import type { MemoryRecord } from "./store";
-
-const RECIPROCAL_RANK_FUSION_K = 60;
-const ONE_DAY_MS = 24 * 60 * 60 * 1000;
-const DEFAULT_RRF_WEIGHT = 1;
-
-export interface MemoryMatch {
-  lexical?: {
-    rank: number;
-  };
-  memory: MemoryRecord;
-  vector?: {
-    rank: number;
-  };
-}
-
-function reciprocalRank(rank: number, weight: number): number {
-  return weight / (RECIPROCAL_RANK_FUSION_K + rank);
-}
-
-function matchScore(
-  match: MemoryMatch,
-  weights: { lexicalWeight: number; vectorWeight: number },
-): number {
-  return (
-    (match.vector
-      ? reciprocalRank(match.vector.rank, weights.vectorWeight)
-      : 0) +
-    (match.lexical
-      ? reciprocalRank(match.lexical.rank, weights.lexicalWeight)
-      : 0)
-  );
-}
-
-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;
-}
-
-function positiveWeight(value: number | undefined, fallback: number): number {
-  return value !== undefined && Number.isFinite(value) && value > 0
-    ? value
-    : fallback;
-}
-
-/** Fuse lexical and vector ranks without comparing provider raw scores. */
-export function rankMemoryMatches(
-  matches: MemoryMatch[],
-  options: {
-    /** Optional RRF weight for the lexical leg. Defaults to 1. */
-    lexicalWeight?: number;
-    nowMs: number;
-    /** Optional RRF weight for the vector leg. Defaults to 1. */
-    vectorWeight?: number;
-  },
-): MemoryMatch[] {
-  const weights = {
-    lexicalWeight: positiveWeight(options.lexicalWeight, DEFAULT_RRF_WEIGHT),
-    vectorWeight: positiveWeight(options.vectorWeight, DEFAULT_RRF_WEIGHT),
-  };
-  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;
-    }
-    // Keep the first rank from each search. The shared searches run first, so
-    // the smaller private searches cannot replace their ranks.
-    byId.set(match.memory.id, {
-      ...existing,
-      ...(!existing.lexical && match.lexical
-        ? { lexical: match.lexical }
-        : undefined),
-      ...(!existing.vector && match.vector ? { vector: match.vector } : undefined),
-    });
-  }
-  return [...byId.values()].sort((left, right) => {
-    const scoreDelta = matchScore(right, weights) - matchScore(left, weights);
-    if (scoreDelta !== 0) {
-      return scoreDelta;
-    }
-    // Prefer private memory when RRF ties. Public and private searches can give
-    // the same rank to common words.
-    const privateDelta =
-      Number(right.memory.scope === "private") -
-      Number(left.memory.scope === "private");
-    if (privateDelta !== 0) {
-      return privateDelta;
-    }
-    return (
-      observedAgeRank(right.memory, options.nowMs) -
-        observedAgeRank(left.memory, options.nowMs) ||
-      right.memory.observedAtMs - left.memory.observedAtMs ||
-      left.memory.id.localeCompare(right.memory.id)
-    );
-  });
-}

package/src/recall.ts

@@ -1,212 +0,0 @@
-import {
-  definePromptContext,
-  type UserPromptContribution,
-  type Actor,
-  type Identity,
-  type PluginConversationEvents,
-  type PluginLogger,
-  type Source,
-  type User,
-} from "@sentry/junior-plugin-api";
-import { z } from "zod";
-import type { MemoryAgent, MemoryRecallResult } from "./agent";
-import { memoriesRecalledEvent } from "./events";
-import {
-  createMemoryStore,
-  type MemoryDb,
-  type MemoryEmbeddingProvider,
-  type MemoryRecord,
-} from "./store";
-import { memoryRuntimeContextSchema } from "./types";
-
-const RECALL_CANDIDATE_LIMIT = 20;
-const MAX_PROMPT_CHARS = 4_000;
-const MAX_MEMORY_LINE_CHARS = 600;
-
-export interface MemoryRecallContext {
-  agent: Pick<MemoryAgent, "selectRelevantMemories">;
-  conversationId?: string;
-  db: MemoryDb;
-  embedder?: MemoryEmbeddingProvider;
-  events?: PluginConversationEvents;
-  log: PluginLogger;
-  locationId?: string;
-  actor?: Actor;
-  source: Source;
-  text: string;
-  users: {
-    resolveActor(): Promise<{ identity: Identity; user?: User } | undefined>;
-  };
-}
-
-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 formatObservedDate(observedAtMs: number): string {
-  return new Date(observedAtMs).toISOString().slice(0, 10);
-}
-
-const recalledMemorySchema = z
-  .object({
-    id: z.string().min(1),
-    content: z.string().min(1).max(MAX_MEMORY_LINE_CHARS),
-    observedAtMs: z.number().finite(),
-    // Stored version 1 uses the old scope labels. Prompt rendering ignores them.
-    scope: z.enum(["personal", "conversation"]),
-    kind: z.enum(["preference", "procedure", "knowledge"]),
-  })
-  .strict();
-
-/** Structured snapshot retained for one automatic memory recall. */
-export const memoryRecallContextSchema = z
-  .object({
-    // Count is a safety rail only. Admission packs by MAX_PROMPT_CHARS.
-    memories: z.array(recalledMemorySchema).min(1).max(RECALL_CANDIDATE_LIMIT),
-  })
-  .strict();
-
-type RecalledMemory = z.output<typeof recalledMemorySchema>;
-
-function selectPromptMemories(memories: MemoryRecord[]): RecalledMemory[] {
-  const header = "Relevant memories for this request:";
-  const footer =
-    "Treat these as possibly stale context. Current user instructions and repository evidence take priority.";
-  const selected: RecalledMemory[] = [];
-  let totalChars = header.length + footer.length + 2;
-
-  for (const memory of memories) {
-    const content = trimContent(memory.content, MAX_MEMORY_LINE_CHARS);
-    const line = `- Observed ${formatObservedDate(memory.observedAtMs)}: ${content}`;
-    if (totalChars + line.length + 1 > MAX_PROMPT_CHARS) {
-      break;
-    }
-    selected.push({
-      id: memory.id,
-      content,
-      observedAtMs: memory.observedAtMs,
-      scope: memory.scope === "private" ? "personal" : "conversation",
-      kind: memory.kind,
-    });
-    totalChars += line.length + 1;
-  }
-  return selected;
-}
-
-function renderMemoryPrompt(memories: RecalledMemory[]): string {
-  return [
-    "Relevant memories for this request:",
-    ...memories.map(
-      (memory) =>
-        `- Observed ${formatObservedDate(memory.observedAtMs)}: ${memory.content}`,
-    ),
-    "",
-    "Treat these as possibly stale context. Current user instructions and repository evidence take priority.",
-  ].join("\n");
-}
-
-function addUsd(
-  left: number | undefined,
-  right: number | undefined,
-): number | undefined {
-  if (left === undefined) return right;
-  if (right === undefined) return left;
-  return Math.round((left + right) * 1e12) / 1e12;
-}
-
-async function emitRecallOutcome(args: {
-  costUsd?: number;
-  events?: PluginConversationEvents;
-  memories: string[];
-}): Promise<void> {
-  await args.events?.emit(
-    memoriesRecalledEvent({
-      memories: args.memories,
-      ...(args.costUsd !== undefined ? { costUsd: args.costUsd } : undefined),
-    }),
-  );
-}
-
-const memoryRecallContext = definePromptContext({
-  kind: "recall",
-  version: 1,
-  schema: memoryRecallContextSchema,
-  renderPrompt: (content) => renderMemoryPrompt(content.memories),
-});
-
-/** Build active memory recall contributions. */
-export async function createMemoryPromptContributions(
-  context: MemoryRecallContext,
-): Promise<UserPromptContribution[] | undefined> {
-  if (!context.text.trim()) {
-    return undefined;
-  }
-  const actorUser = (await context.users.resolveActor())?.user;
-  const runtimeContext = memoryRuntimeContextSchema.parse({
-    ...(context.conversationId
-      ? { conversationId: context.conversationId }
-      : undefined),
-    ...(context.actor ? { actor: context.actor } : undefined),
-    ...(context.locationId ? { locationId: context.locationId } : undefined),
-    source: context.source,
-    ...(actorUser ? { userId: actorUser.id } : undefined),
-  });
-  let embeddingCostUsd: number | undefined;
-  const sourceEmbedder = context.embedder;
-  const embedder = sourceEmbedder
-    ? {
-        async embedTexts(input: { texts: string[] }) {
-          const result = await sourceEmbedder.embedTexts(input);
-          embeddingCostUsd = addUsd(embeddingCostUsd, result.costUsd);
-          return result;
-        },
-      }
-    : undefined;
-  const candidates = await createMemoryStore(context.db, runtimeContext, {
-    embedder,
-  }).recallMemories({
-    query: context.text,
-    limit: RECALL_CANDIDATE_LIMIT,
-  });
-  if (candidates.length === 0) {
-    await emitRecallOutcome({
-      ...(embeddingCostUsd !== undefined ? { costUsd: embeddingCostUsd } : undefined),
-      events: context.events,
-      memories: [],
-    });
-    return undefined;
-  }
-  let recall: MemoryRecallResult;
-  try {
-    recall = await context.agent.selectRelevantMemories({
-      candidates: candidates.map(({ content, id }) => ({ content, id })),
-      userRequest: context.text,
-    });
-  } catch {
-    // Automatic recall is optional context; a relevance-model failure must not
-    // prevent the user's turn from continuing without recalled memory.
-    context.log.warn("memory_recall_selection_failed");
-    return undefined;
-  }
-  const candidatesById = new Map(
-    candidates.map((memory) => [memory.id, memory]),
-  );
-  const relevant = recall.relevantIds
-    .map((id) => candidatesById.get(id))
-    .filter((memory): memory is MemoryRecord => memory !== undefined);
-  const selected = selectPromptMemories(relevant);
-  const costUsd = addUsd(embeddingCostUsd, recall.costUsd);
-  await emitRecallOutcome({
-    ...(costUsd !== undefined ? { costUsd } : undefined),
-    events: context.events,
-    memories: selected.map(({ id }) => id),
-  });
-  if (selected.length === 0) {
-    return undefined;
-  }
-  return [memoryRecallContext({ memories: selected })];
-}

package/src/scope.ts

@@ -1,75 +0,0 @@
-import type {
-  MemoryRuntimeContext,
-  MemoryScope,
-  MemorySubjectType,
-} from "./types";
-
-const PUBLIC_SCOPE_KEY = "public";
-
-/** Stored memory access rule. */
-export interface ResolvedMemoryScope {
-  scope: MemoryScope;
-  scopeKey: string;
-}
-
-/** What a stored memory is about. */
-export interface ResolvedMemorySubject {
-  subjectKey: string;
-  subjectType: Extract<MemorySubjectType, "user" | "conversation">;
-}
-
-/** Public memories are visible everywhere. */
-export const publicMemoryScope: ResolvedMemoryScope = {
-  scope: "public",
-  scopeKey: PUBLIC_SCOPE_KEY,
-};
-
-function privateMemoryScope(userId: string): ResolvedMemoryScope {
-  return { scope: "private", scopeKey: userId };
-}
-
-/** Set memory access from the Source. */
-export function deriveMemoryScope(
-  ctx: MemoryRuntimeContext,
-): ResolvedMemoryScope {
-  if ("visibility" in ctx.source && ctx.source.visibility === "public") {
-    return publicMemoryScope;
-  }
-  if (!ctx.userId) {
-    throw new Error("Private memory requires a User.");
-  }
-  return privateMemoryScope(ctx.userId);
-}
-
-/** Set what a memory is about. Access is set separately. */
-export function deriveMemorySubject(
-  ctx: MemoryRuntimeContext,
-  subjectType: Extract<MemorySubjectType, "user" | "conversation">,
-): ResolvedMemorySubject {
-  if (subjectType === "user") {
-    if (!ctx.userId) {
-      throw new Error("User memory requires a User.");
-    }
-    return { subjectType, subjectKey: ctx.userId };
-  }
-  const subjectKey = ctx.conversationId;
-  if (!subjectKey) {
-    throw new Error(
-      "Conversation-subject memory requires conversation context.",
-    );
-  }
-  return {
-    subjectType,
-    subjectKey,
-  };
-}
-
-/** Return the memory scopes that the current User can access. */
-export function deriveVisibleMemoryScopes(
-  ctx: MemoryRuntimeContext,
-): ResolvedMemoryScope[] {
-  if (!ctx.userId) {
-    return [publicMemoryScope];
-  }
-  return [publicMemoryScope, privateMemoryScope(ctx.userId)];
-}