Memory

The remember, recall, and forget meta-tools give agents a persistent key-value store scoped by their identifier (anonymous IP, BYO key hash, or account ID).

When to use it

• Multi-session research: pin a research target, current ticker, draft text, etc. across sessions
• Long agent runs: store intermediate findings so the conversation history can be pruned without losing facts
• Multi-agent handoff: one agent stores something, another (with the same identifier) reads it

For things that should not persist — temporary intermediates within one conversation — just use the agent’s own scratchpad. Memory is for state worth keeping.

API

remember({
  key: "current_research_target",
  value: { ticker: "AAPL", cik: "0000320193", since: "2026-08-10" }
})
// → { stored: true, key: "current_research_target", ttl: "permanent" }
// ttl is "24h" instead of "permanent" for anonymous callers.

recall({ key: "current_research_target" })
// → { key: "current_research_target", value: "{\"ticker\":\"AAPL\",...}", found: true }
// `value` comes back as whatever string was stored — an object passed to
// remember is JSON.stringify'd on the way in and NOT parsed back on the way
// out. If you remembered an object, JSON.parse(value) yourself after recall.

recall({})  // no key — list all keys
// → { keys: ["current_research_target", "draft_email_to_acme"], count: 2 }

forget({ key: "current_research_target" })
// → { deleted: true, key: "current_research_target" }

value can be any JSON — it’s serialized to a string for storage and handed back as that same string; the round-trip is not automatic. Verified live against the gateway on 2026-08-10 (remember/recall/forget all round-tripped correctly, response shapes as shown above).

Scope and persistence

The gateway’s TTL logic is a single check: anonymous callers get a 24-hour expiration, every other tier gets none. There is no separate 30-day BYO tier — BYO memory persists the same as a signed-in account’s, scoped to a hash of the key instead of an account ID. (Confirmed by reading the gateway’s memory handler and by a live remember from an internal-header call, which came back ttl: "permanent".)

Memory does not flow across identifiers. Two different agents with two different anonymous IPs can’t see each other’s state.

Patterns

Pin a research target

remember({ key: "target", value: { ticker: "AAPL", cik: "..." } })
// ... later, possibly in a different session ...
const { value } = await recall({ key: "target" })
const target = JSON.parse(value)  // value is a string — parse it back

Cross-session findings cache

Agent stores intermediate facts with their _meta.cache.fresh_until from the original call. Next session checks whether the cached fact is still fresh before re-calling:

remember({
  key: "aapl_revenue_fy23",
  value: { value: 383300000000, fresh_until: "2026-05-15T..." }
})

See caching and freshness for the freshness-check pattern.

Multi-agent coordination

Two agents authenticated as the same account share memory. Useful for handing work between specialized agents:

// Research agent
remember({ key: "report_data", value: { metrics: {...}, citations: [...] } })

// Writer agent (same account)
const { value } = await recall({ key: "report_data" })
const { metrics, citations } = JSON.parse(value)
// Now can write a coherent report from the prior agent's findings

Caveats

• Not a database. Memory is for agent-state coordination, not bulk storage. There’s no Pipeworx-imposed cap on key count or value size today (only Workers KV’s own platform limits apply) — don’t rely on that; it’s operational headroom, not a documented allowance.
• Not encrypted. Don’t store secrets or user-private data here. Pass auth tokens via headers, not via memory.
• Identifier changes break continuity. If your client’s auth tier changes (anonymous → signed in), prior anonymous memory is unreachable.