memory-v0.5.0

Summary

Session summaries no longer hallucinate. Three changes address the root causes — unfaithful extraction, lossy transcript truncation, and status-blind decision recording.

What's New

Quote-grounded extraction

Every decision and problem-solved item must now carry a short verbatim quote from the transcript. A deterministic validator (whitespace/case-normalized substring match) drops any item whose quote is missing or fabricated, then strips the quotes before storage. Applied in the single CompositeModelClient.summarize funnel — every provider path is grounded.

Priority-based transcript selection

Replaces the old head+tail 8K char slice that cut the middle of long sessions (where the summarizer then invented what "must have" happened). Turns are now ranked: user turns first, assistant turns by proximity to user turns, tool lines last. Selected turns are re-emitted in original order with [...] gap markers. Tool-only fallback transcripts are never emptied.

Decision status provenance

Decisions are now {text, status} with done | proposed | rejected | open. Renders as Decision (rejected): ... in recall output. Embeds with a status prefix so vectors reflect provenance. Legacy string decisions coerce to {text, status: "done"} at parse time — no migration needed.

What's Changed

• feat: ground session summaries in the transcript by @KIvanow in #7

Full Changelog: memory-v0.4.2...memory-v0.5.0

memory-v0.4.2

What's Changed

• fix: manual insights masked by branch-scoped recall by @KIvanow in #6

Full Changelog: memory-v0.4.1...memory-v0.4.2

v0.4.1

Fix: explicit Ollama provider ignored the configured model

When BETTERDB_SUMMARIZE_PROVIDER=ollama (or BETTERDB_EMBED_PROVIDER=ollama) was set, the explicit-provider path hardcoded PRESET_CLEAN and ignored BETTERDB_SUMMARIZE_MODEL / BETTERDB_EMBED_MODEL. Users on a non-default Ollama model (e.g. qwen2.5:3b) were silently routed to mistral:7b; if that model wasn't pulled, createModelClient() threw and the Stop hook captured zero memories.

Both explicit ollama branches now build the preset from config.ollama.*, so the configured model and embedding dimension are honored.

Recommended: reinstall to rebuild your hook binaries (bunx @betterdb/memory install).

BetterDB Memory for Claude Code v0.4.0

Recall-quality release: memories now embed their full structured detail, recall gates honestly instead of confabulating, and a fresh install produces embeddings with zero configuration.

Highlights

• Richer embeddings — decisions, patterns, problems, and open threads are now folded into the embedded text (previously only the one-line summary was embedded), so recall can actually see a session's substance. Bare file paths are excluded as noise.
• Threshold-gated, escalating recall — over-fetch → relative gate → narrow, escalating project+branch → project → cross-project. A miss is honest ("nothing cleared the bar") rather than surfacing the least-bad match, and the reader contract instructs the model not to fabricate or substitute a codebase grep for recall.
• Model-agnostic gate — relative floor/margin/separation instead of a fixed similarity threshold, so it transfers across embed models that compress cosine similarity into different bands.
• Zero-config on-device embeddings — falls back to all-MiniLM-L6-v2 (384-dim, Apache-2.0) when no Ollama/API provider is present; weights download once and cache.
• Native branch scope + content-type tags — branch maps to the store's thread scope and content types to tags (decision/pattern/problem/open-thread); search_context gains a tags filter.
• Single, configurable recall decay — dropped the dead decayRate knob and exposed the store's real composite decay (BETTERDB_RECALL_HALF_LIFE_DAYS + weights).
• New ops surface — status reports live store stats; a scoped forget CLI (dry-run by default, refuses unbounded deletes) previews exactly what it will delete.
• Local dev Docker setup — docker compose for valkey-search + Ollama.

Fixes

• Cross-project scope="all" requests are no longer silently downgraded when BETTERDB_ALLOW_CROSS_PROJECT is off — the miss message says widening is disabled instead of offering a retry the config would refuse.
• Escalating recall no longer reinforces the pre-gate over-fetch pool, so gated-out candidates don't skew composite ranking.
• forget dry-run now previews via the same native scope filter forgetByScope deletes with, so the preview matches --apply exactly.
• search_context/session-context excerpts now include pattern text, so pattern-filtered hits are answerable from the tool output.

BetterDB Memory for Claude Code v0.2.0

Added plugin installation flow
Added Docker option for spinning up Valkey for the user

BetterDB Memory for Claude Code v0.1.2

• Fixed MCP server registration to use global scope (-s user) so it's available in all projects, not just the install directory
• Uninstall now cleans up MCP server from both local and user scopes

BetterDB Memory for Claude Code v0.1.1

• Fixed runtime crash when running install/status commands (variable initialization order)
• Switched CLI instructions from npx to bunx — Bun is required to execute .ts bin entries

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

• 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

• [Bun](https://bun.sh) >= 1.0
• [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
• [Valkey](https://valkey.io) 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
docke...