Context management

Each model request resends its context. Long runs can spend most of their budget rereading old tool results or exceed the model’s context window. Yielded Agent bounds tool output, reports the remaining budget, and compacts old context. Final-answer policy can grant one constrained turn after turn, tool call, or token exhaustion.

Set these limits from the model and workload. The provider does not supply them:

AgentPolicy.make({
  maxTurns: 12,
  maxToolCalls: 24,
  maxDuration: "5 minutes",
  toolConcurrency: 4,

  tokenBudget: 200_000,
  completionReserveTokens: 32_000,
  costBudgetMicrousd: 2_000_000,
  contextTokenLimit: 150_000,

  toolResultBounds: ToolResultBounds.make({ maxBytes: 50 * 1024 }),
  runStatus: "off",
  compaction: CompactionPolicy.make({ keepRecentTokens: 20_000 }),
  onExhaustion: "final-answer",
});

tokenBudget counts cumulative input and output across the run. costBudgetMicrousd uses the installed cost estimator and cache-split usage. contextTokenLimit bounds the live context for one call. Set it below the model window so output and compaction have room.

Prompt preparation order

At run start, the runtime evaluates instructions and the definition’s optional inputPrompt. Without inputPrompt, the model receives the full encoded input as a JSON user message.

Before each turn, the durable runtime commits the previous completed Tool batch, then RunContextPreparation.hook.prepare transforms the source prompt. A host resolving the next model from successful Tool receipts can therefore read their canonical records during preparation. The engine compacts the prepared history, then loads optional references through RunContextPreparation.transientContext.load. If the references exceed the remaining budget, the engine can compact canonical history further while keeping the same reference snapshot. It appends the references to the compacted view. OpenAI, xAI Responses, and native adapters advertising support for system messages in history preserve chronological guidance, with the output contract after the initial system block. Changing late instructions therefore leaves earlier history reusable. The engine resolves this capability from the selected model on each call. Other adapters, including the pinned Anthropic adapter, group systems before the conversation. Derived run status follows this projection, which preserves stored history and compaction boundaries. See prompt caching for provider differences. Compaction summaries never receive transient references. Durable recovery rebuilds the committed model view before applying prompt preparation; a transient loader receives the current Attempt’s official source, Thread ID, Run ID, Turn ID, and Turn number.

Each turn releases its response trace and prepared context before the next turn starts. Official history and detached event replay retain their own records. Resources acquired by beforeTurn or context.prepare also close at that turn boundary, including on failure or interruption. Acquire resources needed across turns in a surrounding run Layer or Scope.

To add application instructions to each request:

import { RunContextPreparation, type RunContextHook } from "@yielded/agent/run-options";
import { Effect, Layer } from "effect";
import { Prompt } from "effect/ai";

export const metricContext: RunContextHook = {
  prepare: ({ source }) =>
    Effect.succeed({
      prompt: Prompt.concat(
        Prompt.make([{ role: "system", content: "Use metric units in your answer." }]),
        source,
      ),
    }),
};

export const MetricContextLive = Layer.succeed(RunContextPreparation, { hook: metricContext });

Provide MetricContextLive to AgentRuntime.run or start with Effect.provide, or to AgentRuntime.stream with Stream.provide. With start, provide the Layer around the whole scoped workflow, including awaiting the handle, so its resources remain available until the detached Run finishes. For durable execution, install MetricContextLive when configuring the runtime. Transforms change the model prompt, not stored input or history. Use inputPrompt to choose which input fields the model sees.

Prepared and transient context use full provider requests, bypassing native response-ID reuse so discarded material cannot remain in a provider-held conversation. Prompt caching still applies to matching prefixes. A transient user-message suffix can move OpenAI’s implicit cache-write boundary past the retained history, even when the reference text stays identical. To reuse that history, place native explicit cache markers in the stable prefix through context preparation; keep untrusted references in user messages. Append changing trusted system guidance after source; supported chronological adapters keep it after the retained history. Prepending changing content still invalidates the prefix. Anthropic needs both a capable upstream adapter and a supported model; its pinned adapter retains grouped systems. Place native Anthropic cache markers before changing transient context rather than relying on automatic placement after that suffix. See provider cache settings for the release limitation and xAI routing configuration.

Token-limited calls estimate their current prepared messages. The engine reuses default counts within each prepared prompt and recomputes them after the next context preparation. Calls without contextTokenLimit, resolved model capacity, or tokenBudget skip admission estimates; Context Tools still obtain their live-context estimate on demand. For nondurable compaction, retain the original instruction/input messages or an unambiguous, content-equivalent ordering of them. The engine rejects compaction with CompactionError when that block cannot be mapped safely. Original message identities disambiguate repeated instructions or input text. After compaction, preparation must preserve the content and order of the covered prefix. Rebuilding equivalent messages is supported; replacing, inserting into, or reordering that prefix fails before another model request. Durable reconstruction keeps its canonical coverage checks at commit time.

Resolve routing and capacity together

A host that routes between models can return modelCall from prepare. Capture one resolved provider configuration and build both its native Model Layer and ModelCallContext from that configuration. The engine acquires the Layer once for the turn and reuses it for admission, dispatch, usage accounting, and bounded overflow recovery. Its resources close at the turn boundary, including when preparation or admission fails. A separately configured compaction model retains its own binding. A summary using the captured model must also fit its input allowance; an oversized summary fails with CompactionError before provider I/O.

ModelCallContext carries the model’s full contextCapacity, optional maxInputTokens, its configured outputReserveTokens, and uncountedOverheadTokens. The effective input allowance is the minimum of the definition’s optional context limit, the model’s input limit, and context capacity minus output reserve, less uncounted overhead. An exhausted allowance fails with ContextBudgetError before dispatch. Capacity remains an estimate when exact token counting is unavailable.

The engine counts the prepared prompt, transient references, output contract, run status, and the native Tool schemas dispatched for the call. Supply the provider’s native toolSchemaTransformer, such as toCodecOpenAI from effect/ai/OpenAiStructuredOutput, to include its schema conversion. Reserve additional framing or image costs only when they are absent from those estimates. Do not subtract prompt text or Tool schemas again as overhead. The output reserve must match the selected provider’s generation allowance; completionReserveTokens instead reserves cumulative Run budget for delivery and does not provide this per-call allowance.

Durable hosts must capture resolved model settings in their own schema-validated admission data and restore committed routing changes before preparation. Returning a Layer does not persist its configuration or register a different Agent revision. Keep the original registration available for already-admitted Runs.

Hosts may also return rollover: {} to reset prior history below the capacity threshold. The engine selects the prefix before the current Run’s protected instructions and input; an empty or already covered prefix is a no-op, including after recovery. For an explicit selection, return rollover: { through, handoff? }, where through is an exclusive source-message boundary. Leave that prefix intact in the prepared prompt. The engine maps it to complete canonical records and commits ordinary native rollover. Protected input and pending Tool pairs cannot be discarded. This does not manufacture a model Tool Call, start another Run, or reset its deadline and usage. Do not return a host rollover while a successful new_context request is already pending.

Recall application-owned sources

Memory.recall turns readable, application-selected sources into a bounded transient model view. The framework does not own a memory database, write recalled material, or build an embedding index. An Agent that does not need context loading requires no context service, memory reader, or store. RunContextPreparationPassthrough remains available to explicitly disable inherited context preparation.

Each reader returns MemoryLookup. Found carries ranked MemoryPassage values. NoMatch is a successful empty result. Unavailable and InsufficientFreshness remain distinct in the returned source outcomes. An unavailable or stale essential: true source fails recall; an essential source whose matching passages cannot fit also fails. NoMatch remains successful even for an essential source. Expected reader failures propagate unless the reader deliberately maps them to one of the lookup outcomes.

A passage points back to its authoritative source ID, locator, and known revision. Its attribution records the speaker, observers, original activity time, and the application’s interpretation. recordedAt says when the application recorded the content, while extractedAt says when it made this passage. Neither substitutes for activityAt; use null when the original activity time is unknown.

Recall a Markdown passage directly

This source reads a known Markdown note without a store or adapter:

import { Memory } from "@yielded/agent";
import {
  MemoryAttribution,
  MemoryContent,
  type MemoryLookup,
  MemoryPassage,
  MemoryRecallError,
  MemoryRecallLimits,
  MemorySourceReference,
} from "@yielded/agent/memory-reference";
import { RunContextPreparation, type RunTransientContextHook } from "@yielded/agent/run-options";
import { Effect, Layer } from "effect";
import { Prompt } from "effect/ai";

const limits = MemoryRecallLimits.make({
  maxSources: 1,
  maxItems: 4,
  maxBytes: 16_384,
  maxTokens: 4_096,
  timeoutMillis: 1_000,
});

const note = MemoryPassage.make({
  version: 1,
  source: MemorySourceReference.make({
    id: "project-notes",
    locator: "file:///workspace/notes/queue.md",
    revision: "sha256:8d31",
  }),
  passageId: "retry-policy",
  content: MemoryContent.make({
    text: "# Retry policy\nUse a bounded queue and preserve failed work.",
    attributions: [
      MemoryAttribution.make({
        originId: "meeting:2026-08-28:queue",
        speaker: "Dan",
        observers: ["Chad"],
        locator: "meeting://engineering/2026-08-28#queue",
        activityAt: 1_777_334_400_000,
        interpretation: "proposal awaiting review",
      }),
    ],
    metadata: { format: "markdown" },
    recordedAt: 1_777_420_800_000,
    extractedAt: 1_777_420_801_000,
  }),
});

const lookup: MemoryLookup = { _tag: "Found", passages: [note] };

export const projectNotes: RunTransientContextHook<MemoryRecallError> = {
  load: () =>
    Memory.recall(
      [{ id: "project-notes", essential: true, read: Effect.succeed(lookup) }],
      limits,
    ).pipe(
      Effect.map((recalled) =>
        recalled.text === ""
          ? Prompt.empty
          : Prompt.make([{ role: "user", content: recalled.text }]),
      ),
    ),
};

export const ProjectContextLive = Layer.succeed(RunContextPreparation, {
  transientContext: projectNotes,
});

Provide ProjectContextLive to the run. With an existing agent and input:

const runnable = AgentRuntime.run(agent, input).pipe(
  Effect.provide(ProjectContextLive),
  Effect.catchTags({
    MemoryRecallError: handleRecallFailure,
    CompactionError: handleCompactionFailure,
  }),
);

The service declares AgentInputError | MemoryRecallError | CompactionError; method failures retain their original tags and fields. RunContextPreparationError names that type union, not a wrapper class. Effect.provide adds any errors from acquiring the Layer separately. Adapters handle backend-specific failures or translate them into this contract. Providing a Layer does not add undeclared service-method errors to a program’s error type.

For an application-specific error or requirement channel, the existing generic RunOptions.context and RunOptions.transientContext hooks override the corresponding service fields for that Run. Other service fields remain active. Attached children inherit the host context service, not the parent’s per-Run overrides.

Memory.recall renders positional memory:N reference IDs and provenance for that one result. RecalledMemory.outcomes separately reports what happened at each source. The rendered envelope and every citation remain untrusted model input. Validate model claims against RecalledMemory.passages before presenting them as sourced facts.

Source IDs are local to an authority. A host can set MemoryPassage.authority to share that authority across readers; passages without it are scoped to their reader declaration’s id. Deduplication, conflict detection, and the selected-source limit use authority-qualified IDs. Two independent authorities can therefore both contain profile at revision 1 without being merged or rejected. Direct readers must explicitly share an authority to deduplicate across reader declarations. Authority is an identity boundary, not an authorization grant.

The rendered text substitutes positional memory-authority:N labels for private authority values. These labels are local to the result and qualify its evidence origins; different labels alone do not prove independent corroboration. RecalledMemory.passages retains explicit authority for host-side composition and validation. Use RecalledMemory.text for model input, not a raw serialization of those host passages.

MemoryRecallLimits.maxInputBytes separately bounds the aggregate UTF-8 JSON passage encodings considered by one call, including omitted and duplicate candidates. It defaults to 16 MiB and can be set up to 64 MiB. Exceeding it returns a typed budget error before retaining that candidate’s identity or encoding, even when the source is optional. Reader allocation, result decoding, and one candidate’s serialization occur before this check; it is not a whole-process heap limit. Input-budget exhaustion stops validation and returns no partial context. Within admitted input, conflicting known-revision identities fail even when an earlier passage exceeds the output budget. Identity and conflict checks ignore JSON object member order, including nested metadata, while preserving array order. Equivalent unknown-revision passages within one authority share one citation.

Read an external corpus through an Effect service

Keep authorization, credentials, and query policy inside an application service. This contract has one read method; it does not create a durable copy, write to the corpus, or create embeddings:

import { Memory } from "@yielded/agent";
import {
  type MemoryLookup,
  MemoryRecallError,
  MemoryRecallLimits,
} from "@yielded/agent/memory-reference";
import { RunContextPreparation, type RunTransientContextHook } from "@yielded/agent/run-options";
import { Context, Effect, Layer } from "effect";
import { Prompt } from "effect/ai";

class ExternalCorpus extends Context.Service<
  ExternalCorpus,
  {
    readonly search: (query: string) => Effect.Effect<MemoryLookup, MemoryRecallError>;
  }
>()("app/ExternalCorpus") {}

const limits = MemoryRecallLimits.make({
  maxSources: 8,
  maxItems: 8,
  maxBytes: 32_768,
  maxTokens: 8_192,
  timeoutMillis: 2_000,
});

export const ExternalCorpusMemoryLive = Layer.effect(
  RunContextPreparation,
  Effect.gen(function* () {
    const corpus = yield* ExternalCorpus;
    const transientContext: RunTransientContextHook<MemoryRecallError> = {
      load: () =>
        Memory.recall(
          [
            {
              id: "team-corpus",
              essential: false,
              read: corpus.search("current queue design"),
            },
          ],
          limits,
        ).pipe(
          Effect.map((recalled) =>
            recalled.text === ""
              ? Prompt.empty
              : Prompt.make([{ role: "user", content: recalled.text }]),
          ),
        ),
    };
    return RunContextPreparation.of({ transientContext });
  }),
);

Provide the application’s ExternalCorpus Layer to ExternalCorpusMemoryLive, then provide that closed Layer to an ephemeral Run or to DurableAgentRuntime.layerWithServices with RunToolAuthorization. The durable runtime captures RunContextPreparation in its Scope. Put hook, transientContext, and compactor in the same service value when using all three.

The engine reloads transient context in every normal or grace Turn and after durable recovery, after canonical context preparation and initial compaction succeed. Failure in that initial phase does not read transient sources. Post-load admission can compact canonical history further to make room for the references. This pass and a same-Turn provider-overflow retry reuse the loaded snapshot. Each provider call still has to fit contextTokenLimit; transient text participates in output-contract, run-status, token budget, and completion-reserve admission. Oversized context fails before provider I/O.

Transient references never enter Thread history, canonical records, compaction coverage, or a compaction summary request. Recovery reads the source again instead of replaying an earlier snapshot. RunContextRequest.source is the current Attempt’s official pre-preparation history; use its stable identities or an application-owned query when retrieval requires canonical durable state.

Correct or withdraw a remembered source

Define namespaces with an application-owned identity Schema. Constructor inputs retain brands; keys, writes, documents, access values, and index results retain the definition’s name, version, and identity type. Definitions with the same identity fields but different names or versions are not interchangeable.

import { MemoryNamespace } from "@yielded/agent";
import { MemoryAccess } from "@yielded/agent/memory-revalidation";
import { MemoryKey, MemoryScope } from "@yielded/agent/memory-store";
import { Schema } from "effect";

const TenantId = Schema.NonEmptyString.pipe(Schema.brand("app/TenantId"));
const UserId = Schema.NonEmptyString.pipe(Schema.brand("app/UserId"));
const UserConversations = MemoryNamespace.define({
  name: "app/user-conversations",
  version: 1,
  identity: Schema.Struct({ tenantId: TenantId, userId: UserId }),
});

declare const session: {
  readonly tenantId: typeof TenantId.Type;
  readonly userId: typeof UserId.Type;
};
const conversations = UserConversations.make(session);
const key = MemoryKey.make({ namespace: conversations, id: "conversation-42" });
const access = MemoryAccess.make({ namespace: conversations, scope: MemoryScope.make("private") });

make takes decoded identity values and throws on invalid construction. decode(unknown) decodes external identity input as an Effect with MemoryNamespaceError and no service requirements. restore(address) validates a stored address against the specific definition, including its identity codec, name, and version. It rejects noncanonical addresses and reports wrong definitions or unsupported address formats separately. Validation does not authenticate a principal. Two tenants still share the same TenantId type. The host must establish session identity and authorization before constructing namespaces or access values. "private" is only an application-defined scope name, not a built-in privacy policy.

Namespace encoding and adapter boundaries

Every adapter uses namespace.address, a branded, Schema-validated string. Its format is compact JSON [1, definitionName, definitionVersion, encodedIdentity]. Object keys sort recursively in UTF-16 code-unit order, including numeric-looking keys. Array order is preserved. Strings use JSON escaping without Unicode normalization. JSON number serialization normalizes negative zero to zero. Separator characters cannot join distinct identity fields into the same address.

Identity codecs must be deterministic, synchronous, service-free, and encode to JSON. Branded Structs, records, arrays, and codecs such as Schema.DateFromString are supported. Encoding then decoding normalizes constructor values through the identity codec. Another round trip must leave the encoded identity unchanged. Schema-defined normalization, such as ignored excess Struct fields, deliberately selects the same address. Non-JSON values such as undefined, non-finite numbers, and bigint must be converted by the codec or are rejected.

Names contain 1–256 UTF-16 code units; definition versions are positive safe integers. The full address is at most 4,096 UTF-8 bytes. Encoded identities allow at most 16 nested container levels and 128 entries per container. These limits apply before storage or indexing. Changing a definition version selects a distinct namespace, even for the same identity. It never interprets old memory under a new Schema. Document revisions and SQLite’s storage-format version are separate.

MemoryKey.Wire, MemoryDocument.Wire, MemoryWrite.Wire, and the access/index .Wire Schemas are explicitly heterogeneous transport representations. Their namespaces contain only the canonical address, not a recovered application identity type. Adapter authors use MemoryReader.fromAdapter, MemoryWriter.fromAdapter, and SemanticMemoryIndex.fromAdapter to validate results and restore the caller’s namespace type. For persisted documents outside a port, restore a namespace through its definition, then call MemoryDocument.restore(namespace, input). Never assert a wire value into an application namespace type. Generic types without an explicit namespace parameter describe heterogeneous values; use MemoryKey<typeof conversations> and the equivalent document/write/access/index types for family-specific application APIs.

Namespace identities and addresses can contain sensitive identifiers. They are not retrieval parameters for the model and are not automatically added to recall text, logs, or telemetry. The framework does not supply a registry, tenant membership checks, wildcard search, or a fixed memory taxonomy.

This changes SQLite memory storage to format 2. Format-1 memory data and old string-namespace prepared activity outputs are incompatible and fail decoding. Reset affected development memory and processor data before reusing it. There is no migration or raw-string fallback. Existing Thread history is a separate retention concern.

MemoryReader and MemoryWriter are separate optional capabilities. Use a reader to validate search or cache candidates against the current source. A writer is appropriate only when its adapter can atomically check an expected revision and retain idempotency receipts. A read-only corpus needs no writer. An external memory service can implement these ports without copying its corpus into a framework store.

The host selects a namespace and access scope. A document explicitly lists the scopes allowed to recall it; an empty list grants none. No scope name, shared persona, channel, or DM is enabled by default. Call revalidateMemoryLookup(candidates, access, limits) inside the reader supplied to Memory.recall, immediately before composition. It requires only MemoryReader. The optional third argument accepts maxInputBytes from the recall limits, defaulting to 16 MiB and capped at 64 MiB. Revalidation reads one authoritative source at a time and checks aggregate UTF-8 replacement JSON before retaining it, including duplicate passages. Exceeding this bound fails with MemoryRecallError reason budget before reading later source groups. A single reader result and its schema decoding precede the aggregate retention bound.

Validation binds each returned passage’s private authority to the host-selected namespace, replacing any candidate-supplied authority. Combining independently authorized namespaces therefore preserves their distinct source identities without exposing namespace values in model text. Validation reloads each candidate’s source, excludes missing, withdrawn, or access-revoked documents, and replaces stale text with the current document. Even a same-revision excerpt gets its attribution and metadata from the current source. It survives only if its text occurs there. The usual recall budget can omit a replacement that no longer fits. Source failures stay typed; the consumer must explicitly choose any optional fallback.

import { MemoryNamespace } from "@yielded/agent";
import { MemoryContent } from "@yielded/agent/memory-reference";
import { MemoryKey, MemoryScope, MemoryWriter } from "@yielded/agent/memory-store";
import { Effect, Schema } from "effect";

const TeamMemory = MemoryNamespace.define({
  name: "app/team-memory",
  version: 1,
  identity: Schema.String,
});
const key = MemoryKey.make({ namespace: TeamMemory.make("team-a"), id: "queue-discussion" });

export const correctDiscussion = Effect.fn("correctDiscussion")(function* (
  content: MemoryContent,
  expectedRevision: string,
  operationId: string,
) {
  const writer = yield* MemoryWriter;
  return yield* writer.change({
    _tag: "Put",
    key,
    operationId,
    expectedRevision,
    locator: "chat://engineering/42",
    content,
    scopes: [MemoryScope.make("participating-channels")],
  });
});

export const withdrawDiscussion = Effect.fn("withdrawDiscussion")(function* (
  expectedRevision: string,
  operationId: string,
) {
  const writer = yield* MemoryWriter;
  return yield* writer.change({
    _tag: "Withdraw",
    key,
    operationId,
    expectedRevision,
    reason: "Withdrawn by the source owner",
  });
});

Create a source with Put and expectedRevision: null. Later writes use the current revision; a competing edit returns MemoryConflict without discarding the winning edit. Every replacement records its predecessor reference. modifiedAt tracks the update, while the caller’s original activity, recording, and extraction times remain separate. Applications decide how to correct attribution, resolve conflicting claims, and age discussions or commitments. Timestamps alone never choose a winning claim.

Retry an uncertain write with its original operationId and exactly the same Schema-encoded command. A successful replay returns the original receipt’s document and does not undo later edits or withdrawal. Reusing an operation ID for different content returns MemoryOperationConflict. Revalidate the returned document before recall because a receipt can describe an older revision.

Withdrawal is terminal for that source ID within its namespace. A committed withdrawal excludes the source from validation checks begun afterward. The same rule applies after access revocation. An already captured view, including a same-Turn provider retry, may finish. This guarantee needs an authoritative reader; an eventually consistent service must refuse a view it cannot validate. Do not run the SQLite reader inside a caller-owned stale snapshot transaction.

Withdrawal governs future recall. Original Thread records, past model outputs, idempotency receipts, and backups have separate retention policies. Sensitive-information screening is best effort and does not authorize sharing or guarantee privacy.

For a local persistent source, install the optional SQLite adapter:

import { memoryStoreLayer } from "@yielded/agent/sql-memory-store";
import { SqliteClient } from "@effect/sql-sqlite-node";
import { Layer } from "effect";

export const MemoryLive = memoryStoreLayer.pipe(
  Layer.provide(SqliteClient.layer({ filename: "memory.sqlite" })),
);

memoryStoreLayer provides both ports and creates only its own memory tables. It does not initialize Thread history or a Submission Ledger. memoryReaderLayer checks an existing schema without creating tables or starting a write transaction, and supports SqliteClient.layer({ filename, readonly: true }). It fails with MemoryStorageError when the schema is absent or incompatible; initialize it through memoryStoreLayer in the writer process first. The connection belongs to its Layer’s Scope. The adapter rejects a change before writing when its canonical command, document, or receipt-result JSON exceeds 16,777,216 JavaScript string code units. memoryStoreLayerWithFailpoints accepts a MemoryMutationFailpoint service for transaction and lost-acknowledgement tests. Replayed receipts must match their original command’s predecessor, result kind, content, locator, scopes, and withdrawal reason; mismatches fail as corrupt data. Recall and validation helpers add named Effect spans without source text or metadata annotations. For shared Worker memory, use the Cloudflare memory owner. It validates an entire candidate batch locally and returns one attributed response over one RPC. RecalledMemory.outcomes reports source availability and selected, deduplicated, and omitted counts; the host decides which diagnostics to retain and who can inspect them.

Remember without delaying a response

Remembering separates durable admission from extraction and memory updates. The foreground submits an identity-bound intent and receives a queued acknowledgement after persistence succeeds. Queued means accepted for processing. It does not mean that a fact was accepted, saved, or made available to another Thread. Admission adds bounded persistence work and can fail with a typed error.

Use Remembering.admit(store, intent) from @yielded/agent/remembering for admission and Remembering.make({ proposal, loadSource, extract, merge, cleanup }).advance(...) for a finite worker pass. The RememberingStore module defines the portable Schemas and injectable port. Use native Effect AI extraction and source-aware profile callbacks. Provide RememberingStore.MutationFailpoint.layer in production and replace it for fault tests.

Automatic remembering follows the host’s committed source activity and outbox. It needs no memory Tool or extra model turn. The outbox retains activity when admission is unavailable or full; that backlog does not turn a completed chat response into a failure. Explicit remember actions report admission failure instead of claiming success.

The host runs a finite processing pass in a separate Scope with its own concurrency and model budgets. It owns discovery, source order, job quotas, retry deadlines, parking, and wake repair. Do not await processing after AgentRuntime.run: an awaited callback still delays the response. Do not hold a producer lock, database transaction, or all foreground provider permits while extracting, checking evidence, reading profiles, writing, retrying conflicts, or cleaning up.

The protocol saves two different values:

1. An extracted proposal, encoded with the application’s Schema and bound to the admitted source.
2. The exact prepared MemoryWrite, including its operation ID, expected revision, scopes, content, and content timestamps, before dispatch to MemoryWriter.

Unknown write outcomes retry that saved command unchanged. Only a definite MemoryConflict allows a new operation ID and rebase against the latest target. Rebase retains the saved proposal and does not repeat extraction. The application supplies source-aware merging so concurrent source contributions and human corrections survive. An operation-ID/content mismatch remains MemoryOperationConflict; it is not permission to create another command.

loadSource checks the current authorized source after extraction and before saving a new command. It can return an authoritative invalidation event, which the worker durably admits. A saved command is already an uncertain write and must reconcile even if the source is now unavailable. Source changes after preparation therefore rely on durable suppression and current-source recall checks. Extraction may return null when there is no accepted fact; that finishes without reading a target.

The application also supplies canonical source loading, fact acceptance, authorization, and conditional cleanup. Evidence must identify a known source revision and a literal quote or range from that source. The model cannot select a tenant, target, or authority. A valid quote proves provenance, not the truth of an extracted claim.

Source edits, deletion, revocation, and Forget require durable suppression and cleanup admission before acknowledging the source event. Suppression does not discard an uncertain command: reconciliation must still establish its outcome and remove obsolete source-owned contributions. Current-source recall checks exclude invalid evidence while cleanup is pending. Human corrections have independent provenance and survive source cleanup. Disable new extraction separately from required reconciliation and cleanup.

Active job removal must retain bounded source-to-target references, so later invalidation finds completed contributions without a prior read. Retain those references, suppression, and admission and write receipts throughout the host’s supported replay, backfill, and restore window. Reject new work at capacity without evicting existing obligations. Hosts define source-position authority. Sequence numbers are ordered only within the same opaque authority generation. Different generations are incomparable, and revision strings are never ordered. The host fences old workers and performs any restore or authority cutover explicitly. An old database snapshot cannot prove that no later Forget or revocation occurred. Verify its lineage against the current source authority outside that restored snapshot and reject incompatible state before processing or recall. The protocol supplies no migration or automatic authority cutover.

Recall remains the existing transient read path. Load current permitted memory and run the application’s grouped canonical-source checks without draining jobs, waiting for readiness, or refreshing an index. Track first token, completed response, admission duration, and source-to-authorized-recall delay separately. Healthy background progress and cross-Thread freshness depend on the host’s scheduling and source availability.

Callbacks retain their typed errors and Effect service requirements. Defects and interruption remain distinct from expected failure; a processing deadline interrupts cooperative work and runs its finalizers. The helpers use named Effect spans without attaching source text, proposals, profiles, or private namespace identities. Hosts choose retry policy and operational metrics.

Process committed Thread activity

processCommittedActivity is an optional, finite pass over one application-selected Thread. The host chooses the processor ID and version, eligible records, extractor, destination, sharing scope, invocation schedule, and Thread discovery. No background worker starts when the package is imported. A read-only corpus or direct Markdown recall needs none of these services.

The pass claims its own processor lease and receives any pending output atomically with that claim. It captures ThreadStore.inspectTail once and reads bounded, contiguous pages through that prefix. Records appended afterward belong to a later pass. Pending work beyond the captured tail fails as noncontiguous, including when progress and Thread storage were restored to different points. PersistentHistory exposes the batch from a successful Run together; durable Runs expose incremental committed records. A record’s presence is evidence of its commit, not evidence that the whole Run succeeded. Eligibility rules must account for that distinction.

For each record the processor saves a Schema-encoded extraction, applies that saved output, and then advances its separate cursor. The work ID depends on processor, version, Thread, and sequence, never the worker or clock. Advancing clears pending output in the same transaction; there is no separate pending-work read per record. A saved output wins over re-extraction after restart. Its canonical record digest excludes the adapter’s opaque observation cursor. Another processor version has independent progress; changing a version is an application decision about reprocessing and destination identities.

The destination must reconcile the work ID durably before returning. If application and progress storage are separate, application can repeat after a lost acknowledgment. Keep its receipts for as long as pending output can return, including supported backup/restore windows. Conditional writes must prevent delayed work from overwriting later corrections or withdrawals. The SQLite memory writer supplies those properties; an ordinary non-idempotent external effect does not.

This example opts a structured Dan–Chad discussion into a scope the host also grants Tim. Its extraction policy accepts only original user statements. An assistant repeating the statement does not become another witness. Applications that extract assistant references should retain the original originId instead of assigning independent evidence identity.

import { MemoryNamespace } from "@yielded/agent";
import { MemoryContent } from "@yielded/agent/memory-reference";
import { MemoryKey, MemoryScope, MemoryWrite, MemoryWriter } from "@yielded/agent/memory-store";
import { ThreadId } from "@yielded/agent/identifiers";
import { ActivityPassLimits, processCommittedActivity } from "@yielded/agent/committed-activity";
import { ActivityProcessorKey, type PreparedActivity } from "@yielded/agent/activity-store";
import { type CanonicalRecordEnvelope } from "@yielded/agent/records";
import { Clock, DateTime, Effect, Schema } from "effect";

// The application owns this message format and which Threads use it.
const Statement = Schema.Struct({
  speaker: Schema.NonEmptyString,
  observer: Schema.NonEmptyString,
  text: Schema.NonEmptyString,
  activityAt: Schema.NullOr(Schema.Finite),
  interpretation: Schema.NonEmptyString,
});

const extract = Effect.fn("extractDiscussion")(function* (entry: CanonicalRecordEnvelope) {
  if (entry.record.payload._tag !== "UserInputRecorded") return null;
  const statement = yield* Schema.decodeUnknownEffect(Statement)(entry.record.payload.input);
  const locator = `thread://${entry.threadId}/records/${entry.record.recordId}`;
  const content = yield* MemoryContent.makeEffect({
    text: statement.text,
    attributions: [
      {
        originId: `${entry.threadId}:${entry.record.recordId}`,
        speaker: statement.speaker,
        observers: [statement.observer],
        locator,
        activityAt: statement.activityAt,
        interpretation: statement.interpretation,
      },
    ],
    metadata: {
      threadId: entry.threadId,
      recordId: entry.record.recordId,
      recordSchemaVersion: entry.record.schemaVersion,
      sequence: entry.sequence,
    },
    recordedAt: DateTime.toEpochMillis(entry.record.createdAt),
    extractedAt: yield* Clock.currentTimeMillis,
  });
  return yield* Schema.encodeEffect(MemoryContent)(content);
});

const apply = Effect.fn("applyDiscussion")(function* (work: PreparedActivity) {
  const content = yield* Schema.decodeUnknownEffect(Schema.NullOr(MemoryContent))(work.output);
  if (content === null) return;
  const writer = yield* MemoryWriter;
  const namespace = MemoryNamespace.define({
    name: "app/discussions",
    version: 1,
    identity: Schema.String,
  }).make("dan");
  const command = MemoryWrite.make({
    _tag: "Put",
    key: MemoryKey.make({ namespace, id: work.workId }),
    operationId: work.workId,
    expectedRevision: null,
    locator: `memory://dan-discussions/${work.workId}`,
    content: {
      ...content,
      metadata: { ...content.metadata, sourceRecordDigest: work.recordDigest },
    },
    scopes: [MemoryScope.make("dan-approved-chad-and-tim")],
  });
  yield* writer.change(command);
});

const key = ActivityProcessorKey.make({
  processorId: "discussion-statements",
  processorVersion: "1",
  threadId: Schema.decodeSync(ThreadId)("dan-chad"),
});
const limits = ActivityPassLimits.make({
  maxRecords: 128,
  pageSize: 16,
  timeoutMillis: 30_000,
  leaseMillis: 31_000,
});

// Supply a unique owner for each worker lifetime and the application's Layers.
const ingest = (owner: string) => processCommittedActivity({ key, owner, limits, extract, apply });

The optional SQLite progress Layer can share a connection with the memory writer. Supply the host’s existing ThreadStore and Crypto Layer to the pass as well; the processor never uses Thread ownership epochs, SubmissionLedger, or engine checkpoints for its own progress.

import { activityProcessorStoreLayer } from "@yielded/agent-storage-sqlite/sqlite-activity-store";
import { memoryStoreLayer } from "@yielded/agent/sql-memory-store";
import { SqliteClient } from "@effect/sql-sqlite-node";
import { Layer } from "effect";

const MemoryProcessing = Layer.mergeAll(activityProcessorStoreLayer, memoryStoreLayer).pipe(
  Layer.provide(SqliteClient.layer({ filename: "memory.sqlite" })),
);

Every claim acquisition allocates a fresh fencing epoch, including reacquisition by the same owner after release. Expired or superseded workers cannot replace pending output or advance progress. A destination invocation already in flight may finish the saved output, so its own idempotency and conditional writes remain required. Extraction and application each own a Scope; the pass has a deadline and release gets at most another 500ms. If release fails, the lease expires. The failpoint-enabled Layer exposes initialization and each mutation before, inside, and after its transaction for recovery tests. SQLite rejects activity progress whose JSON exceeds 16,777,216 JavaScript string code units before writing, with ActivityStoreError reason invalid-input. Rejected writes leave prior progress intact.

ActivityProcessorStore.inspect exposes the per-processor, per-version, per-Thread cursor, pending work, and last advancement time. A successful pass reports its captured tail, through sequence, and remaining records in that prefix. These are per-Thread watermarks, not a global freshness promise. Process selected Threads with bounded Effect.forEach and handle each pass’s typed result independently when one failed Thread should not hold back others.

For the example workflow, the healthy commit-to-recallable target is 60 seconds. Hosts must measure that interval from the source commit to successful authoritative recall and choose a schedule that meets it. Recorded, extracted, advanced, indexed, and accessed times describe different events; none replaces the original activity time. An embedding index has its own progress and readiness, and must not advance this extraction cursor.

Add optional semantic retrieval

indexMemorySource and querySemanticMemory use the pinned upstream Effect AI EmbeddingModel. Supply its provider Layer directly. Direct loading, keyword retrieval, external attributed passages, and the cross-Thread workflow above need no embedding model or vector index. The framework does not define another provider abstraction or impose a ranking or aging policy.

The host binds SemanticMemoryProfile to the actual provider, model revision, dimensions, and chunking configuration. Rebuild when any of those change. Matching dimensions alone does not make two models compatible. Provider configuration overrides must not silently change the model behind a live index. Treat different preprocessing or precision settings as a new profile identity. Choose chunk sizes within the selected provider’s input limits. Read-only external sources can implement MemoryReader without a writer; sources with unknown revisions should use direct passage retrieval instead of this index.

import {
  SemanticIndexLimits,
  SemanticQueryLimits,
  indexMemorySource,
  querySemanticMemory,
} from "@yielded/agent/semantic-memory";
import { Memory, MemoryNamespace } from "@yielded/agent";
import { MemoryAccess } from "@yielded/agent/memory-revalidation";
import { MemoryKey, MemoryScope } from "@yielded/agent/memory-store";
import { MemoryRecallLimits } from "@yielded/agent/memory-reference";
import { SemanticMemoryProfile } from "@yielded/agent/semantic-memory-index";
import { inMemorySemanticIndexLayer } from "@yielded/agent-storage-memory/memory-semantic-index";
import { Effect, Schema } from "effect";

// Keep this Layer alive across refreshes and queries. A new instance starts empty.
export const makeIndex = (profile: SemanticMemoryProfile) =>
  inMemorySemanticIndexLayer(profile, { maxSources: 1_024, maxChunks: 8_192 });

const TeamMemory = MemoryNamespace.define({
  name: "app/team-memory",
  version: 1,
  identity: Schema.String,
});
const namespace = TeamMemory.make("team-a");

export const refresh = (key: MemoryKey<typeof namespace>) =>
  indexMemorySource(
    key,
    SemanticIndexLimits.make({
      maxSourceBytes: 262_144,
      maxChunks: 128,
      timeoutMillis: 30_000,
    }),
  );

export const recall = (query: string) =>
  Memory.recall(
    [
      {
        id: "team-semantic",
        essential: false,
        read: querySemanticMemory(
          query,
          MemoryAccess.make({
            namespace,
            scope: MemoryScope.make("participating-channels"),
          }),
          SemanticQueryLimits.make({
            maxQueryBytes: 8_192,
            maxCandidates: 16,
            maxScannedChunks: 8_192,
            minScore: 0.35,
            timeoutMillis: 1_000,
          }),
        ).pipe(Effect.map((result) => result.lookup)),
      },
    ],
    MemoryRecallLimits.make({
      maxSources: 8,
      maxItems: 8,
      maxBytes: 16_384,
      maxTokens: 4_096,
      timeoutMillis: 1_000,
    }),
  );

Provide the same index instance, MemoryReader, and native EmbeddingModel to both operations. Refresh also requires Effect Crypto. The provider Layer owns its resources; the index belongs to its Layer’s Scope. Captured index methods fail after that Scope closes. Put recall in the transient-context hook above. The final envelope, including attribution and citations, must fit Memory.recall’s item, UTF-8 byte, and token limits; the engine separately admits the full prompt. essential: false permits explicitly returned unavailable outcomes. It does not swallow errors. Map only intended expected failures to an Unavailable lookup in application policy. SemanticQueryLimits.maxOutputBytes bounds aggregate UTF-8 JSON passage output before retention, including repeated attribution and metadata. It defaults to 16 MiB, accepts at most 64 MiB, and fails with SemanticMemoryError reason budget. Source-byte limits count each distinct source once; they do not substitute for this output bound or the final rendered recall limits.

Chunking greedily packs complete Unicode codepoints up to maxChunkBytes. It neither summarizes nor silently drops a source suffix. Chunk IDs include a digest of the whole profile and the ordinal; candidates also carry source identity, revision, generation, and byte offsets. Indexing checks source-byte and chunk-count limits before calling the provider. Returned vectors must match the profile and have a positive finite norm. This simple chunker is a deterministic baseline; it makes no sentence-boundary or relevance promise.

inMemorySemanticIndexLayer is a replaceable exact cosine adapter. It bounds all registered source keys, including withdrawal tombstones, and all ready chunks. A search over its scan limit fails instead of ranking an arbitrary prefix. Scores tie by source ID, revision, and chunk ordinal. Configuration rejects maxChunks * profile.dimensions above 16,777,216 vector components before allocating index state. For a 4,096-dimensional profile, set maxChunks to at most 4,096. This bounds stored vectors, not total process memory or allocations made by callers. maxSourceBytes caps the aggregate UTF-8 JSON of retained source identities, including terminal tombstones. It defaults to 16 MiB and accepts at most 64 MiB. Replacement and withdrawal check this bound atomically before changing the index. A rejected change leaves the prior source and chunks intact; a smaller replacement releases identity capacity. Replaying a withdrawal does not charge the same tombstone twice. Map keys, object overhead, and vector storage are not included in this source-encoding budget. The adapter holds no authoritative documents or attribution.

Refresh prepares chunks and embeddings before calling SemanticMemoryIndex.replace. Replacement validates the profile and source revision, then exchanges all chunks atomically. Failed or cancelled refreshes leave the last successful index intact. Older generations and divergent same-generation identities are fenced. Withdrawal is terminal within the instance and blocks delayed replacements. The index exposes no build epochs, publication states, inspection, or mutation failpoints. Closing and recreating the Layer discards all chunks and tombstones; rebuild from current authoritative sources before requiring complete semantic recall.

The index and source are independent. Refresh reads the source again before publication, but a change can still occur between that read and the index write. Every query therefore rereads each candidate source, checks namespace, access, revision, generation, locator, and exact excerpt, and takes attribution and metadata from that source. Stale candidates are omitted; their old score is never assigned to corrected text. A source correction may temporarily reduce recall until refresh finishes. Missing, withdrawn, or revoked sources cannot pass checks begun after the authoritative change. Already captured views may finish, as described under withdrawal. Returned passages bind their private authority to the query’s authorized namespace, so downstream recall can combine independent namespaces without confusing their source IDs. Recall renders only opaque authority labels.

Queries group candidates by source, read each source once, and restore the original index ranking after validation. Full source documents and their excerpt-check encodings are local to one group. SemanticQueryLimits.maxSourceBytes separately bounds the aggregate UTF-8 JSON of distinct authorized sources with generation, revision, and locator matches. It defaults to 16 MiB and can be set up to 64 MiB. Missing, withdrawn, unauthorized, and identity-stale sources are excluded without consuming this budget. Exceeding it returns a typed budget error with no partial result. Reader allocation, decoding, and one source’s serialization precede this check; it is not a whole-process heap limit. The indexing limit with the same name bounds one source’s text instead.

SemanticQueryResult reports scanned chunks, excluded stale and unauthorized candidates, query embedding usage when the provider supplies it. It makes no completeness claim; the host owns discovery, refresh scheduling, and required freshness. An empty index or no-match result does not prove the corpus has no relevant memory. No source text, query text, attribution, or vectors are attached to the helpers’ Effect spans.

Deadlines interrupt cooperative work and run finalizers. A provider that cannot cancel native I/O may need to drain its active call before finalizing; account for that in the host’s latency policy. The reproducible tooling/semantic-memory-eval consumer compares direct, lexical, and real local embedding recall on a frozen synthetic corpus. It separates warm query latency, cached-file cold model startup, source-commit-to-recallable lag, background extraction/indexing, and injected slow or failed requests. Its declared targets are 250 ms warm added recall, 3 seconds with a cold model instance and cached files, and 60 seconds from a healthy source commit to recall. These are example targets, not provider or production guarantees. The example reports misses and contradictory retrievals; applications must choose their own decision, commitment, and aging policies.

Limit tool output

Every application tool result, including MCP output, passes through toolResultBounds once before history or durable storage. Results within the limit keep their encoded bytes. Larger results use one canonical envelope:

{
  "truncatedToolResult": true,
  "originalBytes": 412887,
  "head": "...first half of the byte budget...",
  "tail": "...last half..."
}

The model and journal see the same envelope. Replay therefore stays consistent. The default limit is 50 KiB. Provider-executed tool results are exempt because the provider has already put them in the response.

The run-status message

With runStatus: "appended", each outgoing request ends with a derived status line:

<run-status>turn 3/12 · tool-calls 11/24 · tokens 84210/200000 · research-remaining 83790 · completion-reserve 32000 · last-context 23480 · elapsed 74s/300s</run-status>

At 80 percent of a limit, the line asks the model to wrap up. The token warning uses the research balance after reserving completion capacity. The runtime also warns when that balance cannot cover another input as large as the last call.

runStatus defaults to "off". The optional status line is built for each request and never enters canonical history. With chronological adapters, it is trailing system/developer guidance, leaving the retained user/tool message available as a cache boundary. Other adapters receive it as a trailing user message; account for their cache-boundary behavior when enabling it. Provider cache settings remain host-owned, and changing other prompt content can still prevent reuse. Host-enforced limits and BudgetWarning events remain active with either setting.

Budget warnings and finalization

Crossing 80 percent emits one BudgetWarning event for that dimension. Turn, tool call, and token exhaustion follow onExhaustion.

With "final-answer", an over-budget tool batch runs no handlers. The next request forbids tool use, except for the definition’s singleton completion tool. Turn exhaustion allows one grace turn. Token exhaustion completes from the breaching response when it already contains decodable output; otherwise it allows the same single constrained turn.

The result and RunCompleted event report finishReason: "budget-exhausted". Their exhausted field names the limit: "tokens", "turns", or "tool-calls".

Delegated child results carry the same marker through SubagentCompleted.exhausted and projectResult. onExhaustion: "fail" rejects work after the breach. Duration and cost breaches always fail because another model call would add time or cost.

Compaction

With contextTokenLimit, the engine estimates the next prompt before every turn. Ordinary append-only history starts from the last provider-reported input and estimates appended content. Preparation and transient-context hooks use a fresh estimate. Full estimates exclude repeated system messages removed from the outgoing request. Within a turn, the engine reuses the history view and estimate until compaction changes them. The default compactor then:

1. clears old application tool results outside the preferred keepRecentTokens tail while keeping message structure and call/result pairs;
2. if pruning is insufficient, makes one metered summary call and keeps the instruction prefix, summary, and recent tail. The retained tail can exceed keepRecentTokens to keep user inputs with their replies and tool calls with their results.

Compaction changes the model view. It never rewrites the thread log. CompactionPerformed reports each reduction. DN and DC also append CompactionCreated, so later attempts and runs use the same compacted view.

A summary must finish successfully and contain non-whitespace text. The interpreter charges its usage before validating it. A rejected summary leaves the previous summary and coverage in place; already committed pruning remains. All summaries, including custom strategy decisions, are limited to 65,536 characters and fail with CompactionError above that bound. Summaries are never silently truncated to fit.

The complete default summarizer request fits within 80,000 characters, including instructions, transcript delimiters, and the previous summary. It retains the oldest and newest covered messages and marks the omitted middle. Message and string-result previews are clipped before rendering; oversized structured tool results receive an explicit omission marker. An oversized previous summary is rejected before rendering. These limits change only the model view, leaving canonical evidence intact.

If the provider reports context overflow, the engine may compact and retry once. Transport ambiguity can duplicate that model call. A second rejection, or overflow without a definition context limit or resolved modelCall allowance, fails as ContextOverflowError.

Replace compaction

Install a ContextCompactor Layer to change the strategy, estimator, or summary model. The default is ContextCompactor.layer. All AgentRuntime entry points also need a Thread history policy.

const compactorLayer = ContextCompactor.layerWithModel(summaryModel);

const result = AgentRuntime.run(agent, input).pipe(Effect.provide(compactorLayer));

The summary model’s Layer requirements stay visible. Its usage is charged under that model’s provider and name.

A custom compact implementation emits CompactionDecision values. Each decision covers an exclusive source prefix and clears old tool results, supplies a summary, or starts a fresh context window. The interpreter rejects cuts through tool pairs, changes to protected instructions or input, decisions that make no progress, and more than one prune followed by one replacement in a turn. request.trigger distinguishes pressure, overflow, and an explicit requested rollover; request.modelCallAllowed tells the strategy whether a separate summary call is admitted. Summary calls must use request.summarize so metering, response limits, and the run deadline still apply.

estimate must return a non-negative finite integer. Strategy failures use CompactionError. Defects and interruption retain their Effect meaning.

Durable coordinators map the covered prefix to complete canonical records before committing a decision. Summarization covers prior-run records. Pruning and rollover can also cover settled batches inside the current run, preserving its original instructions and input. A transform or decision that cannot map cleanly fails before the view changes. The canonical log remains append-only.

A completed Tool batch enters official history before the repeated-failure limit ends a Run, including provider-executed results. A later Run may cover an incomplete prior-Run batch already omitted from its prompt only when canonical records prove that prior Run ended after its final response. This changes coverage eligibility without settling, rewriting, or replaying the old call. Current-Run, nonterminal, and malformed post-terminal batches remain protected.

Install a compactor for durable runs

Provide ContextCompactor directly to the durable host Layer. In this example, HostLive is your application’s assembled host Layer:

import { ContextCompactor } from "@yielded/agent/context-compactor";
import { OpenAiLanguageModel } from "@effect/ai-openai";
import { Layer } from "effect";

export const CompactorLive = ContextCompactor.layerWithModel(
  OpenAiLanguageModel.model("gpt-6-luna"),
);

export const RuntimeLive = HostLive.pipe(Layer.provide(CompactorLive));

Provide the summary model’s client to CompactorLive. The same composition works with the Node host Layer, Cloudflare application layer, or custom runtime assembly. To use a prompt transform and a custom compactor together, provide RunContextPreparation and ContextCompactor independently. The runtime captures both when its Layer is acquired and retains them across replacement attempts. Providing a different compactor around a worker call does not replace the host’s choice.

Start fresh context windows

ContextCompactor.layerRollover starts a fresh window under context pressure or on the one allowed provider-overflow retry. It makes no summary-model call. The engine retains the original instructions and input, inserts a window marker and bounded recovery excerpts, and keeps trailing user steering verbatim. A rollover changes the prompt within the same run; turn, tool, duration, and spending limits continue accumulating. An automatic rollover that cannot reduce the prompt or fit its handoff fails with CompactionError; admission still checks the final prompt against contextTokenLimit.

For model-directed control, include the native ContextTools.toolkit and its handlers:

import { ContextTools } from "@yielded/agent";
import { ContextCompactor } from "@yielded/agent/context-compactor";
import { ThreadContextHistory } from "@yielded/agent";
import { Layer } from "effect";

const tools = ContextTools.toolkit;
const toolHandlers = ContextTools.layer;
const compactor = ContextCompactor.layerRollover;
const history = ThreadContextHistory.layer({ maxRecords: 16_384 });

// Supply your authorized ThreadStore to history, then provide it at the Run boundary.
const contextServices = Layer.merge(compactor, history);

Merge tools into the Agent’s toolkit and provide toolHandlers when building the Agent. Install compactor directly to the durable host Layer, as shown above. Supply history where the registered Agent’s tool services are provided. It depends on the host’s ThreadStore; an ephemeral application can implement the ContextHistory port over its retained transcript.

Tool	Behavior
new_context({ handoff? })	Requests a rollover before the next turn. Call it alone; a short handoff is optional.
get_context_remaining({})	Returns window identity and estimated live tokens. Unconfigured capacity is null.
search_context_windows({ query, limit?, beforeRecordId? })	Searches retained evidence newest first; returns at most three record snippets per page.
read_context_window({ recordId, offset?, maxChars? })	Reads up to 5,000 characters; use nextOffset to continue.

History search matches one literal substring, after trimming surrounding whitespace and JavaScript case folding. It does not interpret multiple keywords, AND/OR, wildcards, regular expressions, or quotes as query syntax. Search for a short exact phrase, document label, or identifier: "RECEIPTS dock-03" only finds those characters together; "dock-03" finds that label wherever it occurs in eligible text.

Recent search calls and notes can themselves match. To reach older records, repeat the query with beforeRecordId set to the last hit’s recordId. The anchor and every newer canonical position are excluded. Continue until the result contains fewer than the requested limit (default three), including an empty array. A full final page needs one more request to see the empty page. For example, these model tool calls use an illustrative returned ID:

search_context_windows({ query: "dock-03", limit: 3 });
// If the last hit has recordId "record:42":
search_context_windows({ query: "dock-03", limit: 3, beforeRecordId: "record:42" });
// Once an original source is found, read its recordId with read_context_window.

ContextHistory.search keeps its existing hit-array result and one-to-twenty result limit; existing callers can omit the new optional field. IDs are opaque, not sortable positions or authorization capabilities. An anchor must be eligible retained evidence in the current Thread, but need not match the query. An unknown, removed, foreign, or non-evidence anchor returns ContextHistoryError with reason not-found; malformed parameters return invalid-input. Each request captures a fresh tail and checks current authorization. New appends cannot push older matches out of a continued page, but pages do not share a retained snapshot or bypass retention. A scan, deadline, or index-work limit is an explicit failure, never an exhausted page. ThreadContextHistory searches backwards from the captured tail or exact anchor in eight-record pages. maxRecords limits work per search, regardless of Thread age; finding a full page can stop early. Exact reads and window ownership use native locators across archived ranges. Storage verification separately checks global integrity. Search snippets remain at most 2,000 UTF-16 characters each; text reads use their existing bounds. Every continuation is another Tool call charged to the Run’s ordinary cumulative limits.

Both the default compactor and layerRollover honor an explicit new_context request. Custom strategies must emit its requested rollover and cutoff. The engine recognizes the trusted Tool annotation, never the tool’s name. Mixed batches and programmatic broker calls are rejected before handlers start. Failed tool results do not trigger rollover. A successful request is recovered from its canonical result if ownership is lost before the boundary is written; after the boundary is written, recovery uses the saved window without replaying covered tools.

The optional handoff is saved with the rollover boundary and included in the next model prompt; it does not require separate notes tools. It is limited to 20,000 characters and 32 KiB of JSON-encoded UTF-8. Automatic handoffs are smaller deterministic excerpts of covered user messages and the last tool batch; they may omit older progress and do not claim that external actions succeeded. Notes and history are untrusted working evidence. Verify live state before repeating an action.

MemoryNotes.toolkit supplies read_notes and write_notes. Bind MemoryNotes.layer to one host-selected MemoryKey, locator, attributions, and scopes, then supply your existing MemoryReader, MemoryWriter, and Effect AI IdGenerator.IdGenerator. For default operation identities, provide Layer.succeed(IdGenerator.IdGenerator, IdGenerator.defaultIdGenerator) from effect/ai. Notes are a full document replacement with expectedRevision; conflicts require reading and merging again. Durable Steps retain the exact write command and operation identity for recovery. Notes survive a process restart only when the selected Memory store does. The model cannot choose a filesystem path, another memory key, or another thread through these tools.

When using MemoryNotes, tell the Agent to save important state before new_context, read its notes after rollover, and use history to verify details. Notes are optional and independent of window transitions; the framework does not synthesize or overwrite them automatically. This works with any model that can use the native tools.

The canonical history adapter scans a fixed tail in bounded pages, with a default 10-second deadline. It fails explicitly when the configured scan limit is exceeded. It exposes model-visible text, tool calls, and retained tool results, excluding system instructions and operational records. It can retrieve evidence removed by compaction, but cannot recover tool bytes discarded by result bounds, transient references, or records removed by a separate retention policy. Tightening Tool result bounds below these tools’ maximum payloads may truncate their results too.

For an indexed adapter, use @yielded/agent/thread-context-history-projection to project each canonical record into eligible retained text or a rollover boundary. Its query normalization and snippet matching preserve the native literal, case-folded search semantics. Operational records still consume their canonical sequence even when their projection is empty.

Commit each contiguous projection batch and its watermark atomically. Window membership uses coversThrough, which may precede the boundary’s own record: a later rollover can relabel evidence already in the index. Capture one canonical tail for each lookup and restrict both evidence and boundary records to it. Do not return partial results when the index has not covered that prefix. The index supplies candidate identities and sequences; recheck host authorization and reread each selected canonical record before returning evidence. A known sequence permits a single ThreadStore.read with afterSequence: sequence - 1 and limit: 1, followed by identity checks.

Custom ContextHistory adapters, including application-owned Cloudflare indexes, must implement beforeRecordId before using the updated native search tool. Resolve the anchor in the authorized Thread and captured tail, reread its canonical record, and check its identity and evidence eligibility. Then select literal matches with sequence < anchor.sequence, ordered by descending sequence, up to the requested limit. Keep boundary lookup bounded by the captured tail, not the anchor: a later rollover commit can assign older evidence to a window. Reverify each selected source and its literal match. Bound index catch-up, candidate work, result bytes, and deadlines; fail explicitly when a complete page cannot be established. Do not emulate this with an offset into a changing result set, silently ignore the anchor, or truncate candidates before matching. An adapter awaiting this update must reject anchored requests with unavailable rather than returning the first page again. The built-in ThreadContextHistory.layer implements the contract over every ThreadStore; its default scan ceiling and deadline are unchanged, and storage adapters need no persisted-format migration.

An evidence index supplies retrieval candidates; canonical facts and the submission ledger own recovery. A Run continuation references the exact original input, saved context, and declared operations. Compaction changes model context without changing those execution facts or accumulated charges. Selected recovery reads a bounded Run prefix and suffix; unavailable or corrupt required evidence fails typed and leaves the work owed. Initial context assembly and complete history export have their own costs and storage bounds.

Manage summaries yourself

@yielded/agent also has an application-managed data path. prepareModelContext derives bounded text from a Thread.Thread. digestCompactionSource binds a CompactionArtifact to that source. applyCompaction validates the artifact before replacing covered view messages with its summary. The application creates, stores, and applies the artifact.

RetainedFact values remain artifact metadata. They do not enter the prompt or a separate memory store automatically. This path is separate from ContextCompactor; the interpreter does not call applyCompaction. Memory.recall is the optional read path for application-owned sources; it does not persist passages or turn compaction artifacts into memory.

Track usage

The budget snapshot separates cumulative and live context usage:

const report = Effect.gen(function* () {
  const usage = yield* budget.snapshot;
  usage.inputTokens;
  usage.cacheReadInputTokens;
  usage.cacheWriteInputTokens;
  usage.lastInputTokens;
  usage.lastOutputTokens;
});

Watch lastInputTokens for current context pressure. inputTokens is cumulative and grows on every call. Provider caching may lower its cost. See Run & stream for hook setup.

Choose limits

• Leave output and summary room under the model window. For a 200k window, start with a contextTokenLimit between 150k and 170k.
• keepRecentTokens defaults to 20k. Pruning retains this preferred tail while the full prompt fits its target; under pressure it clears additional older results. The newest tool result always stays verbatim. If the remaining prompt cannot fit, the configured summary or overflow policy applies.
• Use tokenBudget as a runaway limit. Use costBudgetMicrousd to bound estimated spend.
• Delegate noisy research to bounded children so their raw tool output stays out of the parent context.