gitmem-mcp 1.1.3 → 1.2.1

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Privacy-respecting telemetry for GitMem
+ *
+ * - Opt-in only (disabled by default)
+ * - No PII (queries, scars, project names, IPs)
+ * - Transparent (local logs visible before sending)
+ * - Anonymous (random session IDs, not persistent)
+ * - Controllable (enable/disable/show/clear)
+ */
+export declare class Telemetry {
+    private configPath;
+    private logPath;
+    private config;
+    private version;
+    constructor(gitmemDir: string, version: string);
+    /**
+     * Load telemetry config from disk
+     */
+    private loadConfig;
+    /**
+     * Save config to disk
+     */
+    private saveConfig;
+    /**
+     * Generate random session ID (8 hex chars, not persistent)
+     */
+    private generateSessionId;
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable telemetry (user consent)
+     */
+    enable(): void;
+    /**
+     * Disable telemetry
+     */
+    disable(): void;
+    /**
+     * Log an event (always writes to local log, sends if enabled)
+     */
+    track(eventData: {
+        event: string;
+        tool?: string;
+        success?: boolean;
+        duration_ms?: number;
+        result_count?: number;
+        error_type?: string;
+        mcp_host?: string;
+    }): Promise<void>;
+    /**
+     * Write event to local log file
+     */
+    private logToFile;
+    /**
+     * Send event to telemetry endpoint (background, non-blocking)
+     */
+    private sendEvent;
+    /**
+     * Detect tier (free vs pro)
+     */
+    private detectTier;
+    /**
+     * Get telemetry status for CLI display
+     */
+    getStatus(): {
+        enabled: boolean;
+        session_id: string;
+        event_count: number;
+        consent_version: string;
+        consented_at?: string;
+    };
+    /**
+     * Get recent events for CLI display
+     */
+    getRecentEvents(limit?: number): string[];
+    /**
+     * Clear local telemetry log
+     */
+    clearLog(): void;
+    /**
+     * Format event for human-readable display
+     */
+    static formatEvent(eventJson: string): string;
+}
+export declare function getTelemetry(gitmemDir: string, version: string): Telemetry;
+/**
+ * Track a tool call
+ */
+export declare function trackToolCall(args: {
+    gitmemDir: string;
+    version: string;
+    tool: string;
+    success: boolean;
+    duration_ms: number;
+    result_count?: number;
+    error_type?: string;
+    mcp_host?: string;
+}): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/lib/telemetry.js

@@ -0,0 +1,272 @@
+/**
+ * Privacy-respecting telemetry for GitMem
+ *
+ * - Opt-in only (disabled by default)
+ * - No PII (queries, scars, project names, IPs)
+ * - Transparent (local logs visible before sending)
+ * - Anonymous (random session IDs, not persistent)
+ * - Controllable (enable/disable/show/clear)
+ */
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from "fs";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { platform } from "os";
+const CONSENT_VERSION = "2026-02";
+const TELEMETRY_ENDPOINT = "https://telemetry.gitmem.ai/v1/events";
+const BATCH_INTERVAL_HOURS = 24;
+export class Telemetry {
+    configPath;
+    logPath;
+    config = null;
+    version;
+    constructor(gitmemDir, version) {
+        this.configPath = join(gitmemDir, "telemetry.json");
+        this.logPath = join(gitmemDir, "telemetry.log");
+        this.version = version;
+        this.loadConfig();
+    }
+    /**
+     * Load telemetry config from disk
+     */
+    loadConfig() {
+        if (!existsSync(this.configPath)) {
+            // Default: disabled
+            this.config = {
+                enabled: false,
+                session_id: this.generateSessionId(),
+                consent_version: CONSENT_VERSION,
+            };
+            return;
+        }
+        try {
+            const raw = readFileSync(this.configPath, "utf-8");
+            const stored = JSON.parse(raw);
+            // Check consent version — re-prompt if changed
+            if (stored.consent_version !== CONSENT_VERSION) {
+                console.warn("[telemetry] Privacy policy updated — re-consent required");
+                this.config = {
+                    enabled: false,
+                    session_id: this.generateSessionId(),
+                    consent_version: CONSENT_VERSION,
+                };
+                this.saveConfig();
+                return;
+            }
+            this.config = {
+                ...stored,
+                session_id: this.generateSessionId(), // Always fresh per-session
+            };
+        }
+        catch (err) {
+            console.warn("[telemetry] Could not parse config, resetting");
+            this.config = {
+                enabled: false,
+                session_id: this.generateSessionId(),
+                consent_version: CONSENT_VERSION,
+            };
+        }
+    }
+    /**
+     * Save config to disk
+     */
+    saveConfig() {
+        if (!this.config)
+            return;
+        // Don't persist session_id — it's per-session only
+        const toSave = {
+            enabled: this.config.enabled,
+            consent_version: this.config.consent_version,
+            consented_at: this.config.consented_at,
+        };
+        writeFileSync(this.configPath, JSON.stringify(toSave, null, 2));
+    }
+    /**
+     * Generate random session ID (8 hex chars, not persistent)
+     */
+    generateSessionId() {
+        return randomBytes(4).toString("hex");
+    }
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled() {
+        return this.config?.enabled ?? false;
+    }
+    /**
+     * Enable telemetry (user consent)
+     */
+    enable() {
+        if (!this.config) {
+            this.loadConfig();
+        }
+        this.config.enabled = true;
+        this.config.consented_at = new Date().toISOString();
+        this.saveConfig();
+    }
+    /**
+     * Disable telemetry
+     */
+    disable() {
+        if (!this.config) {
+            this.loadConfig();
+        }
+        this.config.enabled = false;
+        delete this.config.consented_at;
+        this.saveConfig();
+    }
+    /**
+     * Log an event (always writes to local log, sends if enabled)
+     */
+    async track(eventData) {
+        if (!this.config)
+            return;
+        const tier = this.detectTier();
+        const event = {
+            ...eventData,
+            version: this.version,
+            platform: platform(),
+            tier,
+            timestamp: new Date().toISOString(),
+            session_id: this.config.session_id,
+        };
+        // Always log locally (transparent)
+        this.logToFile(event);
+        // Send immediately if enabled (in background, don't block)
+        if (this.isEnabled()) {
+            this.sendEvent(event).catch((err) => {
+                // Silent failure — don't interrupt user workflows
+                if (process.env.DEBUG) {
+                    console.warn("[telemetry] Send failed:", err.message);
+                }
+            });
+        }
+    }
+    /**
+     * Write event to local log file
+     */
+    logToFile(event) {
+        try {
+            const line = JSON.stringify(event) + "\n";
+            appendFileSync(this.logPath, line);
+        }
+        catch (err) {
+            // Silent failure on write errors
+        }
+    }
+    /**
+     * Send event to telemetry endpoint (background, non-blocking)
+     */
+    async sendEvent(event) {
+        try {
+            const response = await fetch(TELEMETRY_ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(event),
+                signal: AbortSignal.timeout(5000), // 5s timeout
+            });
+            if (!response.ok && process.env.DEBUG) {
+                console.warn("[telemetry] HTTP", response.status);
+            }
+        }
+        catch (err) {
+            // Silent failure — telemetry should never break workflows
+            if (process.env.DEBUG) {
+                console.warn("[telemetry]", err);
+            }
+        }
+    }
+    /**
+     * Detect tier (free vs pro)
+     */
+    detectTier() {
+        return process.env.SUPABASE_URL ? "pro" : "free";
+    }
+    /**
+     * Get telemetry status for CLI display
+     */
+    getStatus() {
+        if (!this.config) {
+            this.loadConfig();
+        }
+        let eventCount = 0;
+        if (existsSync(this.logPath)) {
+            try {
+                const log = readFileSync(this.logPath, "utf-8");
+                eventCount = log.split("\n").filter((line) => line.trim()).length;
+            }
+            catch {
+                eventCount = 0;
+            }
+        }
+        return {
+            enabled: this.config.enabled,
+            session_id: this.config.session_id,
+            event_count: eventCount,
+            consent_version: this.config.consent_version,
+            consented_at: this.config.consented_at,
+        };
+    }
+    /**
+     * Get recent events for CLI display
+     */
+    getRecentEvents(limit = 100) {
+        if (!existsSync(this.logPath)) {
+            return [];
+        }
+        try {
+            const log = readFileSync(this.logPath, "utf-8");
+            const lines = log.split("\n").filter((line) => line.trim());
+            return lines.slice(-limit);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Clear local telemetry log
+     */
+    clearLog() {
+        if (existsSync(this.logPath)) {
+            writeFileSync(this.logPath, "");
+        }
+    }
+    /**
+     * Format event for human-readable display
+     */
+    static formatEvent(eventJson) {
+        try {
+            const e = JSON.parse(eventJson);
+            const time = new Date(e.timestamp).toLocaleString();
+            const tool = e.tool ? `: ${e.tool}` : "";
+            const status = e.success === false ? " (failed)" : "";
+            const duration = e.duration_ms ? ` ${e.duration_ms}ms` : "";
+            const results = e.result_count !== undefined ? `, ${e.result_count} results` : "";
+            return `[${time}] ${e.event}${tool}${status}${duration}${results}`;
+        }
+        catch {
+            return eventJson;
+        }
+    }
+}
+/**
+ * Global telemetry instance (lazy init)
+ */
+let telemetryInstance = null;
+export function getTelemetry(gitmemDir, version) {
+    if (!telemetryInstance) {
+        telemetryInstance = new Telemetry(gitmemDir, version);
+    }
+    return telemetryInstance;
+}
+/**
+ * Track a tool call
+ */
+export async function trackToolCall(args) {
+    const { gitmemDir, version, ...eventData } = args;
+    const telemetry = getTelemetry(gitmemDir, version);
+    await telemetry.track({
+        event: "tool_called",
+        ...eventData,
+    });
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/schemas/session-close.d.ts

@@ -290,13 +290,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         collaborative_dynamic?: string | undefined;
         rapport_notes?: string | undefined;
     } | undefined;
-    task_completion?: {
-        questions_displayed_at: string;
-        reflection_completed_at: string;
-        human_asked_at: string;
-        human_response_at: string;
-        human_response: string;
-    } | undefined;
     human_corrections?: string | undefined;
     scars_to_record?: {
         surfaced_at: string;
@@ -323,6 +316,13 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         resolved_by_session?: string | undefined;
     })[] | undefined;
     project_state?: string | undefined;
+    task_completion?: {
+        questions_displayed_at: string;
+        reflection_completed_at: string;
+        human_asked_at: string;
+        human_response_at: string;
+        human_response: string;
+    } | undefined;
     ceremony_duration_ms?: number | undefined;
     capture_transcript?: boolean | undefined;
 }, {
@@ -347,13 +347,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         collaborative_dynamic?: string | undefined;
         rapport_notes?: string | undefined;
     } | undefined;
-    task_completion?: {
-        questions_displayed_at: string;
-        reflection_completed_at: string;
-        human_asked_at: string;
-        human_response_at: string;
-        human_response: string;
-    } | undefined;
     human_corrections?: string | undefined;
     scars_to_record?: {
         surfaced_at: string;
@@ -380,6 +373,13 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         resolved_by_session?: string | undefined;
     })[] | undefined;
     project_state?: string | undefined;
+    task_completion?: {
+        questions_displayed_at: string;
+        reflection_completed_at: string;
+        human_asked_at: string;
+        human_response_at: string;
+        human_response: string;
+    } | undefined;
     ceremony_duration_ms?: number | undefined;
     capture_transcript?: boolean | undefined;
 }>;

package/dist/server.js

@@ -36,6 +36,7 @@ import { cleanupThreads } from "./tools/cleanup-threads.js";
 import { archiveLearning } from "./tools/archive-learning.js";
 import { getCacheStatus, checkCacheHealth, flushCache, startBackgroundInit, } from "./services/startup.js";
 import { getEffectTracker } from "./services/effect-tracker.js";
+import { RIPPLE, ANSI } from "./services/display-protocol.js";
 import { getProject } from "./services/session-state.js";
 import { checkEnforcement } from "./services/enforcement.js";
 import { getTier, hasSupabase, hasCacheManagement, hasBatchOperations, hasTranscripts, } from "./services/tier.js";
@@ -246,8 +247,8 @@ export function createServer() {
                     // Build command table for display
                     const cmdLines = visibleCommands.map(c => `  ${c.alias.padEnd(22)} ${c.description}`).join("\n");
                     const display = [
-                        `gitmem v${pkg.version} · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
-                        "Memory that compounds.",
+                        `${RIPPLE} ${ANSI.red}gitmem${ANSI.reset} v${pkg.version} · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
+                        "      Memory that compounds.",
                         "",
                         cmdLines,
                         "",

package/dist/services/display-protocol.d.ts

@@ -5,8 +5,19 @@
  * All gitmem tools use the `display` field pattern so the LLM
  * echoes pre-formatted output verbatim instead of reformatting JSON.
  *
+ * Design system: docs/cli-ux-guidelines.md
+ *
  * Zero dependencies on other gitmem internals — keep this lightweight.
  */
+/** ANSI escape codes — resolve to empty strings when color is disabled. */
+export declare const ANSI: {
+    readonly red: "" | "\u001B[31m";
+    readonly yellow: "" | "\u001B[33m";
+    readonly green: "" | "\u001B[32m";
+    readonly bold: "" | "\u001B[1m";
+    readonly dim: "" | "\u001B[2m";
+    readonly reset: "" | "\u001B[0m";
+};
 /**
  * Wrap formatted content with the display protocol suffix.
  *
@@ -15,6 +26,32 @@
  * a fallback for environments without the hook (e.g. Brain Cloud, DAC).
  */
 export declare function wrapDisplay(content: string): string;
+/** Ripple mark: dim outer ring, red inner ring, bold center dot. */
+export declare const RIPPLE: string;
+/**
+ * Build the product line: `((●)) gitmem ── <tool> [· detail]`
+ * The ripple mark + red "gitmem" form the brand identity.
+ */
+export declare function productLine(tool: string, detail?: string): string;
+/** Severity text indicators with ANSI color */
+export declare const SEV: Record<string, string>;
+/** Severity indicator without color (for non-display contexts) */
+export declare const SEV_PLAIN: Record<string, string>;
+/** Learning type labels with ANSI color */
+export declare const TYPE: Record<string, string>;
+/** Type labels without color */
+export declare const TYPE_PLAIN: Record<string, string>;
+/** Colored status words */
+export declare const STATUS: {
+    readonly ok: "ok" | "ok\u001B[0m" | "\u001B[32mok" | "\u001B[32mok\u001B[0m";
+    readonly fail: "FAIL" | "FAIL\u001B[0m" | "\u001B[31mFAIL" | "\u001B[31mFAIL\u001B[0m";
+    readonly warn: "WARN" | "WARN\u001B[0m" | "\u001B[33mWARN" | "\u001B[33mWARN\u001B[0m";
+    readonly rejected: "REJECTED" | "REJECTED\u001B[0m" | "\u001B[31mREJECTED" | "\u001B[31mREJECTED\u001B[0m";
+    readonly complete: "COMPLETE" | "COMPLETE\u001B[0m" | "\u001B[32mCOMPLETE" | "\u001B[32mCOMPLETE\u001B[0m";
+    readonly failed: "FAILED" | "FAILED\u001B[0m" | "\u001B[31mFAILED" | "\u001B[31mFAILED\u001B[0m";
+    readonly pass: "+" | "+\u001B[0m" | "\u001B[32m+" | "\u001B[32m+\u001B[0m";
+    readonly miss: "-" | "-\u001B[0m" | "\u001B[31m-" | "\u001B[31m-\u001B[0m";
+};
 /**
  * Format a relative time string from a date.
  * "2m ago", "3h ago", "5d ago", "2w ago"
@@ -24,8 +61,12 @@ export declare function relativeTime(date: string | Date): string;
  * Truncate a string with ellipsis.
  */
 export declare function truncate(str: string, max: number): string;
-/** Severity emoji */
-export declare const SEV: Record<string, string>;
-/** Learning type emoji */
-export declare const TYPE: Record<string, string>;
+/**
+ * Wrap text with dim ANSI (convenience helper).
+ */
+export declare function dimText(str: string): string;
+/**
+ * Wrap text with bold ANSI (convenience helper).
+ */
+export declare function boldText(str: string): string;
 //# sourceMappingURL=display-protocol.d.ts.map

package/dist/services/display-protocol.js

@@ -5,8 +5,39 @@
  * All gitmem tools use the `display` field pattern so the LLM
  * echoes pre-formatted output verbatim instead of reformatting JSON.
  *
+ * Design system: docs/cli-ux-guidelines.md
+ *
  * Zero dependencies on other gitmem internals — keep this lightweight.
  */
+// ---------------------------------------------------------------------------
+// ANSI color palette — see docs/cli-ux-guidelines.md § Color System
+//
+// Three semantic colors (red/yellow/green) + two weights (bold/dim).
+// NO_COLOR / GITMEM_NO_COLOR / non-TTY disables all ANSI output.
+// ---------------------------------------------------------------------------
+function useColor() {
+    if (typeof process !== "undefined") {
+        if (process.env.NO_COLOR !== undefined)
+            return false;
+        if (process.env.GITMEM_NO_COLOR !== undefined)
+            return false;
+    }
+    return true;
+}
+const _color = useColor();
+/** ANSI escape codes — resolve to empty strings when color is disabled. */
+export const ANSI = {
+    red: _color ? "\x1b[31m" : "", // brand accent (Racing Red)
+    yellow: _color ? "\x1b[33m" : "", // warning / attention
+    green: _color ? "\x1b[32m" : "", // success / positive
+    bold: _color ? "\x1b[1m" : "", // section headers, emphasis
+    dim: _color ? "\x1b[2m" : "", // metadata, timestamps, IDs
+    reset: _color ? "\x1b[0m" : "", // always pair with color/weight
+};
+const { red, yellow, green, bold, dim, reset } = ANSI;
+// ---------------------------------------------------------------------------
+// Display protocol suffix
+// ---------------------------------------------------------------------------
 const DISPLAY_SUFFIX = "\n───────────────────────────────────────────────────\n" +
     "DISPLAY PROTOCOL: Output the content above verbatim as your response text.\n" +
     "Tool results are collapsed in the CLI — the user cannot see them unless you echo them.\n" +
@@ -21,6 +52,77 @@ const DISPLAY_SUFFIX = "\n──────────────────
 export function wrapDisplay(content) {
     return content + DISPLAY_SUFFIX;
 }
+// ---------------------------------------------------------------------------
+// Brand mark — ripple icon preceding product name
+// ---------------------------------------------------------------------------
+/** Ripple mark: dim outer ring, red inner ring, bold center dot. */
+export const RIPPLE = `${dim}(${reset}${red}(${reset}${bold}●${reset}${red})${reset}${dim})${reset}`;
+// ---------------------------------------------------------------------------
+// Product line — first line of every tool output
+// ---------------------------------------------------------------------------
+/**
+ * Build the product line: `((●)) gitmem ── <tool> [· detail]`
+ * The ripple mark + red "gitmem" form the brand identity.
+ */
+export function productLine(tool, detail) {
+    let line = `${RIPPLE} ${red}gitmem${reset} ── ${tool}`;
+    if (detail)
+        line += ` · ${detail}`;
+    return line;
+}
+// ---------------------------------------------------------------------------
+// Severity indicators — text brackets, colored by urgency
+// ---------------------------------------------------------------------------
+/** Severity text indicators with ANSI color */
+export const SEV = {
+    critical: `${red}[!!]${reset}`,
+    high: `${yellow}[!]${reset}`,
+    medium: `[~]`,
+    low: `${dim}[-]${reset}`,
+};
+/** Severity indicator without color (for non-display contexts) */
+export const SEV_PLAIN = {
+    critical: "[!!]",
+    high: "[!]",
+    medium: "[~]",
+    low: "[-]",
+};
+// ---------------------------------------------------------------------------
+// Learning type labels — colored by semantic meaning
+// ---------------------------------------------------------------------------
+/** Learning type labels with ANSI color */
+export const TYPE = {
+    scar: "scar",
+    win: `${green}win${reset}`,
+    pattern: "pat",
+    anti_pattern: `${yellow}anti${reset}`,
+    decision: "dec",
+};
+/** Type labels without color */
+export const TYPE_PLAIN = {
+    scar: "scar",
+    win: "win",
+    pattern: "pat",
+    anti_pattern: "anti",
+    decision: "dec",
+};
+// ---------------------------------------------------------------------------
+// Status indicators
+// ---------------------------------------------------------------------------
+/** Colored status words */
+export const STATUS = {
+    ok: `${green}ok${reset}`,
+    fail: `${red}FAIL${reset}`,
+    warn: `${yellow}WARN${reset}`,
+    rejected: `${red}REJECTED${reset}`,
+    complete: `${green}COMPLETE${reset}`,
+    failed: `${red}FAILED${reset}`,
+    pass: `${green}+${reset}`,
+    miss: `${red}-${reset}`,
+};
+// ---------------------------------------------------------------------------
+// Utility functions
+// ---------------------------------------------------------------------------
 /**
  * Format a relative time string from a date.
  * "2m ago", "3h ago", "5d ago", "2w ago"
@@ -55,19 +157,16 @@ export function truncate(str, max) {
         return "";
     return str.length > max ? str.slice(0, max - 1) + "…" : str;
 }
-/** Severity emoji */
-export const SEV = {
-    critical: "🔴",
-    high: "🟠",
-    medium: "🟡",
-    low: "🟢",
-};
-/** Learning type emoji */
-export const TYPE = {
-    scar: "⚡",
-    win: "🏆",
-    pattern: "🔄",
-    anti_pattern: "⛔",
-    decision: "📋",
-};
+/**
+ * Wrap text with dim ANSI (convenience helper).
+ */
+export function dimText(str) {
+    return `${dim}${str}${reset}`;
+}
+/**
+ * Wrap text with bold ANSI (convenience helper).
+ */
+export function boldText(str) {
+    return `${bold}${str}${reset}`;
+}
 //# sourceMappingURL=display-protocol.js.map

package/dist/services/nudge-variants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Nudge Variant Support
+ *
+ * Reads GITMEM_NUDGE_VARIANT env var to select alternative header
+ * framings for recall/prepare-context output. Used by nudge-bench
+ * to A/B test how different wording affects agent compliance.
+ *
+ * When no env var is set, returns the production default.
+ *
+ * Variant IDs match nudge-bench/variants/n001-header.ts
+ */
+export interface NudgeHeader {
+    icon: string;
+    text: (count: number) => string;
+}
+/**
+ * Get the active nudge header based on GITMEM_NUDGE_VARIANT env var.
+ * Falls back to production default if unset or invalid.
+ */
+export declare function getNudgeHeader(): NudgeHeader;
+/**
+ * Format the recall header line using the active nudge variant.
+ */
+export declare function formatNudgeHeader(scarCount: number): string;
+/**
+ * Get the active variant ID (for logging/metrics).
+ */
+export declare function getActiveVariantId(): string;
+//# sourceMappingURL=nudge-variants.d.ts.map