@mingxy/cerebro-claude-code 0.3.3

package/hooks/stop.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// cerebro Stop hook — periodic session-ingest flush every N turns
+// Does NOT fire on Ctrl+C interrupt (Claude Code design).
+// SessionEnd detached process covers the interrupt case.
+import { parseStdinJSON, emit, flushSessionIngest, stopCounterGet, stopCounterSet, injectionConfig } from "./common.mjs";
+
+const input = parseStdinJSON();
+const tp = input.transcript_path || "";
+const sid = input.session_id || "";
+
+const stopCfg = injectionConfig.stopFlush || {};
+if (stopCfg.enabled === false || !tp || !sid) {
+  emit({});
+  process.exit(0);
+}
+
+const interval = stopCfg.interval || 5;
+const counter = stopCounterGet(sid);
+const newCount = counter + 1;
+
+if (newCount < interval) {
+  stopCounterSet(sid, newCount);
+  emit({});
+  process.exit(0);
+}
+
+// Threshold reached — flush
+stopCounterSet(sid, 0);
+const result = await flushSessionIngest(tp, sid).catch(() => ({ ok: false, count: 0 }));
+
+emit({
+  systemMessage: result.ok
+    ? `🧠 Cerebro · Auto-saved · ${result.count} messages ingested`
+    : `🧠 Cerebro · Auto-save failed (will retry next flush)`,
+});

package/hooks/user-prompt-submit.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// cerebro UserPromptSubmit hook — reasoned recall instruction + keyword nudge
+// Injection content is config-driven (~/.claude/cerebro.json), not hardcoded.
+import { parseStdinJSON, emit, postRecallEvent, injectionConfig } from "./common.mjs";
+
+const input = parseStdinJSON();
+const prompt = typeof input === "object" ? input.prompt || input.message || "" : "";
+const sid = input.session_id || "";
+
+// ─── Build injection from config ────────────────────────────────────────────
+const parts = [];
+
+// Recall instruction
+const recallCfg = injectionConfig.recall || {};
+if (recallCfg.enabled !== false && recallCfg.prompt) {
+  parts.push(`<cerebro-recall>\n${recallCfg.prompt}\n</cerebro-recall>`);
+}
+
+// Keyword nudge
+const nudgeCfg = injectionConfig.nudge || {};
+if (nudgeCfg.enabled !== false) {
+  const pLow = prompt.toLowerCase();
+  const nudges = [];
+  const saveKw = nudgeCfg.saveKeywords || [];
+  const recallKw = nudgeCfg.recallKeywords || [];
+
+  if (saveKw.some((kw) => pLow.includes(String(kw).toLowerCase())) && nudgeCfg.savePrompt) {
+    nudges.push(`<cerebro-nudge>${nudgeCfg.savePrompt}</cerebro-nudge>`);
+  }
+  if (recallKw.some((kw) => pLow.includes(String(kw).toLowerCase())) && nudgeCfg.recallPrompt) {
+    nudges.push(`<cerebro-nudge>${nudgeCfg.recallPrompt}</cerebro-nudge>`);
+  }
+  if (nudges.length) parts.push(nudges.join("\n"));
+}
+
+const injectionText = parts.join("\n\n");
+
+// ─── POST recall-event (web Sessions page) ───────────────────────────────────
+await postRecallEvent({
+  sessionId: sid,
+  recallType: "auto",
+  queryText: prompt,
+  profileInjected: false,
+  keptCount: 0,
+  injectedContent: injectionText,
+  maxScore: 0,
+});
+
+emit({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: injectionText } });

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mingxy/cerebro-claude-code",
+  "version": "0.3.3",
+  "description": "Persistent memory for Claude Code — memories survive across sessions, projects, and machines",
+  "author": {
+    "name": "mingxy-cerebro",
+    "email": "hi@cerebro.dev"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/mingxy-cerebro/cerebro-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mingxy-cerebro/cerebro-server",
+    "directory": "plugins/claude-code"
+  },
+  "keywords": [
+    "claude-code",
+    "memory",
+    "persistent",
+    "agent-memory",
+    "context",
+    "recall",
+    "profile"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/memory-profile.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# cerebro Claude Code plugin — memory-profile skill
+#
+# Retrieve the synthesized user profile (preferences, patterns, identity traits)
+# derived from stored memories. Mirrors plugins/opencode/src/tools.ts::memory_profile.
+#
+# Usage:
+#   bash memory-profile.sh
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [[ -z "$PLUGIN_ROOT" ]]; then
+  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)" || \
+    PLUGIN_ROOT="$(dirname "${BASH_SOURCE[0]:-$0}")/.."
+fi
+# shellcheck source=../hooks/common.sh
+source "${PLUGIN_ROOT}/hooks/common.sh"
+
+pp="$(detect_project_path || true)"
+
+# ─── Build URL-encoded path ──────────────────────────────────────────────────
+url_path="$(MEM_PP="$pp" python3 -c '
+import os, urllib.parse, sys
+pp = (os.environ.get("MEM_PP") or "").strip()
+path = "/v2/profile"
+if pp:
+    path += "?project_path=" + urllib.parse.quote(pp, safe="")
+sys.stdout.write(path)
+')"
+
+# ─── Fetch + format ──────────────────────────────────────────────────────────
+resp="$(omem_get "$url_path")"
+
+printf '%s' "$resp" | python3 -c '
+import sys, json
+raw = sys.stdin.read()
+try:
+    data = json.loads(raw)
+except Exception:
+    print("error: invalid JSON response from server")
+    sys.exit(0)
+if isinstance(data, dict) and data.get("error"):
+    print("error: " + str(data["error"]))
+    sys.exit(0)
+# Server may return either a bare PreferenceDto[] list or {preferences:[...]}.
+if isinstance(data, list):
+    prefs = data
+elif isinstance(data, dict):
+    prefs = data.get("preferences") or data.get("results") or []
+else:
+    prefs = []
+if not prefs:
+    print("no profile preferences")
+    sys.exit(0)
+for p in prefs:
+    if not isinstance(p, dict):
+        continue
+    slot = p.get("slot", "?")
+    val = p.get("value", "")
+    conf = p.get("confidence", 0)
+    scp = p.get("scope", "")
+    try:
+        line = "%s: %s (conf=%.2f, scope=%s)" % (slot, val, float(conf), scp)
+    except (TypeError, ValueError):
+        line = "%s: %s (conf=%s, scope=%s)" % (slot, val, conf, scp)
+    print(line)
+'

package/scripts/memory-save.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# cerebro Claude Code plugin — memory-save skill
+#
+# Persist a fact / decision / preference to long-term memory. Mirrors the
+# LLM-facing contract of plugins/opencode/src/tools.ts::memory_store.
+#
+# Usage:
+#   bash memory-save.sh --content "..." [--tags "t1,t2"] [--category X] \
+#                       [--visibility global|private] [--scope project|global]
+#   echo "..." | bash memory-save.sh            # content from stdin
+#
+# Category enum (lowercase): cases | preferences | entities | events | profile | patterns
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [[ -z "$PLUGIN_ROOT" ]]; then
+  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)" || \
+    PLUGIN_ROOT="$(dirname "${BASH_SOURCE[0]:-$0}")/.."
+fi
+# shellcheck source=../hooks/common.sh
+source "${PLUGIN_ROOT}/hooks/common.sh"
+
+# ─── Arg parsing ─────────────────────────────────────────────────────────────
+content=""
+tags_arg=""
+category=""
+visibility="global"
+scope="project"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --content)    content="${2:-}"; shift 2 ;;
+    --tags)       tags_arg="${2:-}"; shift 2 ;;
+    --category)   category="${2:-}"; shift 2 ;;
+    --visibility) visibility="${2:-}"; shift 2 ;;
+    --scope)      scope="${2:-}"; shift 2 ;;
+    --help|-h)
+      sed -n '2,15p' "${BASH_SOURCE[0]:-$0}" >&2; exit 0 ;;
+    --*)          echo "unknown option: $1" >&2; exit 2 ;;
+    *)            content="$1"; shift ;;
+  esac
+done
+
+# stdin fallback when no --content / positional given
+if [[ -z "$content" && ! -t 0 ]]; then
+  content="$(cat || true)"
+fi
+
+if [[ -z "$content" ]]; then
+  echo 'usage: memory-save.sh --content "..." [--tags t1,t2] [--category X] [--visibility global|private] [--scope project|global]' >&2
+  exit 1
+fi
+
+# Basic enum validation (fail fast with a friendly message, do not crash harder).
+case "$visibility" in
+  global|private) : ;;
+  *) echo "error: --visibility must be 'global' or 'private' (got: $visibility)" >&2; exit 2 ;;
+esac
+case "$scope" in
+  project|global) : ;;
+  *) echo "error: --scope must be 'project' or 'global' (got: $scope)" >&2; exit 2 ;;
+esac
+if [[ -n "$category" ]]; then
+  case "$category" in
+    cases|preferences|entities|events|profile|patterns) : ;;
+    *) echo "error: --category must be one of cases|preferences|entities|events|profile|patterns (got: $category)" >&2; exit 2 ;;
+  esac
+fi
+
+# ─── Sanitize + assemble tags + project_path ─────────────────────────────────
+content="$(printf '%s' "$content" | sanitize_content)"
+container="$(container_tags || true)"
+pp="$(detect_project_path || true)"
+
+# ─── Build JSON body via python3 ─────────────────────────────────────────────
+body="$(MEM_CONTENT="$content" MEM_CONTAINER="$container" MEM_TAGS="$tags_arg" \
+        MEM_CAT="$category" MEM_VIS="$visibility" MEM_SCOPE="$scope" MEM_PP="$pp" \
+        python3 -c '
+import os, json, sys
+content = os.environ["MEM_CONTENT"]
+container = (os.environ.get("MEM_CONTAINER") or "").split()
+user_tags = [t.strip() for t in (os.environ.get("MEM_TAGS") or "").split(",") if t.strip()]
+tags = container + user_tags
+body = {
+    "content": content,
+    "tags": tags,
+    "source": "claude-code",
+    "scope": os.environ.get("MEM_SCOPE") or "project",
+    "agent_id": "cerebro",
+    "visibility": os.environ.get("MEM_VIS") or "global",
+}
+pp = (os.environ.get("MEM_PP") or "").strip()
+if pp:
+    body["project_path"] = pp
+cat = (os.environ.get("MEM_CAT") or "").strip()
+if cat:
+    body["category"] = cat
+sys.stdout.write(json.dumps(body, ensure_ascii=False))
+')"
+
+# ─── POST + format response ──────────────────────────────────────────────────
+resp="$(omem_post "/v1/memories" "$body")"
+
+printf '%s' "$resp" | python3 -c '
+import sys, json
+raw = sys.stdin.read()
+try:
+    data = json.loads(raw)
+except Exception:
+    print("error: invalid JSON response from server")
+    sys.exit(0)
+if isinstance(data, dict) and data.get("error"):
+    print("error: " + str(data["error"]))
+    sys.exit(0)
+if not isinstance(data, dict):
+    print("ok")
+    sys.exit(0)
+mid = data.get("id")
+extra = ""
+tags = data.get("tags") or []
+if isinstance(tags, list) and tags:
+    extra = " tags=" + ",".join(str(t) for t in tags)
+if mid is not None:
+    print("ok id=" + str(mid) + extra)
+else:
+    print("ok" + extra)
+'

package/scripts/memory-search.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# cerebro Claude Code plugin — memory-search skill
+#
+# Semantic search over long-term memory. Mirrors the LLM-facing contract of
+# plugins/opencode/src/tools.ts::memory_search but shells out via common.sh.
+#
+# Usage:
+#   bash memory-search.sh "QUERY" [LIMIT]
+#   echo "auth flow" | bash memory-search.sh - [LIMIT]
+set -euo pipefail
+
+# Locate plugin root (CLAUDE_PLUGIN_ROOT when invoked by Claude Code; otherwise
+# derive from this script's location: scripts/foo.sh -> .. = plugin root).
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [[ -z "$PLUGIN_ROOT" ]]; then
+  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)" || \
+    PLUGIN_ROOT="$(dirname "${BASH_SOURCE[0]:-$0}")/.."
+fi
+# shellcheck source=../hooks/common.sh
+source "${PLUGIN_ROOT}/hooks/common.sh"
+
+# ─── Args ────────────────────────────────────────────────────────────────────
+query="${1:-}"
+limit="${2:-${MEM_SEARCH_COUNT:-8}}"
+
+# Allow `echo "q" | memory-search.sh - [LIMIT]` for stdin-driven queries.
+if [[ "$query" == "-" || (-z "$query" && ! -t 0) ]]; then
+  query=$(cat || true)
+fi
+
+if [[ -z "$query" ]]; then
+  echo "usage: memory-search.sh \"QUERY\" [LIMIT]" >&2
+  exit 1
+fi
+
+query="$(truncate_query "$query")"
+tags="$(container_tags || true)"
+pp="$(detect_project_path || true)"
+
+# ─── Build URL-encoded GET path via python3 (avoid bash quoting traps) ───────
+url_path="$(MEM_Q="$query" MEM_TAGS="$tags" MEM_PP="$pp" MEM_LIMIT="$limit" python3 -c '
+import os, urllib.parse, sys
+q = os.environ.get("MEM_Q", "")
+limit = os.environ.get("MEM_LIMIT", "8")
+parts = [
+    "q=" + urllib.parse.quote(q, safe=""),
+    "limit=" + urllib.parse.quote(str(limit), safe=""),
+]
+tags_raw = (os.environ.get("MEM_TAGS") or "").strip()
+if tags_raw:
+    comma = ",".join(t for t in tags_raw.split() if t)
+    if comma:
+        # comma is reserved-safe in query per RFC 3986; keep literal
+        parts.append("tags=" + ",".join(urllib.parse.quote(t, safe="") for t in comma.split(",")))
+pp = (os.environ.get("MEM_PP") or "").strip()
+if pp:
+    parts.append("project_path=" + urllib.parse.quote(pp, safe=""))
+sys.stdout.write("/v1/memories/search?" + "&".join(parts))
+')"
+
+# ─── Fetch + format ──────────────────────────────────────────────────────────
+resp="$(omem_get "$url_path")"
+
+printf '%s' "$resp" | python3 -c '
+import sys, json
+raw = sys.stdin.read()
+try:
+    data = json.loads(raw)
+except Exception:
+    print("error: invalid JSON response from server")
+    sys.exit(0)
+if isinstance(data, dict) and data.get("error"):
+    print("error: " + str(data["error"]))
+    sys.exit(0)
+results = data.get("results", []) if isinstance(data, dict) else []
+if not results:
+    print("no memories")
+    sys.exit(0)
+for r in results:
+    if not isinstance(r, dict):
+        continue
+    m = r.get("memory") or {}
+    if not isinstance(m, dict):
+        m = {}
+    score = r.get("score", 0.0)
+    mid = m.get("id", "?")
+    content = (m.get("content") or "")
+    snippet = content[:200]
+    try:
+        line = "[%.2f] %s: %s" % (float(score), mid, snippet)
+    except (TypeError, ValueError):
+        line = "[%s] %s: %s" % (score, mid, snippet)
+    print(line)
+'

package/scripts/web-server.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// cerebro web-server — CC 插件独立进程（移植自 plugins/opencode/src/web-server.ts）
+// 由 session-start.sh 经 setsid detach 拉起，多 CC session 共享端口 5212。
+// 与 opencode 版的区别：去掉 takeover 定时器（SessionStart probe 已够），纯静态 serve。
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeFileSync, unlinkSync } from "node:fs";
+
+const PID_FILE = path.join(process.env.HOME || process.env.USERPROFILE || "", ".config/cerebro/web-server.pid");
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = parseInt(process.env.OMEM_LOCAL_PORT || "", 10) || 5212;
+const API_URL = process.env.OMEM_API_URL || "https://www.mengxy.cc";
+
+// web 目录查找：env > 本地 web/ > 兄弟 opencode/web/
+function findWebDir() {
+  const candidates = [
+    process.env.CEREBRO_WEB_DIR,
+    path.resolve(__dirname, "../web"),
+    path.resolve(__dirname, "../../opencode/web"),
+  ].filter(Boolean);
+  for (const d of candidates) {
+    if (fs.existsSync(path.join(d, "index.html"))) return d;
+  }
+  return null;
+}
+
+const WEB_DIR = findWebDir();
+if (!WEB_DIR) {
+  console.error("[cerebro web-server] no web directory found, exiting");
+  process.exit(0); // exit 0 — not an error, just nothing to serve
+}
+
+const COMMON = { "X-Content-Type-Options": "nosniff" };
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".webp": "image/webp",
+  ".map": "application/json",
+};
+
+function resolveSafe(baseDir, pathname) {
+  const rel = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+  const resolved = path.resolve(baseDir, rel || ".");
+  if (!resolved.startsWith(baseDir + path.sep) && resolved !== baseDir) return null;
+  return resolved;
+}
+
+function serveFile(res, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(500, { ...COMMON, "Content-Type": "text/plain" });
+      res.end("Internal Server Error");
+      return;
+    }
+    let body = data;
+    if (ext === ".html" && data.includes("__OMEM_API_URL__")) {
+      body = data.toString("utf-8").replace(
+        /window\.__OMEM_API_URL__\s*=\s*["']__OMEM_API_URL__["']/,
+        `window.__OMEM_API_URL__ = ${JSON.stringify(API_URL)}`,
+      );
+    }
+    res.writeHead(200, {
+      ...COMMON,
+      "Content-Type": MIME[ext] || "application/octet-stream",
+      "Cache-Control": ext === ".html" ? "no-cache, no-store, must-revalidate" : "public, max-age=86400",
+    });
+    res.end(body);
+  });
+}
+
+const indexPath = path.join(WEB_DIR, "index.html");
+const server = http.createServer((req, res) => {
+  if (req.url === "/health" || req.url === "/health/") {
+    res.writeHead(200, { ...COMMON, "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", service: "cerebro", port: PORT }));
+    return;
+  }
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.writeHead(405, { ...COMMON, "Content-Type": "text/plain" });
+    res.end("Method Not Allowed");
+    return;
+  }
+  const url = new URL(req.url || "/", `http://localhost:${PORT}`);
+  const safePath = resolveSafe(WEB_DIR, url.pathname);
+  if (!safePath) {
+    res.writeHead(403, { ...COMMON, "Content-Type": "text/plain" });
+    res.end("Forbidden");
+    return;
+  }
+  fs.stat(safePath, (statErr, stats) => {
+    if (!statErr && stats.isFile()) { serveFile(res, safePath); return; }
+    fs.stat(indexPath, (idxErr, idxStats) => {
+      if (idxErr || !idxStats.isFile()) {
+        res.writeHead(404, { ...COMMON, "Content-Type": "text/plain" });
+        res.end("Not Found");
+        return;
+      }
+      serveFile(res, indexPath);
+    });
+  });
+});
+
+server.on("error", (err) => {
+  if (err.code === "EADDRINUSE") {
+    // 另一个 CC session / opencode 已占端口 — 正常，静默退出
+    process.exit(0);
+  }
+  console.error(`[cerebro web-server] error: ${err.message}`);
+  process.exit(1);
+});
+
+server.listen(PORT, "127.0.0.1", () => {
+  try { writeFileSync(PID_FILE, String(process.pid)); } catch {}
+  console.log(`[cerebro web-server] serving ${WEB_DIR} at http://localhost:${PORT} (pid=${process.pid})`);
+});
+
+process.on("SIGTERM", () => server.close(() => { try { unlinkSync(PID_FILE); } catch {} process.exit(0); }));
+process.on("SIGINT", () => server.close(() => { try { unlinkSync(PID_FILE); } catch {} process.exit(0); }));

package/skills/memory-profile/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: memory-profile
+description: Retrieve the synthesized user profile (preferences, patterns, identity traits) induced from stored memories. Use at session start to ground yourself in the user's working style, tooling preferences, recurring workflows, and role context; or whenever adapting tone, format, or approach to match the user's established patterns would improve the interaction.
+---
+
+# Memory Profile
+
+Read the induced preference profile for the current user/project. Each preference is a `{slot, value, confidence, scope}` tuple synthesized from raw memories.
+
+## When to use
+
+- Session bootstrap — load working-style context before doing work
+- User asks "what do you know about me / my preferences / how I work"
+- Adapting response format, tone, or tooling to the user's established patterns
+- Checking whether a candidate action aligns with stored preferences
+
+## How to run
+
+```bash
+bash "$CLAUDE_PLUGIN_ROOT/scripts/memory-profile.sh"
+```
+
+No arguments. `project_path` is auto-detected from git toplevel and forwarded to the server.
+
+## Output format
+
+One line per preference:
+
+```
+preferred_language: rust (conf=0.92, scope=global)
+review_style: terse, no praise (conf=0.85, scope=project)
+indent_style: 2-space (conf=0.78, scope=global)
+```
+
+`no profile preferences` when the profile is empty. `error: …` on transport/server failure.
+
+## Notes
+
+- Confidence (`conf`) is the induction strength — treat values below ~0.5 as weak signals.
+- `scope=global` preferences apply across projects; `scope=project` only to the current one.
+- Profile is read-only here. To influence it, save memories via `memory-save` with `category=preferences` or `category=profile`; the server's induction pipeline will fold them in.

package/skills/memory-save/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: memory-save
+description: Persist a fact, decision, or preference to the user's long-term memory (Cerebro). Use when the user explicitly says "remember / save / store / don't forget / note this", or when you identify important information worth preserving across sessions — preferences, coding style, architecture decisions, bug fixes, project entities, milestones, workflows, or user identity traits. Each memory must be atomic (one fact), self-contained, and precise. Private secrets/credentials/personal data MUST use visibility=private; cross-project knowledge uses scope=global.
+---
+
+# Memory Save
+
+Store one atomic, self-contained memory. Before calling, decide:
+1. **category** — which of the 6 buckets does this belong to?
+2. **scope** — project-specific or cross-project?
+3. **visibility** — does it contain sensitive data?
+4. **tags** — at least one descriptive snake_case tag.
+
+## Category enum (lowercase, exact)
+
+| Value | Use for |
+|-------|---------|
+| `cases` (default) | Work records, bug fixes, architecture decisions, troubleshooting notes |
+| `preferences` | User likes/dislikes, coding style, tool choices, review habits |
+| `entities` | Projects, tools, libraries, people, concepts worth remembering |
+| `events` | Time-bound milestones — deployments, releases, incidents, deadlines |
+| `profile` | User identity traits — role, skills, team membership, timezone |
+| `patterns` | Workflows, methodologies, recurring best practices |
+
+## Visibility
+
+- `global` (default) — all agents can see and recall. Correct for normal work notes.
+- `private` — ONLY the current agent sees it. **MUST use for**: passwords, API keys, tokens, DB credentials, SSH keys, personal info (phone/email/address), internal company details, or anything the user would not want other agents to access. When in doubt, ask the user.
+
+## Scope
+
+- `project` (default) — visible only in this project's context (auto `project_path`).
+- `global` — visible across all projects. Use for user preferences, general knowledge, cross-project patterns.
+
+## How to run
+
+```bash
+bash "$CLAUDE_PLUGIN_ROOT/scripts/memory-save.sh" \
+  --content "Fixed memory_type validation bug in memory.rs:1480 — LLM returned illegal 'pinned' value, added match guard normalizing to WORK/EMOTIONAL fallback" \
+  --tags "rust_backend,memory_system,bug_fix" \
+  --category cases \
+  --scope project \
+  --visibility global
+```
+
+Content can also be piped:
+
+```bash
+echo "user prefers terse caveman-style replies" | \
+  bash "$CLAUDE_PLUGIN_ROOT/scripts/memory-save.sh" --tags "communication,style" --category preferences --scope global
+```
+
+## Writing good content
+
+- BAD: "fixed some bugs"
+- GOOD: "Fixed refresh-token rotation bug in auth.rs:230 — replay window allowed token reuse; added nonce cache with 60s TTL."
+- BAD: "user likes stuff"
+- GOOD: "User prefers dark IDE theme, 2-space indent for Rust, tabs for Go."
+
+## Output
+
+- Success: `ok id=mem_abc123 tags=omem_user_xxx,rust_backend`
+- Failure: `error: <reason>`
+
+## Notes
+
+- Content is sanitized (XML tags stripped, whitespace collapsed, truncated to `$MEM_MAX_CONTENT`).
+- Container tags (`omem_user_<hash>`, `omem_project_<hash>`) are auto-prepended.
+- `project_path` is auto-detected from git toplevel.
+- `source` is hardcoded to `claude-code`, `agent_id` to `cerebro`.