@remnic/plugin-claude-code 1.0.0 → 9.3.515

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "remnic",
   "description": "Universal memory for AI agents — automatic recall, observation, and cross-agent knowledge sharing",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "author": "Joshua Warren",
   "homepage": "https://github.com/joshuaswarren/remnic",
   "repository": "https://github.com/joshuaswarren/remnic"

package/README.md

@@ -0,0 +1,90 @@
+# @remnic/plugin-claude-code
+
+Native [Claude Code](https://docs.claude.com/en/docs/claude-code) plugin for [Remnic](https://github.com/joshuaswarren/remnic) memory. Wires Claude Code's session hooks, MCP server, skills, and the `memory-review` agent into a running Remnic daemon so every Claude Code session gets persistent long-term memory automatically.
+
+## Install
+
+Three discrete steps. None is automated for you end-to-end today; each writes to a different place.
+
+1. **Mint a Remnic-side bearer token and record the connector.**
+
+    ```bash
+    remnic connectors install claude-code
+    ```
+
+    This writes `~/.remnic/connectors/claude-code.json` (Remnic's connector-state file) and stores a bearer token in Remnic's token store. It does NOT touch any Claude Code configuration — the Claude Code memory-extension publisher in `@remnic/core` is a stub (`isHostAvailable()` → false, `publish()` → no-op), so no hook/skill/agent files are written and no Claude MCP config is edited.
+
+2. **Add Remnic as an MCP server in your Claude Code config.** Paste the `.mcp.json` block from the "MCP setup" section below into Claude Code's MCP config (commonly `~/.mcp.json` or `~/.claude.json`, per your Claude install), replacing `{{REMNIC_TOKEN}}` with the token minted in step 1. Without this step Claude Code has no way to talk to the Remnic daemon.
+
+3. **Install this package and load it through Claude Code's plugin system** so the hook scripts, skills, and `memory-review` agent are actually active:
+
+    ```bash
+    npm install -g @remnic/plugin-claude-code
+    ```
+
+    Consult Claude Code's plugin docs for the exact load mechanism your install supports (plugin marketplace / symlink / etc.). Until this step runs, auto-recall and auto-observe don't fire even if step 2 is correct.
+
+## What ships
+
+The package is **data-only** (no JavaScript runtime) — it's a bundle of Claude Code configuration:
+
+| File / dir | Purpose |
+|---|---|
+| `.claude-plugin/plugin.json` | Plugin manifest |
+| `hooks/hooks.json` | `SessionStart`, `PostToolUse` (Write/Edit/MultiEdit), and `UserPromptSubmit` hook wiring |
+| `hooks/bin/*.sh` | Small shell scripts that call the local Remnic daemon |
+| `skills/` | `remnic-recall`, `remnic-remember`, `remnic-search`, `remnic-status`, `remnic-entities`, `remnic-memory-workflow` |
+| `agents/memory-review.md` | Subagent that audits + summarizes memory for long-running sessions |
+| `.mcp.json` | MCP server config pointing Claude Code at `http://localhost:4318/mcp` |
+| `settings.json` | Default Claude Code settings for the plugin |
+
+## What you get at runtime
+
+Once installed and a Remnic daemon is running (`remnic daemon start`):
+
+- **Auto-recall** on `SessionStart` and on every `UserPromptSubmit` — relevant memories are injected into the session prompt before Claude Code's first turn and before each subsequent user turn.
+- **Auto-observe** on `PostToolUse` for `Write`, `Edit`, and `MultiEdit` tools — new facts, decisions, and entities touched by file edits are buffered for extraction without the user lifting a finger.
+- **Memory skills** — invoke `/remnic-recall`, `/remnic-search`, `/remnic-remember`, `/remnic-entities`, `/remnic-status` directly in Claude Code chats.
+- **Cross-agent sharing** — the same memory store is shared with every other Remnic-connected agent (Codex, OpenClaw, Replit, Hermes, etc.), so what one agent learns is available to all.
+
+## MCP setup
+
+The plugin expects a Remnic daemon reachable at `http://localhost:4318/mcp` with a bearer token. `remnic connectors install claude-code` does NOT write this for you — the Claude Code publisher in `@remnic/core` is a stub, so no Claude MCP config is touched. You must paste the following `.mcp.json` block into Claude Code's MCP config by hand (step 2 of the Install flow above):
+
+```json
+{
+  "mcpServers": {
+    "remnic": {
+      "type": "http",
+      "url": "http://localhost:4318/mcp",
+      "headers": {
+        "Authorization": "Bearer {{REMNIC_TOKEN}}",
+        "X-Engram-Client-Id": "claude-code"
+      }
+    }
+  }
+}
+```
+
+Replace `{{REMNIC_TOKEN}}` with a token minted via `remnic token generate <connector-id>`.
+
+## Agent note
+
+If you're an AI agent scaffolding a Claude Code integration: **do not** hand-edit hook scripts in a user's `~/.claude/` tree. The full setup has two components:
+
+1. `remnic connectors install claude-code` mints the MCP token and writes Remnic-side connector config. This does NOT deploy hooks/skills/agents — Claude Code doesn't yet expose a file-based extension directory, so the corresponding publisher in `@remnic/core` is a stub.
+2. Install this npm package and load it through Claude Code's plugin system so the hook/skill/agent tree is picked up. Until both steps run, auto-recall and auto-observe will not fire even though `remnic connectors doctor claude-code` reports green.
+
+The plugin is intentionally data-only so Claude Code's plugin loader can manage upgrades atomically.
+
+## Related
+
+- [`@remnic/cli`](https://www.npmjs.com/package/@remnic/cli) — daemon lifecycle + installer
+- [`@remnic/plugin-codex`](https://www.npmjs.com/package/@remnic/plugin-codex) — same idea, for OpenAI Codex CLI
+- [`@remnic/plugin-openclaw`](https://www.npmjs.com/package/@remnic/plugin-openclaw) — OpenClaw memory-slot plugin
+- Connector guide: [docs/integration/connector-setup.md](https://github.com/joshuaswarren/remnic/blob/main/docs/integration/connector-setup.md) in the repo
+- Source + issues: <https://github.com/joshuaswarren/remnic>
+
+## License
+
+MIT. See the root [LICENSE](https://github.com/joshuaswarren/remnic/blob/main/LICENSE) file.

package/hooks/bin/session-start.sh

@@ -56,7 +56,87 @@ SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write
 CWD="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.cwd||'')" "$INPUT" 2>/dev/null || echo "")"
 PROJECT_NAME="$(basename "$CWD" 2>/dev/null || echo "unknown")"
 
-log "session=$SESSION_ID project=$PROJECT_NAME"
+# Resolve git context for the session's cwd (issue #569 PR 5). Produces
+# either a JSON object for the `codingContext` field, or an empty string
+# when the cwd is not inside a git repo. All git calls are wrapped in &&
+# so any failure silently drops back to no-context.
+CODING_CONTEXT_JSON=""
+if [ -n "$CWD" ] && [ -d "$CWD" ] && command -v git >/dev/null 2>&1; then
+  # `git` calls are short-timeout and local. Any failure → empty.
+  REMNIC_GIT_TOP="$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null || echo "")"
+  if [ -n "$REMNIC_GIT_TOP" ]; then
+    REMNIC_GIT_BRANCH="$(git -C "$REMNIC_GIT_TOP" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")"
+    [ "$REMNIC_GIT_BRANCH" = "HEAD" ] && REMNIC_GIT_BRANCH=""
+    REMNIC_GIT_ORIGIN="$(git -C "$REMNIC_GIT_TOP" remote get-url origin 2>/dev/null || echo "")"
+    REMNIC_GIT_DEFAULT_BRANCH="$(git -C "$REMNIC_GIT_TOP" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||' || echo "")"
+    CODING_CONTEXT_JSON="$(REMNIC_GIT_TOP="$REMNIC_GIT_TOP" REMNIC_GIT_BRANCH="$REMNIC_GIT_BRANCH" REMNIC_GIT_ORIGIN="$REMNIC_GIT_ORIGIN" REMNIC_GIT_DEFAULT_BRANCH="$REMNIC_GIT_DEFAULT_BRANCH" node -e "
+      // Mirror the pure logic from @remnic/core's resolveGitContext so the
+      // hook produces the same projectId without calling into the daemon
+      // first. FNV-1a 32-bit stable hash.
+      const rootPath = process.env.REMNIC_GIT_TOP || '';
+      const branch = process.env.REMNIC_GIT_BRANCH || null;
+      const origin = process.env.REMNIC_GIT_ORIGIN || '';
+      const defaultBranch = process.env.REMNIC_GIT_DEFAULT_BRANCH || null;
+      function stableHash(input) {
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < input.length; i++) {
+          hash ^= input.charCodeAt(i);
+          hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+        return hash.toString(16).padStart(8, '0');
+      }
+      // Mirrors packages/remnic-core/src/coding/git-context.ts
+      // normalizeOriginUrl. Keep the two in sync so the hook-computed
+      // projectId matches what the daemon computes on the same origin.
+      function normalizeOriginUrl(raw) {
+        let u = (raw || '').trim();
+        if (!u) return '';
+        // Case-insensitive .git strip — matches the TS canonical form.
+        if (/\\.git\$/i.test(u)) u = u.slice(0, -4);
+        // Windows drive-letter: short-circuit scp parsing.
+        if (/^[A-Za-z]:[\\\\/]/.test(u)) return u.toLowerCase();
+        // Protocol form: handles ssh://, https://, file:///, bracketed
+        // IPv6 hosts, optional user, optional port, and empty host
+        // (file:///path).
+        const proto = /^[a-z][a-z0-9+.-]*:\\/\\/(?:[^@/]+@)?(\\[[^\\]]+\\]|[^/:]*)(?::(\\d+))?(\\/.*)?\$/i.exec(u);
+        if (proto) {
+          let host = proto[1] || '';
+          const wasBracketed = host.startsWith('[') && host.endsWith(']');
+          if (wasBracketed) host = host.slice(1, -1);
+          const port = proto[2];
+          const p = (proto[3] || '').replace(/^\\/+/, '');
+          const hostPort = port
+            ? (wasBracketed ? '[' + host + ']:' + port : host + ':' + port)
+            : host;
+          const prefix = hostPort.length > 0 ? hostPort : 'localhost';
+          return (prefix + '/' + p).toLowerCase();
+        }
+        // scp form: [user@]host:path — user@ optional, bracketed IPv6 host
+        // supported. A matched path starting with // is a protocol-URL
+        // leftover and is rejected.
+        const scp = /^(?:([^@\\s\\/]+)@)?(\\[[^\\]]+\\]|[^:@\\s\\/]+):(.+)\$/.exec(u);
+        if (scp) {
+          let host = scp[2] || '';
+          if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+          const p = scp[3] || '';
+          if (p.startsWith('//')) return u.toLowerCase();
+          return (host + '/' + p.replace(/^\\/+/, '')).toLowerCase();
+        }
+        return u.toLowerCase();
+      }
+      const normalized = normalizeOriginUrl(origin);
+      const projectId = normalized ? 'origin:' + stableHash(normalized) : 'root:' + stableHash(rootPath);
+      process.stdout.write(JSON.stringify({
+        projectId,
+        branch: branch || null,
+        rootPath,
+        defaultBranch: defaultBranch || null,
+      }));
+    " 2>/dev/null || echo "")"
+  fi
+fi
+
+log "session=$SESSION_ID project=$PROJECT_NAME coding-context=${CODING_CONTEXT_JSON:+yes}"
 
 # Health check — start daemon if not running
 if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
@@ -82,12 +162,29 @@ fi
 
 QUERY="Starting a new coding session in project: ${PROJECT_NAME}. Recall relevant memories, preferences, decisions, patterns, and context about this project and the user."
 
-REQUEST_BODY="$(node -e "process.stdout.write(JSON.stringify({
-  query: process.argv[1],
-  sessionKey: process.argv[2],
-  topK: 12,
-  mode: 'auto'
-}))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+REQUEST_BODY="$(REMNIC_CODING_CONTEXT_JSON="$CODING_CONTEXT_JSON" node -e "
+  const body = {
+    query: process.argv[1],
+    sessionKey: process.argv[2],
+    topK: 12,
+    mode: 'auto',
+  };
+  const raw = process.env.REMNIC_CODING_CONTEXT_JSON || '';
+  if (raw) {
+    try { body.codingContext = JSON.parse(raw); } catch (_) {
+      // Context envelope was provided but failed to parse. Explicitly
+      // clear any previously-attached context for this session so a
+      // malformed envelope does not silently keep stale state.
+      body.codingContext = null;
+    }
+  } else {
+    // No git context resolvable for this cwd. Explicitly clear any
+    // previously-attached context so a session that moves out of a repo
+    // does not keep routing to the old project namespace.
+    body.codingContext = null;
+  }
+  process.stdout.write(JSON.stringify(body));
+" "$QUERY" "$SESSION_ID" 2>/dev/null)"
 
 [ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
 
@@ -104,12 +201,19 @@ RESPONSE="$(echo "$RAW" | sed '$d')"
 
 if [ $CURL_EXIT -ne 0 ] || ! [[ "$HTTP_STATUS" =~ ^2 ]] || [ -z "$RESPONSE" ]; then
   log "full recall failed (curl=$CURL_EXIT http=$HTTP_STATUS) — falling back to minimal"
-  MINIMAL_BODY="$(node -e "process.stdout.write(JSON.stringify({
-    query: process.argv[1],
-    sessionKey: process.argv[2],
-    topK: 8,
-    mode: 'minimal'
-  }))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+  MINIMAL_BODY="$(REMNIC_CODING_CONTEXT_JSON="$CODING_CONTEXT_JSON" node -e "
+    const body = {
+      query: process.argv[1],
+      sessionKey: process.argv[2],
+      topK: 8,
+      mode: 'minimal',
+    };
+    const raw = process.env.REMNIC_CODING_CONTEXT_JSON || '';
+    if (raw) {
+      try { body.codingContext = JSON.parse(raw); } catch (_) { /* ignore */ }
+    }
+    process.stdout.write(JSON.stringify(body));
+  " "$QUERY" "$SESSION_ID" 2>/dev/null)"
   RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
     -X POST "$REMNIC_URL" \
     -H "Authorization: Bearer ${REMNIC_TOKEN}" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/plugin-claude-code",
-  "version": "1.0.0",
+  "version": "9.3.515",
   "description": "Remnic memory plugin for Claude Code — hooks, skills, MCP integration",
   "type": "module",
   "license": "MIT",