Skip to content

BetterDB Memory for Claude Code v0.1.0

Choose a tag to compare

View all tags
@KIvanow KIvanow released this 02 Mar 17:02
· 78 commits to master since this release
memory-v0.1.0
5cd40e5
This commit was signed with the committer’s verified signature.
KIvanow Kristiyan Ivanov
GPG key ID: 4BB27D5B662BC86B
Verified
Learn about vigilant mode.

Persistent, semantic memory for Claude Code sessions, powered by Valkey (Redis compatible).

Every Claude Code session starts from zero. BetterDB Memory fixes that. It automatically captures what you did, embeds it as vectors in Valkey (Redis compatible), and retrieves relevant history when you start a new session. No manual effort, just use Claude Code normally.

What's in this release

Automatic session capture

Four lifecycle hooks integrate directly with Claude Code:

  • SessionStart retrieves relevant memories via vector search and injects them as context. Claude starts every session aware of your recent work.
  • PostToolUse silently records every tool call (file reads, bash commands, edits) to a JSONL event file.
  • Stop summarizes the full session transcript, generates a vector embedding, and stores the memory in Valkey.
  • PreToolUse surfaces file-specific history when you access files that appeared in past sessions.

If the summarization model is unavailable when a session ends, raw transcripts are queued to betterdb:ingest_queue. Nothing is ever dropped.

MCP tools for mid-conversation use

Claude can use four tools during a session:

  • search_context - semantic search over all past sessions ("what was that API pattern we used?")
  • store_insight - explicitly save a decision, pattern, or warning to persistent memory
  • list_open_threads - surface unresolved items and TODOs from past sessions
  • forget - permanently delete a specific memory

Valkey-native vector search

Memories are stored as Valkey hashes with HNSW vector indexes for cosine similarity search. Each memory includes the embedding, project/branch tags, a one-line summary, importance score, access count, and a full structured summary (decisions, patterns, problems solved, open threads, files changed).

TAG and NUMERIC indexes enable filtered searches by project and branch, plus efficient queries for the aging and decay pipeline. Lists serve as async processing queues, and sorted sets index distilled knowledge entries.

Smart memory lifecycle

Memories aren't just stored, they're managed:

  • Importance scoring - sessions that solved problems and changed files score higher than sessions where Claude only answered a question
  • Aging and decay - importance decays over time (0.95^days), keeping recent and frequently-accessed memories prominent
  • Compression - similar memories are clustered via cosine similarity and merged into consolidated entries
  • Distillation - recurring patterns across 5+ sessions are extracted into stable knowledge entries that don't decay

6 model providers, mix and match

Embedding and summarization are decoupled. Use different providers for each:

Provider Embedding Summarization
Ollama (local) mxbai-embed-large (1024d) mistral:7b
Voyage AI voyage-3 (1024d) -
OpenAI text-embedding-3-small (1536d) gpt-4o-mini
Anthropic - claude-haiku-4-5
Groq nomic-embed-text-v1_5 (768d) llama-3.1-8b-instant
Together AI m2-bert-80M-8k-retrieval (768d) Meta-Llama-3.1-8B-Instruct-Turbo

Auto-detection picks the best available provider based on what's running (Ollama) or which API keys are set. Explicit overrides via BETTERDB_EMBED_PROVIDER and BETTERDB_SUMMARIZE_PROVIDER.

One-command install

npx @betterdb/memory install

Compiles native binaries for your platform, registers hooks and the MCP server with Claude Code, creates the Valkey search index, and saves config to ~/.betterdb/. After install, hooks run as standalone executables with zero runtime dependencies.

CLI

npx @betterdb/memory install    # Set up everything
npx @betterdb/memory status     # Check Valkey, hooks, index health
npx @betterdb/memory uninstall  # Clean removal
npx @betterdb/memory maintain   # Run aging/compression/distillation manually

Requirements

  • Bun >= 1.0
  • Claude Code
  • Valkey 8.0+ (Redis compatible) with the Search module
  • At least one embedding provider (Ollama with mxbai-embed-large, or an API key)
  • At least one summarization provider (Ollama with mistral:7b, or an API key)

Quick start

# Start Valkey (Redis compatible) with search module + Ollama
docker compose up -d

Install and register with Claude Code


npx @betterdb/memory install


Start a Claude Code session, that's it


claude

License

MIT

Built by BetterDB Inc. - operational intelligence for Valkey (Redis compatible).

# BetterDB Memory for Claude Code v0.1.0

Persistent, semantic memory for Claude Code sessions, powered by Valkey (Redis compatible).

Every Claude Code session starts from zero. BetterDB Memory fixes that. It automatically captures what you did, embeds it as vectors in Valkey (Redis compatible), and retrieves relevant history when you start a new session. No manual effort, just use Claude Code normally.

What's in this release

Automatic session capture

Four lifecycle hooks integrate directly with Claude Code:

  • SessionStart retrieves relevant memories via vector search and injects them as context. Claude starts every session aware of your recent work.
  • PostToolUse silently records every tool call (file reads, bash commands, edits) to a JSONL event file.
  • Stop summarizes the full session transcript, generates a vector embedding, and stores the memory in Valkey.
  • PreToolUse surfaces file-specific history when you access files that appeared in past sessions.

If the summarization model is unavailable when a session ends, raw transcripts are queued to betterdb:ingest_queue. Nothing is ever dropped.

MCP tools for mid-conversation use

Claude can use four tools during a session:

  • search_context - semantic search over all past sessions ("what was that API pattern we used?")
  • store_insight - explicitly save a decision, pattern, or warning to persistent memory
  • list_open_threads - surface unresolved items and TODOs from past sessions
  • forget - permanently delete a specific memory

Valkey-native vector search

Memories are stored as Valkey hashes with HNSW vector indexes for cosine similarity search. Each memory includes the embedding, project/branch tags, a one-line summary, importance score, access count, and a full structured summary (decisions, patterns, problems solved, open threads, files changed).

TAG and NUMERIC indexes enable filtered searches by project and branch, plus efficient queries for the aging and decay pipeline. Lists serve as async processing queues, and sorted sets index distilled knowledge entries.

Smart memory lifecycle

Memories aren't just stored, they're managed:

  • Importance scoring - sessions that solved problems and changed files score higher than sessions where Claude only answered a question
  • Aging and decay - importance decays over time (0.95^days), keeping recent and frequently-accessed memories prominent
  • Compression - similar memories are clustered via cosine similarity and merged into consolidated entries
  • Distillation - recurring patterns across 5+ sessions are extracted into stable knowledge entries that don't decay

6 model providers, mix and match

Embedding and summarization are decoupled. Use different providers for each:

Provider Embedding Summarization
Ollama (local) mxbai-embed-large (1024d) mistral:7b
Voyage AI voyage-3 (1024d) -
OpenAI text-embedding-3-small (1536d) gpt-4o-mini
Anthropic - claude-haiku-4-5
Groq nomic-embed-text-v1_5 (768d) llama-3.1-8b-instant
Together AI m2-bert-80M-8k-retrieval (768d) Meta-Llama-3.1-8B-Instruct-Turbo

Auto-detection picks the best available provider based on what's running (Ollama) or which API keys are set. Explicit overrides via BETTERDB_EMBED_PROVIDER and BETTERDB_SUMMARIZE_PROVIDER.

One-command install

npx @betterdb/memory install

Compiles native binaries for your platform, registers hooks and the MCP server with Claude Code, creates the Valkey search index, and saves config to ~/.betterdb/. After install, hooks run as standalone executables with zero runtime dependencies.

CLI

npx @betterdb/memory install    # Set up everything
npx @betterdb/memory status     # Check Valkey, hooks, index health
npx @betterdb/memory uninstall  # Clean removal
npx @betterdb/memory maintain   # Run aging/compression/distillation manually

Requirements

Quick start

# Start Valkey (Redis compatible) with search module + Ollama
docker compose up -d

# Install and register with Claude Code
npx @betterdb/memory install

# Start a Claude Code session, that's it
claude

License

MIT

Built by [BetterDB Inc.](https://betterdb.com) - operational intelligence for Valkey (Redis compatible).

Assets 2
Loading