@mingxy/cerebro-claude-code 0.3.3

package/skills/memory-search/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: memory-search
+description: Semantic search over the user's long-term memory (Cerebro). Use when the user references past work, prior decisions, stored preferences, or session history you may have saved; when an ambiguous name/concept could be disambiguated by stored context; or when you need background that earlier sessions likely captured. Searches are auto-filtered to the current project + user tags. Returns ranked matches with relevance scores.
+---
+
+# Memory Search
+
+Search long-term memory by semantic similarity. Memories are scoped to the current project automatically; global-scope memories are always included.
+
+## When to use
+
+- User mentions "earlier / before / last time / we discussed / remember when …"
+- A name, file, or concept feels ambiguous and stored context could resolve it
+- You need a prior decision, rationale, or preference before acting
+- Recovering context that was compacted away in a previous session
+
+## How to run
+
+```bash
+bash "$CLAUDE_PLUGIN_ROOT/scripts/memory-search.sh" "auth flow refresh-token decision" 10
+```
+
+- Arg 1: natural-language query (auto-truncated; quoting is recommended).
+- Arg 2 (optional): result limit. Defaults to `$MEM_SEARCH_COUNT` (8).
+
+Content can also be piped via stdin:
+
+```bash
+echo "why did we pick sqlite over postgres" | bash "$CLAUDE_PLUGIN_ROOT/scripts/memory-search.sh" -
+```
+
+## Output format
+
+One line per match:
+
+```
+[0.91] mem_abc123: Fixed refresh-token rotation bug in auth.rs — added replay guard
+[0.78] mem_def456: Decision: use sqlite for local cache, postgres only on cloud
+```
+
+`no memories` when nothing matches. `error: …` on transport/server failure.
+
+## Notes
+
+- Query is auto-truncated to `$MEM_MAX_QUERY_LENGTH` (200 chars).
+- Filters by `omem_user_<hash>` and `omem_project_<hash>` tags plus `project_path`, so results respect project isolation.
+- For full content of a truncated match, follow up with `memory-save` is NOT the right tool — fetch by id via the server API or re-run search with a sharper query.

package/tests/common.test.mjs

@@ -0,0 +1,123 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import {
+  cleanText,
+  formatRelativeAge,
+  truncateQuery,
+  sanitizeContent,
+} from "../hooks/common.mjs";
+
+describe("cleanText", () => {
+  test("strips cerebro inject tags", () => {
+    const input = "hello <cerebro-memory>secret</cerebro-memory> world";
+    assert.equal(cleanText(input), "hello world");
+  });
+
+  test("strips cerebro self-closing tags", () => {
+    const input = "text <cerebro-nudge /> after";
+    assert.equal(cleanText(input), "text after");
+  });
+
+  test("strips system-reminder tags", () => {
+    const input = "before <system-reminder>internal</system-reminder> after";
+    assert.equal(cleanText(input), "before after");
+  });
+
+  test("strips supermemory tags", () => {
+    const input = "a <supermemory-context>data</supermemory-context> b";
+    assert.equal(cleanText(input), "a b");
+  });
+
+  test("collapses whitespace", () => {
+    const input = "line1\n\n\n  line2   \n\tline3";
+    assert.equal(cleanText(input), "line1 line2 line3");
+  });
+
+  test("handles non-string input", () => {
+    assert.equal(cleanText(42), "42");
+    assert.equal(cleanText(null), "null");
+  });
+});
+
+describe("formatRelativeAge", () => {
+  test("returns 'unknown' for null/undefined", () => {
+    assert.equal(formatRelativeAge(null), "unknown");
+    assert.equal(formatRelativeAge(undefined), "unknown");
+    assert.equal(formatRelativeAge(""), "unknown");
+  });
+
+  test("returns minutes for recent dates", () => {
+    const fiveMinAgo = new Date(Date.now() - 5 * 60000).toISOString();
+    const result = formatRelativeAge(fiveMinAgo);
+    assert.match(result, /^\d+m ago$/);
+  });
+
+  test("returns hours for older dates", () => {
+    const threeHrAgo = new Date(Date.now() - 3 * 3600000).toISOString();
+    const result = formatRelativeAge(threeHrAgo);
+    assert.match(result, /^\d+h ago$/);
+  });
+
+  test("returns days for dates > 24h", () => {
+    const threeDayAgo = new Date(Date.now() - 3 * 86400000).toISOString();
+    const result = formatRelativeAge(threeDayAgo);
+    assert.match(result, /^\d+d ago$/);
+  });
+
+  test("returns months for dates > 30d", () => {
+    const twoMonthAgo = new Date(Date.now() - 70 * 86400000).toISOString();
+    const result = formatRelativeAge(twoMonthAgo);
+    assert.match(result, /^\d+mo ago$/);
+  });
+});
+
+describe("truncateQuery", () => {
+  test("returns empty for empty input", () => {
+    assert.equal(truncateQuery(""), "");
+    assert.equal(truncateQuery(null), "");
+    assert.equal(truncateQuery(undefined), "");
+  });
+
+  test("returns short query unchanged", () => {
+    assert.equal(truncateQuery("hello"), "hello");
+  });
+
+  test("truncates long query to default length", () => {
+    const long = "x".repeat(300);
+    const result = truncateQuery(long);
+    assert.equal(result.length, 200);
+  });
+
+  test("respects custom length", () => {
+    const long = "x".repeat(100);
+    assert.equal(truncateQuery(long, 50).length, 50);
+  });
+});
+
+describe("sanitizeContent", () => {
+  test("removes HTML tags", () => {
+    const input = "text <div>inner</div> more";
+    assert.equal(sanitizeContent(input, 1000), "text more");
+  });
+
+  test("removes self-closing tags", () => {
+    const input = "a <br/> b";
+    assert.equal(sanitizeContent(input, 1000), "a b");
+  });
+
+  test("collapses whitespace", () => {
+    const input = "line1\n\n  line2";
+    assert.equal(sanitizeContent(input, 1000), "line1 line2");
+  });
+
+  test("truncates with ellipsis marker when exceeding maxLen", () => {
+    const long = "x".repeat(200);
+    const result = sanitizeContent(long, 50);
+    assert.ok(result.length <= 65); // 50 + "…[truncated]"
+    assert.ok(result.includes("…[truncated]"));
+  });
+
+  test("does not truncate short content", () => {
+    assert.equal(sanitizeContent("short", 1000), "short");
+  });
+});

package/tests/hooks.test.mjs

@@ -0,0 +1,111 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOKS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "hooks");
+
+/**
+ * Run a hook script with given stdin JSON, return parsed stdout JSON.
+ * Points OMEM_API_URL to a dead port so fetch calls fail fast
+ * (postRecallEvent / buildMemoryInjection swallow errors via try/catch).
+ */
+function runHook(script, stdinObj, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [join(HOOKS_DIR, script)], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        OMEM_API_KEY: opts.apiKey ?? "test-key-12345",
+        OMEM_API_URL: opts.apiUrl ?? "http://127.0.0.1:1",
+      },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("close", (code) => resolve({ stdout, stderr, code }));
+    child.on("error", reject);
+    child.stdin.write(JSON.stringify(stdinObj));
+    child.stdin.end();
+  });
+}
+
+describe("user-prompt-submit.mjs", () => {
+  test("injects cerebro-recall instruction for normal message", async () => {
+    const { stdout } = await runHook("user-prompt-submit.mjs", {
+      session_id: "test-sid",
+      prompt: "hello world",
+    });
+    const out = JSON.parse(stdout);
+    const ctx = out.hookSpecificOutput.additionalContext;
+    assert.ok(ctx.includes("<cerebro-recall>"), "should contain cerebro-recall instruction");
+    assert.ok(!ctx.includes("cerebro-nudge"), "should NOT contain nudge for normal message");
+  });
+
+  test("injects save nudge when prompt contains save keyword", async () => {
+    const { stdout } = await runHook("user-prompt-submit.mjs", {
+      session_id: "test-sid",
+      prompt: "记住这个配置",
+    });
+    const ctx = JSON.parse(stdout).hookSpecificOutput.additionalContext;
+    assert.ok(ctx.includes("<cerebro-nudge>"), "should contain nudge");
+    assert.ok(ctx.includes("memory-save"), "should mention memory-save skill");
+  });
+
+  test("injects recall nudge when prompt contains recall keyword", async () => {
+    const { stdout } = await runHook("user-prompt-submit.mjs", {
+      session_id: "test-sid",
+      prompt: "之前那个bug怎么修的",
+    });
+    const ctx = JSON.parse(stdout).hookSpecificOutput.additionalContext;
+    assert.ok(ctx.includes("<cerebro-nudge>"), "should contain nudge");
+    assert.ok(ctx.includes("memory-search"), "should mention memory-search skill");
+  });
+
+  test("handles English keywords", async () => {
+    const { stdout } = await runHook("user-prompt-submit.mjs", {
+      session_id: "test-sid",
+      prompt: "remember to update the docs",
+    });
+    const ctx = JSON.parse(stdout).hookSpecificOutput.additionalContext;
+    assert.ok(ctx.includes("cerebro-nudge"), "should detect English save keyword");
+  });
+});
+
+describe("pre-compact.mjs", () => {
+  test("outputs empty JSON (no hookSpecificOutput)", async () => {
+    const { stdout } = await runHook("pre-compact.mjs", {
+      session_id: "test-sid",
+      transcript_path: "/nonexistent/path.jsonl",
+    });
+    const out = JSON.parse(stdout);
+    assert.deepEqual(out, {});
+  });
+
+  test("outputs empty JSON when missing session_id", async () => {
+    const { stdout } = await runHook("pre-compact.mjs", {
+      transcript_path: "/nonexistent/path.jsonl",
+    });
+    const out = JSON.parse(stdout);
+    assert.deepEqual(out, {});
+  });
+});
+
+describe("session-end.mjs", () => {
+  test("outputs empty JSON for nonexistent transcript", async () => {
+    const { stdout } = await runHook("session-end.mjs", {
+      session_id: "test-sid",
+      transcript_path: "/nonexistent/path.jsonl",
+    });
+    const out = JSON.parse(stdout);
+    assert.deepEqual(out, {});
+  });
+
+  test("outputs empty JSON when missing fields", async () => {
+    const { stdout } = await runHook("session-end.mjs", {});
+    const out = JSON.parse(stdout);
+    assert.deepEqual(out, {});
+  });
+});

package/tests/test_smoke.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+# cerebro Claude Code plugin — Phase5 smoke tests
+#
+# 零依赖：纯 bash + python3（不装 bats）。一键跑：bash tests/test_smoke.sh
+#
+# 覆盖：
+#   - session-start：无 key 分支（[cerebro] 提示）+ 带 key 分支（stub server，
+#     断言 [CEREBRO-MEMORY] / [CEREBRO-TIME] / <cerebro-profile> / recent）
+#   - user-prompt-submit：保存类 / 召回类 / 普通 / 英文 关键词 nudge
+#   - recall-approve：memory-search 放行 / 普通 Bash / 危险 Bash
+#   - memory-save / memory-search：参数校验 exit code + --help
+#   - stop / pre-compact：无 key 短路 {}
+set -uo pipefail
+
+PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HOOKS="$PLUGIN_DIR/hooks"
+SCRIPTS="$PLUGIN_DIR/scripts"
+TMP="$(mktemp -d)"
+STUB_PID=""
+
+cleanup() {
+  [[ -n "$STUB_PID" ]] && kill "$STUB_PID" 2>/dev/null || true
+  rm -rf "$TMP" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ─── 环境隔离：不读真实 config，不带真实 key，不写日志 ────────────────────────
+export CEREBRO_CONFIG_PATH="/nonexistent-test-cfg.json"
+export OMEM_API_KEY=""
+export OMEM_API_URL="http://127.0.0.1:1"   # unreachable → curl fails silently
+export MEM_LOG_ENABLED="0"
+export MEM_LOG_DIR="$TMP/logs"
+
+PASS=0
+FAIL=0
+FAILED_CASES=()
+
+ok()   { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); FAILED_CASES+=("$1"); }
+
+assert_contains()     { # <label> <haystack> <needle>
+  if [[ "$2" == *"$3"* ]]; then ok "$1"; else fail "$1 (missing: $3)"; fi
+}
+assert_not_contains() { # <label> <haystack> <needle>
+  if [[ "$2" != *"$3"* ]]; then ok "$1"; else fail "$1 (unexpected: $3)"; fi
+}
+assert_exit()         { # <label> <expected> <actual>
+  if [[ "$2" == "$3" ]]; then ok "$1"; else fail "$1 (exit: want=$2 got=$3)"; fi
+}
+assert_eq()           { # <label> <expected> <actual>
+  if [[ "$2" == "$3" ]]; then ok "$1"; else fail "$1 (want=[$2] got=[$3])"; fi
+}
+
+# ─── 本地 stub HTTP server（测 session-start 带 key 分支）─────────────────────
+# 返回固定 profile + recent JSON，让 hook 走 [CEREBRO-MEMORY] 组装分支。
+start_stub() {
+  cat > "$TMP/stub.py" <<'PYEOF'
+import http.server, socketserver, json
+class H(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        p = self.path
+        if p.startswith("/v2/profile/inject"):
+            body = json.dumps({"content": "TEST PROFILE", "preference_count": 1})
+        elif p.startswith("/v1/memories"):
+            body = json.dumps({"memories": [{"content": "recent activity line", "id": "m1"}]})
+        else:
+            body = "{}"
+        b = body.encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(b)))
+        self.end_headers()
+        self.wfile.write(b)
+    def log_message(self, *a): pass
+class S(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    daemon_threads = True
+srv = S(("127.0.0.1", 0), H)
+print(srv.server_address[1], flush=True)
+srv.serve_forever()
+PYEOF
+  python3 "$TMP/stub.py" > "$TMP/port" 2>/dev/null &
+  STUB_PID=$!
+  for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+    [[ -s "$TMP/port" ]] && break
+    sleep 0.1
+  done
+  STUB_PORT="$(cat "$TMP/port" 2>/dev/null || echo "")"
+}
+
+echo "=== SessionStart ==="
+
+# (1) 无 key 分支
+out="$(OMEM_API_KEY="" bash "$HOOKS/session-start.sh" </dev/null 2>/dev/null || true)"
+assert_contains "session-start no-key: hookSpecificOutput" "$out" '"hookSpecificOutput"'
+assert_contains "session-start no-key: [cerebro] prefix"    "$out" '[cerebro]'
+assert_contains "session-start no-key: mentions API key"    "$out" 'OMEM_API_KEY'
+
+# (2) 带 key 分支（stub server）——验证 [CEREBRO-MEMORY] / [CEREBRO-TIME] / profile / recent
+start_stub
+if [[ -z "$STUB_PORT" ]]; then
+  fail "session-start stub: server did not start"
+else
+  out="$(OMEM_API_KEY="test-key" OMEM_API_URL="http://127.0.0.1:$STUB_PORT" \
+         bash "$HOOKS/session-start.sh" </dev/null 2>/dev/null || true)"
+  assert_contains "session-start stub: hookSpecificOutput"   "$out" '"hookSpecificOutput"'
+  assert_contains "session-start stub: [CEREBRO-MEMORY] open" "$out" '[CEREBRO-MEMORY]'
+  assert_contains "session-start stub: [/CEREBRO-MEMORY] close" "$out" '[/CEREBRO-MEMORY]'
+  assert_contains "session-start stub: [CEREBRO-TIME] line"  "$out" '[CEREBRO-TIME]'
+  assert_contains "session-start stub: time prefix text"     "$out" '当前:'
+  assert_contains "session-start stub: <cerebro-profile>"    "$out" '<cerebro-profile>'
+  assert_contains "session-start stub: profile content"      "$out" 'TEST PROFILE'
+  assert_contains "session-start stub: recent activity"      "$out" 'recent activity line'
+fi
+
+echo
+echo "=== UserPromptSubmit (keyword nudge) ==="
+
+run_ups() { printf '%s' "$1" | bash "$HOOKS/user-prompt-submit.sh" 2>/dev/null || true; }
+
+# 保存类（中文）
+out="$(run_ups '{"prompt":"请记住这个决定：以后用 rust 写后端"}')"
+assert_contains "ups save-zh: nudge tag"     "$out" '<cerebro-nudge>'
+assert_contains "ups save-zh: memory-save"   "$out" 'memory-save skill'
+assert_contains "ups save-zh: recall instr"  "$out" '<cerebro-recall>'
+
+# 召回类（中文）
+out="$(run_ups '{"prompt":"上次那个 bug 修好了吗"}')"
+assert_contains "ups recall-zh: nudge tag"   "$out" '<cerebro-nudge>'
+assert_contains "ups recall-zh: memory-search" "$out" 'memory-search skill'
+
+# 保存类（英文）
+out="$(run_ups '{"prompt":"please remember this decision"}')"
+assert_contains "ups save-en: nudge tag"     "$out" '<cerebro-nudge>'
+assert_contains "ups save-en: memory-save"   "$out" 'memory-save skill'
+
+# 召回类（英文）
+out="$(run_ups '{"prompt":"lets continue from earlier"}')"
+assert_contains "ups recall-en: nudge tag"   "$out" '<cerebro-nudge>'
+assert_contains "ups recall-en: memory-search" "$out" 'memory-search skill'
+
+# 普通消息：无 nudge，只有 recall 指令
+out="$(run_ups '{"prompt":"你好，今天天气如何"}')"
+assert_not_contains "ups plain: no nudge"    "$out" '<cerebro-nudge>'
+assert_contains     "ups plain: recall instr" "$out" '<cerebro-recall>'
+
+# 空/缺字段 stdin：不崩，有 recall 指令
+out="$(run_ups '{}')"
+assert_contains "ups empty: recall instr"    "$out" '<cerebro-recall>'
+assert_not_contains "ups empty: no nudge"    "$out" '<cerebro-nudge>'
+
+echo
+echo "=== recall-approve (PreToolUse) ==="
+
+run_ra() { printf '%s' "$1" | bash "$HOOKS/recall-approve.sh" 2>/dev/null || true; }
+
+# memory-search Skill → allow
+out="$(run_ra '{"tool_name":"Skill","tool_input":{"name":"memory-search"}}')"
+assert_contains "ra skill-search: allow"     "$out" '"permissionDecision"'
+assert_contains "ra skill-search: allow val" "$out" 'allow'
+
+# tool_name 直接含 memory-search → allow
+out="$(run_ra '{"tool_name":"memory-search","tool_input":{}}')"
+assert_contains "ra direct-search: allow"    "$out" 'allow'
+
+# 普通 Bash（非 memory-search）→ {}
+out="$(run_ra '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}')"
+assert_eq "ra plain-bash: deny {}"           '{}' "$out"
+
+# 危险 Bash（memory-search.sh; rm）→ {}
+out="$(run_ra '{"tool_name":"Bash","tool_input":{"command":"bash memory-search.sh; rm -rf /"}}')"
+assert_eq "ra danger-bash: deny {}"          '{}' "$out"
+
+# 危险 Bash（$( 命令替换）→ {}
+out="$(run_ra '{"tool_name":"Bash","tool_input":{"command":"memory-search.sh $(whoami)"}}')"
+assert_eq "ra subst-bash: deny {}"           '{}' "$out"
+
+echo
+echo "=== memory-save arg validation ==="
+
+# 空 content → exit 1
+bash "$SCRIPTS/memory-save.sh" </dev/null >/dev/null 2>&1; rc=$?
+assert_exit "save empty-content: exit 1"     "1" "$rc"
+
+# bad visibility → exit 2
+bash "$SCRIPTS/memory-save.sh" --content "x" --visibility bad >/dev/null 2>&1; rc=$?
+assert_exit "save bad-visibility: exit 2"    "2" "$rc"
+
+# bad category → exit 2
+bash "$SCRIPTS/memory-save.sh" --content "x" --category bad >/dev/null 2>&1; rc=$?
+assert_exit "save bad-category: exit 2"      "2" "$rc"
+
+# bad scope → exit 2
+bash "$SCRIPTS/memory-save.sh" --content "x" --scope bad >/dev/null 2>&1; rc=$?
+assert_exit "save bad-scope: exit 2"         "2" "$rc"
+
+# unknown option → exit 2
+bash "$SCRIPTS/memory-save.sh" --bogus >/dev/null 2>&1; rc=$?
+assert_exit "save unknown-opt: exit 2"       "2" "$rc"
+
+# --help → exit 0 + usage text
+help_out="$(bash "$SCRIPTS/memory-save.sh" --help 2>&1 || true)"; rc=$?
+assert_exit "save --help: exit 0"            "0" "$rc"
+assert_contains "save --help: usage text"    "$help_out" 'content'
+
+echo
+echo "=== memory-search arg validation ==="
+
+# 空 query → exit 1
+bash "$SCRIPTS/memory-search.sh" "" </dev/null >/dev/null 2>&1; rc=$?
+assert_exit "search empty-query: exit 1"     "1" "$rc"
+
+echo
+echo "=== stop / pre-compact (no-key short-circuit) ==="
+
+# stop 无 key → {}
+out="$(OMEM_API_KEY="" bash "$HOOKS/stop.sh" </dev/null 2>/dev/null || true)"
+assert_eq "stop no-key: {}"                  '{}' "$out"
+
+# pre-compact 无 key → {}
+out="$(OMEM_API_KEY="" bash "$HOOKS/pre-compact.sh" </dev/null 2>/dev/null || true)"
+assert_eq "pre-compact no-key: {}"           '{}' "$out"
+
+echo
+echo "========================"
+TOTAL=$((PASS + FAIL))
+echo "Total: $TOTAL | PASS: $PASS | FAIL: $FAIL"
+if [[ "$FAIL" -ne 0 ]]; then
+  echo "Failed cases:"
+  for c in "${FAILED_CASES[@]}"; do echo "  - $c"; done
+  exit 1
+fi
+echo "ALL PASS"
+exit 0