linksee-memory 0.0.2 → 0.0.4

package/README.md

@@ -139,6 +139,46 @@ Claude Code ships a built-in memory feature at `~/.claude/projects/<path>/memory
 
 Use both.
 
+## Telemetry (opt-in, off by default)
+
+linksee-memory ships with **opt-in** anonymous telemetry that helps us understand which MCP servers and workflows actually work in the wild. **Nothing is sent unless you explicitly enable it.** No conversation content, no file content, no entity names, no project paths — ever.
+
+### Enable
+
+```bash
+export LINKSEE_TELEMETRY=basic     # opt in
+export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)
+```
+
+### Exactly what gets sent (Level 1 contract)
+
+After each Claude Code session ends, the Stop hook sends one POST to `https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee` containing only these fields:
+
+| Field | Example | What it is |
+|---|---|---|
+| `anon_id` | `d7924ced-3879-…` | Random UUID generated locally on first opt-in. Stored at `~/.linksee-memory/telemetry-id` — delete the file to reset. |
+| `linksee_version` | `0.0.3` | Package version |
+| `session_turn_count` | `120` | How many turns the session had |
+| `session_duration_sec` | `3600` | How long the session lasted |
+| `file_ops_edit/write/read` | `12, 2, 40` | Counts only |
+| `mcp_servers` | `["kansei-link","freee","slack"]` | Names of MCP servers configured (from `~/.claude.json`). Names only — never command paths. |
+| `file_extensions` | `{".ts":60,".md":30}` | Percent distribution of file extensions touched |
+| `read_smart_*`, `recall_*` | counts | Tool usage counters |
+
+**What is NEVER sent**:
+- ❌ Conversation messages (user or assistant)
+- ❌ File contents
+- ❌ Entity names, project names, file paths, URLs
+- ❌ Memory-layer text (goal / context / emotion / impl / caveat / learning)
+- ❌ Authentication tokens, API keys, secrets
+- ❌ Your IP address (only a one-way hash for abuse detection)
+
+### Why we ask
+
+Aggregated MCP-usage data helps the [KanseiLink](https://kansei-link.com) project rank which agent integrations actually work for real developers. If you're happy to contribute, `LINKSEE_TELEMETRY=basic` takes 1 second to set and helps the entire MCP ecosystem improve.
+
+The full payload schema and validation logic is open-source — read `src/lib/telemetry.ts` if you want to verify exactly what leaves your machine.
+
 ## License
 
 MIT — Synapse Arrows PTE. LTD.

package/dist/bin/sync-session.js

@@ -10,10 +10,12 @@
 //   - MUST be silent on stdout (Claude does not need feedback)
 //   - All errors logged to ~/.linksee-memory/hook.log
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, appendFileSync, existsSync, statSync, renameSync } from 'node:fs';
+import { mkdirSync, appendFileSync, existsSync, statSync, renameSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { isTelemetryEnabled, buildPayload, sendTelemetry } from '../lib/telemetry.js';
+import Database from 'better-sqlite3';
 const LOG_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
 const LOG_FILE = join(LOG_DIR, 'hook.log');
 const LOG_MAX_BYTES = 1024 * 1024; // 1 MB → rotate
@@ -80,13 +82,57 @@ async function main() {
     const elapsed = Date.now() - startedAt;
     if (r.error) {
         log(`importer spawn error (session=${sessionId}, ${elapsed}ms): ${r.error.message}`);
+        process.exit(0);
     }
     else if (r.status !== 0) {
         log(`importer exited ${r.status} (session=${sessionId}, ${elapsed}ms): ${(r.stderr || '').slice(0, 500)}`);
+        process.exit(0);
     }
-    else {
-        const out = (r.stdout || '').trim().split('\n').slice(-1)[0] || '';
-        log(`ok (session=${sessionId}, cwd=${cwd}, ${elapsed}ms): ${out}`);
+    const out = (r.stdout || '').trim().split('\n').slice(-1)[0] || '';
+    log(`ok (session=${sessionId}, cwd=${cwd}, ${elapsed}ms): ${out}`);
+    // ── Opt-in telemetry (LINKSEE_TELEMETRY=basic) ──────────────────
+    // Runs ONLY if explicitly enabled. Failures are silent. Never blocks Claude Code.
+    if (isTelemetryEnabled() && sessionId) {
+        try {
+            // Detect MCP servers in use from BOTH ~/.claude.json and ~/.claude/settings.json
+            // (Claude Code reads both — names only, never commands or arg paths.)
+            const mcpServerSet = new Set();
+            for (const confPath of [join(homedir(), '.claude.json'), join(homedir(), '.claude', 'settings.json')]) {
+                try {
+                    if (!existsSync(confPath))
+                        continue;
+                    const parsed = JSON.parse(readFileSync(confPath, 'utf8'));
+                    if (parsed && typeof parsed.mcpServers === 'object' && parsed.mcpServers) {
+                        for (const name of Object.keys(parsed.mcpServers)) {
+                            mcpServerSet.add(String(name).slice(0, 64));
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            const mcpServers = Array.from(mcpServerSet);
+            const dbDir = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
+            const dbPath = join(dbDir, 'memory.db');
+            if (existsSync(dbPath)) {
+                const db = new Database(dbPath, { readonly: true });
+                try {
+                    const payload = buildPayload(db, sessionId, { mcpServersInUse: mcpServers });
+                    if (payload) {
+                        const result = await sendTelemetry(payload, { timeoutMs: 3000 });
+                        if (result.ok)
+                            log(`telemetry: sent (anon=${payload.anon_id.slice(0, 8)}, mcp=${mcpServers.length}, exts=${Object.keys(payload.file_extensions).length})`);
+                        else
+                            log(`telemetry: send failed: ${result.error}`);
+                    }
+                }
+                finally {
+                    db.close();
+                }
+            }
+        }
+        catch (e) {
+            log(`telemetry: error (non-fatal): ${e?.message ?? e}`);
+        }
     }
     process.exit(0);
 }

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,31 @@
+import type Database from 'better-sqlite3';
+export type TelemetryMode = 'off' | 'basic';
+export declare function getTelemetryMode(): TelemetryMode;
+export declare function getOrCreateAnonId(): string;
+interface TelemetryPayload {
+    anon_id: string;
+    linksee_version: string;
+    session_turn_count: number;
+    session_duration_sec: number;
+    file_ops_edit: number;
+    file_ops_write: number;
+    file_ops_read: number;
+    errors_count: number;
+    mcp_servers: string[];
+    file_extensions: Record<string, number>;
+    read_smart_savings_pct: number | null;
+    read_smart_calls: number;
+    recall_calls: number;
+    recall_file_calls: number;
+}
+export declare function buildPayload(db: Database.Database, sessionId: string, options?: {
+    mcpServersInUse?: string[];
+}): TelemetryPayload | null;
+export declare function sendTelemetry(payload: TelemetryPayload, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function isTelemetryEnabled(): boolean;
+export {};

package/dist/lib/telemetry.js

@@ -0,0 +1,143 @@
+// Opt-in, privacy-preserving telemetry for linksee-memory.
+//
+// PRIVACY CONTRACT (also documented in README):
+//   - DEFAULT OFF. Activated only when LINKSEE_TELEMETRY=basic.
+//   - Sends only Level 1 fields: aggregated counts and signal distributions.
+//   - NEVER sends conversation content, user messages, file content,
+//     entity names, project paths, or any layer text (goal/context/emotion/
+//     impl/caveat/learning content is not included).
+//   - Anonymous UUID generated locally on first opt-in; stored at
+//     ~/.linksee-memory/telemetry-id. User can delete it any time.
+//   - Disable any time: LINKSEE_TELEMETRY=off (or unset the variable).
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, extname, join as pathJoin, dirname as pathDirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+// Production endpoint hosted on Railway. (kansei-link.com is a GitHub Pages site;
+// the dynamic API lives on the Railway deployment.)
+const DEFAULT_ENDPOINT = 'https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee';
+// Allow override for testing or self-hosting
+const ENDPOINT = process.env.LINKSEE_TELEMETRY_URL || DEFAULT_ENDPOINT;
+const TELEMETRY_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
+const TELEMETRY_ID_FILE = join(TELEMETRY_DIR, 'telemetry-id');
+export function getTelemetryMode() {
+    const v = (process.env.LINKSEE_TELEMETRY || '').toLowerCase().trim();
+    if (v === 'basic' || v === 'on' || v === '1' || v === 'true')
+        return 'basic';
+    return 'off';
+}
+export function getOrCreateAnonId() {
+    try {
+        if (existsSync(TELEMETRY_ID_FILE)) {
+            const id = readFileSync(TELEMETRY_ID_FILE, 'utf8').trim();
+            if (/^[A-Za-z0-9_-]{8,64}$/.test(id))
+                return id;
+        }
+    }
+    catch { /* ignore */ }
+    // Generate a fresh one
+    const id = randomUUID();
+    try {
+        mkdirSync(TELEMETRY_DIR, { recursive: true });
+        writeFileSync(TELEMETRY_ID_FILE, id);
+    }
+    catch { /* best-effort */ }
+    return id;
+}
+// Read package version from our own package.json (best-effort, ESM-safe)
+function getLinkseeVersion() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        // dist/lib/telemetry.js → ../../package.json
+        const pkgPath = pathJoin(pathDirname(pathDirname(pathDirname(here))), 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            return String(pkg.version || 'unknown');
+        }
+    }
+    catch { /* ignore */ }
+    return 'unknown';
+}
+// Build a payload from a single just-imported session.
+// All inputs come from session_file_edits + events; nothing reads memories.content.
+export function buildPayload(db, sessionId, options = {}) {
+    const eventRow = db.prepare(`SELECT payload, occurred_at FROM events WHERE kind = 'session_imported' AND payload LIKE ? ORDER BY id DESC LIMIT 1`).get(`%"session_id":"${sessionId}"%`);
+    // Aggregate file ops
+    const opsRows = db.prepare(`SELECT operation, COUNT(*) as c FROM session_file_edits WHERE session_id = ? GROUP BY operation`).all(sessionId);
+    const opCounts = { edit: 0, write: 0, read: 0 };
+    for (const r of opsRows)
+        opCounts[r.operation] = (opCounts[r.operation] || 0) + r.c;
+    // File extension distribution (anonymized — just extensions, never paths/names)
+    const extRows = db.prepare(`SELECT file_path FROM session_file_edits WHERE session_id = ?`).all(sessionId);
+    const extCounts = {};
+    for (const r of extRows) {
+        const ext = (extname(r.file_path) || '(none)').toLowerCase().slice(0, 12);
+        extCounts[ext] = (extCounts[ext] || 0) + 1;
+    }
+    // Convert to percent distribution, drop low-count extensions to save space
+    const total = extRows.length || 1;
+    const extPct = {};
+    for (const [ext, count] of Object.entries(extCounts)) {
+        const pct = Math.round((count / total) * 100);
+        if (pct >= 1)
+            extPct[ext] = pct;
+    }
+    // Pull session metadata from the recorded event
+    let stats = {};
+    let durationSec = 0;
+    if (eventRow) {
+        try {
+            stats = JSON.parse(eventRow.payload).stats || {};
+        }
+        catch { }
+    }
+    const turnsTotal = stats.turns_total || 0;
+    // session start/end approximation
+    const tsRow = db.prepare(`SELECT MIN(occurred_at) as start, MAX(occurred_at) as end FROM session_file_edits WHERE session_id = ?`).get(sessionId);
+    if (tsRow && tsRow.start && tsRow.end)
+        durationSec = Math.max(0, tsRow.end - tsRow.start);
+    return {
+        anon_id: getOrCreateAnonId(),
+        linksee_version: getLinkseeVersion(),
+        session_turn_count: turnsTotal,
+        session_duration_sec: durationSec,
+        file_ops_edit: opCounts.edit || 0,
+        file_ops_write: opCounts.write || 0,
+        file_ops_read: opCounts.read || 0,
+        errors_count: 0, // session_extractor doesn't surface this currently; safe default
+        mcp_servers: (options.mcpServersInUse || []).slice(0, 50),
+        file_extensions: extPct,
+        read_smart_savings_pct: null, // wired up later when we track this per session
+        read_smart_calls: 0,
+        recall_calls: 0,
+        recall_file_calls: 0,
+    };
+}
+// Fire-and-forget POST. Any failure is silent (logged by caller).
+export async function sendTelemetry(payload, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    try {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeoutMs);
+        const res = await fetch(ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'user-agent': `linksee-memory/${payload.linksee_version}` },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        clearTimeout(t);
+        if (!res.ok) {
+            return { ok: false, error: `http_${res.status}` };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.name || e?.message || e).slice(0, 100) };
+    }
+}
+// Convenience: helper for caller to know if it should bother building a payload
+export function isTelemetryEnabled() {
+    return getTelemetryMode() !== 'off';
+}
+//# sourceMappingURL=telemetry.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Local-first agent memory MCP — cross-agent brain with 6-layer structured memory + token-saving file diff cache",
   "type": "module",
   "bin": {