AI (all-in-one)

@betterdb/ai is one install for the whole BetterDB AI stack on Valkey. It re-exports, and pins exact versions of, five packages:

Package	Purpose
@betterdb/agent-cache	Multi-tier exact-match cache
@betterdb/semantic-cache	Embedding-similarity cache
@betterdb/retrieval	Vector + filtered query over valkey-search
@betterdb/agent-memory	Short-term tiers plus semantic long-term memory
@betterdb/valkey-search-kit	Shared FT.* helpers

Each remains published and supported. Install them directly for a narrower dependency; install @betterdb/ai for the whole stack at one mutually compatible set of versions.

npm install @betterdb/ai iovalkey

import Valkey from 'iovalkey';
import { AgentCache, SemanticCache, MemoryStore, Retriever } from '@betterdb/ai';

const client = new Valkey({ host: 'localhost', port: 6379 });
const cache = new AgentCache({ client });

Framework adapters

Import	Provides
@betterdb/ai/langchain	BetterDBLlmCache, BetterDBSemanticCache
@betterdb/ai/langgraph	BetterDBSaver, BetterDBSemanticStore
@betterdb/ai/vercel	createAgentCacheMiddleware, createSemanticCacheMiddleware
@betterdb/ai/openai	prepareParams, prepareSemanticParams
@betterdb/ai/openai-responses	prepareParams, prepareSemanticParams
@betterdb/ai/anthropic	prepareParams, prepareSemanticParams
@betterdb/ai/llamaindex	prepareParams, prepareSemanticParams

Six framework peers are optional — install the ones you use (/openai and /openai-responses both use the openai peer). The seventh peer, iovalkey, is required.

Subpath imports (everything but the root @betterdb/ai import) require "moduleResolution" set to "node16", "nodenext", or "bundler" in your tsconfig.json. The root import works under classic "node" resolution too.

Embedding functions

SemanticCache requires an embedFn to turn text into a vector. Bring your own, or use one of these provider-backed factories:

Import	Provides
@betterdb/ai/embed/openai	createOpenAIEmbed
@betterdb/ai/embed/bedrock	createBedrockEmbed
@betterdb/ai/embed/voyage	createVoyageEmbed
@betterdb/ai/embed/cohere	createCohereEmbed
@betterdb/ai/embed/ollama	createOllamaEmbed
@betterdb/ai/embed/google	createGoogleEmbed

import { SemanticCache } from '@betterdb/ai';
import { createOpenAIEmbed } from '@betterdb/ai/embed/openai';

const cache = new SemanticCache({ client, embedFn: createOpenAIEmbed() });

Namespaces

Twenty-five names are declared by more than one underlying package, so they are not exported flat. Reach them through the namespace for the package you want:

import Valkey from 'iovalkey';
import { AgentCache, agentCache, semanticCache } from '@betterdb/ai';

const cache = new AgentCache({ client: new Valkey() });

try {
  await cache.llm.check({
    model: 'claude-sonnet-4-5',
    messages: [{ role: 'user', content: 'hello' }],
  });
} catch (err) {
  if (err instanceof agentCache.ValkeyCommandError) {
    // agent-cache errors extend AgentCacheError
  } else if (err instanceof semanticCache.ValkeyCommandError) {
    // semantic-cache's ValkeyCommandError extends Error — a different class
    // that happens to share the name
  }
}

Namespaces: agentCache, semanticCache, retrieval, memory, searchKit. Each mirrors its package’s full root surface, so anything unavailable flat is available here.

The Python counterpart is betterdb-ai. It splits a different set of names — 22 rather than 25 — because the two ecosystems’ packages are not identical, and it versions independently of this one.

Versioning

Facade releases are automatic patch bumps triggered by each child’s own release, and may carry breaking changes from a child package. Consumers who need strict semver guarantees should pin @betterdb/ai to an exact version.