BetterDB Memory for Claude Code

Persistent, semantic memory for Claude Code sessions — powered by Valkey.

Every time you start a new Claude Code session, context is lost. BetterDB Memory automatically captures what you did, embeds it as vectors in Valkey, and retrieves relevant history at the start of each new session.

Quick Start

Prerequisites

• Bun runtime — required (the CLI and all hooks run on Bun, not Node)
• Claude Code installed
• Valkey 8.0+ with the Search module

Install

# 1. Copy .env.example and fill in your settings
cp .env.example .env

# 2. Install
bunx @betterdb/memory install

The install will:

1. Compile native hook binaries to ~/.betterdb/bin/
2. Register 4 lifecycle hooks with Claude Code
3. Register the MCP server for mid-conversation tools
4. Create the Valkey search index
5. Save your .env values to ~/.betterdb/memory.json for runtime use

Don't have Valkey?

The setup skill will offer to spin one up in Docker for you. Or run it manually:

# Via CLI
bunx @betterdb/memory docker-valkey

# Or directly with Docker
docker run -d --name betterdb-valkey -p 6379:6379 -v betterdb-valkey-data:/data valkey/valkey-search:8 valkey-server --save 60 1

How It Works

Hook	What it does
SessionStart	Retrieves relevant memories via vector search, injects as context
PostToolUse	Records every tool call to a temp JSONL file
Stop	Summarizes the session, embeds it, stores in Valkey
PreToolUse	Surfaces file-specific history when accessing known files

MCP Tools

Claude can use these mid-conversation:

• search_context — Semantic search over past sessions
• store_insight — Save a decision, pattern, or warning
• list_open_threads — Show unresolved items
• forget — Delete a specific memory

CLI Commands

bunx @betterdb/memory install        # Set up hooks + MCP server
bunx @betterdb/memory status         # Check health
bunx @betterdb/memory uninstall      # Remove everything
bunx @betterdb/memory maintain       # Run aging/compression manually
bunx @betterdb/memory docker-valkey  # Manage Docker Valkey container

Configuration

Copy .env.example to .env and fill in your values before running bunx @betterdb/memory install. They get saved to ~/.betterdb/memory.json and used by the compiled binaries at runtime.

Core

Variable	Default	Description
BETTERDB_VALKEY_URL	redis://localhost:6379	Valkey connection URL
BETTERDB_VALKEY_INDEX_NAME	betterdb-memory-index	Valkey search index name
BETTERDB_EMBED_DIM	1024	Embedding dimensions
BETTERDB_MAX_CONTEXT_MEMORIES	5	Memories injected per session
BETTERDB_CONTEXT_FILE	.betterdb_context.md	Context injection file
BETTERDB_ALLOW_REMOTE_FALLBACK	true	Fall back to remote APIs if local models unavailable

Model Providers

Variable	Default	Description
BETTERDB_EMBED_PROVIDER	auto-detect	Force embed provider: ollama, voyage, openai, groq, together
BETTERDB_SUMMARIZE_PROVIDER	auto-detect	Force summarize provider: ollama, anthropic, openai, groq, together
BETTERDB_EMBED_MODEL	mxbai-embed-large	Ollama embedding model name
BETTERDB_SUMMARIZE_MODEL	mistral:7b	Ollama summarization model name
BETTERDB_OLLAMA_URL	http://localhost:11434	Ollama API URL

API Keys

At least one embedding provider and one summarization provider must be available. Ollama is free and local; the others require API keys.

Variable	Provider	Used for
ANTHROPIC_API_KEY	Anthropic	Summarization only (no embeddings)
VOYAGE_API_KEY	Voyage AI	Embeddings only
OPENAI_API_KEY	OpenAI	Embeddings + summarization
GROQ_API_KEY	Groq	Embeddings + summarization
TOGETHER_API_KEY	Together AI	Embeddings + summarization

Aging Pipeline

Variable	Default	Description
BETTERDB_DECAY_RATE	0.95	Memory importance decay per day
BETTERDB_COMPRESS_THRESHOLD	0.3	Importance threshold for compression
BETTERDB_DISTILL_MIN_SESSIONS	5	Min sessions before knowledge distillation
BETTERDB_AGING_INTERVAL_HOURS	6	Hours between automatic aging runs

License

MIT