betterdb-agent-cache v0.8.0

Maintenance release. No API or behavior changes.

Changes

• Added a runnable examples guide (examples/README.md) covering every adapter
  and major feature: OpenAI Chat Completions, OpenAI Responses, Anthropic
  Messages, LlamaIndex, LangChain, LangGraph, and the monitor proposals loop.

Installation

pip install betterdb-agent-cache

Full changelog

See the repository history for detailed changes.

What's Changed

• feat(semantic-cache): add Google AI (Gemini) embedding provider by @Vswaroop04 in #160

Full Changelog: agent-cache-py-v0.10.0...semantic-cache-v0.10.0

betterdb-semantic-cache v0.1.0

Python port of @betterdb/semantic-cache. Embeddings-based semantic cache for AI
workloads backed by Valkey vector search — similarity matching, cost tracking,
multi-modal prompts, embedding cache, and threshold tuning, with built-in
OpenTelemetry and Prometheus instrumentation.

Requires Valkey 8+ with the valkey-search module (vector index support).
Works with ElastiCache for Valkey, Memorystore for Valkey, and MemoryDB.

Installation

pip install betterdb-semantic-cache

Optional extras install the provider SDKs alongside the library:

pip install "betterdb-semantic-cache[openai]"
pip install "betterdb-semantic-cache[anthropic]"
pip install "betterdb-semantic-cache[langchain]"
pip install "betterdb-semantic-cache[langgraph]"
pip install "betterdb-semantic-cache[llamaindex]"
pip install "betterdb-semantic-cache[httpx]"   # voyage / cohere / ollama embed helpers
pip install "betterdb-semantic-cache[bedrock]"  # AWS Bedrock embed helper

What's included

SemanticCache

Provider adapters

Embedding helpers

Bundled default cost table

A default cost table sourced from LiteLLM's model_prices_and_context_window.json
is bundled and refreshed on every release. Cost savings tracking works out of the
box for 1,900+ models — no cost_table configuration required.

Observability

• OpenTelemetry spans on every cache operation
• Prometheus metrics: requests_total, similarity_score, operation_duration_seconds,
  embedding_duration_seconds, cost_saved_total, embedding_cache_total,
  stale_model_evictions_total

Cluster support

Pass a ValkeyCluster client and all SCAN-based operations (flush,
invalidate_by_model, invalidate_by_category) automatically iterate all master nodes.

Quick start

import asyncio
import valkey.asyncio as valkey
from betterdb_semantic_cache import SemanticCache, SemanticCacheOptions
from betterdb_semantic_cache.types import CacheStoreOptions
from betterdb_semantic_cache.embed.openai import create_openai_embed

client = valkey.Valkey(host="localhost", port=6379)
cache = SemanticCache(SemanticCacheOptions(
    client=client,
    embed_fn=create_openai_embed(),
    default_threshold=0.12,
))

async def main():
    await cache.initialize()

    result = await cache.check("What is the capital of France?")
    if result.hit:
        print("Cache hit:", result.response)
    else:
        answer = "Paris"  # ... call your LLM ...
        await cache.store(
            "What is the capital of France?", answer,
            CacheStoreOptions(model="gpt-4o", input_tokens=20, output_tokens=5),
        )

asyncio.run(main())

Full changelog

See CHANGELOG.md for detailed history.

What's Changed

• Adding OpenAI Agents SDK adapter by @amitkojha05 in #149

Full Changelog: v0.26.0...mcp-v1.3.1

What's Changed

• feat(anomaly): detect duplicate primaries in a shard (split-brain) by @KIvanow in #305
• feat(anomaly): detect stalled BGSAVE/AOF persistence forks by @KIvanow in #294
• feat(retrieval): LongMemEval question-type filter + stratified slice by @KIvanow in #300
• refactor: replace hardcoded 'env-default' strings with ENV_DEFAULT_ID by @Vswaroop04 in #156
• feat(webhooks): implement adaptive polling in WebhookProcessorService by @Vswaroop04 in #157
• feat(agent-memory): opt-in write-time fact consolidation by @KIvanow in #299
• feat(anomaly): data-loss guard for empty-primary full resync (valkey#579) by @KIvanow in #302
• feat(bulk-delete): incremental delete-by-pattern (client-side SCANDEL) by @KIvanow in #308
• feat(latency): P99 latency regression guard for version upgrades (valkey#3527) by @KIvanow in #304

Full Changelog: agent-cache-v0.11.0...agent-memory-v0.6.0

betterdb-agent-memory v0.3.0

Long-term memory tier for AI agents backed by Valkey Search — semantic recall
with recency/importance ranking, scoped capacity eviction, and consolidation.
Pairs with betterdb-agent-cache.

What's new in v0.3.0

• Product analytics now start on the first data-path call (remember,
  recall, recall_by_vector, get, list, stats, forget,
  forget_by_scope, consolidate), not only on ensure_index. Apps that
  attach to an existing index now report usage analytics as expected. Opt out
  with BETTERDB_TELEMETRY=false.

Analytics (since v0.2.0)

• Opt-out anonymous usage analytics (PostHog). Disable with
  BETTERDB_TELEMETRY=false (or 0/no/off), or per-instance via options.
  Instance id is an anonymous UUID persisted in Valkey; no payload data is sent.

Requires Valkey 8+ with the valkey-search module (vector index support).
Works with ElastiCache for Valkey, Memorystore for Valkey, and MemoryDB.

Built on betterdb-valkey-search-kit
and betterdb-agent-cache.

Installation

pip install betterdb-agent-memory

What's included

MemoryStore (long-term tier)

Scoped capacity eviction, live config refresh, and discovery are built in.

AgentMemory facade

Convenience facade over betterdb-agent-cache combining the exact-match cache
tier with the long-term memory tier.

Observability

• OpenTelemetry spans on every memory operation
• Prometheus metrics for recall latency and eviction counts

Full changelog

See the repository history for detailed changes.

What's Changed

• Adding OpenAI Agents SDK adapter by @amitkojha05 in #149

Full Changelog: agent-memory-py-v0.5.0...agent-cache-v0.11.1

betterdb-agent-cache v0.8.0

Maintenance release. No API or behavior changes.

Changes

• Added a runnable examples guide (examples/README.md) covering every adapter
  and major feature: OpenAI Chat Completions, OpenAI Responses, Anthropic
  Messages, LlamaIndex, LangChain, LangGraph, and the monitor proposals loop.

Installation

pip install betterdb-agent-cache

Full changelog

See the repository history for detailed changes.

Anomaly-detection expansion (three new Valkey-issue-backed detectors), a P99 latency regression guard, client-side bulk delete-by-pattern, and faster webhook retries.

✨ Added

Anomaly detection

• Split-brain - duplicate primaries in a shard (#305, valkey#2261 (valkey-io/valkey#2261)) - flags a hash-slot range claimed by more than one master-flagged node and names the phantom primary (lower configEpoch). Emits a CRITICAL CLUSTER_TOPOLOGY anomaly, deduped per conflict signature and re-armed once resolved.
• Stalled BGSAVE / AOF persistence forks (#294, valkey#2322 (valkey-io/valkey#2322)) - tracks RDB/AOF fork children from INFO persistence. CRITICAL when progress freezes (MONITOR_PERSISTENCE_STALL_SEC, 60s), elapsed exceeds the ceiling (MONITOR_PERSISTENCE_CRIT_SEC, 600s), or last-save status flips ok → err; WARNING past MONITOR_PERSISTENCE_WARN_SEC (120s) while still advancing.
• Data-loss guard for empty-primary full resync (#302, valkey#579 (valkey-io/valkey#579), Pro) - Rule A alerts when a persistence-less primary restarts empty with restart evidence (replid change / uptime reset / offset regression); Rule B confirms a replica whose keyspace collapsed ≥90% after a replid change. Same-replid FLUSHALL is not flagged. Adds the data.loss.detected webhook + dashboard banner.

Latency

• P99 regression guard for version upgrades (#304, valkey#3527 (valkey-io/valkey#3527), Pro) - a version change opens a 24h window; when a command's P99 stays ≥1.5× its pre-upgrade baseline (and ≥1ms above) for 5 consecutive samples, fires one aggregated command_p99 anomaly + the latency.regression.detected webhook. Adds a latencystats poller (60s/7d), the latency_stats_samples store across all adapters, and GET /metrics/latencystats/summary + /history (Community).

Data management

• Bulk delete-by-pattern (client-side SCANDEL) (#308, valkey#2623 (valkey-io/valkey#2623), Pro) - client-driven SCAN + per-key UNLINK with dry-run preview, maxKeys cap + truncation reporting, pacing, cooperative cancel, and cluster fan-out (per-key UNLINK avoids CROSSSLOT). Catch-all * requires explicit confirmation. Gated behind the bulkDelete feature.

🔧 Changed

• Adaptive webhook retry polling (#157) - self-scheduling loop: 2s while retries pend, 10s when idle (same DB load), with a shutdown guard. Backoff retries (1s/2s/4s) now picked up in ~2s instead of up to 10s.
• Centralized ENV_DEFAULT_ID (#156) - replaces 28+ hardcoded 'env-default' literals with one constant.

🐛 Fixed

• MCP info endpoint (#280) - passes the section parameter through to the underlying INFO call.

Full changelog: v0.25.0...v0.26.0

What's Changed

• fix(telemetry-py): reliable event delivery and per-install identity by @KIvanow in #292
• fix(telemetry): reliable delivery + per-install identity in TS packages by @KIvanow in #293
• fix(telemetry): serverless-aware event delivery for TS SDKs by @KIvanow in #301
• feat(retrieval): LongMemEval lever ablation foundation by @jamby77 in #284
• feat(retrieval): structured context assembly (Issue 1) by @jamby77 in #285
• feat(retrieval): query-time temporal resolver (Issue 2, slim) by @jamby77 in #287
• fix(mcp): pass section param through to info endpoint by @AruneshDwivedi in #280
• fix(mcp): report package version from metadata by @RitwijParmar in #222
• feat(agent-cache/ai): cache streaming LLM responses via wrapStream by @amitkojha05 in #262
• chore(agent-cache): release v0.11.0 (streaming cache) + fix TS build by @KIvanow in #306
• feat(anomaly): detect duplicate primaries in a shard (split-brain) by @KIvanow in #305
• feat(anomaly): detect stalled BGSAVE/AOF persistence forks by @KIvanow in #294
• feat(retrieval): LongMemEval question-type filter + stratified slice by @KIvanow in #300
• refactor: replace hardcoded 'env-default' strings with ENV_DEFAULT_ID by @Vswaroop04 in #156
• feat(webhooks): implement adaptive polling in WebhookProcessorService by @Vswaroop04 in #157
• feat(agent-memory): opt-in write-time fact consolidation by @KIvanow in #299
• feat(anomaly): data-loss guard for empty-primary full resync (valkey#579) by @KIvanow in #302
• feat(bulk-delete): incremental delete-by-pattern (client-side SCANDEL) by @KIvanow in #308
• feat(latency): P99 latency regression guard for version upgrades (valkey#3527) by @KIvanow in #304

New Contributors

• @AruneshDwivedi made their first contribution in #280
• @RitwijParmar made their first contribution in #222

Full Changelog: v0.25.0...v0.26.0

Streaming responses are now cached. The Vercel AI SDK adapter implements wrapStream alongside wrapGenerate, so streamText calls hit the cache too - on a miss the streamed text is accumulated and stored on finish; on a hit it's replayed instantly (marked providerMetadata.agentCache.hit). Tool-call streams are left uncached, store happens asynchronously so it never blocks the caller-facing stream, and upstream errors pass through untouched. No breaking changes; requires ai ^6.0.135.

npm install @betterdb/[email protected]

What's Changed

• feat(retrieval): LongMemEval lever ablation foundation by @jamby77 in #284
• feat(retrieval): structured context assembly (Issue 1) by @jamby77 in #285
• feat(retrieval): query-time temporal resolver (Issue 2, slim) by @jamby77 in #287
• fix(mcp): pass section param through to info endpoint by @AruneshDwivedi in #280
• fix(mcp): report package version from metadata by @RitwijParmar in #222
• feat(agent-cache/ai): cache streaming LLM responses via wrapStream by @amitkojha05 in #262
• chore(agent-cache): release v0.11.0 (streaming cache) + fix TS build by @KIvanow in #306

New Contributors

• @AruneshDwivedi made their first contribution in #280
• @RitwijParmar made their first contribution in #222

Full Changelog: agent-cache-v0.10.0...agent-cache-v0.11.0