Betterdb Mcp

List all Valkey/Redis instances registered in BetterDB. Shows connection status and capabilities.

Select which instance subsequent tool calls operate on.

Add a new Valkey/Redis connection to BetterDB. Optionally set it as the active default.

Test a Valkey/Redis connection without persisting it. Use before add_connection to validate credentials.

Remove a connection from BetterDB.

Set a connection as the active default for BetterDB.

Get INFO stats for the active instance. Contains all health data: memory, clients, replication, keyspace, stats (hit rate, ops/sec), and server info. Optionally filter to a section: server|clients|memory|stats|replication|keyspace.

Get the most recent slow commands from the slowlog.

Get the most recent entries from COMMANDLOG (Valkey 8+ only, superset of slowlog).

Get latency event history for the active instance.

Get memory diagnostics: MEMORY DOCTOR assessment and MEMORY STATS breakdown.

Get the active client list with connection details.

Get a synthetic health summary for the active instance: keyspace hit rate, memory fragmentation ratio, connected clients, replication lag (replicas only), and keyspace size. Use this as the first call when investigating an instance — it surfaces the most actionable signals without requiring you to parse raw INFO output.

Get analyzed slowlog patterns from persisted storage. Groups slow commands by normalized pattern, showing frequency, average duration, and example commands. Survives slowlog buffer rotation — data goes back as far as BetterDB has been running.

Get persisted COMMANDLOG entries from storage (Valkey 8+ only). Supports time range filtering to investigate specific incidents. Returns empty with a note if COMMANDLOG is not supported on this instance.

Get analyzed COMMANDLOG patterns from persisted storage (Valkey 8+ only). Like get_slowlog_patterns but includes large-request and large-reply patterns in addition to slow commands.

Get anomaly detection events from persisted storage. BetterDB continuously runs Z-score analysis on memory, hit rate, CPU, and other metrics — this returns the detected anomalies. Use to investigate what triggered an alert or correlate with an incident.

Get time-bucketed client activity from persisted snapshots. Shows connection counts, command distribution, and buffer usage over time. Use startTime/endTime to focus on a specific incident window.

Get hot key tracking data from persisted storage. BetterDB periodically scans keys using LFU frequency scores (when maxmemory-policy is an LFU variant) or OBJECT IDLETIME / COMMANDLOG-derived frequency. Each snapshot captures the top keys ranked by access frequency. Use this to find cache-busting keys, uneven access patterns, or keys that dominate throughput. The signalType field in each entry indicates which detection mode was active (lfu or idletime).

Discover all nodes in the Valkey cluster — role (master/replica), address, health status, and slot ranges. Returns an error message if this instance is not running in cluster mode.

Get per-node performance stats: memory usage, ops/sec, connected clients, replication offset, and CPU. Use this to identify hot nodes, lagging replicas, or uneven load distribution.

Get the aggregated slowlog across ALL nodes in the cluster. This is the primary tool for finding slow commands in cluster mode — per-node slowlogs are incomplete. Returns an error message if not in cluster mode.

Get per-slot key counts and CPU usage (Valkey 8.0+ only). Use orderBy='cpu-usec' to find hot slots, or 'key-count' to find the most populated slots. Returns an error message if not supported.

Get the full latency history for a named event (e.g. 'command', 'fast-command'). Call get_latency first to see which event names are available, then use this to investigate a specific event's trend over time.

Get persisted ACL audit log entries from storage. Filter by username, reason (auth, command, key, channel), or time range. Use this to investigate why a connection is failing or audit access patterns.

Start the BetterDB monitor as a persistent background process. If already running, returns the existing URL. The monitor persists across MCP sessions and must be stopped explicitly with stop_monitor.

List all caches (semantic_cache and agent_cache) registered for the active instance, with hit rate and total ops.

Detailed health for a single cache. Response branches by type: semantic_cache reports category_breakdown + uncertain_hit_rate; agent_cache reports tool_breakdown.

Threshold-tuning recommendation for a semantic_cache, based on the rolling similarity-score window. Errors with INVALID_CACHE_TYPE on agent_cache.

Per-tool hit rate, cost saved, and TTL recommendation for an agent_cache. Errors with INVALID_CACHE_TYPE on semantic_cache.

Histogram of recent similarity scores (20 buckets, width 0.1) for a semantic_cache. Errors on agent_cache.

Recent proposals for a single cache (any status), so agents can avoid re-proposing pending or recently-applied changes. Newest first.

Propose a semantic-cache similarity-threshold change for review. Creates a pending proposal that requires human approval before any change is applied. Reasoning must be at least 20 characters.

Propose an agent-cache per-tool TTL change for review. Creates a pending proposal that requires human approval. Reasoning must be at least 20 characters.

Propose a cache invalidation for review. Filter shape depends on cache type: semantic_cache requires filter_kind=valkey_search + filter_expression; agent_cache requires filter_kind in (tool|key_prefix|session) + filter_value. Warns when estimated_affected exceeds 10000.

List pending cache proposals for the active instance, newest first. Optionally filter by cache_name.

Fetch a single cache proposal by id, including its audit trail.

Approve a pending proposal. Synchronously applies the change to Valkey and returns the terminal status (applied|failed). Idempotent: a second call on an already-applied proposal returns the cached result.

Reject a pending proposal. Optionally records a reason in the audit trail.

Edit an existing pending proposal and approve it in one step. Provide exactly one edit field matching the proposal type: new_threshold for threshold_adjust, new_ttl_seconds for tool_ttl_adjust. Invalidate proposals are not editable.

Stop a persistent BetterDB monitor process that was previously started with start_monitor or --autostart --persist.

List agent-memory stores discovered on an instance (name, capabilities, stats key).

List memories in a store, newest first, with optional scope and tag filters.

Fetch a single memory by ID from a store.

Get item count, eviction count, and live config for a memory store.

Recall memories from a store by a precomputed query vector (the caller supplies the embedding).

Propose forgetting memories (by id, or by scope/tags). Creates a pending proposal that a human must approve before anything is deleted.

List pending forget proposals awaiting approval on an instance.

Approve a pending forget proposal, applying the deletion against the live store.

Reject a pending forget proposal without deleting anything.

List AI component instances (semantic caches, agent caches, agent memory stores, retrieval pipelines) auto-discovered on the connected Valkey/Redis instance, with liveness and the latest stored metrics sample. This is the superset discovery view across all AI components — use cache_list for cache-specific live stats and memory_stores for memory-store details. Use the returned instance field value as the field parameter of ai_instance_history.

Get the stored metrics time-series for one AI component instance (hits, misses, hit rate, cost saved, evictions, item count, index size, threshold). Use ai_list_instances first to find the instance field identifier. Use this to see trends: hit-rate degradation, growth, threshold drift.

List recent AI application traces ingested via OpenTelemetry (LLM calls, cache lookups, memory recalls, retrieval spans). Not tied to a Valkey instance — traces come from instrumented AI apps. Use get_ai_trace for a full span waterfall and correlate_ai_trace to join a trace with live Valkey state.

Get the full span waterfall for one AI trace: every span with timing, parent relationships, and attributes (model, cache hit/miss, similarity scores). Use list_ai_traces to find trace IDs.

Explain WHY a trace behaved the way it did by joining its cache/memory spans with live Valkey state: does the key still exist, what is its TTL, what threshold was active, what is the index state. The strongest tool for diagnosing unexpected cache misses or stale memory recalls. Requires a selected instance (the one the AI components run on).

Get a capacity forecast for one metric: current trajectory and projected time until the resource ceiling is hit. Metric kinds: opsPerSec, usedMemory, cpuTotal, memFragmentation. Use for capacity planning ("when does memory run out at current growth?").

Get detected latency regressions (sustained p99 command-latency degradations vs baseline) from persisted storage. Companion to get_anomalies: same event store, pre-filtered to latency regressions. Use when investigating "the database got slower".

Get the largest keys from key analytics snapshots, ranked by measured memory usage. Coverage note: snapshots track the biggest collections by element count, so a memory-heavy key with few elements may not be tracked. Companion to get_hot_keys, which ranks by access frequency. Use to find memory hogs, bloated hashes/sets, or candidates for TTL/eviction. Requires BetterDB Pro (keyAnalytics).

Get health details for every vector search index on the instance: document count, memory usage, indexing failures, and percent indexed. Requires the Search module (valkey-search / RediSearch) on the connection — errors clearly if absent. Use to diagnose incomplete indexing or index memory growth.

Get the FT.SEARCH latency profile: p50/p95/p99 per vector index over the sampling window, plus SLA breach status per index. sla is null when BetterDB Pro inference SLA monitoring is absent or unlicensed, and an empty array when it is active with no indexes configured. More specific than get_latency, which covers general command latency. Use to answer "are vector searches meeting their latency budget?".