@dvquys/qrec 0.2.0

package/README.md

@@ -0,0 +1,99 @@
+# qrec
+
+Purpose-built session recall engine for Claude Code. Keeps an embedding model resident in memory for fast hybrid search (BM25 + vector) over your Claude session transcripts.
+
+- **Warm query**: ~55ms vs ~2600ms cold model load per invocation
+
+## Install
+
+### Step 1 — Install the CLI
+
+```bash
+npm install -g qrec
+qrec onboard
+```
+
+`qrec onboard` downloads the embedding model (~313 MB, once), indexes your Claude sessions at `~/.claude/projects/`, and starts the daemon. Your browser opens automatically to show live progress.
+
+### Step 2 — Claude Code integration (optional)
+
+Install the plugin so the daemon auto-starts with every Claude Code session:
+
+```bash
+/plugin marketplace add dvquy13/qrec
+/plugin install qrec@dvquy13-qrec
+```
+
+That's it — no further configuration needed.
+
+### Local dev
+
+```bash
+bun install
+bun link        # register qrec globally → ~/.bun/bin/qrec
+qrec onboard
+```
+
+## Usage
+
+The daemon runs at **http://localhost:3030**. Open it in your browser to search sessions and monitor indexing activity.
+
+```bash
+qrec status     # check if daemon is running
+qrec stop       # stop the daemon
+```
+
+### API
+
+```bash
+curl -s -X POST http://localhost:3030/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "sqlite vec extension", "k": 5}' | jq .
+```
+
+```json
+{
+  "results": [
+    {
+      "session_id": "a1b2c3d4",
+      "title": "...",
+      "date": "2026-03-09",
+      "project": "qrec",
+      "score": 0.042,
+      "preview": "...best matching chunk..."
+    }
+  ],
+  "latencyMs": 58
+}
+```
+
+### MCP server
+
+```bash
+qrec mcp          # stdio (Claude Code MCP config)
+qrec mcp --http   # HTTP on port 3031
+```
+
+Tools: `search(query, k?)`, `get(session_id)`, `status()`
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `qrec onboard` | First-time setup: model download + index + start daemon + open browser |
+| `qrec teardown` | Stop daemon and remove all qrec data (`~/.qrec/`) |
+| `qrec index [path]` | Re-index sessions (default: `~/.claude/projects/`) |
+| `qrec serve [--daemon]` | Start HTTP server on port 3030 |
+| `qrec stop` | Stop daemon |
+| `qrec mcp [--http]` | Start MCP server (stdio or HTTP) |
+| `qrec status` | Status summary + log tail |
+
+## Stack
+
+| Layer | Choice |
+|---|---|
+| Runtime | Bun |
+| Language | TypeScript |
+| Search DB | SQLite (FTS5 + sqlite-vec) |
+| Embeddings | node-llama-cpp 3.15.1 (`embeddinggemma-300M-Q8_0`) |
+| MCP | `@modelcontextprotocol/sdk` |

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dvquys/qrec",
+  "version": "0.2.0",
+  "description": "Purpose-built session recall engine — persistent daemon with BM25 + vector hybrid search",
+  "bin": {
+    "qrec": "plugin/scripts/qrec-cli.js"
+  },
+  "files": [
+    "plugin/scripts/qrec.cjs",
+    "plugin/scripts/qrec-cli.js",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "node scripts/build.js",
+    "release": "bash scripts/release.sh",
+    "smoke-test": "bash scripts/smoke-test.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-llama-cpp": "3.15.1",
+    "sqlite-vec": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.0.0"
+  },
+  "trustedDependencies": [
+    "node-llama-cpp"
+  ]
+}

package/plugin/scripts/qrec-cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// qrec-cli.js — npm bin entry. Locates bun and spawns qrec.cjs with all CLI args.
+
+"use strict";
+
+const { spawnSync, spawn } = require("child_process");
+const { existsSync } = require("fs");
+const { homedir } = require("os");
+const path = require("path");
+
+const BUN_CANDIDATES = [
+  path.join(homedir(), ".bun", "bin", "bun"),
+  "/usr/local/bin/bun",
+  "/opt/homebrew/bin/bun",
+  "/home/linuxbrew/.linuxbrew/bin/bun",
+];
+
+function findBun() {
+  for (const candidate of BUN_CANDIDATES) {
+    if (existsSync(candidate)) return candidate;
+  }
+  try {
+    const r = spawnSync("which", ["bun"], { encoding: "utf-8", timeout: 3000 });
+    if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
+  } catch {}
+  return null;
+}
+
+const bunPath = findBun();
+if (!bunPath) {
+  process.stderr.write("[qrec] ERROR: bun not found. Install from https://bun.sh\n");
+  process.exit(1);
+}
+
+const qrecCjs = path.join(__dirname, "qrec.cjs");
+const userArgs = process.argv.slice(2);
+const bunArgs = ["run", qrecCjs, ...userArgs];
+
+// serve --daemon: fire-and-fork so the hook returns immediately.
+// Claude Code hooks never close stdin, so blocking on stdin would hang forever.
+if (userArgs.includes("serve") && userArgs.includes("--daemon")) {
+  const child = spawn(bunPath, bunArgs, {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  process.exit(0);
+}
+
+// Buffer stdin before passing to bun (avoids libuv pipe crash on Linux).
+const stdinChunks = [];
+process.stdin.on("data", chunk => stdinChunks.push(chunk));
+process.stdin.on("end", () => {
+  const buf = Buffer.concat(stdinChunks);
+  const result = spawnSync(bunPath, bunArgs, {
+    input: buf.length > 0 ? buf : undefined,
+    stdio: buf.length > 0 ? ["pipe", "inherit", "inherit"] : ["ignore", "inherit", "inherit"],
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+});
+
+if (process.stdin.isTTY) {
+  process.stdin.destroy();
+  const result = spawnSync(bunPath, bunArgs, {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+}