Changelog

v0.2.0 — 2026-05

First public release.

Core

• CogniCache class with query() / query_with_meta() / cached() decorator API
• MemoryStore (default) and RedisStore (Redis Stack 7+ with HNSW) backends
• TTL eviction on find_match and list_entries paths
• Per-instance configuration; multiple caches in one process supported
• Fail-open on backend errors (CacheStoreError is caught at call sites)

Quality

• LLMJudge ABC with NoopJudge and LLMJudgeOpenAI implementations
• "Write strict, hit lenient" policy:
• write_min_quality — gate writes (default 0.8)
• low_quality_ttl — short-lived storage for marginal answers
• judge_on_hit + hit_min_quality — async warning on degraded hits

Observability

• MetricsCollector with thread-safe bounded deque + sink fan-out
• QueryEvent frozen dataclass
• PrometheusSink with lazy prometheus_client import
• p50/p95/p99 latency breakdown by cache_hit=true/false
• Token savings ratio and quality score gauges

Integrations

• cogcache.integrations.langchain.CogniCacheLangChain — LangChain BaseCache adapter

Benchmarks

• python -m cogcache.bench.run_bench reproducible offline benchmark
• --real-llm mode for DashScope / OpenAI compatible APIs
• Built-in ecommerce.jsonl dataset (50 queries, 5 clusters)

Packaging

• PyPI: pip install cogcache
• Extras: [redis], [prometheus], [openai-judge], [langchain], [bench], [all], [dev]
• Single required dependency: numpy
• Wheel size: ~35 KB

Renamed

• Module cognicache → cogcache (the class name CogniCache is unchanged).
• Environment variable COGNICACHE_* names are unchanged for compatibility with the cogcache-playground reference deployment.

v0.0.0 — 2026-05

Placeholder release on PyPI to reserve the name. Not functional.