@agent-trace-cache/sdk

Framework-agnostic SDK for AgentTrace-Cache. Wraps any agent function — Mastra agent.generate.bind(agent), a LangGraph node, a raw OpenAI Agents SDK call, a custom loop — with a deterministic trajectory cache that returns cached outcomes when the new query is semantically similar to a cached one.

The cache hit path is zero-LLM by design. No plan adaptation, no parameter rewriting, no runtime LLM judgment.

Install

pnpm add @agent-trace-cache/sdk
# or: npm install @agent-trace-cache/sdk

Quickstart

import { createCache, withCache } from '@agent-trace-cache/sdk'

const cache = await createCache({
  apiKey: process.env.OPENAI_API_KEY,
  storage: 'memory', // or 'libsql:file:./traj.db' for persistence
})

const cachedAgent = withCache(myAgent, {
  cache,
  extractGoal: (input) => input.question,
  extractContext: (input) => ({ user_id: input.userId }),
  toOutput: (cached) => ({ answer: cached.outcome }),
  recordTrajectory: (input, output) => ({
    id: `${input.userId}-${Date.now()}`,
    goal: input.question,
    goalEmbedding: [], // auto-filled by cache.store
    contextSnapshot: [],
    steps: [],
    taintMap: [],
    outcome: output.answer,
    cost: { promptTokens: 0, completionTokens: 0, totalTokens: 0, estimatedUsd: 0 },
    replayAccuracy: null,
    timestamp: new Date(),
    metadata: { source: 'my-agent' },
  }),
})

// First call: miss → runs your agent → trajectory recorded
// Second call with similar input: L1 hit → cached outcome returned, no agent run
const result = await cachedAgent({ question: 'cancel my flight', userId: 'u1' })

Storage shorthands

• 'memory' → in-process HNSW + Map (no persistence)
• 'libsql:file:./traj.db' → LibSQL with separate columns + opt-in HNSW persistence
• { kind: 'libsql', url, authToken? } → structured config
• { kind: 'custom', store } → bring your own TrajectoryStore

Documentation + benchmarks

• Project overview: github.com/kylemaa/agent-trace-cache
• Methodology + headline numbers (69% hit rate, 90% precision, 62.7% L2 partial replay): see blog/agent-trace-cache.md in the repo

License

MIT