DataGrout.ai Logo
Tool Suite ยท Ephemerals

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.

ephemerals.list

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.

Best for: Giving your agent a snapshot of what data is available before deciding the next step

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
๐Ÿ’ณ 0 credits โ€” ETS scan only
View ephemerals.list docs โ†’
โฑ

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.

ephemerals.listephemerals.inspect

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.

ephemerals.inspectephemerals.list

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.

ephemerals.listephemerals.inspect

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.

ephemerals.inspect

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.

ephemerals.listephemerals.inspect

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.

ephemerals.inspectephemerals.list
Power-Up Combos

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.

Ephemerals+Frame

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.

ephemerals.inspect(cache_ref) โ†’ schema confirmed โ†’ frame.filter(cache_ref, where=[...])

โœฆ Catch field-name mismatches before spending credits on a transform

Ephemerals+Prism

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.

ephemerals.list โ†’ pick cache_ref โ†’ prism.chart(cache_ref, goal='bar chart by region')

โœฆ Instant visualization from any prior tool output still in cache

Ephemerals+Discovery

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.

ephemerals.list โ†’ cache hit found โ†’ skip discovery.plan โ†’ use cache_ref directly

โœฆ Eliminate redundant integration calls when working data is already in flight

Ephemerals+flow.into

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.

flow.into โ†’ ephemerals.list โ†’ [cache hit] skip fetch โ†’ [miss] run integration โ†’ frame.group

โœฆ Workflows that adapt to available cache state without re-running expensive queries

Conduit SDK

Integrate Ephemerals in Minutes

Ephemerals tools are standard MCP calls โ€” available through any MCP client or via the Conduit SDK with zero configuration.

ephemerals.list ยท Python ยท Conduit SDK
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

We use cookies to improve your experience, analyze site traffic, and serve personalized content. You can accept all, decline non-essential cookies, or manage your preferences. See our Privacy Policy for details.

Ask the Advisor