@nex-ai/nex 0.1.8 → 0.1.10

package/dist/plugin/nex-client.js

@@ -0,0 +1,129 @@
+/**
+ * HTTP client for the Nex Developer API.
+ * Adapted from openclaw-plugin — uses native fetch with timeout.
+ */
+// --- Error types ---
+export class NexAuthError extends Error {
+    constructor(message = "Invalid or missing API key") {
+        super(message);
+        this.name = "NexAuthError";
+    }
+}
+export class NexRateLimitError extends Error {
+    retryAfterMs;
+    constructor(retryAfterMs = 60_000) {
+        super(`Rate limited — retry after ${retryAfterMs}ms`);
+        this.name = "NexRateLimitError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class NexServerError extends Error {
+    status;
+    constructor(status, body) {
+        super(`Nex API error ${status}${body ? `: ${body}` : ""}`);
+        this.name = "NexServerError";
+        this.status = status;
+    }
+}
+// --- Client ---
+export class NexClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(method, path, body, timeoutMs = 10_000) {
+        const url = `${this.baseUrl}/api/developers${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const headers = {
+                Authorization: `Bearer ${this.apiKey}`,
+            };
+            if (body !== undefined) {
+                headers["Content-Type"] = "application/json";
+            }
+            const res = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (res.status === 401 || res.status === 403) {
+                throw new NexAuthError();
+            }
+            if (res.status === 429) {
+                const retryAfter = res.headers.get("retry-after");
+                const ms = retryAfter ? parseInt(retryAfter, 10) * 1000 : 60_000;
+                throw new NexRateLimitError(ms);
+            }
+            if (!res.ok) {
+                let errorBody;
+                try {
+                    errorBody = await res.text();
+                }
+                catch {
+                    // ignore
+                }
+                throw new NexServerError(res.status, errorBody);
+            }
+            const text = await res.text();
+            if (!text || !text.trim())
+                return {};
+            return JSON.parse(text);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Register a new account and get an API key.
+     * Does NOT require an existing API key — uses the public registration endpoint.
+     */
+    static async register(baseUrl, email, name, companyName) {
+        const url = `${baseUrl}/api/v1/agents/register`;
+        const body = { email, source: "claude-code" };
+        if (name)
+            body.name = name;
+        if (companyName)
+            body.company_name = companyName;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                let errorBody;
+                try {
+                    errorBody = await res.text();
+                }
+                catch { /* ignore */ }
+                throw new NexServerError(res.status, errorBody);
+            }
+            return await res.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Ingest text content into the Nex knowledge graph. */
+    async ingest(content, context, timeoutMs) {
+        const body = { content };
+        if (context)
+            body.context = context;
+        return this.request("POST", "/v1/context/text", body, timeoutMs ?? 60_000);
+    }
+    /** Ask a question against the Nex knowledge graph. */
+    async ask(query, sessionId, timeoutMs) {
+        const body = { query };
+        if (sessionId)
+            body.session_id = sessionId;
+        return this.request("POST", "/v1/context/ask", body, timeoutMs);
+    }
+}
+//# sourceMappingURL=nex-client.js.map

package/dist/plugin/nex-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nex-client.js","sourceRoot":"","sources":["../../src/plugin/nex-client.ts"],"names":[],"mappings":"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"}

package/dist/plugin/rate-limiter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * File-based sliding window rate limiter.
+ * Designed for Nex /text endpoint (10 req/min).
+ *
+ * Since Claude Code hooks are short-lived processes (start, run, exit),
+ * in-memory state is lost between invocations. This implementation persists
+ * timestamps to a JSON file so rate limits are respected across invocations.
+ */
+export interface RateLimiterConfig {
+    maxRequests: number;
+    windowMs: number;
+    dataDir: string;
+}
+export declare class RateLimiter {
+    private config;
+    private filePath;
+    constructor(config?: Partial<RateLimiterConfig>);
+    private readTimestamps;
+    private writeTimestamps;
+    /**
+     * Check if a request can proceed, and if so, record the timestamp.
+     * Returns true if the request is allowed, false if rate limited.
+     */
+    canProceed(): boolean;
+    get pending(): number;
+}

package/dist/plugin/rate-limiter.js

@@ -0,0 +1,65 @@
+/**
+ * File-based sliding window rate limiter.
+ * Designed for Nex /text endpoint (10 req/min).
+ *
+ * Since Claude Code hooks are short-lived processes (start, run, exit),
+ * in-memory state is lost between invocations. This implementation persists
+ * timestamps to a JSON file so rate limits are respected across invocations.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULTS = {
+    maxRequests: 10,
+    windowMs: 60_000,
+    dataDir: join(homedir(), ".nex"),
+};
+export class RateLimiter {
+    config;
+    filePath;
+    constructor(config) {
+        this.config = { ...DEFAULTS, ...config };
+        this.filePath = join(this.config.dataDir, "rate-limiter.json");
+        mkdirSync(this.config.dataDir, { recursive: true });
+    }
+    readTimestamps() {
+        try {
+            const raw = readFileSync(this.filePath, "utf-8");
+            const data = JSON.parse(raw);
+            if (Array.isArray(data))
+                return data;
+            return [];
+        }
+        catch {
+            return [];
+        }
+    }
+    writeTimestamps(timestamps) {
+        try {
+            writeFileSync(this.filePath, JSON.stringify(timestamps), "utf-8");
+        }
+        catch {
+            // Best-effort — if we can't write, proceed without rate limiting
+        }
+    }
+    /**
+     * Check if a request can proceed, and if so, record the timestamp.
+     * Returns true if the request is allowed, false if rate limited.
+     */
+    canProceed() {
+        const now = Date.now();
+        const timestamps = this.readTimestamps().filter((t) => now - t < this.config.windowMs);
+        if (timestamps.length >= this.config.maxRequests) {
+            // Write back pruned timestamps
+            this.writeTimestamps(timestamps);
+            return false;
+        }
+        timestamps.push(now);
+        this.writeTimestamps(timestamps);
+        return true;
+    }
+    get pending() {
+        return 0;
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/plugin/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/plugin/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAQlC,MAAM,QAAQ,GAAsB;IAClC,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,MAAM;IAChB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,OAAO,WAAW;IACd,MAAM,CAAoB;IAC1B,QAAQ,CAAS;IAEzB,YAAY,MAAmC;QAC7C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QAC/D,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,UAAoB;QAC1C,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;QACnE,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CACtC,CAAC;QAEF,IAAI,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACjD,+BAA+B;YAC/B,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;YACjC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO;QACT,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}

package/dist/plugin/recall-filter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Smart prompt classifier for selective recall.
+ *
+ * Determines whether a prompt is likely knowledge-seeking (needs recall)
+ * or a pure coding directive (skip recall). Also handles debounce —
+ * skips recall if a successful recall happened within the debounce window,
+ * unless the current prompt contains question words.
+ *
+ * Persistence: last-recall timestamp stored in ~/.nex/recall-state.json
+ */
+export interface RecallDecision {
+    shouldRecall: boolean;
+    reason: string;
+}
+/**
+ * Record that a successful recall just happened.
+ * Call this after a non-empty /ask response.
+ */
+export declare function recordRecall(sessionId?: string): void;
+/**
+ * Determine whether this prompt should trigger a Nex /ask recall.
+ */
+export declare function shouldRecall(prompt: string, isFirstPrompt: boolean): RecallDecision;

package/dist/plugin/recall-filter.js

@@ -0,0 +1,94 @@
+/**
+ * Smart prompt classifier for selective recall.
+ *
+ * Determines whether a prompt is likely knowledge-seeking (needs recall)
+ * or a pure coding directive (skip recall). Also handles debounce —
+ * skips recall if a successful recall happened within the debounce window,
+ * unless the current prompt contains question words.
+ *
+ * Persistence: last-recall timestamp stored in ~/.nex/recall-state.json
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DATA_DIR = join(homedir(), ".nex");
+const STATE_FILE = join(DATA_DIR, "recall-state.json");
+const DEBOUNCE_MS = 30_000; // 30 seconds
+// --- Question words that signal knowledge-seeking intent ---
+const QUESTION_WORDS = /\b(who|what|when|where|why|how|which|tell|explain|describe|summarize|summarise|list|find|show|get|any|does|did|is|are|was|were|have|has|do|can|could|should|would|will)\b/i;
+// --- Tool/action commands that are pure coding directives ---
+const TOOL_COMMANDS = /^\s*(run|build|test|lint|format|deploy|install|uninstall|start|stop|restart|commit|push|pull|merge|rebase|checkout|fetch|init|fix|refactor|rename|move|delete|remove|add|create|update|upgrade|downgrade|migrate|generate|scaffold|compile|bundle|watch|serve|debug|profile|bench|clean|reset|undo|redo|revert|squash|cherry-pick|tag|release|publish|npm|npx|yarn|pnpm|bun|pip|cargo|go|make|docker|kubectl|terraform|git|gh|cd|ls|cat|grep|find|mkdir|rm|cp|mv|touch|echo|export|source|chmod|chown|curl|wget|ssh|scp)\b/i;
+// --- File reference pattern (paths, extensions) ---
+const FILE_REF = /(?:[\w./\\-]+\.\w{1,10}|src\/|lib\/|dist\/|node_modules\/|\.\/|\.\.\/)/;
+// --- Code-heavy: >50% non-alpha characters (brackets, operators, etc.) ---
+function isCodeHeavy(text) {
+    const alpha = text.replace(/[^a-zA-Z]/g, "").length;
+    return alpha < text.length * 0.5;
+}
+function readState() {
+    try {
+        const raw = readFileSync(STATE_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { lastRecallAt: 0 };
+    }
+}
+function writeState(state) {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        writeFileSync(STATE_FILE, JSON.stringify(state), "utf-8");
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Record that a successful recall just happened.
+ * Call this after a non-empty /ask response.
+ */
+export function recordRecall(sessionId) {
+    writeState({ lastRecallAt: Date.now(), lastRecallSessionId: sessionId });
+}
+/**
+ * Determine whether this prompt should trigger a Nex /ask recall.
+ */
+export function shouldRecall(prompt, isFirstPrompt) {
+    const trimmed = prompt.trim();
+    // Always recall on first prompt of session
+    if (isFirstPrompt) {
+        return { shouldRecall: true, reason: "first-prompt" };
+    }
+    // Explicit opt-out: prompt starts with !
+    if (trimmed.startsWith("!")) {
+        return { shouldRecall: false, reason: "opt-out" };
+    }
+    // Too short — likely a directive like "yes", "ok", "done"
+    if (trimmed.length < 15) {
+        return { shouldRecall: false, reason: "too-short" };
+    }
+    // Has question words — likely knowledge-seeking
+    const hasQuestion = QUESTION_WORDS.test(trimmed);
+    // Check debounce: skip if recent successful recall, unless question
+    if (!hasQuestion) {
+        const state = readState();
+        if (state.lastRecallAt > 0 && Date.now() - state.lastRecallAt < DEBOUNCE_MS) {
+            return { shouldRecall: false, reason: "debounce" };
+        }
+    }
+    // Tool/action commands — pure coding directives
+    if (TOOL_COMMANDS.test(trimmed) && !hasQuestion) {
+        return { shouldRecall: false, reason: "tool-command" };
+    }
+    // Code-heavy with file references and no question words
+    if (isCodeHeavy(trimmed) && FILE_REF.test(trimmed) && !hasQuestion) {
+        return { shouldRecall: false, reason: "code-prompt" };
+    }
+    // Has question words — always recall
+    if (hasQuestion) {
+        return { shouldRecall: true, reason: "question" };
+    }
+    // Default: recall (err on the side of providing context)
+    return { shouldRecall: true, reason: "default" };
+}
+//# sourceMappingURL=recall-filter.js.map

package/dist/plugin/recall-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-filter.js","sourceRoot":"","sources":["../../src/plugin/recall-filter.ts"],"names":[],"mappings":"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"}

package/dist/plugin/session-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * File-based session store mapping Claude Code session IDs to Nex session IDs.
+ *
+ * Since Claude Code hooks are short-lived processes (start, run, exit),
+ * in-memory state is lost between invocations. This implementation persists
+ * session mappings to a JSON file so multi-turn continuity works.
+ */
+export interface SessionStoreConfig {
+    maxSize: number;
+    dataDir: string;
+}
+export declare class SessionStore {
+    private filePath;
+    private maxSize;
+    constructor(config?: Partial<SessionStoreConfig>);
+    private readStore;
+    private writeStore;
+    get(sessionKey: string): string | undefined;
+    set(sessionKey: string, nexSessionId: string): void;
+    delete(sessionKey: string): boolean;
+    get size(): number;
+    clear(): void;
+}

package/dist/plugin/session-store.js

@@ -0,0 +1,74 @@
+/**
+ * File-based session store mapping Claude Code session IDs to Nex session IDs.
+ *
+ * Since Claude Code hooks are short-lived processes (start, run, exit),
+ * in-memory state is lost between invocations. This implementation persists
+ * session mappings to a JSON file so multi-turn continuity works.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_MAX = 100;
+const DEFAULT_DATA_DIR = join(homedir(), ".nex");
+export class SessionStore {
+    filePath;
+    maxSize;
+    constructor(config) {
+        const dataDir = config?.dataDir ?? DEFAULT_DATA_DIR;
+        this.maxSize = config?.maxSize ?? DEFAULT_MAX;
+        this.filePath = join(dataDir, "claude-sessions.json");
+        mkdirSync(dataDir, { recursive: true });
+    }
+    readStore() {
+        try {
+            const raw = readFileSync(this.filePath, "utf-8");
+            const data = JSON.parse(raw);
+            if (data && typeof data === "object" && !Array.isArray(data)) {
+                return data;
+            }
+            return {};
+        }
+        catch {
+            return {};
+        }
+    }
+    writeStore(store) {
+        try {
+            writeFileSync(this.filePath, JSON.stringify(store), "utf-8");
+        }
+        catch {
+            // Best-effort — if we can't write, session continuity degrades gracefully
+        }
+    }
+    get(sessionKey) {
+        const store = this.readStore();
+        return store[sessionKey];
+    }
+    set(sessionKey, nexSessionId) {
+        const store = this.readStore();
+        store[sessionKey] = nexSessionId;
+        // Evict oldest entries if over max size
+        const keys = Object.keys(store);
+        while (keys.length > this.maxSize) {
+            const oldest = keys.shift();
+            delete store[oldest];
+        }
+        this.writeStore(store);
+    }
+    delete(sessionKey) {
+        const store = this.readStore();
+        if (sessionKey in store) {
+            delete store[sessionKey];
+            this.writeStore(store);
+            return true;
+        }
+        return false;
+    }
+    get size() {
+        return Object.keys(this.readStore()).length;
+    }
+    clear() {
+        this.writeStore({});
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/plugin/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/plugin/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AAOjD,MAAM,OAAO,YAAY;IACf,QAAQ,CAAS;IACjB,OAAO,CAAS;IAExB,YAAY,MAAoC;QAC9C,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,gBAAgB,CAAC;QACpD,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,WAAW,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC;QACtD,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAEO,SAAS;QACf,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7D,OAAO,IAA8B,CAAC;YACxC,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,KAA6B;QAC9C,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;IAED,GAAG,CAAC,UAAkB;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAED,GAAG,CAAC,UAAkB,EAAE,YAAoB;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,KAAK,CAAC,UAAU,CAAC,GAAG,YAAY,CAAC;QAEjC,wCAAwC;QACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAG,CAAC;YAC7B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,CAAC,UAAkB;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;YACzB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,IAAI;QACN,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC;IAC9C,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nex-ai/nex",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Nex CLI provides organizational context & memory to AI agents",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "plugin-commands",
     "README.md"
   ],
   "scripts": {

package/plugin-commands/entities.md

@@ -0,0 +1,18 @@
+---
+description: Search for entities (people, companies, topics) in Nex knowledge base
+---
+Search for entities matching: $ARGUMENTS
+If no query provided, respond: "Usage: /entities <search query>"
+
+Use the `mcp__nex__query_context` tool with the query.
+From the response, extract the `entity_references` array.
+If no entities found, respond: "No matching entities found."
+
+Format each entity as a bullet list:
+```
+Found {count} entities:
+- {name} ({type_label}) — {mention_count} mentions
+```
+
+Type labels: type "14" → Person, type "15" → Company, all others → Entity.
+Only show mention count if available (count > 0).

package/plugin-commands/integrate.md

@@ -0,0 +1,34 @@
+Help the user connect third-party integrations (Gmail, Google Calendar, Outlook, Outlook Calendar, Slack, Attio, HubSpot, Salesforce) to their Nex workspace.
+
+## Available Integrations
+
+| Type | Provider | Display Name |
+|------|----------|-------------|
+| email | google | Gmail |
+| calendar | google | Google Calendar |
+| email | microsoft | Outlook |
+| calendar | microsoft | Outlook Calendar |
+| messaging | slack | Slack |
+| crm | attio | Attio |
+| crm | hubspot | HubSpot |
+| crm | salesforce | Salesforce |
+
+## Steps
+
+1. First, list current integrations to see what's already connected:
+   Use the `list_integrations` MCP tool, or suggest the user runs `nex integrate list` in the terminal.
+
+2. To connect a new integration:
+   Use the `connect_integration` MCP tool with the `type` and `provider` from the table above.
+   This returns an `auth_url` — open it in the user's browser.
+   Alternatively, the user can run: `nex integrate connect <type> <provider>`
+
+3. Poll for completion:
+   Use the `get_connect_status` MCP tool with the `connect_id` every few seconds until `status` is `"connected"`.
+
+4. To disconnect:
+   Use the `disconnect_integration` MCP tool with the `connection_id`.
+   Alternatively: `nex integrate disconnect <id>`
+
+5. To check overall setup status:
+   Suggest the user runs `nex setup status` to see all platforms, integrations, and config status.

package/plugin-commands/recall.md

@@ -0,0 +1,5 @@
+---
+description: Recall relevant memories from Nex knowledge base
+---
+Search the nex knowledge base for: $ARGUMENTS
+Use the mcp__nex__context_ask tool to query and return formatted results with sources.

package/plugin-commands/register.md

@@ -0,0 +1,28 @@
+---
+description: Register for a Nex API key (required for first-time setup)
+---
+Register for a Nex account to get an API key for the memory plugin.
+
+If $ARGUMENTS contains an email address, use it directly. Otherwise, ask the user for their email.
+
+Run the registration script. Find the script path by running:
+```
+node -e "console.log(require('path').join(require('path').dirname(require.resolve('@nex-ai/nex/package.json')), 'dist', 'plugin', 'auto-register.js'))"
+```
+
+Then run:
+```
+node <resolved-path> <email> [name] [company]
+```
+
+If the resolve fails, try the global install path:
+```
+node $(npm prefix -g)/lib/node_modules/@nex-ai/nex/dist/plugin/auto-register.js <email> [name] [company]
+```
+
+After successful registration:
+1. The API key is saved to ~/.nex-mcp.json automatically
+2. All Nex memory features (auto-recall, auto-capture, file scanning) will work immediately
+3. No need to set NEX_API_KEY manually
+
+If already registered, inform the user their existing API key is active.

package/plugin-commands/remember.md

@@ -0,0 +1,5 @@
+---
+description: Store information in Nex knowledge base
+---
+Use the mcp__nex__context_add_text tool to store the following text: $ARGUMENTS
+Confirm what was stored.

package/plugin-commands/scan.md

@@ -0,0 +1,8 @@
+---
+description: Scan and ingest project files into Nex knowledge base
+---
+Scan the current project directory for business documents (md, txt, csv, json, yaml)
+and ingest new or changed files into the Nex knowledge base.
+Use the mcp__nex__context_add_text tool for each file found.
+If $ARGUMENTS contains a path, scan that directory instead.
+Report which files were ingested and which were skipped.