effect-assistant 0.0.0-stage → 0.2.0

package/src/Compaction.ts

@@ -0,0 +1,207 @@
+/**
+ * This module provides what a long chat needs so that the model can read a summary in place of
+ * everything before it.
+ *
+ * The app decides when to compact, which model writes the summary, and what the summary says.
+ * Its handler reads the chat's entries, has a model write a summary, and stores the summary as one
+ * of the assistant's own events (see {@link Summary}). Its loop then reads the chat through
+ * {@link since}. {@link inputTokens} helps decide when the prompt has grown large enough to
+ * compact. The log keeps every entry, so the user still sees the whole chat.
+ *
+ * @since 0.1.0
+ */
+import type * as Prompt from "effect/ai/Prompt"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import type * as Assistant from "./Assistant.ts"
+import * as AssistantActivity from "./AssistantActivity.ts"
+import * as AssistantEvent from "./AssistantEvent.ts"
+import * as BlockKit from "./BlockKit.ts"
+import { userText } from "./internal/history.ts"
+
+/**
+ * Represents the fields a summary event must have: its text and the last `seq` it covers.
+ *
+ * Entries after `throughSeq` are kept as they are, so an input that arrived while the summary was
+ * being written isn't lost.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Summary {
+  readonly _tag: string
+  readonly text: string
+  readonly throughSeq: number
+}
+
+/**
+ * Returns the number of input tokens used by the chat's last model call, which shows how large
+ * the prompt has grown. Returns 0 before the first call.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {
+  const last = entries.findLast(
+    ({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "ModelOutput") && event.usage !== undefined
+  )?.event
+
+  return last !== undefined && AssistantEvent.isLibraryEvent(last) && Predicate.isTagged(last, "ModelOutput")
+    ? (last.usage?.inputTokens.total ?? 0)
+    : 0
+}
+
+/**
+ * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't
+ * answered, and specialists that are working. The result is text for
+ * the model, or `None` when nothing is open.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const openItems = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  throughSeq: number
+): Option.Option<string> => {
+  const seqOf = (found: (event: AssistantEvent.AnyEntry["event"]) => boolean) =>
+    entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY
+
+  const opened = (seq: number) => seq <= throughSeq
+
+  const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {
+    const shown = entries.find(
+      ({ event }) =>
+        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === messageId
+    )
+
+    const message = shown?.event
+
+    return state.open &&
+      shown !== undefined &&
+      opened(shown.seq) &&
+      message !== undefined &&
+      AssistantEvent.isLibraryEvent(message) &&
+      Predicate.isTagged(message, "AssistantMessage")
+      ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`]
+      : []
+  })
+
+  const specialists = [...AssistantActivity.fromEntries(entries).specialists.values()].flatMap((run) =>
+    opened(
+      seqOf(
+        (event) =>
+          AssistantEvent.isLibraryEvent(event) &&
+          Predicate.isTagged(event, "SpecialistStarted") &&
+          event.runId === run.runId
+      )
+    )
+      ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`]
+      : []
+  )
+
+  const sections = [
+    blocks.length > 0 ? `Blocks the user hasn't answered:\n${blocks.join("\n")}` : "",
+    specialists.length > 0 ? `Specialists still working:\n${specialists.join("\n")}` : ""
+  ].filter((section) => section.length > 0)
+
+  return sections.length === 0 ? Option.none() : Option.some(sections.join("\n\n"))
+}
+
+/**
+ * Returns the files the user attached up to `throughSeq`, as lines of text for the model, or
+ * `None` when there are none. A summary may leave out a file's id, which tools need.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const attachedFiles = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  throughSeq: number
+): Option.Option<string> => {
+  const lines = entries.flatMap(({ seq, event }) =>
+    seq <= throughSeq && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "UserMessage")
+      ? (event.attachments ?? []).map(AssistantEvent.attachmentLine)
+      : []
+  )
+
+  return lines.length === 0 ? Option.none() : Option.some(lines.join("\n"))
+}
+
+/**
+ * Creates a history view that starts at the last summary.
+ *
+ * **Details**
+ *
+ * `isSummary` identifies the app's summary events. The model reads the last summary, the files
+ * attached earlier ({@link attachedFiles}), and the items that are still open
+ * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,
+ * the view returns every entry.
+ *
+ * **Example** (Compacting a long chat after each turn)
+ *
+ * ```ts
+ * import { AppEvent, Assistant, type AssistantEvent, Compaction } from "effect-assistant"
+ * import * as LanguageModel from "effect/ai/LanguageModel"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ * import * as Stream from "effect/Stream"
+ *
+ * class Summary extends Schema.TaggedClass<Summary>()("Summary", {
+ *   text: Schema.String,
+ *   throughSeq: Schema.Int
+ * }) {}
+ *
+ * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { events: [AppEvent.make(Summary)] })
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) => {
+ *   const compact = Effect.gen(function* () {
+ *     const chat = yield* MyAssistant.Chat
+ *     const entries = yield* chat.entries
+ *
+ *     if (Compaction.inputTokens(entries) < 100_000) return
+ *
+ *     const { text } = yield* LanguageModel.generateText({
+ *       prompt: `Summarize this chat:\n\n${transcript(entries)}`
+ *     })
+ *
+ *     yield* chat.append(Summary.make({ text, throughSeq: entries.at(-1)?.seq ?? 0 }))
+ *   })
+ *
+ *   // After the reply, so the user doesn't wait for the summary.
+ *   return Stream.concat(
+ *     turn.loop({ instructions: "Be brief.", history: Compaction.since(Schema.is(Summary)) }),
+ *     Stream.drain(Stream.fromEffect(compact))
+ *   )
+ * })
+ * ```
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const since =
+  (isSummary: (event: unknown) => event is Summary) =>
+  <Events extends { readonly _tag: string }>(
+    entries: ReadonlyArray<Assistant.Entry<Events>>
+  ): ReadonlyArray<Assistant.Entry<Events> | Prompt.Message> => {
+    const last = entries.findLast(({ event }) => isSummary(event))?.event
+
+    if (last === undefined || !isSummary(last)) return entries
+
+    const open = Option.match(openItems(entries, last.throughSeq), {
+      onNone: () => "",
+      onSome: (items) => `\n\n<still_open>\n${items}\n</still_open>`
+    })
+
+    const files = Option.match(attachedFiles(entries, last.throughSeq), {
+      onNone: () => "",
+      onSome: (lines) => `\n\n<files_attached_earlier>\n${lines}\n</files_attached_earlier>`
+    })
+
+    return [
+      userText(`<earlier_in_this_chat>\n${last.text}\n</earlier_in_this_chat>${files}${open}`),
+      ...entries.filter(({ seq, event }) => seq > last.throughSeq && !isSummary(event))
+    ]
+  }

package/src/CurrentChat.ts

@@ -0,0 +1,47 @@
+/**
+ * This module provides the `CurrentChat` service, which gives code that runs inside a chat
+ * access to that chat: its id, its entries, and a way to append to it.
+ *
+ * A turn's handler, its tools, and its specialists' runs get the chat with `yield* CurrentChat`.
+ * Inside a specialist's run, it is the chat the run belongs to, which is the chat of the turn
+ * that spawned the run. The service doesn't carry an assistant's event types, so code that
+ * doesn't know the assistant, such as a shared tool, can use it. Code that knows the assistant
+ * can use `MyAssistant.Chat`, which is the same chat typed with the assistant's events.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as AssistantEvent from "./AssistantEvent.ts"
+import type { ChatId } from "./ChatId.ts"
+
+/**
+ * Service that represents the chat the current code runs in.
+ *
+ * **Details**
+ *
+ * In a turn, it is the chat the turn runs in. In a specialist's run, and in its handler's build,
+ * it is the chat the run belongs to: the chat of the turn that spawned the run. A run's tools
+ * read and append to that chat.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class CurrentChat extends Context.Service<
+  CurrentChat,
+  {
+    readonly chatId: ChatId
+    /**
+     * The chat's entries so far, in order. They include the library's events and the assistant's
+     * own events, decoded; check for these with `Schema.is(MyEvent)` or `instanceof`. An app event
+     * that no longer decodes is left out.
+     */
+    readonly entries: Effect.Effect<ReadonlyArray<AssistantEvent.AnyEntry>>
+    /**
+     * Appends events after the chat's last entry and sends them to the chat's subscribers. The
+     * events can be the library's or the assistant's own (registered with its `events` option),
+     * such as a summary. An event that wakes a turn is handled by the next turn.
+     */
+    readonly append: (...events: ReadonlyArray<{ readonly _tag: string }>) => Effect.Effect<void>
+  }
+>()("effect-assistant/CurrentChat") {}

package/src/InputId.ts

@@ -0,0 +1,43 @@
+/**
+ * This module provides the id of an input to an assistant. An input is a user message, a block
+ * answer, or one of the app's events, and the id is stored in its `id` field.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Uuid from "./internal/uuid.ts"
+
+/**
+ * Schema for input ids. Any string is a valid input id, and the schema brands it.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const InputId = Schema.String.pipe(Schema.brand("~effect-assistant/InputId"))
+
+/**
+ * Represents an input id.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type InputId = typeof InputId.Type
+
+/**
+ * Creates a new random input id using Effect's `Random`. Seed `Random` in tests to get the same ids
+ * on every run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (): Effect.Effect<InputId> => Effect.map(Uuid.make, (uuid) => InputId.make(uuid))
+
+/**
+ * Creates the input id for a key, such as `${runId}:order_placed`. The same key always gives the
+ * same id, so an input that is sent again is stored only once.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromKey = (key: string): InputId => InputId.make(key)

package/src/Instructions.ts

@@ -0,0 +1,72 @@
+/**
+ * Defines the instructions that tell an assistant, specialist, or skill what to do.
+ *
+ * Instructions are text, or an Effect that produces text, optionally with span attributes
+ * (a {@link Resolved}). {@link resolve} turns them into a `Resolved`, and {@link protocol} is the
+ * text a turn's loop needs the model to know.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+
+/**
+ * The text the model has to know for a turn's loop to work.
+ *
+ * **Details**
+ *
+ * It tells the model that every step is a tool call, that `wait` (or a last message with
+ * `wait: true`) ends the turn, that the user sees only what it sends with `send_user_message`, and
+ * that messages can arrive mid-turn. The rest, such as what a `<specialist>` block or an app's
+ * event is, is in the tools' descriptions and in the history itself.
+ *
+ * `turn.instructions(text)` puts it before the text, and a custom loop on `AssistantLoop.run` can
+ * use it too.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const protocol = `Every step is a tool call. When you have nothing more to do right now, end your turn: set wait to true on your last send_user_message, or call wait if you have nothing to say.
+The user sees only the text of what you send with send_user_message: anything else you write is never shown, so put the whole answer in the message, not next to it.
+Messages and updates can arrive while you work: handle the newest one, and don't repeat what you already told the user.`
+
+/**
+ * Represents the span attributes added to every model call made with a prompt.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SpanAttributes = Readonly<Record<string, string | number | boolean>>
+
+/**
+ * Represents instructions resolved to text, with the span attributes to record them under.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Resolved {
+  readonly text: string
+  readonly attributes?: SpanAttributes | undefined
+}
+
+/**
+ * Represents instructions as text, or as an Effect that produces the text (optionally with span
+ * attributes).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Instructions<R = never> = string | Effect.Effect<string | Resolved, never, R>
+
+/**
+ * Resolves instructions to their text and span attributes.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const resolve = Effect.fn("Instructions.resolve")(function* <R = never>(instructions: Instructions<R>) {
+  return Predicate.isString(instructions) ? { text: instructions } : toResolved(yield* instructions)
+})
+
+const toResolved = (resolved: string | Resolved): Resolved =>
+  Predicate.isString(resolved) ? { text: resolved } : resolved

package/src/Memory.ts

@@ -0,0 +1,276 @@
+/**
+ * Keeps facts an assistant remembers across chats.
+ *
+ * The model keeps facts with the `remember` tool, finds them with `recall`, and drops them with
+ * `forget` ({@link Tools}). Where facts are stored and who shares them is up to the application,
+ * which implements {@link MemoryStore}; every method receives the chat it's for. {@link render}
+ * shows the facts in a turn's instructions.
+ *
+ * @since 0.1.0
+ */
+import * as Tool from "effect/ai/Tool"
+import * as Toolkit from "effect/ai/Toolkit"
+import * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
+import * as DateTime from "effect/DateTime"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import type { ChatId } from "./ChatId.ts"
+import { CurrentChat } from "./CurrentChat.ts"
+import * as Uuid from "./internal/uuid.ts"
+import * as ToolFailure from "./ToolFailure.ts"
+
+/**
+ * Represents a fact the assistant remembers.
+ *
+ * It holds the fact's id, one short sentence, and when the fact stops mattering, if it does.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class Fact extends Schema.Class<Fact>("effect-assistant/Memory/Fact")({
+  id: Schema.String,
+  text: Schema.String,
+  expiresAt: Schema.optional(Schema.DateTimeUtc)
+}) {}
+
+/**
+ * Represents a fact to keep, as the `remember` tool hands it to the store.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface NewFact {
+  readonly text: string
+  readonly expiresAt?: DateTime.Utc | undefined
+  /** The id of a fact this one replaces. */
+  readonly replaces?: string | undefined
+}
+
+/**
+ * Service that keeps facts, implemented by the application.
+ *
+ * Every method receives the chat it's for, and the application decides whose facts that means
+ * (the chat's user, their team, ...).
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class MemoryStore extends Context.Service<
+  MemoryStore,
+  {
+    /** Returns the unexpired facts a chat should know. */
+    readonly facts: (chatId: ChatId) => Effect.Effect<ReadonlyArray<Fact>>
+    /** Keeps a fact for the chat's owner, and returns its id. */
+    readonly remember: (chatId: ChatId, fact: NewFact) => Effect.Effect<string>
+    /**
+     * Drops a fact. Fails with a message for the model when the chat's owner has no fact with
+     * that id.
+     */
+    readonly forget: (chatId: ChatId, id: string) => Effect.Effect<void, ToolFailure.ToolFailure>
+    /** Returns the chat owner's facts that match a query, best first. */
+    readonly recall: (chatId: ChatId, query: string) => Effect.Effect<ReadonlyArray<Fact>>
+  }
+>()("effect-assistant/Memory/MemoryStore") {}
+
+const day = (at: DateTime.Utc): string => DateTime.formatIsoDateUtc(at)
+
+const line = (fact: Fact): string =>
+  `- [${fact.id}] ${fact.text}${fact.expiresAt === undefined ? "" : ` (until ${day(fact.expiresAt)})`}`
+
+/**
+ * Renders facts as the model reads them, for a turn's instructions.
+ *
+ * Each fact is listed with its id, so the model can replace or forget it. The result is an empty
+ * string when there are no facts.
+ *
+ * @see {@link Tools} for an example
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const render = (facts: ReadonlyArray<Fact>): string =>
+  facts.length === 0
+    ? ""
+    : `<memory>\nWhat you remember from earlier chats. Use it without saying where it came from; when their data or what they say now disagrees, that wins.\n${facts.map(line).join("\n")}\n</memory>`
+
+const words = (text: string): ReadonlyArray<string> =>
+  text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((word) => word.length > 2)
+
+const matches = (fact: Fact, query: ReadonlyArray<string>): number => {
+  const own = words(fact.text)
+
+  return query.filter((word) => own.some((w) => w.startsWith(word) || word.startsWith(w))).length
+}
+
+const live = (now: number) => (fact: Fact) =>
+  fact.expiresAt === undefined || DateTime.toEpochMillis(fact.expiresAt) > now
+
+/**
+ * Layer that provides a {@link MemoryStore} in memory, for tests and local runs.
+ *
+ * Every chat shares one set of facts.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerMemory: Layer.Layer<MemoryStore> = Layer.effect(
+  MemoryStore,
+  Effect.gen(function* () {
+    // Newest first.
+    const all = yield* Ref.make<ReadonlyArray<Fact>>([])
+
+    const current = Effect.gen(function* () {
+      const now = yield* Clock.currentTimeMillis
+
+      return (yield* Ref.get(all)).filter(live(now))
+    })
+
+    return MemoryStore.of({
+      facts: () => current,
+      remember: Effect.fnUntraced(function* (_chatId: ChatId, fact: NewFact) {
+        const same = (yield* current).find((kept) => kept.text === fact.text.trim())
+        const id = same?.id ?? `f-${(yield* Uuid.make).slice(0, 8)}`
+        const kept = new Fact({ id, text: fact.text.trim(), expiresAt: fact.expiresAt })
+
+        yield* Ref.update(all, (facts) => [kept, ...facts.filter((old) => old.id !== id && old.id !== fact.replaces)])
+
+        return id
+      }),
+      forget: Effect.fnUntraced(function* (_chatId: ChatId, id: string) {
+        if (!(yield* current).some((fact) => fact.id === id))
+          return yield* ToolFailure.fail(`Nothing remembered as ${id}.`)
+
+        yield* Ref.update(all, (facts) => facts.filter((fact) => fact.id !== id))
+      }),
+      recall: Effect.fnUntraced(function* (_chatId: ChatId, query: string) {
+        const wanted = words(query)
+
+        return (yield* current)
+          .map((fact) => ({ fact, score: matches(fact, wanted) }))
+          .filter(({ score }) => score > 0)
+          .sort((a, b) => b.score - a.score)
+          .slice(0, 10)
+          .map(({ fact }) => fact)
+      })
+    })
+  })
+)
+
+const Remember = Tool.make("remember", {
+  description: `Remember something for later chats. Only what you can't look up again and that will still matter: a preference, a standing decision, how they like to work ("Rotterdam's copy is always Dutch"). For something short-lived ("out of office until Friday"), pass until. Not records your tools can read (orders, locations, budgets, people), not the state of a task in progress, and nothing you'd only need in this chat. One fact per call, in one short sentence that stands on its own. When it changes one you already have, pass that one's id as replaces.`,
+  parameters: Schema.Struct({
+    text: Schema.String,
+    until: Schema.optional(Schema.String).annotate({
+      description: "For something short-lived: the last day it matters, as YYYY-MM-DD."
+    }),
+    replaces: Schema.optional(Schema.String).annotate({ description: "The id of a fact this one replaces." })
+  }),
+  success: Schema.String,
+  failure: ToolFailure.ToolFailure,
+  dependencies: [CurrentChat, MemoryStore]
+})
+
+const Forget = Tool.make("forget", {
+  description: "Forget a fact you remember, by its id, when they ask or it's no longer true.",
+  parameters: Schema.Struct({ id: Schema.String }),
+  success: Schema.String,
+  failure: ToolFailure.ToolFailure,
+  dependencies: [CurrentChat, MemoryStore]
+})
+
+const Recall = Tool.make("recall", {
+  description: "Search what you remember, by words that would be in it.",
+  parameters: Schema.Struct({ query: Schema.String }),
+  success: Schema.Array(Schema.String),
+  failure: ToolFailure.ToolFailure,
+  dependencies: [CurrentChat, MemoryStore]
+})
+
+/**
+ * Toolkit with the `remember`, `forget`, and `recall` tools.
+ *
+ * **Details**
+ *
+ * Merge it into the loop's toolkit, and provide {@link layerTools} and a {@link MemoryStore}. Show
+ * the facts in the turn's instructions with {@link render}.
+ *
+ * **Example** (Giving an assistant memory)
+ *
+ * ```ts
+ * import { Assistant, Memory } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ * import * as Layer from "effect/Layer"
+ * import * as Stream from "effect/Stream"
+ *
+ * export const MyAssistant = Assistant.make("my-assistant")
+ *
+ * const MyAssistantLive = MyAssistant.toLayer(
+ *   Effect.gen(function* () {
+ *     const memory = yield* Memory.MemoryStore
+ *
+ *     return (turn) =>
+ *       Stream.unwrap(
+ *         Effect.map(memory.facts(turn.chatId), (facts) =>
+ *           turn.loop({
+ *             instructions: `You help a small team.\n\n${Memory.render(facts)}`,
+ *             toolkit: Memory.Tools
+ *           })
+ *         )
+ *       ).pipe(Stream.provideService(Memory.MemoryStore, memory))
+ *   })
+ * ).pipe(Layer.provide(Memory.layerTools), Layer.provide(Memory.layerMemory))
+ * ```
+ *
+ * @category tools
+ * @since 0.1.0
+ */
+export const Tools = Toolkit.make(Remember, Forget, Recall)
+
+const endOf = (date: string): Option.Option<DateTime.Utc> =>
+  /^\d{4}-\d{2}-\d{2}$/.test(date) ? DateTime.make(`${date}T23:59:59Z`) : Option.none()
+
+/**
+ * Layer that provides the handlers of {@link Tools}.
+ *
+ * The handlers call the {@link MemoryStore} with the chat they run in.
+ *
+ * @see {@link Tools} for an example
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerTools = Tools.toLayer({
+  remember: Effect.fnUntraced(function* ({ text, until, replaces }) {
+    const chat = yield* CurrentChat
+    const store = yield* MemoryStore
+    const expiresAt = until === undefined ? Option.none() : endOf(until)
+
+    if (until !== undefined && Option.isNone(expiresAt)) {
+      return yield* ToolFailure.fail(`until must be a date as YYYY-MM-DD, not ${until}.`)
+    }
+
+    const id = yield* store.remember(chat.chatId, { text, expiresAt: Option.getOrUndefined(expiresAt), replaces })
+
+    return `Remembered as ${id}.`
+  }),
+  forget: Effect.fnUntraced(function* ({ id }) {
+    const chat = yield* CurrentChat
+
+    yield* (yield* MemoryStore).forget(chat.chatId, id)
+
+    return `Forgot ${id}.`
+  }),
+  recall: Effect.fnUntraced(function* ({ query }) {
+    const chat = yield* CurrentChat
+    const found = yield* (yield* MemoryStore).recall(chat.chatId, query)
+
+    return found.map(line)
+  })
+})

package/src/RunId.ts

@@ -0,0 +1,46 @@
+/**
+ * This module provides the id of a background run, such as a specialist run or a workflow started
+ * from a tool. A run id is `run:` followed by a UUID.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Uuid from "./internal/uuid.ts"
+
+/**
+ * Schema for run ids of the form `` `run:${uuid}` ``, branded.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const RunId = Schema.TemplateLiteral(["run:", Uuid.Uuid]).pipe(Schema.brand("~effect-assistant/RunId"))
+
+/**
+ * Represents a run id.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RunId = typeof RunId.Type
+
+/**
+ * Creates a new random run id using Effect's `Random`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (): Effect.Effect<RunId> => Effect.map(Uuid.make, (uuid) => RunId.make(`run:${uuid}`))
+
+/**
+ * Creates the run id for a key. The same key always gives the same id.
+ *
+ * **When to use**
+ *
+ * Use it for a run that a tool call starts, with the call's `AssistantToolCall.idempotencyKey` as
+ * the key, so running the call again finds the same run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromKey = (key: string): RunId => RunId.make(`run:${Uuid.fromKey(key)}`)