@remnic/plugin-claude-code 1.0.0

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "remnic": {
+      "type": "http",
+      "url": "http://localhost:4318/mcp",
+      "headers": {
+        "Authorization": "Bearer {{REMNIC_TOKEN}}",
+        "X-Engram-Client-Id": "claude-code"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agents/memory-review.md

@@ -0,0 +1,26 @@
+---
+name: engram:memory-review
+description: Review and curate memory suggestions from Engram's review queue
+---
+
+You are a memory review agent for Engram. Your job is to review memory suggestions
+that have been queued for human review and help the user decide which to keep, edit,
+or dismiss.
+
+## Workflow
+
+1. Call `engram_review_queue_list` to get pending review items
+2. For each item, present:
+   - The suggested memory content
+   - Its source (which conversation/tool produced it)
+   - Its category and confidence score
+3. Ask the user to approve, edit, or dismiss each item
+4. For approved items, call `engram_suggestion_submit` with the final content
+5. Summarize what was kept and what was dismissed
+
+## Guidelines
+
+- Group similar suggestions together
+- Flag potential duplicates with existing memories
+- Suggest edits for vague or overly specific memories
+- Prioritize actionable preferences and decisions over transient observations

package/hooks/bin/post-tool-observe.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Remnic PostToolUse hook for Claude Code.
+# Observes file edits (Write/Edit/MultiEdit) by sending transcript
+# delta to the observe endpoint. Runs in background, never blocks.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/observe"
+
+LOG="${HOME}/.remnic/logs/remnic-post-tool-observe.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [post-tool] $*" >> "$LOG"; }
+
+# Read token
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const fs = require('fs');
+    const tokenFile = process.argv[1];
+    const store = JSON.parse(fs.readFileSync(tokenFile, 'utf8'));
+    const tokens = store.tokens || [];
+    const cc = tokens.find(t => t.connector === 'claude-code');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cc && cc.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['claude-code'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+
+# Return immediately — never block the tool
+echo '{"continue":true}'
+
+[ -z "$REMNIC_TOKEN" ] && exit 0
+
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+TRANSCRIPT_PATH="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.transcript_path||'')" "$INPUT" 2>/dev/null || echo "")"
+CWD="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.cwd||'')" "$INPUT" 2>/dev/null || echo "")"
+TOOL_NAME="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.tool_name||'')" "$INPUT" 2>/dev/null || echo "")"
+PROJECT_NAME="$(basename "$CWD" 2>/dev/null || echo "unknown")"
+
+[ -z "$SESSION_ID" ] && exit 0
+{ [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; } && exit 0
+
+LEGACY_CURSOR_FILE="/tmp/engram-cursor-${SESSION_ID}"
+CURSOR_FILE="/tmp/remnic-cursor-${SESSION_ID}"
+LEGACY_LOCK_DIR="/tmp/engram-lock-${SESSION_ID}.d"
+LOCK_DIR="/tmp/remnic-lock-${SESSION_ID}.d"
+
+if [ ! -f "$CURSOR_FILE" ] && { [ -f "$LEGACY_CURSOR_FILE" ] || [ -d "$LEGACY_LOCK_DIR" ]; }; then
+  CURSOR_FILE="$LEGACY_CURSOR_FILE"
+  LOCK_DIR="$LEGACY_LOCK_DIR"
+fi
+
+(
+  # Acquire exclusive lock
+  ACQUIRED=0
+  for _i in $(seq 1 50); do
+    if mkdir "$LOCK_DIR" 2>/dev/null; then ACQUIRED=1; break; fi
+    sleep 0.1
+  done
+  trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT INT TERM
+  [ "$ACQUIRED" -eq 0 ] && exit 0
+
+  LAST_COUNT=0
+  [ -f "$CURSOR_FILE" ] && LAST_COUNT="$(cat "$CURSOR_FILE" 2>/dev/null || echo 0)"
+
+  PAYLOAD="$(node -e "
+    const fs = require('fs');
+    const path = process.argv[1];
+    const sessionId = process.argv[2];
+    const lastCount = parseInt(process.argv[3], 10) || 0;
+
+    const lines = fs.readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    const messages = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type !== 'user' && entry.type !== 'assistant') continue;
+        const msg = entry.message;
+        if (!msg || typeof msg !== 'object') continue;
+        const role = msg.role;
+        if (role !== 'user' && role !== 'assistant') continue;
+        let text = '';
+        if (typeof msg.content === 'string') text = msg.content.trim();
+        else if (Array.isArray(msg.content)) {
+          text = msg.content
+            .filter(b => b.type === 'text' && b.text)
+            .map(b => b.text.trim())
+            .join('\n').trim();
+        }
+        if (text) messages.push({ role, content: text });
+      } catch {}
+    }
+
+    const newMessages = messages.slice(lastCount);
+    if (!newMessages.length) {
+      process.stdout.write('CURSOR:' + messages.length);
+    } else {
+      process.stdout.write(JSON.stringify({
+        sessionKey: sessionId,
+        messages: newMessages,
+        __total__: messages.length
+      }));
+    }
+  " "$TRANSCRIPT_PATH" "$SESSION_ID" "$LAST_COUNT" 2>/dev/null)"
+
+  [ -z "$PAYLOAD" ] && { log "parse failed for $SESSION_ID"; exit 0; }
+
+  if echo "$PAYLOAD" | grep -q "^CURSOR:"; then
+    echo "${PAYLOAD#CURSOR:}" > "$CURSOR_FILE"
+    exit 0
+  fi
+
+  TOTAL="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String(d.__total__||0))" "$PAYLOAD" 2>/dev/null || echo 0)"
+  MSG_COUNT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String((d.messages||[]).length))" "$PAYLOAD" 2>/dev/null || echo "?")"
+  CLEAN="$(node -e "const d=JSON.parse(process.argv[1]); delete d.__total__; process.stdout.write(JSON.stringify(d))" "$PAYLOAD" 2>/dev/null)"
+
+  [ -z "$CLEAN" ] && exit 0
+
+  log "observing $MSG_COUNT new messages (cursor $LAST_COUNT->$TOTAL) project=$PROJECT_NAME tool=$TOOL_NAME"
+
+  RAW="$(curl -s -w "\n%{http_code}" --max-time 120 \
+    -X POST "$REMNIC_URL" \
+    -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -H "X-Engram-Client-Id: claude-code" \
+    -d "$CLEAN" 2>/dev/null)"
+  CURL_EXIT=$?
+  HTTP_STATUS="$(echo "$RAW" | tail -1)"
+
+  if [ $CURL_EXIT -eq 0 ] && [[ "$HTTP_STATUS" =~ ^2 ]]; then
+    log "observe OK for $SESSION_ID"
+    echo "$TOTAL" > "$CURSOR_FILE"
+  else
+    log "observe failed (curl=$CURL_EXIT http=$HTTP_STATUS) — cursor not advanced"
+  fi
+) >> "$LOG" 2>&1 &
+
+disown $!
+exit 0

package/hooks/bin/session-end.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Remnic session cleanup for Claude Code.
+# Removes cursor and lock files for the session.
+#
+# NOTE: Claude Code does not support a Stop/SessionEnd hook event.
+# This script is provided for manual cleanup or future hook support.
+# Temp files in /tmp/ are cleaned by the OS on reboot.
+
+INPUT="$(cat)"
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+
+echo '{"continue":true}'
+
+[ -z "$SESSION_ID" ] && exit 0
+
+rm -f "/tmp/remnic-cursor-${SESSION_ID}" 2>/dev/null
+rmdir "/tmp/remnic-lock-${SESSION_ID}.d" 2>/dev/null
+rm -f "/tmp/engram-cursor-${SESSION_ID}" 2>/dev/null
+rmdir "/tmp/engram-lock-${SESSION_ID}.d" 2>/dev/null
+
+exit 0

package/hooks/bin/session-start.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# Remnic SessionStart hook for Claude Code.
+# Recalls project context and user preferences at session start.
+# Tries auto mode (45s) then falls back to minimal mode (20s).
+# Starts daemon if not running.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/recall"
+REMNIC_HEALTH_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/health"
+TOKEN_FILES=("${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json")
+
+LOG="${HOME}/.remnic/logs/remnic-session-recall.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [session-start] $*" >> "$LOG"; }
+
+# Read token from per-plugin token store
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${TOKEN_FILES[@]}"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const store = JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));
+    const tokens = store.tokens || [];
+    const cc = tokens.find(t => t.connector === 'claude-code');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cc && cc.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['claude-code'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+
+# Fallback to env var
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+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"
+
+# Health check — start daemon if not running
+if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
+  log "daemon not responding, attempting start..."
+  if command -v remnic >/dev/null 2>&1; then
+    remnic daemon start >/dev/null 2>&1 &
+  elif command -v engram >/dev/null 2>&1; then
+    engram daemon start >/dev/null 2>&1 &
+  fi
+  sleep 2
+  if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
+    log "daemon still not responding after start attempt"
+    echo '{"continue":true,"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[Remnic: daemon not running — start with: remnic daemon start]"}}'
+    exit 0
+  fi
+fi
+
+if [ -z "$REMNIC_TOKEN" ]; then
+  log "skipping: no token found"
+  echo '{"continue":true,"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[Remnic: no auth token — run: remnic connectors install claude-code]"}}'
+  exit 0
+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)"
+
+[ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
+
+log "attempting full recall (auto mode)..."
+RAW="$(curl -s -w "\n%{http_code}" --max-time 45 \
+  -X POST "$REMNIC_URL" \
+  -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-Engram-Client-Id: claude-code" \
+  -d "$REQUEST_BODY" 2>/dev/null)"
+CURL_EXIT=$?
+HTTP_STATUS="$(echo "$RAW" | tail -1)"
+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)"
+  RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
+    -X POST "$REMNIC_URL" \
+    -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -H "X-Engram-Client-Id: claude-code" \
+    -d "${MINIMAL_BODY:-$REQUEST_BODY}" 2>/dev/null)"
+  CURL_EXIT=$?
+  HTTP_STATUS="$(echo "$RAW" | tail -1)"
+  RESPONSE="$(echo "$RAW" | sed '$d')"
+  [[ "$CURL_EXIT" -eq 0 && "$HTTP_STATUS" =~ ^2 ]] && log "minimal recall succeeded" || { log "minimal recall also failed"; CURL_EXIT=1; }
+fi
+
+if [ $CURL_EXIT -eq 0 ] && [[ "$HTTP_STATUS" =~ ^2 ]] && [ -n "$RESPONSE" ]; then
+  CONTEXT="$(node -e "
+    const d = JSON.parse(process.argv[1]);
+    const ctx = d.context || '';
+    const count = d.count || 0;
+    const mode = d.mode || '';
+    if (ctx) {
+      const label = '[Remnic Memory Recall — ' + count + ' memories' + (mode ? ', ' + mode + ' mode' : '') + ']';
+      process.stdout.write(label + '\n\n' + ctx);
+    } else {
+      process.stdout.write('[Remnic: no relevant memories found for this session]');
+    }
+  " "$RESPONSE" 2>/dev/null || echo "[Remnic: recall parse error]")"
+  log "recall complete: $(echo "$CONTEXT" | head -1)"
+else
+  CONTEXT="[Remnic: server unreachable — continuing without memory recall]"
+  log "$CONTEXT"
+fi
+
+node -e "
+  const context = process.argv[1];
+  process.stdout.write(JSON.stringify({
+    continue: true,
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context }
+  }));
+" "$CONTEXT"

package/hooks/bin/user-prompt-recall.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Remnic UserPromptSubmit hook for Claude Code.
+# Recalls per-prompt context using the user's message as query.
+# Skips short prompts (<4 words). Minimal mode, 20s timeout.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/recall"
+
+LOG="${HOME}/.remnic/logs/remnic-user-prompt-recall.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [user-prompt] $*" >> "$LOG"; }
+
+# Read token
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const fs = require('fs');
+    const tokenFile = process.argv[1];
+    const store = JSON.parse(fs.readFileSync(tokenFile, 'utf8'));
+    const tokens = store.tokens || [];
+    const cc = tokens.find(t => t.connector === 'claude-code');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cc && cc.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['claude-code'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+
+if [ -z "$REMNIC_TOKEN" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+PROMPT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.prompt||'')" "$INPUT" 2>/dev/null || echo "")"
+
+# Skip very short prompts
+WORD_COUNT="$(echo "$PROMPT" | wc -w | tr -d ' ')"
+if [ "$WORD_COUNT" -lt 4 ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+log "session=$SESSION_ID words=$WORD_COUNT"
+
+REQUEST_BODY="$(node -e "process.stdout.write(JSON.stringify({
+  query: process.argv[1],
+  sessionKey: process.argv[2],
+  topK: 8,
+  mode: 'minimal'
+}))" "$PROMPT" "$SESSION_ID" 2>/dev/null)"
+
+[ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
+
+RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
+  -X POST "$REMNIC_URL" \
+  -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-Engram-Client-Id: claude-code" \
+  -d "$REQUEST_BODY" 2>/dev/null)"
+CURL_EXIT=$?
+HTTP_STATUS="$(echo "$RAW" | tail -1)"
+RESPONSE="$(echo "$RAW" | sed '$d')"
+
+if [ $CURL_EXIT -ne 0 ] || ! [[ "$HTTP_STATUS" =~ ^2 ]] || [ -z "$RESPONSE" ]; then
+  log "recall failed (curl=$CURL_EXIT http=$HTTP_STATUS)"
+  echo '{"continue":true}'
+  exit 0
+fi
+
+node -e "
+  const d = JSON.parse(process.argv[1]);
+  const ctx = d.context || '';
+  const count = d.count || 0;
+  if (!ctx || count === 0) {
+    process.stdout.write(JSON.stringify({continue: true}));
+  } else {
+    process.stdout.write(JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: '<remnic-memory count=\"' + count + '\">\n' + ctx + '\n</remnic-memory>'
+      }
+    }));
+  }
+" "$RESPONSE" 2>/dev/null || echo '{"continue":true}'
+
+COUNT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String(d.count||0))" "$RESPONSE" 2>/dev/null || echo "?")"
+log "done: ${COUNT} memories injected"

package/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/session-start.sh",
+            "timeout": 45000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/post-tool-observe.sh",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/user-prompt-recall.sh",
+            "timeout": 20000
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@remnic/plugin-claude-code",
+  "version": "1.0.0",
+  "description": "Remnic memory plugin for Claude Code — hooks, skills, MCP integration",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joshuaswarren/remnic.git",
+    "directory": "packages/plugin-claude-code"
+  },
+  "keywords": [
+    "remnic",
+    "memory",
+    "claude-code",
+    "plugin",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    ".claude-plugin",
+    "hooks",
+    "skills",
+    "agents",
+    ".mcp.json",
+    "settings.json"
+  ]
+}

package/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "mcp": {
+      "remnic": {
+        "allow": ["remnic_*", "engram_*"]
+      }
+    }
+  }
+}

package/skills/remnic-entities/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: remnic-entities
+description: Browse entities in the Remnic knowledge graph and surface their facts and relationships. Trigger phrases include "tell me about the entity", "look up", "what do we know about".
+allowed-tools:
+  - remnic_entity_get
+---
+
+## When to use
+
+Use when the user names a specific project, person, service, or concept and asks what is known about it. Entities are the structured graph view of memory — facts and relationships rather than free text.
+
+Triggers:
+
+- "Tell me about the entity …"
+- "Look up …"
+- `/remnic:entities <name>` slash command invocation.
+- Any reference to a named thing that could have linked facts.
+
+## Inputs
+
+- `name` (required) — canonical entity name, ideally as the user wrote it.
+- Optional: entity type hint (project, person, service, tool).
+
+## Procedure
+
+1. Extract the entity name from the user's message. Preserve capitalization.
+2. Call `remnic_entity_get` with that name.
+3. If found, present facts, relationships, and a last-updated timestamp in a compact block.
+4. If missing, say so and offer to create it via `remnic-remember` with the user's permission.
+5. If multiple candidates match, list them briefly and ask which the user meant.
+
+## Efficiency plan
+
+- Do not fetch speculatively for every proper noun — only when the user asks or the task depends on it.
+- Cache the entity payload within the current turn.
+- Pair with `remnic-recall` when unstructured context would round out the view.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Guessing entity names. **Fix:** Use the user's wording; disambiguate rather than inventing.
+- **Pitfall:** Dumping the full payload. **Fix:** Summarize into facts, relations, last-updated.
+- **Pitfall:** Treating missing entities as a bug. **Fix:** Missing just means the graph has not captured it yet.
+
+## Verification checklist
+
+- [ ] `remnic_entity_get` was called with a user-supplied or user-confirmed name.
+- [ ] Output shows facts, relationships, and timestamps in a compact view.
+- [ ] Missing entities are acknowledged plainly with an offer to create.
+- [ ] Canonical `remnic_entity_get` was used over legacy `engram_entity_get`.
+
+> Tool names: canonical name is `remnic_entity_get`. The legacy `engram_entity_get` alias remains accepted during v1.x.

package/skills/remnic-memory-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: remnic-memory-workflow
+description: Shared memory workflow for Claude Code agents connected to Remnic — recall before acting, observe during work, remember at the end. Trigger phrases include "what do you remember about", "save this for later", "any context from last time".
+disable-model-invocation: true
+allowed-tools:
+  - remnic_recall
+  - remnic_memory_store
+  - remnic_lcm_search
+  - remnic_entity_get
+  - remnic_observe
+---
+
+## When to use
+
+Use this skill as the default playbook whenever Claude Code picks up a task that could benefit from prior context, or when the user explicitly asks the agent to remember or recall something. The individual `remnic-recall`, `remnic-remember`, `remnic-search`, `remnic-entities`, and `remnic-status` skills implement the detailed steps.
+
+Triggers:
+
+- New ticket, branch, or task begins.
+- "What do you remember about …"
+- "Save this for later."
+- Long-running turn produces a durable outcome worth capturing.
+
+## Inputs
+
+- Current user request (natural language).
+- Optional: active project path, ticket number, branch name.
+- Optional: topic keywords surfaced earlier in the session.
+
+## Procedure
+
+1. **Recall first.** Call `remnic_recall` with a concise natural-language query built from the user's request. Pull 3–8 results and filter for relevance.
+2. **Mention relevant memories briefly** to the user when they change the plan; otherwise use them as quiet context.
+3. **Observe during work.** For significant tool results (Write/Edit/MultiEdit, Bash exits, test output) call `remnic_observe` so Remnic keeps its ambient context fresh.
+4. **Deep search on demand.** If `remnic_recall` missed something the user insists exists, fall back to `remnic_lcm_search` with a more literal phrase.
+5. **Browse entities.** When the user names a project, person, or concept, call `remnic_entity_get` to pull facts and relations.
+6. **Remember at the end.** Before ending the turn, store durable decisions, preferences, and findings via `remnic_memory_store`.
+
+## Efficiency plan
+
+- One broad recall beats several narrow ones.
+- Skip recall for trivially local tasks (formatting, arithmetic, mechanical refactors).
+- Reuse recall results within the same turn.
+- Store each memory once; update rather than duplicate.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Storing transient state. **Fix:** Only store facts with durable value.
+- **Pitfall:** Leaking secrets. **Fix:** Redact credentials and tokens before calling `remnic_memory_store`.
+- **Pitfall:** Flooding the user with recalled context. **Fix:** Summarize in 1–3 bullet points.
+- **Pitfall:** Forgetting the final write. **Fix:** Make "remember the decision" the last step of any non-trivial turn.
+
+## Verification checklist
+
+- [ ] Recall was attempted before the agent committed to a plan.
+- [ ] User-facing mentions of recalled context were concise and relevant.
+- [ ] Durable decisions and findings were stored via `remnic_memory_store`.
+- [ ] No secrets, credentials, or transient state were written.
+- [ ] Canonical `remnic_*` tool names were used over legacy aliases.
+
+> Tool names: this skill uses the canonical `remnic_*` MCP tools. Legacy `engram_*` aliases remain accepted during v1.x for backward compatibility.

package/skills/remnic-recall/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: remnic-recall
+description: Search Remnic memories by natural-language query. Trigger phrases include "what do you remember about", "recall anything on", "have we discussed".
+allowed-tools:
+  - remnic_recall
+---
+
+## When to use
+
+Use when the user or the current task needs prior context from Remnic. This is the default first step for any non-trivial Claude Code turn that could benefit from memory.
+
+Triggers:
+
+- "What do you remember about …"
+- "Have we talked about …"
+- `/remnic:recall <query>` slash command invocation.
+- A new task begins and the agent wants background.
+
+## Inputs
+
+- `query` (required) — natural-language question or topic string.
+- Optional: caller-supplied budget hint (brief, deep).
+
+## Procedure
+
+1. Build a concise natural-language query from the user's message. Prefer the user's own wording.
+2. Call `remnic_recall` with that query; request 3–8 results unless the caller specified otherwise.
+3. Filter results for topical relevance.
+4. Present 1–5 bullet points summarizing the relevant memories, attributed when useful.
+5. If nothing relevant came back, say so plainly and suggest `remnic-remember` if there is something worth storing now.
+
+## Efficiency plan
+
+- One broad recall beats several narrow ones.
+- Reuse recall results within the same turn — do not re-query the same topic.
+- Skip recall for trivially local tasks.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Quoting irrelevant recalls just because they came back. **Fix:** Filter for relevance before surfacing.
+- **Pitfall:** Over-narrowing the query. **Fix:** Start broad; refine only when the first pass was noisy.
+- **Pitfall:** Showing raw memory payloads. **Fix:** Summarize in the user's own terms.
+
+## Verification checklist
+
+- [ ] `remnic_recall` was called with a natural-language query.
+- [ ] Results were filtered for relevance before being shown.
+- [ ] Summary is ≤ 5 bullets unless the user asked for more.
+- [ ] Canonical `remnic_recall` was used over legacy `engram_recall`.
+
+> Tool names: canonical name is `remnic_recall`. The legacy `engram_recall` alias remains accepted during v1.x.

package/skills/remnic-remember/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: remnic-remember
+description: Store a durable memory in Remnic so every connected agent can recall it. Trigger phrases include "remember this", "save this for later", "add a note that".
+disable-model-invocation: true
+allowed-tools:
+  - remnic_memory_store
+---
+
+## When to use
+
+Use when the user explicitly asks Claude Code to remember something, or when a turn produces a durable decision, preference, or finding worth storing for later sessions.
+
+Triggers:
+
+- "Remember that …"
+- "Save this for later."
+- `/remnic:remember <text>` slash command invocation.
+- End-of-turn consolidation after a non-trivial conclusion.
+
+## Inputs
+
+- `content` (required) — the statement to store, in the user's own words where possible.
+- Optional: category hint (preference, decision, fact, procedure).
+- Optional: related entity or project name.
+
+## Procedure
+
+1. Confirm the content is durable — it should still be useful days or weeks from now.
+2. Strip any secrets, credentials, or transient context.
+3. Keep the user's voice; rephrase only when needed for clarity.
+4. Call `remnic_memory_store` with the text as `content`. Include category or entity hints when the tool accepts them.
+5. Confirm to the user in one line what was stored.
+6. Mention that the memory is available across connected agents (Claude Code, Codex, Hermes, OpenClaw).
+
+## Efficiency plan
+
+- Batch related facts into a single memory rather than writing many tiny ones.
+- If a prior memory on the same topic exists, update it rather than duplicating.
+- Do not store anything easily re-derived from source code or docs.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Storing transient state. **Fix:** Only commit facts that will still matter tomorrow.
+- **Pitfall:** Leaking secrets. **Fix:** Redact before calling the tool.
+- **Pitfall:** Duplicates on the same topic. **Fix:** Recall first; prefer update.
+- **Pitfall:** Vague entries. **Fix:** Be specific — who, what, when, why.
+
+## Verification checklist
+
+- [ ] Content is durable and specific.
+- [ ] No secrets or PII were included.
+- [ ] `remnic_memory_store` was called with the final content.
+- [ ] User received a one-line confirmation.
+- [ ] Canonical `remnic_memory_store` was used over legacy `engram_memory_store`.
+
+> Tool names: canonical name is `remnic_memory_store`. The legacy `engram_memory_store` alias remains accepted during v1.x.

package/skills/remnic-search/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: remnic-search
+description: Run a deep full-text search across every Remnic memory. Trigger phrases include "search memories for", "find anything about", "deep search".
+allowed-tools:
+  - remnic_lcm_search
+---
+
+## When to use
+
+Use when `remnic-recall` did not surface something the user insists exists, or when the task genuinely needs exhaustive coverage rather than a ranked semantic summary.
+
+Triggers:
+
+- "Search memories for …"
+- "Deep search on …"
+- `/remnic:search <query>` slash command invocation.
+- Follow-up after `remnic-recall` returned nothing useful.
+
+## Inputs
+
+- `query` (required) — literal phrase or keyword string; this is full-text, not semantic.
+- Optional: date range, category filter, entity constraint.
+
+## Procedure
+
+1. Pick the most literal phrase the user expects to match.
+2. Call `remnic_lcm_search` with that phrase.
+3. Group results by date or category when the tool returns enough metadata.
+4. Present the top 5–10 matches with dates and short excerpts.
+5. If still nothing, say so plainly and offer `remnic-remember` for capturing the content going forward.
+
+## Efficiency plan
+
+- Use the most specific phrase available.
+- One targeted search beats several broad ones.
+- Do not re-run a deep search for the same topic in the same turn after recall already covered it.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Using `remnic_lcm_search` as the default. **Fix:** Start with `remnic_recall`; escalate only when recall fails.
+- **Pitfall:** Pasting huge result dumps. **Fix:** Show top matches with excerpts.
+- **Pitfall:** Over-broad queries. **Fix:** Require at least one distinctive keyword.
+
+## Verification checklist
+
+- [ ] `remnic_lcm_search` was called only after recall fell short or exhaustive matching was required.
+- [ ] Results were grouped by relevance or date when possible.
+- [ ] Output shows excerpts, not raw payloads.
+- [ ] Canonical `remnic_lcm_search` was used over legacy `engram_lcm_search`.
+
+> Tool names: canonical name is `remnic_lcm_search`. The legacy `engram_lcm_search` alias remains accepted during v1.x.

package/skills/remnic-status/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: remnic-status
+description: Check the health of the Remnic daemon, stores, and connected clients. Trigger phrases include "is remnic running", "check memory status", "daemon health".
+---
+
+## When to use
+
+Use when the user asks whether Remnic is running, when recall or store calls start failing, or when diagnosing cross-agent memory issues from Claude Code.
+
+Triggers:
+
+- "Is Remnic running?"
+- "Check memory status."
+- `/remnic:status` slash command invocation.
+- Recall/store tools returned connection errors in this turn.
+
+## Inputs
+
+- Optional: specific component to check (daemon, HTTP server, MCP server, store backend).
+
+## Procedure
+
+1. Check the Remnic health endpoint via the MCP bridge or run `remnic daemon status` in a shell.
+2. Report, in a compact block:
+   - Daemon running state (PID if known).
+   - Listening port(s).
+   - Memory store path.
+   - Connected clients or plugins, if exposed.
+3. If the daemon is not running, suggest `remnic daemon start` and mention the log path.
+4. If recall/store tools were erroring earlier in the turn, correlate the health state with those errors in one sentence.
+
+## Efficiency plan
+
+- One health call per turn is enough; do not poll.
+- Skip the check for trivially local tasks.
+- Reuse the health payload for downstream troubleshooting within the same turn.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Running `remnic daemon status` on a host where the daemon lives in a container. **Fix:** Prefer the MCP health endpoint, or run the CLI inside the container.
+- **Pitfall:** Reporting "down" from a single failed tool call. **Fix:** Confirm with the health endpoint before claiming an outage.
+- **Pitfall:** Forgetting the log path. **Fix:** Always include a pointer to logs on failure.
+
+## Verification checklist
+
+- [ ] Health was checked via the endpoint or CLI, not guessed.
+- [ ] Daemon state, port, store path, and clients were reported concisely.
+- [ ] If unhealthy, the user got a concrete next step.
+- [ ] Canonical `remnic daemon` wording was used over legacy `engram daemon` where the CLI has been renamed.
+
+> CLI names: canonical CLI is `remnic daemon`. The legacy `engram daemon` invocation remains accepted during v1.x.