Memory Pointer Pattern

The problem

When a tool returns 200KB of logs, or 5,000 database rows, or a full PDF, passing the raw output back into the LLM context causes three failures:

Token blowup. A 200KB log dump is ~50,000 tokens. At GPT-4o’s $2.50 / 1M input rate, that's$ 0.13 per turn just to feed the model context it doesn’t need.
Silent truncation. Most providers cap at 128K–200K tokens. A few big tool calls can break the conversation entirely.
Worse answers. Models get distracted by huge irrelevant blobs (the “needle in a haystack” problem).

IBM reported reducing 20,000,000 tokens to 1,234 tokens in production by adopting this pattern. The principle is simple: store the big value outside the LLM’s view, give the LLM a short pointer instead.

How it works

                   ┌──────────────────────────────────┐
   tool returns ──▶│  ToolExecutor (size check)        │
                   └──────────────────────────────────┘
                              │
            < maxToolOutputBytes ─▼      ≥ maxToolOutputBytes ─▼
             ┌────────────────┐        ┌─────────────────────────────────┐
             │ Pass through   │        │ Store in ArtifactStore on        │
             │ unchanged      │        │ RunContext.sessionState          │
             └────────────────┘        │ Return { pointer, preview, ... } │
                                       └─────────────────────────────────┘

The agent sees only the short JSON pointer envelope. If it needs the full value later, it calls the auto-injected getArtifact(pointer) tool.

Enabling on an Agent

import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "log-investigator",
  model: openai("gpt-4o"),
  tools: [fetchLogs, summarize],
  artifacts: {
    enabled: true,                    // turns the pattern on
    maxToolOutputBytes: 50 * 1024,    // default: 50KB
    previewChars: 200,                // default: 200
  },
});

`ArtifactsConfig` fields

Field	Type	Default	Meaning
`enabled`	`boolean`	`false`	Master switch. When `true`, the auto-conversion runs after every tool call.
`maxToolOutputBytes`	`number`	`51200` (50KB)	Threshold above which the result becomes an artifact. UTF-8 byte length of the stringified content.
`previewChars`	`number`	`200`	How many chars of the original content are kept in the visible `preview` field.

When enabled: true, three tools are auto-injected into the agent’s tool list:

storeArtifact(name, value, contentType?)
getArtifact(pointerOrName)
listArtifacts()

The auto-converted result

When a tool exceeds the threshold, its result is replaced with a JSON string of this shape:

{
  "pointer": "art:550e8400-e29b-41d4-a716-446655440000",
  "preview": "[auth-service] error: something went wrong\nerror: something went wrong\n...(truncated, 98000 more chars)",
  "sizeBytes": 102400,
  "note": "Output too large; full value stored as artifact. Call getArtifact(pointer) to read it."
}

The LLM sees ~250 tokens instead of ~25,000. The preview field is critical — it lets the model decide whether the artifact is interesting before fetching the full value.

Manual artifact storage

Tools can opt into the pattern explicitly:

import { storeArtifact } from "@agentium/core";
import { defineTool } from "@agentium/core";
import { z } from "zod";

const fetchReport = defineTool({
  name: "fetchReport",
  description: "Download the quarterly report PDF as text.",
  parameters: z.object({ quarter: z.string() }),
  execute: async ({ quarter }, ctx) => {
    const huge = await downloadReport(quarter); // 10MB of text

    const ptr = storeArtifact(ctx, huge, {
      name: `report-${quarter}`,
      contentType: "application/json",
      previewChars: 500,
    });

    return JSON.stringify({
      pointer: ptr.pointer,
      preview: ptr.preview,
      sizeBytes: ptr.sizeBytes,
    });
  },
});

Now the LLM can refer to the artifact by name:

> Read report-2024-q4 and summarize the top 5 KPIs.

The agent calls getArtifact("report-2024-q4") (by name, not pointer) and gets the full text.

API reference

`storeArtifact(ctx, value, opts?)`

Stores a value and returns a pointer.

function storeArtifact(
  ctx: RunContext,
  value: unknown,
  opts?: {
    name?: string;          // optional human-readable name (also looked up via getArtifact)
    contentType?: string;   // MIME-style hint
    previewChars?: number;  // override the default preview length
  },
): ArtifactPointer;

interface ArtifactPointer {
  pointer: string;          // "art:<uuid>"
  preview: string;          // short preview of value
  sizeBytes: number;        // serialized size
  name?: string;            // echoed back if provided
}

value can be any JSON-serializable object or a string. Objects are JSON.stringify’d for preview and size computation; the raw value is preserved for retrieval.

`getArtifact(ctx, pointerOrName)`

Looks up an artifact by either its art: pointer or its name. Returns null for missing.

function getArtifact(ctx: RunContext, pointerOrName: string): StoredArtifact | null;

interface StoredArtifact {
  id: string;
  name?: string;
  value: unknown;
  preview: string;
  sizeBytes: number;
  storedAt: number;       // Date.now()
  contentType?: string;
}

`listArtifacts(ctx)`

Returns every artifact stored in the current RunContext, deduplicated (name aliases don’t double-count).

function listArtifacts(ctx: RunContext): StoredArtifact[];

`isPointer(value)`

Helper for runtime checks:

function isPointer(value: unknown): value is string;
// returns true for any string starting with "art:"

`approxByteSize(value)`

Quick UTF-8 size estimate used by the executor:

function approxByteSize(value: unknown): number;

Falls back to 0 for circular objects.

Auto-injected tools (when `artifacts.enabled`)

Tool name	Parameters	Returns
`storeArtifact`	`{ name: string, value: string, contentType?: string }`	JSON `{ pointer, preview, sizeBytes, name }`
`getArtifact`	`{ pointerOrName: string }`	The raw value (or `"[no artifact found for '...']"`)
`listArtifacts`	`{}`	JSON array of `{ pointer, name, sizeBytes, preview, contentType, storedAt }`

These tools intentionally bypass the size threshold themselves — otherwise storeArtifact calls would recursively wrap their own output.

Lifecycle and scope

Artifacts live on RunContext.sessionState["__artifacts"] as a Map<string, StoredArtifact>. That means:

Per-run by default: A new RunContext starts with an empty map.
Per-session if you persist sessionState: Pass the same sessionState between runs (e.g. via your session manager) and artifacts carry forward.
Not persisted by default: The default SessionManager does write sessionState to storage, but the map serializes to [] unless you use a JSON-aware codec. For durable artifacts, persist them explicitly to your own storage and re-hydrate.

When to use

Database query tools that may return many rows
Web scraping / page fetch tools
Log search tools
File reading tools where files can be > a few hundred KB
Tool chains where output of step N is input to step N+1 but doesn’t need to pass through the LLM in between

When NOT to use

Short status checks (“is X online?”) — overhead isn’t worth it
Single-row lookups
Anything the LLM legitimately needs to reason over inline (e.g. a small JSON config)
Streaming output (the threshold check is one-shot on the final result)

​Memory Pointer Pattern

​The problem

​How it works

​Enabling on an Agent

​ArtifactsConfig fields

​The auto-converted result

​Manual artifact storage

​API reference

​storeArtifact(ctx, value, opts?)

​getArtifact(ctx, pointerOrName)

​listArtifacts(ctx)

​isPointer(value)

​approxByteSize(value)

​Auto-injected tools (when artifacts.enabled)

​Lifecycle and scope

​When to use

​When NOT to use

​See also