See What's Cached.
Act Before It Expires.
Ephemerals is your agent's working-memory view. When any tool call produces a cache_ref, Ephemerals lets you list what's live, preview its schema, and decide what to do next โ all at zero credit cost.
2 tools
ephemerals.list ยท ephemerals.inspect
Zero credit cost
pure ETS lookups, no LLM
Working-memory view
see what any prior tool cached
Free forever ยท No credit card required
Two Tools. Complete Working-Memory Visibility.
Every tool call in DataGrout produces a cache_ref. Ephemerals tells your agent exactly what's cached and what shape it's in โ before the window closes.
List Active Cache Entries
Returns every active cached dataset for the current user โ including the cache_ref, the source tool that produced it, the record count, type, and how many seconds until it expires. Pure ETS scan: no LLM, no database, zero credits.
What it returns
- Returns cache_ref, source_tool, record_count, type, created_seconds_ago, expires_in_seconds per entry
- Sort by newest, expiring_soon, or largest
- Limit up to 100 entries
- Entries disappear automatically when expired โ no stale refs
- Message field summarizes what's available for immediate use
- Zero credits โ pure ETS lookup
Cache Lifecycle
Cached entries expire after 10 minutes of inactivity (touch-on-access). All cached data is encrypted at rest with AES-256-GCM, scoped to the current user, and never shared across sessions. When an entry expires it disappears from ephemerals.list automatically. To promote important outputs to permanent storage, use deliverables.register.
How Agents Use Ephemerals
Every time an agent needs to know what data is already in flight โ or verify a dataset's shape before transforming it โ Ephemerals provides the answer instantly, for free.
Adaptive Pipeline Decisions
Before committing to an expensive transform or chart, an agent calls ephemerals.list to see what's already cached. If the right dataset is already there, it reuses it โ no repeat API call, no wasted tokens.
Related Solutions
Multi-Step Data Pipeline Debugging
When a flow.into pipeline produces unexpected output, inspect intermediate cache_refs step-by-step to see exactly where the data shape changed โ schema, row count, and preview all visible without re-running upstream queries.
Related Solutions
Cache-Aware Context Rehydration
When an agent resumes after a pause, it lists ephemerals to discover which prior results are still live. Rather than requerying integrations, it rehydrates context from existing cache_refs โ saving credits and latency.
Related Solutions
Schema Verification Before Transform
Before calling frame.group or prism.refract on an unknown cache_ref, inspect it first to confirm field names, types, and row count. Catch schema mismatches before burning credits on a transform that would fail.
Related Solutions
Opportunistic Chart Generation
An agent working through a report notices a cached grouped dataset in ephemerals.list. It inspects the schema to confirm it has the right columns, then immediately passes the cache_ref to prism.chart โ no data re-fetch required.
Related Solutions
Agentic Coding Data Introspection
When Invariant returns structured code analysis results as a cached payload, inspect them to confirm schema before filtering by severity โ ensuring Frame or Data operations are applied to the right shape before the agent reasons over findings.
Related Solutions
Ephemerals Connects Every Tool in the Pipeline
Ephemerals is the awareness layer โ it tells your agent what's in flight so every downstream tool can make smarter decisions.
Verify Shape Before You Transform
Inspect a cache_ref to confirm its schema and row count, then immediately pass it to any Frame operation โ filter, sort, group, pivot โ without an extra round-trip to the upstream integration.
โฆ Catch field-name mismatches before spending credits on a transform
Chart Any Cached Dataset On Demand
ephemerals.list surfaces all live datasets with their record counts and source tools. When an agent spots a useful grouped result, it passes the cache_ref directly to prism.chart โ no requery, no re-transmission.
โฆ Instant visualization from any prior tool output still in cache
Check Cache Before Planning
Before asking Discovery to plan a new multi-step workflow, list ephemerals to see if the needed data is already cached. If it is, skip the upstream query entirely and start from the cached result.
โฆ Eliminate redundant integration calls when working data is already in flight
Dynamic Cache-Aware Routing
Inside a flow.into plan, use ephemerals.list as an early step to conditionally branch: if a required dataset is already cached, skip the upstream query step and route directly to the transform. Deterministic, zero-cost decision gate.
โฆ Workflows that adapt to available cache state without re-running expensive queries
Integrate Ephemerals in Minutes
Ephemerals tools are standard MCP calls โ available through any MCP client or via the Conduit SDK with zero configuration.
from datagrout.conduit import Client
async with Client(
"https://gateway.datagrout.ai/servers/{uuid}/mcp",
auth={"bearer": "your-access-token"}
) as client:
result = await client.perform("data-grout@1/ephemerals.list@1", {
"sort": "expiring_soon",
"limit": 20
})
# result["ephemerals"] โ list of active cached entries
# result["total"] โ total count
# result["message"] โ human-readable summary
for entry in result["ephemerals"]:
print(
entry["cache_ref"],
entry["source_tool"],
entry["record_count"],
f"expires in {entry['expires_in_seconds']}s"
)Also available in TypeScript, Rust, Elixir, and Ruby. View Conduit SDK โ
Frequently Asked Questions
What developers ask before wiring Ephemerals into their agent pipelines.
More questions? Read the full Ephemerals documentation.
Your agents deserve to know what they have.
Ephemerals gives every agent instant, zero-cost visibility into its own working memory โ so it can reuse, verify, and act on cached data before the window closes.
Free forever ยท No credit card required
