Agent Cache v0.3.0

Multi-modal support and full provider adapter coverage for OpenAI, Anthropic, and LlamaIndex.

---

What's new

New provider adapters

Four new sub-path imports covering every major provider:

Import	Provider
@betterdb/agent-cache/openai	OpenAI Chat Completions
@betterdb/agent-cache/openai-responses	OpenAI Responses API
@betterdb/agent-cache/anthropic	Anthropic Messages
@betterdb/agent-cache/llamaindex	LlamaIndex

Each adapter converts provider-native request params into the canonical LlmCacheParams format — no manual normalisation required.

OpenAI Chat handles text, images (URL + base64), audio, files, tool calls, and legacy function role messages.

OpenAI Responses additionally covers reasoning items, function_call / function_call_output item types, and instructions promoted to a system message.

Anthropic covers tool use blocks, tool result blocks, and thinking / extended thinking blocks alongside standard image sources.

LlamaIndex wraps ChatMessage history including text and image nodes.

---

Pluggable binary normalizer

Binary content (images, audio, documents) is now a first-class part of the cache key pipeline. The new BinaryNormalizer interface lets you control how blobs are reduced to a stable string before hashing.

import { composeNormalizer } from '@betterdb/agent-cache';

const normalizer = composeNormalizer({
  // Hash base64 payloads by their decoded bytes
  base64: (data) => hashBase64(data),
  // Fetch remote images and hash the response body
  url: (url) => fetchAndHash(url),
  // Use OpenAI file IDs directly as cache keys
  fileId: (id, provider) => `${provider}:${id}`,
});

Built-in helpers:

Helper	Behaviour
hashBase64(data)	SHA-256 of decoded bytes
hashBytes(data)	SHA-256 of raw bytes
hashUrl(url)	Normalised URL (sorted query params, lowercased host)
fetchAndHash(url)	Fetches URL and SHA-256s the body
passthrough(ref)	Scheme-prefixed ref, no transformation
composeNormalizer(cfg)	Build a normalizer from per-source / per-kind handlers

The defaultNormalizer uses passthrough — zero-latency, no network calls, suitable for most use cases.

---

Extended cache key coverage

LlmCacheParams now includes all parameters that affect model output:

• toolChoice, seed, stop, responseFormat
• reasoningEffort — for extended thinking models
• promptCacheKey — pass-through for provider-level prompt caching

---

New examples

Runnable examples added for all three new providers:

examples/openai/
examples/anthropic/
examples/llamaindex/

---

Bug fixes

• Null tool output (openai-responses): function_call_output items with null or undefined output now produce an empty string instead of the two-character literal "", which was corrupting cache key hashes.

---

Installation

npm install @betterdb/agent-cache@0.3.0

---

Full changelog

See CHANGELOG.md for a complete list of changes.

What's Changed

• Feature/agent cache adding OpenAI anthropic llamaindex adapters by @KIvanow in #115
• Feature/agent cache adding OpenAI anthropic llamaindex adapters by @KIvanow in #116

Full Changelog: v0.14.2...agent-cache-v0.3.0

v0.14.2

Security updates

fastify 5.8.4 → 5.8.5

Fixes CVE-2026-33806 — a security vulnerability in the Fastify HTTP framework. See GHSA-247c-9743-5963.

@fastify/static 9.0.0 → 9.1.1

Fixes two CVEs in static file serving:

• CVE-2026-6410 (GHSA-pr96-94w5-mx2h)
• CVE-2026-6414 (GHSA-x428-ghpx-8j92)

vite 8.0.2 → 8.0.5

Multiple path traversal and filesystem boundary bypass fixes in the dev server:

• server.fs checks now apply to env transport requests and query-stripped paths
• Sourcemap handlers no longer allow referencing files outside the package root

Bug fixes

Vector Search

• Fixed crashes caused by out-of-bounds data
• Fixed Find Similar button being difficult to click
• Fixed graph labels being unreadable and not respecting the active color scheme

What's Changed

• added licenseKey to posthog events by @KIvanow in #104
• Add @betterdb/agent-cache package — multi-tier LLM/tool/session cache with framework adapters by @KIvanow in #105
• cluster support for agent-cache by @KIvanow in #108
• build(deps-dev): bump vite from 8.0.2 to 8.0.5 by @dependabot[bot] in #99
• build(deps): bump @nestjs/core from 11.1.17 to 11.1.18 by @dependabot[bot] in #100
• build(deps): bump fastify from 5.8.4 to 5.8.5 by @dependabot[bot] in #106
• build(deps): bump @fastify/static from 9.0.0 to 9.1.1 by @dependabot[bot] in #110

Full Changelog: v0.14.1...v0.14.2

Agent Cache v0.2.0

Cluster mode support

All SCAN-based operations now work correctly when an iovalkey Cluster client is passed. No API changes required - swap a standalone Valkey instance for a Cluster instance and everything works.

Affected methods: flush(), destroyThread(), invalidateByModel(), invalidateByTool(), getAll(), touch(), scanFieldsByPrefix()

import { Cluster } from 'iovalkey';

const client = new Cluster([
  { host: 'localhost', port: 6401 },
  { host: 'localhost', port: 6402 },
  { host: 'localhost', port: 6403 },
]);

const cache = new AgentCache({ client: client as any, ... });

CROSSSLOT fix

Multi-key DEL and MGET commands cause CROSSSLOT errors in cluster mode when keys span different hash slots on the same node. All bulk operations now use pipelines of individual commands instead.

Framework examples

The LangChain, LangGraph, and Vercel AI SDK examples support a VALKEY_CLUSTER=1 environment variable to run against a cluster without code changes:

VALKEY_CLUSTER=1 npx tsx index.ts
Cluster mode - nodes: localhost:6401, localhost:6402, localhost:6403

VALKEY_CLUSTER_NODES overrides the default node list.

Breaking changes

• The agent_cache.session.touch OTel span attribute is renamed from cache.touched_count to cache.touched_count_approx. The value counts keys sent to EXPIRE, not keys that successfully refreshed. Update any dashboards or alerts keyed on
  cache.touched_count.

Infrastructure

• docker-compose.test.yml gains a 3-node cluster on ports 6401–6403 with an init container that forms the cluster automatically
• global-setup.ts starts the cluster containers and waits for cluster_state:ok before running tests
• New integration test suite (AgentCache.cluster.integration.test.ts) covering all cluster operations - skips gracefully when the cluster is unavailable

What's Changed

• cluster support for agent-cache by @KIvanow in #108

Full Changelog: agent-cache-v0.1.0...agent-cache-v0.2.0

Agent Cache v0.1.0

Multi-tier exact-match cache for AI agent workloads backed by Valkey. Three cache tiers behind one connection: LLM responses, tool results, and session state. Built-in OpenTelemetry tracing and Prometheus metrics. No modules required - works on vanilla Valkey 7+, ElastiCache, Memorystore, MemoryDB, and any Redis 6.2+ endpoint.

Install

npm install @betterdb/agent-cache iovalkey

What's in this release

Three cache tiers

• LLM response cache - exact match on model, messages, temperature, top_p, max_tokens, and tools. Canonical JSON serialization with sorted keys for deterministic hashing. Tool arrays sorted by function name for order-independent matching.
• Tool result cache - cache by tool name and argument hash. Per-tool TTL policies persisted to Valkey. Invalidate by tool, by specific arguments, or by model.
• Session state - key-value storage with sliding window TTL. Individual field expiry (not Redis HASH). LangGraph checkpoint support on vanilla Valkey without RedisJSON or RediSearch.

Framework adapters

Three optional subpath exports. Only install the peer dependency you use.

• LangChain (@betterdb/agent-cache/langchain) - BetterDBLlmCache implementing BaseCache. Plugs into ChatOpenAI's cache option. Auto-extracts token counts from usage_metadata for cost tracking.
• Vercel AI SDK (@betterdb/agent-cache/ai) - createAgentCacheMiddleware() implementing LanguageModelMiddleware. Intercepts non-streaming doGenerate calls. Cache hits include providerMetadata: { agentCache: { hit: true } }.
• LangGraph (@betterdb/agent-cache/langgraph) - BetterDBSaver implementing BaseCheckpointSaver. Full checkpoint protocol including pendingWrites reconstruction, interrupt/resume, and human-in-the-loop patterns. Works on vanilla Valkey 7+ without Redis 8, RedisJSON, or RediSearch.

Observability

• OpenTelemetry - every public method emits a span with attributes for cache key, tier, hit/miss, model, tool name, TTL, and byte size.
• Prometheus via prom-client - requests_total, operation_duration_seconds, cost_saved_total, stored_bytes_total, active_sessions. Configurable metric prefix and registry.

Stats and self-optimization

• stats() returns per-tier hit/miss counts, hit rates, session read/write counts, aggregate cost savings in microdollars, and per-tool breakdowns.
• toolEffectiveness() ranks cached tools by hit rate and recommends TTL adjustments: increase_ttl (>80% hit rate, TTL <1hr), optimal (40-80%), or decrease_ttl_or_disable (<40%).
• Cost tracking via costTable config - provide model pricing, and cache hits automatically accumulate savings.

Error handling

• AgentCacheError base class, AgentCacheUsageError for caller mistakes (colons in tool names, glob chars in thread IDs), ValkeyCommandError for Valkey failures with cause chaining.
• Corrupt JSON entries are self-healing - deleted on first detection and treated as misses.
• Tool name validation rejects colons (used as key delimiters) at call time rather than producing silent key collisions.

Known limitations

• Streaming - not cached by the Vercel AI SDK adapter (only doGenerate, not doStream). LangChain .stream() bypasses the cache (LangChain architecture limitation). Accumulate the full response before caching when using the direct API.
• Cluster mode - SCAN-based operations (destroyThread, invalidateByTool, invalidateByModel, flush) only iterate the node they're sent to. In multi-node clusters these may silently leave keys on other nodes. Use the iovalkey cluster client's per-node scan for full coverage. Cluster mode support is planned.
• LangGraph list() - loads all checkpoint data for a thread into memory before filtering. The limit: 1 fast path reads checkpoint:latest directly. For threads with thousands of large checkpoints, consider langgraph-checkpoint-redis with Redis 8+.
• Active sessions gauge - approximate, tracked via in-memory LRU (bounded at 10k). Does not survive process restarts.

Links

• npm
• Documentation
• LangChain example
• Vercel AI SDK example
• LangGraph example

What's Changed

• added licenseKey to posthog events by @KIvanow in #104
• Add @betterdb/agent-cache package — multi-tier LLM/tool/session cache with framework adapters by @KIvanow in #105

Full Changelog: v0.14.1...agent-cache-v0.1.0

v0.14.1

Url updates

Full Changelog: v0.14.0...v0.14.1

BetterDB Monitor v0.14.0

Highlights: an integrated browser CLI for running Valkey/Redis commands directly from the Monitor UI, a free registration + license activation flow, and a refactored responsive
layout.

Features

Integrated CLI panel (#96)

Run Valkey/Redis commands without leaving the browser. A new collapsible bottom panel exposes a WebSocket-backed terminal with command history and keyboard shortcuts.

• Two modes:
  • Safe (default) — read-only allowlist, 18 destructive commands blocked, bare-subcommand bypass closed (e.g. CONFIG without a subcommand is rejected), SENTINEL and SLOWLOG RESET
    removed from the allowlist.
  • Unsafe — opt in with BETTERDB_UNSAFE_CLI=true to allow writes; surfaces a startup warning and an unsafeCliEnabled flag in the health response.
• Backend (apps/api/src/cli/): new CliGateway WebSocket endpoint at /cli/ws with per-connection token-bucket rate limiting (50 cmd/s), 30s command timeout, 512 KB response
  truncation, 1 MiB payload limit, and JWT session-cookie validation in cloud mode. Each WS connection gets a dedicated BetterDB-CLI Valkey client via a new DatabasePort.call(..., { cli })
  adapter API.
• Frontend: collapsible CliPanel with Ctrl+` shortcut, ref-based history navigation (no re-render cascade), sessionStorage persistence, and an auto-reconnecting WebSocket hook
  with exponential backoff. Built-in commands: help, clear, history, exit.
• Shared: command parser and checkSafeMode / checkBlocked filters centralized in @betterdb/shared so backend and frontend agree on policy.
• 44 backend tests + 13 frontend tests.

Closes #91, #92, #93, #94.

Free registration & license activation flow (#98)

End-to-end self-serve onboarding from email to active Enterprise license.

• Web: new Settings → License section. Users register an email (via VITE_REGISTRATION_URL) and activate the returned key in-app.
• API: new POST /license/activate endpoint, persists activated keys to disk, hardened error handling and message extraction.
• Entitlement service: new /v1/registrations endpoint creates or resends Enterprise licenses and delivers them via Resend; cloud entitlement resolution now keys off tenantId; CORS and
  env wiring updated.
• New env vars: VITE_REGISTRATION_URL, ENTITLEMENT_URL.

Responsive layout refactor (#103)

App.tsx slimmed down to providers and bootstrap; layout extracted into a dedicated module.

• New components in src/components/layout/: AppLayout, AppSidebar, NavItem, CommunityBanner, FeedbackModal.
• New shadcn primitives: Sidebar, Sheet, Input, plus a useIsMobile hook.
• Responsive collapsible sidebar with persisted open/closed state; CliPanel repositioned to follow the sidebar via peer-data-[state].
• Print styles updated to hide the new sidebar.

Bumps

• @betterdb/agent 1.3.0 → 1.4.0 (#101)
• App workspaces (api, web, cli, shared, root) → 0.14.0

Notes for upgraders

• The integrated CLI is read-only by default. Set BETTERDB_UNSAFE_CLI=true to allow writes; this is intentionally a deploy-time decision, not a UI toggle.
• Cloud-mode deployments must permit /cli/ws through the auth middleware (already whitelisted in this release).
• If you use the new registration flow, configure `...

BetterDB Agent v1.4.0

Added CLI support for command execution in safe and unsafe mode depending on user provided flags

v0.13.5

Fixed build flow

Full Changelog: v0.13.1...v0.13.5

v0.13.1

Fixed build flow

Full Changelog: v0.13.0...v0.13.1

v0.13.0

Features

• Telemetry adapter abstraction — Introduced TelemetryPort interface with NoopAdapter and a factory, decoupling telemetry from concrete providers (#77)
• shadcn UI migration — Migrated the web frontend to the shadcn component library (#82)

Fixes

• Fix banner coloring for themes (#95)

What's Changed

• shadcn to a working point by @KIvanow in #82
• feature: telemetry adapter abstraction (TelemetryPort + NoopAdapter + factory) by @jamby77 in #77
• fix banner coloring for themes by @KIvanow in #95

Full Changelog: v0.12.1...v0.13.0