@betterdb/memory 0.1.2 → 0.2.0

package/README.md

@@ -16,14 +16,31 @@ relevant history at the start of each new session.
 ### Install
 
 ```bash
+# 1. Copy .env.example and fill in your settings
+cp .env.example .env
+
+# 2. Install
 bunx @betterdb/memory install
 ```
 
-This will:
+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:
+
+```bash
+# 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
 
@@ -45,24 +62,58 @@ Claude can use these mid-conversation:
 ### CLI Commands
 
 ```bash
-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 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
 
-Via environment variables or `~/.betterdb/memory.json`:
+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_EMBED_MODEL` | auto-detect | Embedding provider |
-| `BETTERDB_SUMMARIZE_MODEL` | auto-detect | Summarization provider |
+| `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](https://console.anthropic.com/) | Summarization only (no embeddings) |
+| `VOYAGE_API_KEY` | [Voyage AI](https://www.voyageai.com/) | Embeddings only |
+| `OPENAI_API_KEY` | [OpenAI](https://platform.openai.com/) | Embeddings + summarization |
+| `GROQ_API_KEY` | [Groq](https://console.groq.com/) | Embeddings + summarization |
+| `TOGETHER_API_KEY` | [Together AI](https://www.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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterdb/memory",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "BetterDB Memory for Claude Code — Valkey-powered persistent memory across sessions",
   "license": "MIT",
   "author": "BetterDB Inc. <hello@betterdb.com>",

package/scripts/docker-valkey.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONTAINER_NAME="betterdb-valkey"
+VOLUME_NAME="betterdb-valkey-data"
+PORT="${1:-6379}"
+ACTION="${2:-start}"
+
+# Check if Docker is available
+if ! command -v docker &>/dev/null; then
+  echo "ERROR: Docker is not installed."
+  echo "Install Docker: https://docs.docker.com/get-docker/"
+  exit 1
+fi
+
+case "$ACTION" in
+  start)
+    # Check if container already exists
+    if docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
+      if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
+        echo "Valkey container '${CONTAINER_NAME}' is already running on port ${PORT}."
+        exit 0
+      else
+        echo "Starting existing Valkey container '${CONTAINER_NAME}'..."
+        docker start "${CONTAINER_NAME}"
+        exit 0
+      fi
+    fi
+
+    # Try valkey-search image first (includes Search module)
+    echo "Pulling valkey/valkey-search:8..."
+    if docker pull valkey/valkey-search:8 2>/dev/null; then
+      IMAGE="valkey/valkey-search:8"
+    else
+      echo "valkey-search image not available, falling back to valkey/valkey:8-alpine..."
+      docker pull valkey/valkey:8-alpine
+      IMAGE="valkey/valkey:8-alpine"
+    fi
+
+    echo "Starting Valkey container on port ${PORT}..."
+    if ! docker run -d \
+      --name "${CONTAINER_NAME}" \
+      -p "${PORT}:6379" \
+      -v "${VOLUME_NAME}:/data" \
+      "${IMAGE}" \
+      valkey-server --save 60 1 2>/dev/null; then
+      # Port likely in use — retry on 16379
+      PORT=16379
+      echo "Port conflict. Retrying on port ${PORT}..."
+      docker run -d \
+        --name "${CONTAINER_NAME}" \
+        -p "${PORT}:6379" \
+        -v "${VOLUME_NAME}:/data" \
+        "${IMAGE}" \
+        valkey-server --save 60 1
+    fi
+
+    # Wait for startup
+    sleep 2
+
+    # Verify
+    if docker exec "${CONTAINER_NAME}" valkey-cli ping | grep -q PONG; then
+      echo "Valkey is running on redis://localhost:${PORT}"
+    else
+      echo "WARNING: Container started but ping failed. Check: docker logs ${CONTAINER_NAME}"
+      exit 1
+    fi
+    ;;
+
+  stop)
+    if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
+      docker stop "${CONTAINER_NAME}"
+      echo "Valkey container stopped."
+    else
+      echo "Valkey container is not running."
+    fi
+    ;;
+
+  status)
+    if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
+      RUNNING_PORT=$(docker port "${CONTAINER_NAME}" 6379 2>/dev/null | head -1 | cut -d: -f2)
+      echo "Valkey container '${CONTAINER_NAME}' is running on port ${RUNNING_PORT:-unknown}."
+    elif docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
+      echo "Valkey container '${CONTAINER_NAME}' exists but is stopped."
+    else
+      echo "No Valkey container found."
+    fi
+    ;;
+
+  remove)
+    docker stop "${CONTAINER_NAME}" 2>/dev/null || true
+    docker rm "${CONTAINER_NAME}" 2>/dev/null || true
+    echo "Valkey container removed. Volume '${VOLUME_NAME}' preserved."
+    echo "To remove data: docker volume rm ${VOLUME_NAME}"
+    ;;
+
+  *)
+    echo "Usage: docker-valkey.sh [port] [start|stop|status|remove]"
+    exit 1
+    ;;
+esac

package/scripts/register-hooks.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+
+/**
+ * Register BetterDB Memory lifecycle hooks in ~/.claude/settings.json.
+ *
+ * Usage:
+ *   bun run scripts/register-hooks.ts <plugin-root>
+ *
+ * <plugin-root> is the absolute path to the plugin directory (where src/hooks/ lives).
+ * Hook commands are written with resolved absolute paths — no env vars.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error("Usage: bun run register-hooks.ts <plugin-root>");
+  process.exit(1);
+}
+
+const resolvedRoot = resolve(pluginRoot);
+const hooksDir = join(resolvedRoot, "src", "hooks");
+
+// Verify hook source files exist
+const hookFiles = ["session-start.ts", "pre-tool.ts", "post-tool.ts", "session-end.ts"];
+for (const file of hookFiles) {
+  if (!existsSync(join(hooksDir, file))) {
+    console.error(`ERROR: Hook source not found: ${join(hooksDir, file)}`);
+    process.exit(1);
+  }
+}
+
+const HOME = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
+const claudeDir = join(HOME, ".claude");
+const settingsPath = join(claudeDir, "settings.json");
+
+// Ensure ~/.claude/ exists
+mkdirSync(claudeDir, { recursive: true });
+
+// Read existing settings (or start fresh)
+let settings: Record<string, unknown> = {};
+if (existsSync(settingsPath)) {
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // Corrupted file — start fresh but warn
+    console.warn("WARNING: Could not parse ~/.claude/settings.json — existing content will be preserved as backup.");
+    const backupPath = settingsPath + ".bak";
+    writeFileSync(backupPath, readFileSync(settingsPath));
+    console.warn(`  Backup saved to ${backupPath}`);
+  }
+}
+
+function cmd(hookFile: string): string {
+  return `bash -c 'bun run "${join(hooksDir, hookFile)}"'`;
+}
+
+// Merge hooks — replaces BetterDB entries per event, preserves all others
+const existingHooks = (settings["hooks"] ?? {}) as Record<string, unknown[]>;
+const betterdbHooks: Record<string, unknown[]> = {
+  SessionStart: [
+    { hooks: [{ type: "command", command: cmd("session-start.ts") }] },
+  ],
+  PreToolUse: [
+    { matcher: "", hooks: [{ type: "command", command: cmd("pre-tool.ts") }] },
+  ],
+  PostToolUse: [
+    { matcher: "", hooks: [{ type: "command", command: cmd("post-tool.ts") }] },
+  ],
+  Stop: [
+    { hooks: [{ type: "command", command: cmd("session-end.ts") }] },
+  ],
+};
+
+for (const [event, entries] of Object.entries(betterdbHooks)) {
+  const prev = Array.isArray(existingHooks[event]) ? existingHooks[event] : [];
+  const filtered = prev.filter((entry) => {
+    const json = JSON.stringify(entry);
+    return !json.includes("betterdb") && !json.includes(hooksDir);
+  });
+  existingHooks[event] = [...filtered, ...entries];
+}
+settings["hooks"] = existingHooks;
+
+writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+
+console.log("BetterDB Memory — Hooks registered in ~/.claude/settings.json\n");
+console.log("  SessionStart → session-start.ts");
+console.log("  PreToolUse   → pre-tool.ts");
+console.log("  PostToolUse  → post-tool.ts");
+console.log("  Stop         → session-end.ts");
+console.log(`\n  Plugin root: ${resolvedRoot}`);
+console.log("\n  Restart Claude Code for hooks to take effect.");

package/scripts/unregister-hooks.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env bun
+
+/**
+ * Remove BetterDB Memory lifecycle hooks from ~/.claude/settings.json.
+ *
+ * Only removes hook entries whose commands contain "betterdb-memory" or
+ * "betterdb" in the path. Other hooks from other plugins are preserved.
+ *
+ * Usage:
+ *   bun run scripts/unregister-hooks.ts
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const HOME = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
+const settingsPath = join(HOME, ".claude", "settings.json");
+
+if (!existsSync(settingsPath)) {
+  console.log("No ~/.claude/settings.json found — nothing to remove.");
+  process.exit(0);
+}
+
+let settings: Record<string, unknown>;
+try {
+  settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+} catch {
+  console.error("ERROR: Could not parse ~/.claude/settings.json");
+  process.exit(1);
+}
+
+const hooks = settings["hooks"];
+if (!hooks || typeof hooks !== "object") {
+  console.log("No hooks found in ~/.claude/settings.json — nothing to remove.");
+  process.exit(0);
+}
+
+const hooksObj = hooks as Record<string, unknown[]>;
+const BETTERDB_PATTERN = /betterdb/i;
+let removedCount = 0;
+
+for (const [event, entries] of Object.entries(hooksObj)) {
+  if (!Array.isArray(entries)) continue;
+
+  const filtered = entries.filter((entry) => {
+    if (typeof entry !== "object" || entry === null) return true;
+    const hooksList = (entry as Record<string, unknown>)["hooks"];
+    if (!Array.isArray(hooksList)) return true;
+
+    // Keep this entry if ANY of its hooks are NOT betterdb-related
+    const hasBetterdb = hooksList.some((h) => {
+      if (typeof h !== "object" || h === null) return false;
+      const command = (h as Record<string, unknown>)["command"];
+      return typeof command === "string" && BETTERDB_PATTERN.test(command);
+    });
+
+    if (hasBetterdb) removedCount++;
+    return !hasBetterdb;
+  });
+
+  if (filtered.length === 0) {
+    delete hooksObj[event];
+  } else {
+    hooksObj[event] = filtered;
+  }
+}
+
+// If hooks object is now empty, remove it entirely
+if (Object.keys(hooksObj).length === 0) {
+  delete settings["hooks"];
+}
+
+writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+
+if (removedCount > 0) {
+  console.log(`BetterDB Memory — Removed ${removedCount} hook(s) from ~/.claude/settings.json`);
+} else {
+  console.log("No BetterDB Memory hooks found in ~/.claude/settings.json.");
+}

package/src/config.ts

@@ -1,17 +1,21 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
+const CONFIG_PATH = join(
+  process.env["HOME"] ?? process.env["USERPROFILE"] ?? "",
+  ".betterdb",
+  "memory.json",
+);
+
 /**
  * Load saved config from ~/.betterdb/memory.json as fallback for env vars.
  * This allows compiled binaries (hooks, MCP server) to work without
  * requiring env vars to be set — config is saved during `install`.
  */
 const _fileConfig: Record<string, string> = (() => {
-  const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
-  const p = join(home, ".betterdb", "memory.json");
-  if (!existsSync(p)) return {};
+  if (!existsSync(CONFIG_PATH)) return {};
   try {
-    const data: unknown = JSON.parse(readFileSync(p, "utf-8"));
+    const data: unknown = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
     if (typeof data !== "object" || data === null) return {};
     const result: Record<string, string> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
@@ -65,3 +69,8 @@ export const config = {
 } as const;
 
 export type Config = typeof config;
+
+/** Returns true if ~/.betterdb/memory.json exists (i.e. setup has been run). */
+export function isConfigured(): boolean {
+  return existsSync(CONFIG_PATH);
+}

package/src/hooks/post-tool.ts

@@ -1,6 +1,7 @@
 import { readRawPayload, runHook } from "./_utils.js";
 import { appendFile } from "node:fs/promises";
 import type { SessionEvent } from "../memory/schema.js";
+import { isConfigured } from "../config.js";
 
 /**
  * PostToolUse hook: Records tool call results to a temp JSONL file.
@@ -13,6 +14,7 @@ import type { SessionEvent } from "../memory/schema.js";
  * The JSONL file is read by session-end.ts to build the session transcript.
  */
 runHook(async () => {
+  if (!isConfigured()) return;
   const payload = await readRawPayload();
   const sessionId = payload["session_id"] as string;
   const toolName = (payload["tool_name"] as string) ?? "unknown";

package/src/hooks/pre-tool.ts

@@ -1,6 +1,6 @@
 import { readRawPayload, runHook } from "./_utils.js";
 import { getValkeyClient } from "../client/valkey.js";
-import { config } from "../config.js";
+import { config, isConfigured } from "../config.js";
 
 /**
  * PreToolUse hook: Checks for file history and appends notes to context.
@@ -11,6 +11,7 @@ import { config } from "../config.js";
  * - Exit 0 to allow, exit 2 to block
  */
 runHook(async () => {
+  if (!isConfigured()) return;
   const payload = await readRawPayload();
   const toolInput = payload["tool_input"] as Record<string, unknown> | undefined;
 

package/src/hooks/session-end.ts

@@ -8,7 +8,7 @@ import {
   getCwdProject,
 } from "../memory/capture.js";
 import { SessionEventSchema, type EpisodicMemory } from "../memory/schema.js";
-import { config } from "../config.js";
+import { config, isConfigured } from "../config.js";
 import { unlink } from "node:fs/promises";
 
 /**
@@ -25,6 +25,7 @@ import { unlink } from "node:fs/promises";
  * 3. If model client is unavailable, queue for later processing
  */
 runHook(async () => {
+  if (!isConfigured()) return;
   const payload = await readRawPayload();
   const sessionId = payload["session_id"] as string;
   const cwd = (payload["cwd"] as string) ?? process.cwd();
@@ -77,7 +78,14 @@ runHook(async () => {
       transcript.slice(-half);
   }
 
-  const valkeyClient = await getValkeyClient();
+  let valkeyClient;
+  try {
+    valkeyClient = await getValkeyClient();
+  } catch {
+    await cleanup(eventFilePath);
+    return; // Valkey unreachable — skip silently
+  }
+
   const project = getCwdProject();
   const branch = getGitBranch();
 

package/src/hooks/session-start.ts

@@ -3,7 +3,7 @@ import { getValkeyClient } from "../client/valkey.js";
 import { createModelClient } from "../client/model.js";
 import { SessionCapture } from "../memory/capture.js";
 import { MemoryRetriever, formatForInjection } from "../memory/retrieval.js";
-import { config } from "../config.js";
+import { config, isConfigured } from "../config.js";
 
 /**
  * SessionStart hook: Retrieves relevant memories and injects context.
@@ -14,6 +14,13 @@ import { config } from "../config.js";
  * - Exit 0 for success
  */
 runHook(async () => {
+  if (!isConfigured()) {
+    process.stdout.write(
+      "[BetterDB Memory] Not configured yet. Run /betterdb-memory:setup to connect to Valkey.\n",
+    );
+    return;
+  }
+
   const payload = await readRawPayload();
   const cwd = (payload["cwd"] as string) ?? process.cwd();
 
@@ -21,7 +28,13 @@ runHook(async () => {
     process.chdir(cwd);
   }
 
-  const valkeyClient = await getValkeyClient();
+  let valkeyClient;
+  try {
+    valkeyClient = await getValkeyClient();
+  } catch {
+    return; // Valkey unreachable — skip silently
+  }
+
   const modelClient = await createModelClient();
 
   const capture = new SessionCapture();

package/src/index.ts

@@ -36,11 +36,12 @@ Usage:
   betterdb-memory <command>
 
 Commands:
-  install     Compile binaries, register hooks + MCP server
-  uninstall   Remove hooks, MCP server, and compiled binaries
-  status      Check health of Valkey and model providers
-  maintain    Run aging/compression pipeline manually
-  version     Print version
+  install        Compile binaries, register hooks + MCP server
+  uninstall      Remove hooks, MCP server, and compiled binaries
+  status         Check health of Valkey and model providers
+  maintain       Run aging/compression pipeline manually
+  docker-valkey  Manage Docker Valkey container [start|stop|status|remove]
+  version        Print version
 
 Environment:
   BETTERDB_VALKEY_URL   Valkey connection (default: redis://localhost:6379)
@@ -63,6 +64,16 @@ switch (command) {
   case "maintain":
     await runMaintain();
     break;
+  case "docker-valkey": {
+    const action = process.argv[3] ?? "start";
+    const port = process.argv[4] ?? "6379";
+    const script = join(PKG_ROOT, "scripts", "docker-valkey.sh");
+    const result = Bun.spawnSync(["bash", script, port, action]);
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+    break;
+  }
   case "version":
   case "--version":
   case "-v":
@@ -175,12 +186,14 @@ async function runInstall() {
     }
   }
 
-  settings["hooks"] = {
+  const existingHooks = (settings["hooks"] ?? {}) as Record<string, unknown[]>;
+  const betterdbHooks: Record<string, unknown[]> = {
     SessionStart: [{ hooks: [{ type: "command", command: join(BIN_DIR, "session-start") }] }],
     PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: join(BIN_DIR, "pre-tool") }] }],
     PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: join(BIN_DIR, "post-tool") }] }],
     Stop: [{ hooks: [{ type: "command", command: join(BIN_DIR, "session-end") }] }],
   };
+  settings["hooks"] = mergeHooks(existingHooks, betterdbHooks);
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   console.log("  Registered 4 hooks in ~/.claude/settings.json");
@@ -364,6 +377,30 @@ async function runStatus() {
     console.log("FAILED (could not read settings)");
   }
 
+  // Check Docker container (only if config has "docker": true)
+  const dockerFlag = readConfigValue("docker");
+  if (dockerFlag === "true") {
+    process.stdout.write("Docker container... ");
+    const script = join(PKG_ROOT, "scripts", "docker-valkey.sh");
+    if (existsSync(script)) {
+      const result = Bun.spawnSync(["bash", script, "6379", "status"]);
+      const output = result.stdout.toString().trim();
+      if (output.includes("is running")) {
+        const portMatch = output.match(/port (\d+)/);
+        console.log(`OK (betterdb-valkey, running, port ${portMatch?.[1] ?? "unknown"})`);
+      } else if (output.includes("stopped")) {
+        console.log(`STOPPED (run: bunx @betterdb/memory docker-valkey)`);
+      } else {
+        console.log(`NOT FOUND (run: bunx @betterdb/memory docker-valkey)`);
+      }
+    } else {
+      console.log("SCRIPT MISSING (docker-valkey.sh not found)");
+    }
+  } else {
+    process.stdout.write("Docker container... ");
+    console.log("NOT USED (Valkey managed externally)");
+  }
+
   // Check config file
   process.stdout.write("Config file... ");
   if (existsSync(CONFIG_PATH)) {
@@ -417,6 +454,29 @@ function commandExists(cmd: string): boolean {
   return result.exitCode === 0;
 }
 
+/**
+ * Merge BetterDB hooks into existing settings hooks without clobbering
+ * entries from other plugins or user-defined hooks. For each event,
+ * removes any previous BetterDB entries (matched by BIN_DIR path)
+ * then appends the new ones.
+ */
+function mergeHooks(
+  existing: Record<string, unknown[]>,
+  ours: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+  const merged = { ...existing };
+  for (const [event, entries] of Object.entries(ours)) {
+    const prev = Array.isArray(merged[event]) ? merged[event] : [];
+    // Filter out previous BetterDB entries (contain our BIN_DIR or betterdb path)
+    const filtered = prev.filter((entry) => {
+      const json = JSON.stringify(entry);
+      return !json.includes(BIN_DIR) && !json.includes("betterdb");
+    });
+    merged[event] = [...filtered, ...entries];
+  }
+  return merged;
+}
+
 function readConfigValue(key: string): string | undefined {
   if (!existsSync(CONFIG_PATH)) return undefined;
   try {
@@ -425,6 +485,7 @@ function readConfigValue(key: string): string | undefined {
     const val = (data as Record<string, unknown>)[key];
     if (typeof val === "string") return val;
     if (typeof val === "number") return String(val);
+    if (typeof val === "boolean") return String(val);
     return undefined;
   } catch {
     return undefined;

package/src/mcp/server.ts

@@ -5,11 +5,15 @@ import { getValkeyClient } from "../client/valkey.js";
 import { createModelClient } from "../client/model.js";
 import { formatForInjection } from "../memory/retrieval.js";
 import { getCwdProject } from "../memory/capture.js";
+import { isConfigured } from "../config.js";
 import type { EpisodicMemory, KnowledgeEntry } from "../memory/schema.js";
 
+const SETUP_MESSAGE =
+  "BetterDB Memory is not configured yet. Run /betterdb-memory:setup to connect to Valkey and create the search index.";
+
 const server = new McpServer({
   name: "betterdb-memory",
-  version: "0.1.0",
+  version: "0.2.0",
 });
 
 // --- Tool: search_context ---
@@ -22,6 +26,10 @@ server.tool(
     top_k: z.number().int().min(1).max(20).optional().describe("Max results (default: 5)"),
   },
   async ({ query, top_k }) => {
+    if (!isConfigured()) {
+      return { content: [{ type: "text" as const, text: SETUP_MESSAGE }] };
+    }
+
     const valkeyClient = await getValkeyClient();
     const modelClient = await createModelClient();
 
@@ -56,6 +64,10 @@ server.tool(
     project: z.string().optional().describe("Project name (auto-detected if omitted)"),
   },
   async ({ content, category, project: projectInput }) => {
+    if (!isConfigured()) {
+      return { content: [{ type: "text" as const, text: SETUP_MESSAGE }] };
+    }
+
     const valkeyClient = await getValkeyClient();
     const modelClient = await createModelClient();
     const project = projectInput ?? getCwdProject();
@@ -114,6 +126,10 @@ server.tool(
     project: z.string().optional().describe("Project name (auto-detected if omitted)"),
   },
   async ({ project: projectInput }) => {
+    if (!isConfigured()) {
+      return { content: [{ type: "text" as const, text: SETUP_MESSAGE }] };
+    }
+
     const valkeyClient = await getValkeyClient();
     const project = projectInput ?? getCwdProject();
 
@@ -154,6 +170,10 @@ server.tool(
     confirmed: z.boolean().optional().describe("Set to true to confirm deletion"),
   },
   async ({ memory_id, confirmed }) => {
+    if (!isConfigured()) {
+      return { content: [{ type: "text" as const, text: SETUP_MESSAGE }] };
+    }
+
     const valkeyClient = await getValkeyClient();
 
     if (!confirmed) {