agent-scratchpad

Lightweight key-value scratchpad for AI agent working memory.

agent-scratchpad is a zero-dependency, in-process key-value store purpose-built for AI agent reasoning loops. Agents executing multi-step workflows (ReAct, Plan-and-Execute, Chain-of-Thought with tool use) need a place to write down intermediate state between steps -- tool outputs, extracted entities, partial computations, decision rationale, and task decomposition state. This package provides that working memory with typed entries, automatic TTL-based expiration, hierarchical namespaces, tag-based querying, point-in-time snapshots, event-driven change observation, pluggable persistence, and a toContext() method that renders scratchpad contents directly into LLM prompts. It works with any agent framework or custom agent loop.

Installation

npm install agent-scratchpad

Quick Start

import { createScratchpad } from 'agent-scratchpad';

const pad = createScratchpad();

// Store intermediate results
pad.set('step', 'analyze');
pad.set('user', { id: 42, name: 'Alice' });

console.log(pad.get('step'));   // 'analyze'
console.log(pad.has('user'));   // true
console.log(pad.keys());       // ['step', 'user']

// Render contents for an LLM prompt
const context = pad.toContext({ format: 'markdown' });

Features

Zero runtime dependencies -- all logic uses built-in JavaScript APIs
TypeScript-first -- full generic type safety on get<T>() and set<T>()
TTL expiration -- fixed or sliding time-to-live with lazy and active sweep modes
Hierarchical namespaces -- scope entries per agent, task, or step with pad.namespace('name')
Tag-based querying -- label entries and retrieve them with findByTag()
Snapshots -- capture and restore full scratchpad state for backtracking and debugging
Context rendering -- format entries as Markdown, XML, JSON, or key-value pairs for LLM prompts
Event system -- observe set, delete, expire, and clear events
Pluggable persistence -- save and load scratchpad state via a simple adapter interface
Framework-agnostic -- works with LangChain, Vercel AI SDK, AutoGen, CrewAI, or any custom loop

API Reference

`createScratchpad(options?)`

Creates a new Scratchpad instance.

import { createScratchpad } from 'agent-scratchpad';

const pad = createScratchpad({
  defaultTtl: 60_000,
  defaultSlidingTtl: false,
  sweepIntervalMs: 10_000,
  now: () => Date.now(),
  persistence: adapter,
});

Parameters:

Option	Type	Default	Description
`defaultTtl`	`number \| null`	`null`	Default TTL in milliseconds applied to entries that do not specify their own. `null` means no expiration.
`defaultSlidingTtl`	`boolean`	`false`	Whether the default TTL mode is sliding (resets on access) or fixed (from creation).
`sweepIntervalMs`	`number \| null`	`null`	Interval in milliseconds for proactive background sweep of expired entries. `null` disables active sweep.
`now`	`() => number`	`Date.now`	Custom time source. Useful for deterministic testing.
`persistence`	`PersistenceAdapter`	`undefined`	Optional adapter for saving and loading scratchpad state.

Returns: Scratchpad

`fromSnapshot(snapshot, options?)`

Creates a new Scratchpad pre-populated from a previously captured snapshot.

import { fromSnapshot } from 'agent-scratchpad';

const pad = fromSnapshot(snap, { defaultTtl: 30_000 });

Parameters:

snapshot (ScratchpadSnapshot) -- A snapshot object previously obtained from pad.snapshot() or pad.serialize().
options (ScratchpadOptions, optional) -- Configuration options passed to the underlying createScratchpad() call.

Returns: Scratchpad

Scratchpad Methods

`set<T>(key, value, options?)`

Stores a value under the given key. If the key already exists, updates the value and updatedAt timestamp while preserving createdAt.

pad.set('result', { score: 0.95 });
pad.set('cache', 'value', { ttl: 5_000, tags: ['temporary'] });
pad.set('session', token, { ttl: 30_000, slidingTtl: true });

Parameters:

key (string) -- The entry key.
value (T) -- The value to store.
options (EntryOptions, optional) -- Per-entry configuration.

Option	Type	Default	Description
`ttl`	`number \| null`	Inherits `defaultTtl`	TTL in milliseconds. `null` disables expiration for this entry.
`slidingTtl`	`boolean`	Inherits `defaultSlidingTtl`	Whether TTL resets on each `get()` access.
`tags`	`string[]`	`[]`	String labels for categorizing the entry.

Returns: void

`get<T>(key)`

Retrieves the value for a key. If the entry has expired, it is removed, an expire event fires, and undefined is returned. On a successful read, accessedAt is updated (which resets the sliding TTL window if applicable).

const user = pad.get<{ id: number; name: string }>('user');

Parameters:

key (string) -- The entry key.

Returns: T | undefined

`has(key)`

Checks whether a key exists and is not expired. Expired entries are removed and trigger an expire event.

if (pad.has('apiResponse')) {
  // entry is live
}

Parameters:

key (string) -- The entry key.

Returns: boolean

`delete(key)`

Removes an entry by key. Fires a delete event if the entry existed.

const removed = pad.delete('staleData'); // true if it existed

Parameters:

key (string) -- The entry key.

Returns: boolean -- true if the entry existed and was removed, false otherwise.

`clear()`

Removes all entries from the scratchpad. Fires a clear event with the count of removed entries.

pad.clear();

Returns: void

`keys()`

Returns an array of all non-expired keys. Expired entries encountered during iteration are excluded.

const allKeys = pad.keys(); // ['step', 'user', 'result']

Returns: string[]

`entries()`

Returns an array of [key, ScratchpadEntry] tuples for all non-expired entries.

for (const [key, entry] of pad.entries()) {
  console.log(key, entry.value, entry.tags);
}

Returns: [string, ScratchpadEntry][]

`findByTag(tag)`

Returns all non-expired entries whose tags array includes the given tag (exact match).

pad.set('london', 'UK capital', { tags: ['geo', 'important'] });
pad.set('paris', 'France capital', { tags: ['geo'] });

const geoEntries = pad.findByTag('geo'); // both entries

Parameters:

tag (string) -- The tag to search for.

Returns: ScratchpadEntry[]

`namespace(name)`

Returns a scoped view of the scratchpad where all operations are prefixed with name:. Namespaces share the underlying storage with the parent -- they are views, not copies. Namespaces can be nested.

const memory = pad.namespace('memory');
memory.set('fact', 'The sky is blue');
memory.get('fact');           // 'The sky is blue'
pad.get('memory:fact');       // 'The sky is blue'

// Nested namespaces compose prefixes
const deep = pad.namespace('a').namespace('b');
deep.set('key', 'val');
pad.get('a:b:key');           // 'val'

// Namespace-scoped operations
memory.keys();                // ['fact'] (prefix stripped)
memory.clear();               // removes only memory:* entries

Parameters:

name (string) -- The namespace prefix.

Returns: Scratchpad -- A namespace-scoped scratchpad instance with the same full API.

`snapshot()`

Captures the full scratchpad state at the current point in time. The returned snapshot is a plain object suitable for serialization.

const snap = pad.snapshot();
// { entries: { ... }, timestamp: 1710000000000, version: 1 }

Returns: ScratchpadSnapshot

`restore(snapshot)`

Replaces the entire scratchpad state with the contents of a snapshot. Clears all existing entries before restoring. Throws ScratchpadVersionError if the snapshot version is not supported.

pad.restore(snap);

Parameters:

snapshot (ScratchpadSnapshot) -- A snapshot previously obtained from snapshot() or serialize().

Returns: void

Throws: ScratchpadVersionError if snapshot.version is not 1.

`serialize()`

Alias for snapshot(). Returns the same ScratchpadSnapshot structure.

const data = pad.serialize();

Returns: ScratchpadSnapshot

`toContext(options?)`

Renders scratchpad contents as a formatted string suitable for injection into an LLM prompt. Supports filtering by tags or namespace, multiple output formats, token budget limits, and custom headers.

pad.set('name', 'Alice');
pad.set('role', 'admin');

pad.toContext();
// 'name: Alice\nrole: admin'

pad.toContext({ format: 'markdown' });
// '## name\nAlice\n\n## role\nadmin'

pad.toContext({ format: 'json' });
// '{"name":"Alice","role":"admin"}'

pad.toContext({ format: 'xml' });
// '<entry key="name">Alice</entry>\n<entry key="role">admin</entry>'

Parameters:

Option	Type	Default	Description
`format`	`'kv' \| 'markdown' \| 'xml' \| 'json'`	`'kv'`	Output format.
`filterTags`	`string[]`	`undefined`	Only include entries that have at least one of the specified tags.
`filterNamespace`	`string`	`undefined`	Only include entries whose key starts with the given namespace prefix.
`maxTokens`	`number`	`undefined`	Truncate output to fit within this token budget.
`tokenCounter`	`(text: string) => number`	`text.length`	Function to count tokens. Used with `maxTokens`.
`includeMetadata`	`boolean`	`undefined`	Reserved for future use.
`header`	`string`	`undefined`	Text prepended to the output before the formatted entries.

Returns: string

`stats()`

Returns aggregate statistics about the scratchpad's current state.

const st = pad.stats();
// {
//   size: 3,             // live (non-expired) entry count
//   rawSize: 4,          // total entries including expired-not-yet-swept
//   namespaceCount: 2,
//   namespaces: ['ctx', 'mem'],
//   entriesWithTtl: 1,
//   tagCounts: { geo: 2, important: 1 },
//   oldestEntryAt: 1710000000000,
//   newestEntryAt: 1710000001000,
// }

Returns: ScratchpadStats

Field	Type	Description
`size`	`number`	Count of non-expired entries.
`rawSize`	`number`	Total entries in the store, including expired entries not yet swept.
`namespaceCount`	`number`	Number of distinct namespace prefixes.
`namespaces`	`string[]`	List of distinct namespace prefixes.
`entriesWithTtl`	`number`	Count of entries that have a TTL set.
`tagCounts`	`Record<string, number>`	Count of entries per tag.
`oldestEntryAt`	`number \| null`	`createdAt` of the oldest live entry, or `null` if empty.
`newestEntryAt`	`number \| null`	`createdAt` of the newest live entry, or `null` if empty.

`on(event, handler)`

Registers an event handler. Returns an unsubscribe function.

const unsub = pad.on('set', ({ key, entry, isUpdate }) => {
  console.log(isUpdate ? 'updated' : 'created', key);
});

pad.on('delete', ({ key, entry }) => {
  console.log('deleted', key);
});

pad.on('expire', ({ key, entry }) => {
  console.log('expired', key);
});

pad.on('clear', ({ count }) => {
  console.log('cleared', count, 'entries');
});

// Stop listening
unsub();

Parameters:

event (ScratchpadEventName) -- One of 'set', 'delete', 'expire', 'clear'.
handler (ScratchpadEventHandler<K>) -- Callback receiving the event payload.

Event Payloads:

Event	Payload
`set`	`{ key: string; entry: ScratchpadEntry; isUpdate: boolean }`
`delete`	`{ key: string; entry: ScratchpadEntry }`
`expire`	`{ key: string; entry: ScratchpadEntry }`
`clear`	`{ count: number }`

Returns: () => void -- Call to unsubscribe.

`save()`

Persists the current scratchpad state using the configured PersistenceAdapter. No-op if no adapter was provided.

await pad.save();

Returns: Promise<void>

`load()`

Loads scratchpad state from the configured PersistenceAdapter and restores it. No-op if no adapter was provided or the adapter returns null.

await pad.load();

Returns: Promise<void>

`destroy()`

Cleans up resources. Stops the background sweep timer if one is running.

await pad.destroy();

Returns: Promise<void>

TTL Utility Functions

`isExpired(entry, now)`

Determines whether a scratchpad entry has expired based on its TTL configuration.

import { isExpired } from 'agent-scratchpad';

const expired = isExpired(entry, Date.now());

Parameters:

entry (ScratchpadEntry) -- The entry to check.
now (number) -- Current timestamp in milliseconds.

Returns: boolean -- true if the entry's TTL has elapsed.

Logic:

Returns false if entry.ttl is null.
For fixed TTL (slidingTtl: false): expired when now >= entry.createdAt + entry.ttl.
For sliding TTL (slidingTtl: true): expired when now >= entry.accessedAt + entry.ttl.

`expiresAt(entry)`

Calculates the absolute expiration timestamp for an entry.

import { expiresAt } from 'agent-scratchpad';

const expiry = expiresAt(entry); // number | null

Parameters:

entry (ScratchpadEntry) -- The entry to inspect.

Returns: number | null -- The Unix timestamp (ms) when the entry expires, or null if it has no TTL.

Types

`ScratchpadEntry<T>`

interface ScratchpadEntry<T = unknown> {
  key: string;
  value: T;
  createdAt: number;    // Unix ms when first created
  updatedAt: number;    // Unix ms when value last updated
  accessedAt: number;   // Unix ms when last read via get()
  ttl: number | null;   // TTL in ms, null = no expiration
  slidingTtl: boolean;  // true = TTL resets on access
  tags: string[];       // string labels for categorization
}

`EntryOptions`

interface EntryOptions {
  ttl?: number | null;
  slidingTtl?: boolean;
  tags?: string[];
}

`ScratchpadOptions`

interface ScratchpadOptions {
  defaultTtl?: number | null;
  defaultSlidingTtl?: boolean;
  sweepIntervalMs?: number | null;
  now?: () => number;
  persistence?: PersistenceAdapter;
}

`ScratchpadSnapshot`

interface ScratchpadSnapshot {
  entries: Record<string, ScratchpadEntry>;
  timestamp: number;
  version: 1;
}

`ScratchpadStats`

interface ScratchpadStats {
  size: number;
  rawSize: number;
  namespaceCount: number;
  namespaces: string[];
  entriesWithTtl: number;
  tagCounts: Record<string, number>;
  oldestEntryAt: number | null;
  newestEntryAt: number | null;
}

`ToContextOptions`

interface ToContextOptions {
  format?: 'markdown' | 'xml' | 'json' | 'kv';
  filterTags?: string[];
  filterNamespace?: string;
  maxTokens?: number;
  tokenCounter?: (text: string) => number;
  includeMetadata?: boolean;
  header?: string;
}

`PersistenceAdapter`

interface PersistenceAdapter {
  load(): Promise<ScratchpadSnapshot | null>;
  save(snap: ScratchpadSnapshot): Promise<void>;
}

`ScratchpadEvents`

interface ScratchpadEvents {
  set: { key: string; entry: ScratchpadEntry; isUpdate: boolean };
  delete: { key: string; entry: ScratchpadEntry };
  expire: { key: string; entry: ScratchpadEntry };
  clear: { count: number };
}

`ScratchpadEventName`

type ScratchpadEventName = 'set' | 'delete' | 'expire' | 'clear';

`ScratchpadEventHandler<K>`

type ScratchpadEventHandler<K extends ScratchpadEventName> = (
  data: ScratchpadEvents[K]
) => void;

Error Handling

agent-scratchpad exports three error classes, all extending a common base.

`ScratchpadError`

Base class for all scratchpad errors. Extends Error with a code property.

import { ScratchpadError } from 'agent-scratchpad';

try {
  pad.restore(badSnapshot);
} catch (err) {
  if (err instanceof ScratchpadError) {
    console.error(err.code);    // e.g. 'SCRATCHPAD_VERSION_ERROR'
    console.error(err.message); // human-readable description
  }
}

Property	Type	Description
`code`	`string`	Machine-readable error code.
`message`	`string`	Human-readable error description.
`name`	`string`	Always `'ScratchpadError'`.

`ScratchpadConfigError`

Thrown when invalid configuration is provided to createScratchpad().

Code: SCRATCHPAD_CONFIG_ERROR

`ScratchpadVersionError`

Thrown when restore() encounters a snapshot with an unsupported version number.

Code: SCRATCHPAD_VERSION_ERROR
Additional property: version (number) -- The unsupported version that was encountered.

import { ScratchpadVersionError } from 'agent-scratchpad';

try {
  pad.restore(snap);
} catch (err) {
  if (err instanceof ScratchpadVersionError) {
    console.error(`Unsupported version: ${err.version}`);
  }
}

Advanced Usage

Agent Working Memory in a ReAct Loop

import { createScratchpad } from 'agent-scratchpad';

const pad = createScratchpad({ defaultTtl: 300_000 }); // 5-minute default

// Step 1: Store tool output
pad.set('search:result', apiResponse, { tags: ['tool-result', 'search'] });

// Step 2: Extract and store entities
pad.set('entities:user', { name: 'Alice', id: 42 }, { tags: ['entity'] });
pad.set('entities:order', { orderId: '#12345' }, { tags: ['entity'] });

// Step 3: Inject scratchpad into prompt
const agentContext = pad.toContext({
  format: 'markdown',
  header: '## Agent Working Memory',
  filterTags: ['entity'],
});
// Produces:
// ## Agent Working Memory
// ## entities:user
// [object Object]
// ...

Namespace Isolation for Multi-Agent Systems

const pad = createScratchpad();

const agent1 = pad.namespace('agent1');
const agent2 = pad.namespace('agent2');

agent1.set('plan', 'Research the topic');
agent2.set('plan', 'Draft the response');

// Each agent sees only its own entries
agent1.keys(); // ['plan']
agent2.keys(); // ['plan']

// Parent sees all entries with prefixed keys
pad.keys(); // ['agent1:plan', 'agent2:plan']

// Clear one agent without affecting the other
agent1.clear();
agent2.keys(); // ['plan'] -- unaffected

Sliding TTL for Session-Like Data

const pad = createScratchpad();

// Session token stays alive as long as the agent keeps accessing it
pad.set('session', { token: 'abc123' }, { ttl: 30_000, slidingTtl: true });

// Each access resets the 30-second expiration window
pad.get('session'); // resets timer
pad.get('session'); // resets timer again

// If 30 seconds pass without access, the entry expires

Background Sweep with Event Logging

const pad = createScratchpad({ sweepIntervalMs: 10_000 });

pad.on('expire', ({ key, entry }) => {
  console.log(`Expired: ${key} (created ${new Date(entry.createdAt).toISOString()})`);
});

pad.set('temp', 'data', { ttl: 15_000 });

// The sweep timer runs every 10 seconds and removes expired entries.
// The expire event fires for each entry removed by the sweep.

// Stop the sweep timer when done
await pad.destroy();

Persistence with a File-Based Adapter

import { createScratchpad, PersistenceAdapter, ScratchpadSnapshot } from 'agent-scratchpad';
import fs from 'fs/promises';

const fileAdapter: PersistenceAdapter = {
  async load() {
    try {
      const data = await fs.readFile('scratchpad.json', 'utf8');
      return JSON.parse(data) as ScratchpadSnapshot;
    } catch {
      return null;
    }
  },
  async save(snap) {
    await fs.writeFile('scratchpad.json', JSON.stringify(snap, null, 2));
  },
};

const pad = createScratchpad({ persistence: fileAdapter });

// Restore previous state on startup
await pad.load();

// Work with the scratchpad
pad.set('progress', 'step-3');

// Persist state before shutdown
await pad.save();

Snapshot-Based Backtracking

const pad = createScratchpad();

pad.set('approach', 'strategy-A');
pad.set('findings', ['result-1']);

// Save state before trying something risky
const checkpoint = pad.snapshot();

pad.set('approach', 'strategy-B');
pad.set('findings', ['result-1', 'result-2-failed']);

// Strategy B failed -- roll back
pad.restore(checkpoint);
pad.get('approach'); // 'strategy-A'

Token-Budget-Aware Context Rendering

import { createScratchpad } from 'agent-scratchpad';

const pad = createScratchpad();
pad.set('summary', 'A long summary of findings...');
pad.set('details', 'Extensive details that may not fit...');

// Use a custom token counter (e.g., tiktoken)
const context = pad.toContext({
  format: 'kv',
  maxTokens: 500,
  tokenCounter: (text) => Math.ceil(text.length / 4), // rough estimate
  header: '## Working Memory',
});

Deterministic Testing with Custom Time

import { createScratchpad } from 'agent-scratchpad';

let now = 0;
const pad = createScratchpad({ now: () => now });

pad.set('key', 'value', { ttl: 100 });

now = 50;
pad.get('key');   // 'value' -- still alive

now = 100;
pad.get('key');   // undefined -- expired exactly at 100ms

TypeScript

agent-scratchpad is written in TypeScript and ships with full type declarations. All exported functions, interfaces, and types are available for import:

import {
  createScratchpad,
  fromSnapshot,
  toContext,
  isExpired,
  expiresAt,
  ScratchpadError,
  ScratchpadConfigError,
  ScratchpadVersionError,
} from 'agent-scratchpad';

import type {
  Scratchpad,
  ScratchpadEntry,
  ScratchpadOptions,
  ScratchpadSnapshot,
  ScratchpadStats,
  ToContextOptions,
  EntryOptions,
  ScratchpadEventName,
  ScratchpadEventHandler,
  ScratchpadEvents,
  PersistenceAdapter,
} from 'agent-scratchpad';

Generic type parameters on get<T>() and set<T>() provide type-safe value access without casts:

interface User {
  id: number;
  name: string;
}

pad.set<User>('user', { id: 1, name: 'Alice' });
const user = pad.get<User>('user');
// user is User | undefined

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
dist		dist
src		src
README.md		README.md
SPEC.md		SPEC.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tasks.md		tasks.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

agent-scratchpad

Installation

Quick Start

Features

API Reference

createScratchpad(options?)

fromSnapshot(snapshot, options?)

Scratchpad Methods

set<T>(key, value, options?)

get<T>(key)

has(key)

delete(key)

clear()

keys()

entries()

findByTag(tag)

namespace(name)

snapshot()

restore(snapshot)

serialize()

toContext(options?)

stats()

on(event, handler)

save()

load()

destroy()

TTL Utility Functions

isExpired(entry, now)

expiresAt(entry)

Types

ScratchpadEntry<T>

EntryOptions

ScratchpadOptions

ScratchpadSnapshot

ScratchpadStats

ToContextOptions

PersistenceAdapter

ScratchpadEvents

ScratchpadEventName

ScratchpadEventHandler<K>

Error Handling

ScratchpadError

ScratchpadConfigError

ScratchpadVersionError

Advanced Usage

Agent Working Memory in a ReAct Loop

Namespace Isolation for Multi-Agent Systems

Sliding TTL for Session-Like Data

Background Sweep with Event Logging

Persistence with a File-Based Adapter

Snapshot-Based Backtracking

Token-Budget-Aware Context Rendering

Deterministic Testing with Custom Time

TypeScript

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`createScratchpad(options?)`

`fromSnapshot(snapshot, options?)`

`set<T>(key, value, options?)`

`get<T>(key)`

`has(key)`

`delete(key)`

`clear()`

`keys()`

`entries()`

`findByTag(tag)`

`namespace(name)`

`snapshot()`

`restore(snapshot)`

`serialize()`

`toContext(options?)`

`stats()`

`on(event, handler)`

`save()`

`load()`

`destroy()`

`isExpired(entry, now)`

`expiresAt(entry)`

`ScratchpadEntry<T>`

`EntryOptions`

`ScratchpadOptions`

`ScratchpadSnapshot`

`ScratchpadStats`

`ToContextOptions`

`PersistenceAdapter`

`ScratchpadEvents`

`ScratchpadEventName`

`ScratchpadEventHandler<K>`

`ScratchpadError`

`ScratchpadConfigError`

`ScratchpadVersionError`

Packages