@betterdb/memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterDB Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# 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](https://bun.sh) runtime — **required** (the CLI and all hooks run on Bun, not Node)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+- [Valkey](https://valkey.io) 8.0+ with the Search module
+
+### Install
+
+```bash
+# Bun must be installed first — npx delegates to it
+npx @betterdb/memory install
+```
+
+This 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
+
+### 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
+
+```bash
+npx @betterdb/memory install    # Set up hooks + MCP server
+npx @betterdb/memory status     # Check health
+npx @betterdb/memory uninstall  # Remove everything
+npx @betterdb/memory maintain   # Run aging/compression manually
+```
+
+### Configuration
+
+Via environment variables or `~/.betterdb/memory.json`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BETTERDB_VALKEY_URL` | `redis://localhost:6379` | Valkey connection URL |
+| `BETTERDB_EMBED_MODEL` | auto-detect | Embedding provider |
+| `BETTERDB_SUMMARIZE_MODEL` | auto-detect | Summarization provider |
+| `BETTERDB_EMBED_DIM` | `1024` | Embedding dimensions |
+| `BETTERDB_MAX_CONTEXT_MEMORIES` | `5` | Memories injected per session |
+| `BETTERDB_CONTEXT_FILE` | `.betterdb_context.md` | Context injection file |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@betterdb/memory",
+  "version": "0.1.0",
+  "description": "BetterDB Memory for Claude Code — Valkey-powered persistent memory across sessions",
+  "license": "MIT",
+  "author": "BetterDB Inc. <hello@betterdb.com>",
+  "homepage": "https://github.com/BetterDB-inc/memory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BetterDB-inc/memory.git"
+  },
+  "keywords": [
+    "claude-code",
+    "memory",
+    "valkey",
+    "mcp",
+    "ai-memory",
+    "vector-search",
+    "betterdb"
+  ],
+  "type": "module",
+  "bin": {
+    "betterdb-memory": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "bun test tests/integration",
+    "validate": "bash scripts/validate-pack.sh",
+    "prepublishOnly": "bash scripts/validate-pack.sh",
+    "setup-index": "bun run scripts/setup-index.ts",
+    "migrate-embeddings": "bun run scripts/migrate-embeddings.ts",
+    "check-providers": "bun run scripts/check-providers.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "iovalkey": "^0.2.1",
+    "ollama": "^0.5.14",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4",
+    "zod-to-json-schema": "^3.24.5",
+    "@anthropic-ai/sdk": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  }
+}

package/scripts/aging-worker.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+/**
+ * Standalone aging pipeline worker.
+ * Runs decay, compression, and distillation on all stored memories.
+ *
+ * Can be run via cron, docker compose, or manually:
+ *   bun run scripts/aging-worker.ts
+ */
+import { getValkeyClient } from "../src/client/valkey.js";
+import { createModelClient } from "../src/client/model.js";
+import { AgingPipeline } from "../src/memory/aging.js";
+
+try {
+  const valkeyClient = await getValkeyClient();
+  const modelClient = await createModelClient();
+
+  const pipeline = new AgingPipeline(valkeyClient, modelClient);
+  await pipeline.runFullPipeline();
+
+  await valkeyClient.quit();
+} catch (err) {
+  console.error("[betterdb] Aging worker failed:", err);
+  process.exit(1);
+}

package/scripts/check-providers.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+/**
+ * Checks which providers are available and prints a summary.
+ *
+ * Usage:
+ *   bun run check-providers
+ *   bun run check-providers -- --test   (makes live API calls)
+ */
+import { Ollama } from "ollama";
+import { config } from "../src/config.js";
+import { createModelClient } from "../src/client/model.js";
+import { PRESET_CLEAN, PRESET_ATTRIBUTION, PRESET_LIGHTWEIGHT } from "../src/client/model.js";
+
+const testMode = process.argv.includes("--test");
+
+console.log("BetterDB Provider Check");
+console.log("─────────────────────────────");
+
+// --- Ollama ---
+let ollamaModels: Set<string> = new Set();
+try {
+  const ollama = new Ollama({ host: config.ollama.url });
+  const list = await ollama.list();
+  ollamaModels = new Set(list.models.map((m) => m.name.split(":")[0]!));
+
+  const presets = [PRESET_CLEAN, PRESET_ATTRIBUTION, PRESET_LIGHTWEIGHT];
+  const modelChecks: string[] = [];
+  for (const preset of presets) {
+    const embedBase = preset.embedModel.split(":")[0]!;
+    const summarizeBase = preset.summarizeModel.split(":")[0]!;
+    if (ollamaModels.has(embedBase)) modelChecks.push(`${preset.embedModel} ✓`);
+    if (ollamaModels.has(summarizeBase)) modelChecks.push(`${preset.summarizeModel} ✓`);
+  }
+
+  const modelStr = modelChecks.length > 0 ? ` (${modelChecks.join(", ")})` : "";
+  console.log(`  Ollama        ✓ running${modelStr}`);
+} catch {
+  console.log("  Ollama        ✗ not running");
+}
+
+// --- API Key Providers ---
+const providers = [
+  { name: "OpenAI", key: config.providers.openaiKey },
+  { name: "Anthropic", key: config.providers.anthropicKey },
+  { name: "Voyage", key: config.providers.voyageKey },
+  { name: "Groq", key: config.providers.groqKey },
+  { name: "Together", key: config.providers.togetherKey },
+] as const;
+
+for (const p of providers) {
+  const status = p.key ? "✓ key set" : "✗ no key";
+  console.log(`  ${p.name.padEnd(14)}${status}`);
+}
+
+// --- Resolved Configuration ---
+console.log("");
+try {
+  const client = await createModelClient();
+  console.log("Resolved configuration:");
+  console.log(`  Embed:      ${client.preset.embedModel} (dim=${client.embedDim})`);
+  console.log(`  Summarize:  ${client.preset.summarizeModel}`);
+} catch (err) {
+  console.log("Resolution failed:");
+  console.log(`  ${err instanceof Error ? err.message : String(err)}`);
+}
+
+// --- Live Test ---
+if (testMode) {
+  console.log("");
+  console.log("Live API tests:");
+  console.log("─────────────────────────────");
+
+  try {
+    const client = await createModelClient();
+
+    // Embed test
+    const embedStart = performance.now();
+    try {
+      const embedding = await client.embed("BetterDB provider test");
+      const embedMs = (performance.now() - embedStart).toFixed(0);
+      console.log(`  Embed:      ✓ ${embedding.length} dims, ${embedMs}ms`);
+    } catch (err) {
+      const embedMs = (performance.now() - embedStart).toFixed(0);
+      console.log(`  Embed:      ✗ ${err instanceof Error ? err.message : String(err)} (${embedMs}ms)`);
+    }
+
+    // Summarize test
+    const sumStart = performance.now();
+    try {
+      const summary = await client.summarize("User asked to add a login button. Added onClick handler to LoginForm component.");
+      const sumMs = (performance.now() - sumStart).toFixed(0);
+      console.log(`  Summarize:  ✓ "${summary.oneLineSummary}" (${sumMs}ms)`);
+    } catch (err) {
+      const sumMs = (performance.now() - sumStart).toFixed(0);
+      console.log(`  Summarize:  ✗ ${err instanceof Error ? err.message : String(err)} (${sumMs}ms)`);
+    }
+  } catch (err) {
+    console.log(`  ✗ Cannot test — provider resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+} else {
+  console.log("");
+  console.log("Run 'bun run check-providers --test' to make a live API call to each available provider.");
+}

package/scripts/install-hooks.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# BetterDB Memory for Claude Code — Hook & MCP Installer
+# Compiles hook binaries and registers them with Claude Code
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Check prerequisites
+if ! command -v claude &>/dev/null; then
+  echo "ERROR: 'claude' CLI not found on PATH."
+  echo "Install Claude Code first: https://docs.anthropic.com/en/docs/claude-code"
+  exit 1
+fi
+
+if ! command -v bun &>/dev/null; then
+  echo "ERROR: 'bun' not found on PATH."
+  echo "Install Bun: https://bun.sh"
+  exit 1
+fi
+
+# Detect platform
+PLATFORM="$(uname -s)-$(uname -m)"
+echo "Platform: $PLATFORM"
+echo "Note: Hook binaries are platform-specific. Rebuild if deploying elsewhere."
+echo ""
+
+# Build hooks
+echo "Building hook binaries..."
+cd "$PROJECT_DIR"
+bun run build:hooks
+echo "Hook binaries compiled to dist/hooks/"
+echo ""
+
+# Write hooks to global settings
+GLOBAL_SETTINGS="$HOME/.claude/settings.json"
+mkdir -p "$HOME/.claude"
+
+# Create file with empty object if it doesn't exist
+if [ ! -f "$GLOBAL_SETTINGS" ]; then
+  echo '{}' > "$GLOBAL_SETTINGS"
+fi
+
+# Merge hooks into existing settings using Bun (preserves other fields, overwrites hooks block)
+# Each hook command sources the .env file first so compiled binaries get the right env vars
+# (bun build --compile binaries don't auto-load .env like `bun run` does)
+DIST_DIR="$PROJECT_DIR/dist/hooks"
+ENV_FILE="$PROJECT_DIR/.env"
+
+bun -e "
+const fs = require('fs');
+const settingsPath = '$GLOBAL_SETTINGS';
+const envFile = '$ENV_FILE';
+const distDir = '$DIST_DIR';
+const existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+// Wrap each binary so it loads .env at runtime
+const wrap = (bin) =>
+  'bash -c ' + JSON.stringify('set -a; [ -f ' + envFile + ' ] && . ' + envFile + '; set +a; ' + distDir + '/' + bin);
+
+const hooks = {
+  SessionStart: [{ hooks: [{ type: 'command', command: wrap('session-start') }] }],
+  PreToolUse:   [{ matcher: '', hooks: [{ type: 'command', command: wrap('pre-tool') }] }],
+  PostToolUse:  [{ matcher: '', hooks: [{ type: 'command', command: wrap('post-tool') }] }],
+  Stop:         [{ hooks: [{ type: 'command', command: wrap('session-end') }] }],
+};
+fs.writeFileSync(settingsPath, JSON.stringify({ ...existing, hooks }, null, 2));
+console.log('Hook configuration written to: ' + settingsPath);
+"
+
+# Register MCP server
+echo ""
+echo "Registering MCP server..."
+claude mcp add-json betterdb-memory "{\"type\":\"stdio\",\"command\":\"bun\",\"args\":[\"run\",\"$PROJECT_DIR/src/mcp/server.ts\"]}" 2>/dev/null || true
+echo "MCP server registered: betterdb-memory"
+
+# Verify hooks
+echo ""
+echo "Verifying global settings..."
+bun -e "
+const fs = require('fs');
+const settings = JSON.parse(fs.readFileSync('$HOME/.claude/settings.json', 'utf8'));
+const hookCount = Object.keys(settings.hooks || {}).length;
+console.log('Hooks registered: ' + hookCount + ' lifecycle events');
+"
+
+# Summary
+echo ""
+echo "=== Installation Complete ==="
+echo ""
+echo "Hooks written to: ~/.claude/settings.json"
+echo "  SessionStart  → $DIST_DIR/session-start"
+echo "  Stop          → $DIST_DIR/session-end"
+echo "  PreToolUse    → $DIST_DIR/pre-tool"
+echo "  PostToolUse   → $DIST_DIR/post-tool"
+echo ""
+echo "MCP server: betterdb-memory (stdio)"
+echo ""
+echo "Next steps:"
+echo "  1. Start infrastructure: docker compose up -d"
+echo "  2. Create search index: bun run setup-index"
+echo "  3. Start a new Claude Code session — memories will be captured automatically"

package/scripts/migrate-embeddings.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+/**
+ * Re-embeds all stored memories using the currently configured model.
+ * Required after changing BETTERDB_EMBED_MODEL or BETTERDB_EMBED_DIM.
+ *
+ * Usage:
+ *   bun run migrate-embeddings
+ *   bun run migrate-embeddings -- --dry-run
+ */
+import { getValkeyClient } from "../src/client/valkey.js";
+import { createModelClient } from "../src/client/model.js";
+import { config } from "../src/config.js";
+
+const dryRun = process.argv.includes("--dry-run");
+
+const valkeyClient = await getValkeyClient();
+const modelClient = await createModelClient();
+
+const memoryIds = await valkeyClient.listMemoryIds();
+console.log(`Found ${memoryIds.length} memories to migrate.`);
+console.log(`Target model: ${modelClient.preset.embedModel} (dim=${modelClient.embedDim})`);
+
+if (dryRun) {
+  console.log("Dry run — no changes will be made.");
+  await valkeyClient.quit();
+  process.exit(0);
+}
+
+// Step 1: Drop existing index
+console.log("Dropping existing index...");
+await valkeyClient.dropIndex();
+
+// Step 2: Update embed dimension metadata
+const redis = await getValkeyClient();
+
+// Step 3: Re-embed each memory
+let processed = 0;
+let failed = 0;
+
+for (const id of memoryIds) {
+  const memory = await valkeyClient.getMemory(id);
+  if (!memory) {
+    failed++;
+    continue;
+  }
+
+  try {
+    const newEmbedding = await modelClient.embed(memory.summary.oneLineSummary);
+    await valkeyClient.storeMemory(memory, newEmbedding);
+    processed++;
+    if (processed % 10 === 0) {
+      console.log(`Processed ${processed}/${memoryIds.length}...`);
+    }
+  } catch (err) {
+    console.error(`Failed to re-embed memory ${id}:`, err);
+    failed++;
+  }
+}
+
+// Step 4: Recreate index with new dimension
+console.log("Recreating index...");
+await valkeyClient.ensureIndex(modelClient.embedDim);
+
+console.log(`\nMigration complete:`);
+console.log(`  Processed: ${processed}`);
+console.log(`  Failed: ${failed}`);
+console.log(`  Index: ${config.valkey.indexName} (dim=${modelClient.embedDim})`);
+
+await valkeyClient.quit();

package/scripts/setup-index.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+import { getValkeyClient } from "../src/client/valkey.js";
+import { createModelClient } from "../src/client/model.js";
+import { config } from "../src/config.js";
+
+const client = await getValkeyClient();
+const modelClient = await createModelClient();
+
+await client.ensureIndex(modelClient.embedDim, modelClient.preset.embedModel);
+console.log("Index ready:", config.valkey.indexName);
+console.log("Embedding dimension:", modelClient.embedDim);
+console.log("Preset:", modelClient.preset.embedModel, "/", modelClient.preset.summarizeModel);
+
+await client.quit();

package/scripts/validate-pack.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Validating @betterdb/memory package ==="
+FAIL=0
+
+# Package name
+NAME=$(node -e "console.log(require('./package.json').name)")
+[ "$NAME" = "@betterdb/memory" ] && echo "✅ Name: $NAME" || { echo "❌ Name: $NAME (expected @betterdb/memory)"; FAIL=1; }
+
+# files field
+node -e "const p=require('./package.json'); if(!p.files) process.exit(1)" 2>/dev/null \
+  && echo "✅ Has files field" || { echo "❌ Missing files field"; FAIL=1; }
+
+# src/ in files
+node -e "const p=require('./package.json'); if(!p.files.includes('src/')) process.exit(1)" 2>/dev/null \
+  && echo "✅ src/ in files" || { echo "❌ src/ not in files"; FAIL=1; }
+
+# dist/ NOT in files
+node -e "const p=require('./package.json'); if(p.files && p.files.includes('dist/')) process.exit(1)" 2>/dev/null \
+  || { echo "❌ dist/ in files — remove it"; FAIL=1; }
+echo "✅ dist/ not in files"
+
+# bin entry
+node -e "const p=require('./package.json'); if(!p.bin?.['betterdb-memory']) process.exit(1)" 2>/dev/null \
+  && echo "✅ bin: betterdb-memory" || { echo "❌ Missing bin entry"; FAIL=1; }
+
+# bin target exists
+BIN=$(node -e "console.log(require('./package.json').bin['betterdb-memory'])")
+[ -f "$BIN" ] && echo "✅ bin target exists: $BIN" || { echo "❌ bin target missing: $BIN"; FAIL=1; }
+
+# No monorepo artifacts
+[ ! -f pnpm-workspace.yaml ] && echo "✅ No pnpm-workspace.yaml" || { echo "❌ pnpm-workspace.yaml exists"; FAIL=1; }
+[ ! -f turbo.json ] && echo "✅ No turbo.json" || { echo "❌ turbo.json exists"; FAIL=1; }
+[ ! -d packages ] && echo "✅ No packages/" || { echo "❌ packages/ directory exists"; FAIL=1; }
+
+# No Docker artifacts to ship
+PACK=$(npm pack --dry-run 2>&1)
+echo "$PACK" | grep -q "Dockerfile" && { echo "❌ Dockerfile in package"; FAIL=1; } || echo "✅ No Dockerfile in package"
+
+# Leaks
+for leak in "node_modules" ".env" ".git/"; do
+  echo "$PACK" | grep -q "$leak" && { echo "❌ $leak leaking"; FAIL=1; }
+done
+echo "✅ No leaks"
+
+# Standalone install
+echo ""
+echo "--- Standalone install ---"
+TMPDIR=$(mktemp -d)
+TARBALL=$(npm pack 2>/dev/null)
+(
+  cd "$TMPDIR"
+  npm init -y > /dev/null 2>&1
+  if npm install "$OLDPWD/$TARBALL" > /dev/null 2>&1; then
+    echo "✅ Installs standalone"
+    [ -d "node_modules/@betterdb/memory/src" ] && echo "✅ src/ present" || { echo "❌ src/ missing"; FAIL=1; }
+    [ -f node_modules/.bin/betterdb-memory ] && echo "✅ bin linked" || echo "⚠️  bin not linked"
+  else
+    echo "❌ Install failed"; FAIL=1
+  fi
+)
+rm -rf "$TMPDIR"
+rm -f "$TARBALL"
+
+echo ""
+[ $FAIL -eq 0 ] && echo "=== ✅ All checks passed ===" || { echo "=== ❌ FAILED ==="; exit 1; }