@everme/claude-code 0.1.0

package/hooks/scripts/session-start.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook — surface a recent-context block when a new
+ * Claude Code session begins. Helps the user (and Claude) pick up
+ * where the previous session left off without manually pasting
+ * context.
+ *
+ * Hook contract:
+ *   stdin  = JSON { cwd, session_id, ... }
+ *   stdout = JSON { systemMessage, hookSpecificOutput: { ..., additionalContext } }
+ */
+
+process.on("uncaughtException", () => process.exit(0));
+process.on("unhandledRejection", () => process.exit(0));
+
+import { isConfigured } from "./lib/config.js";
+import { getContext } from "./lib/api.js";
+import { redactError, debug } from "./lib/redact.js";
+import { renderProfileBlock, profileItemCount } from "./lib/profile.js";
+
+const TOP_K = 6;
+
+async function main() {
+  if (!isConfigured()) {
+    debug("start", "skip: not configured");
+    return process.exit(0);
+  }
+  await readStdinJSON(); // drain stdin (may be empty)
+
+  let block = "";
+  let count = 0;
+  try {
+    // Empty query — the gateway returns the user's profile snapshot.
+    // Shape: { profile: {explicit_info, implicit_traits, ...} }
+    const ctx = await getContext("", { topK: TOP_K });
+    block = renderProfileBlock(ctx?.profile);
+    count = profileItemCount(ctx?.profile);
+  } catch (err) {
+    debug("start", "context failed:", redactError(err?.message));
+    return process.exit(0);
+  }
+  if (!block || count === 0) {
+    debug("start", "no context");
+    return process.exit(0);
+  }
+
+  const out = {
+    systemMessage: `🧠 EverMe loaded ${count} memory ${count === 1 ? "item" : "items"} from past sessions`,
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: block,
+    },
+  };
+  process.stdout.write(JSON.stringify(out));
+  process.exit(0);
+}
+
+async function readStdinJSON() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+main();

package/hooks/scripts/session-summary.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd hook — no runtime persistence here.
+ *
+ * Claude Code runtime memory is written turn-by-turn by the Stop hook through
+ * /mem/agent-memory. SessionEnd must not upload a markdown summary to
+ * /mem/sources, otherwise long-lived sessions create document sources.
+ *
+ * Hook contract:
+ *   stdin  = JSON { transcript_path, session_id, cwd, ... }
+ *   stdout = empty (no UI surface needed)
+ */
+
+process.on("uncaughtException", () => process.exit(0));
+process.on("unhandledRejection", () => process.exit(0));
+
+import { debug } from "./lib/redact.js";
+
+async function main() {
+  debug("summary", "skip: runtime persistence is handled by Stop via /mem/agent-memory");
+  process.exit(0);
+}
+
+main();

package/hooks/scripts/store-memories.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — fires after Claude finishes responding to a turn.
+ * We read the transcript JSONL Claude Code wrote, extract the
+ * just-completed raw turn, and POST it through the realtime gateway
+ * (/mem/agent-memory). Runtime turns must not create /mem/sources.
+ *
+ * Hook contract (from Claude Code):
+ *   stdin  = JSON { transcript_path, cwd, session_id, ... }
+ *   stdout = empty (no need to surface anything to the user)
+ *
+ * Failure-mode: silent exit 0 — host must NEVER notice memory
+ * persistence is broken. The gateway has its own retry loop on the
+ * worker side, so a single dropped Stop event isn't catastrophic.
+ */
+
+process.on("uncaughtException", () => process.exit(0));
+process.on("unhandledRejection", () => process.exit(0));
+
+import { isConfigured, getConfig } from "./lib/config.js";
+import {
+  saveAgentMemory,
+  EvermeError,
+} from "./lib/api.js";
+import { AGENT_MEMORY_ROLES } from "@everme/agent-sdk";
+import { readTranscript, extractAgentMessages } from "./lib/transcript.js";
+import { redactError, debug } from "./lib/redact.js";
+
+const MIN_MESSAGES = 1;
+
+async function main() {
+  if (!isConfigured()) {
+    debug("store", "skip: not configured");
+    return process.exit(0);
+  }
+  const cfg = getConfig();
+  if (cfg.authMode !== "evt" || !cfg.agentId) {
+    debug("store", "skip: realtime agent memory requires EVERME_AGENT_TOKEN + EVERME_AGENT_ID");
+    return process.exit(0);
+  }
+  const data = await readStdinJSON();
+  const transcriptPath = data?.transcript_path;
+  const sessionId = data?.session_id || "claude-code-session";
+  if (!transcriptPath) {
+    debug("store", "skip: no transcript_path");
+    return process.exit(0);
+  }
+
+  const lines = await readTranscript(transcriptPath);
+  const messages = extractAgentMessages(lines);
+  // Only persist the LAST user/assistant pair from this Stop event so
+  // we don't re-upload the entire history every turn — backend chains
+  // versions per documentKey, so each call appends.
+  const tail = lastTurn(messages);
+  if (tail.length < MIN_MESSAGES) {
+    debug("store", `skip: tail < ${MIN_MESSAGES} messages (got ${tail.length})`);
+    return process.exit(0);
+  }
+
+  try {
+    // Stop is the natural session-end signal for Claude Code; flush
+    // so EverOS extracts episodes/profiles instead of letting
+    // raw_messages accumulate indefinitely.
+    const res = await saveAgentMemory({
+      conversationId: sessionId,
+      messages: tail,
+      flush: true,
+    });
+    debug("store", `ok agent-memory status=${res?.status || "unknown"} flushed=${!!res?.flushed} messages=${res?.messageCount || tail.length}`);
+  } catch (err) {
+    if (err instanceof EvermeError) {
+      debug("store", `failed type=${err.type}:`, redactError(err.message));
+    } else {
+      debug("store", "unexpected:", redactError(err?.message || String(err)));
+    }
+  }
+  process.exit(0);
+}
+
+/**
+ * Take the latest user prompt + assistant reply pair (plus any
+ * tool/tool_result events that fall between them). The gateway's
+ * realtime write API receives only this delta — uploading the whole
+ * history would duplicate memories on every turn.
+ */
+function lastTurn(messages) {
+  if (messages.length === 0) return [];
+  // Walk backwards: take everything from the last `user` event
+  // through the end. That captures user → tool... → assistant flow.
+  let startIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === AGENT_MEMORY_ROLES.USER) {
+      startIdx = i;
+      break;
+    }
+  }
+  if (startIdx === -1) return messages;
+  return messages.slice(startIdx);
+}
+
+async function readStdinJSON() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+main();

package/install.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+#
+# EverMe plugin installer for Claude Code.
+#
+# What it does:
+#   1. Verifies `claude` CLI exists and Node 18+.
+#   2. Prompts for EVERME_API_KEY (an emk_*) if not already set, and
+#      writes it to ~/.claude/everme.env (mode 0600). The plugin's
+#      lib/config.js loads this file at hook startup.
+#   3. Tells `claude` to install this plugin from the local directory.
+#
+# What it does NOT do:
+#   - Edit the user's shell profile. Earlier revisions appended an
+#     `export EVERME_API_KEY=…` line to ~/.zshrc / ~/.bashrc — that
+#     stored a secret in a typically world-readable file (mode 0644)
+#     and accumulated a duplicate line on every re-install. We now
+#     mirror the path `evercli plugin install claude-code` uses: a
+#     0600 file at ~/.claude/everme.env, scoped to the plugin.
+set -e
+
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PLUGIN_DIR="$(cd "$(dirname "$0")" && pwd)"
+ENV_FILE="$HOME/.claude/everme.env"
+
+echo
+echo -e "${CYAN}EverMe — Claude Code plugin installer${NC}"
+echo
+
+if ! command -v claude >/dev/null 2>&1; then
+    echo -e "${RED}claude CLI not found.${NC}"
+    echo "Install Claude Code first: https://claude.ai/code"
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} Claude Code CLI detected"
+
+if ! command -v node >/dev/null 2>&1; then
+    echo -e "${RED}node not found.${NC} Plugin hooks need Node 18+."
+    exit 1
+fi
+NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]" 2>/dev/null || echo 0)
+if [ "$NODE_MAJOR" -lt 18 ]; then
+    echo -e "${RED}node $NODE_MAJOR is too old.${NC} Need Node 18+."
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} Node $(node --version)"
+
+# Persist credentials to ~/.claude/everme.env (mode 0600). atomic_write
+# mirrors evercli's writeFileAtomic — body goes via .tmp then rename so
+# the plugin never reads a half-written file.
+atomic_write_env() {
+    local body=$1
+    mkdir -p "$(dirname "$ENV_FILE")"
+    chmod 0700 "$(dirname "$ENV_FILE")" 2>/dev/null || true
+    local tmp="${ENV_FILE}.tmp"
+    rm -f "$tmp"
+    # umask 0077 → 0600 file; -e/-c work with O_EXCL semantics on noclobber.
+    (umask 0077 && printf '%s' "$body" > "$tmp")
+    mv -f "$tmp" "$ENV_FILE"
+    chmod 0600 "$ENV_FILE"
+}
+
+# Configure auth.
+if [ -z "${EVERME_API_KEY:-}" ] && [ -z "${EVERME_AGENT_TOKEN:-}" ] && [ ! -f "$ENV_FILE" ]; then
+    echo
+    echo -e "${YELLOW}EverMe credentials not found.${NC}"
+    echo -n "Paste your account API key (starts with emk_, from the EverMe Web UI; input is hidden): "
+    # -s suppresses echo so the token never lands in shell scrollback.
+    read -rs EMK_INPUT
+    echo
+    if [ -z "$EMK_INPUT" ]; then
+        echo -e "${RED}No key provided. Aborting.${NC}"
+        exit 1
+    fi
+
+    BODY="# Managed by ${PLUGIN_DIR##*/}/install.sh — do not edit by hand.
+# Re-run install.sh to refresh, or remove this file to disable the plugin.
+"
+    if [ -n "${EVERME_API_BASE:-}" ]; then
+        BODY="${BODY}EVERME_API_BASE=${EVERME_API_BASE}
+"
+    fi
+    BODY="${BODY}EVERME_API_KEY=${EMK_INPUT}
+"
+    atomic_write_env "$BODY"
+    unset EMK_INPUT BODY
+    echo -e "${GREEN}✓${NC} Wrote credentials to $ENV_FILE (mode 0600)"
+elif [ -f "$ENV_FILE" ]; then
+    echo -e "${GREEN}✓${NC} Existing $ENV_FILE detected — leaving credentials as-is"
+fi
+
+# Optional API base override (default https://everme.evermind.ai).
+if [ -n "${EVERME_API_BASE:-}" ]; then
+    echo -e "${GREEN}✓${NC} Using EVERME_API_BASE=$EVERME_API_BASE"
+fi
+
+# Install via Claude Code's plugin system.
+echo
+echo -e "${CYAN}Installing plugin via 'claude plugin install'…${NC}"
+claude plugin install "$PLUGIN_DIR"
+
+echo
+echo -e "${GREEN}✓ EverMe plugin installed.${NC}"
+echo
+echo "Next steps:"
+echo "  1. Start Claude Code:   claude"
+echo "  2. Try '/everme-help' or '/recall <something>' to verify."
+echo "  3. Set EVERME_DEBUG=1 in your environment to see hook traces on stderr."

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@everme/claude-code",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "EverMe native plugin for Claude Code — automatic memory recall via SessionStart/UserPromptSubmit/Stop/SessionEnd hooks, plus /recall slash + bundled MCP server.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test tests/redact.test.js tests/config.test.js tests/transcript.test.js"
+  },
+  "files": [
+    "plugin.json",
+    ".claude-plugin/",
+    "hooks/",
+    "commands/",
+    "skills/",
+    "install.sh",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@everme/agent-sdk": "^0.1.0"
+  },
+  "keywords": ["evermind", "everme", "claude-code", "claude", "anthropic", "memory", "ai", "agent", "mcp"],
+  "homepage": "https://everme.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alwaysday1/everme.git",
+    "directory": "plugins/claude-code"
+  },
+  "bugs": {
+    "url": "https://github.com/alwaysday1/everme/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "everme",
+  "version": "0.1.0",
+  "description": "EverMe — automatic memory recall for Claude Code. Recalls relevant context from past sessions before each prompt and saves new turns through the EverMe gateway.",
+  "author": {
+    "name": "EverMind AI",
+    "url": "https://everme.evermind.ai"
+  },
+  "homepage": "https://everme.evermind.ai",
+  "keywords": ["memory", "context", "recall", "persistence", "everme"],
+  "license": "Apache-2.0"
+}

package/skills/memory-tools.md

@@ -0,0 +1,35 @@
+---
+description: How and when to use EverMe memory tools to bring past-session context into the current Claude Code conversation.
+alwaysInclude: true
+---
+
+# EverMe Memory Tools
+
+You have two MCP tools that surface memory persisted by EverMe across past Claude Code sessions:
+
+- `everme_search` — semantic + keyword hybrid search over the user's memory store. Returns ranked items with subject, summary, score.
+- `everme_context` — fetch a server-rendered context block (profile + recent episodes) ready to inject into the current turn.
+
+The plugin's UserPromptSubmit hook already injects relevant memory automatically before each prompt. You usually do NOT need to call these tools manually — they're for cases the auto-recall missed.
+
+## When to use these tools
+
+**Do call** when:
+- The user references something they discussed before ("last time", "remember when", "we decided to use X")
+- The user asks about a project pattern, decision, or convention you have no inline context for
+- You're debugging an error message that may have been seen + resolved before
+- The auto-recall block (`<everme_recall>...</everme_recall>` in your context) is empty or clearly unrelated to the current task
+- The user explicitly asks you to "search my memory" / "recall" / "look up"
+
+**Do NOT call** when:
+- The current message is self-contained and you can answer from inline context
+- You already searched in the current turn (don't duplicate)
+- It's a general-knowledge question with no project history component
+
+## Best practices
+
+1. Search with the user's specific terms first; only broaden if zero hits.
+2. Cite memories by subject so the user can trace them.
+3. Synthesize, don't copy-paste — quote the relevant lines, not whole memory bodies.
+4. If recall returns conflicting info ("two prior sessions disagree"), say so and ask the user which is current.
+5. The user's emk / evt is a credential — never echo it back, even when EverMe-related errors surface.