becki-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,32 @@
+becki-mcp — Becki Core MCP server
+Copyright © 2026 BECKI.IO LLC
+
+All rights reserved.
+
+This npm package and its compiled JavaScript are distributed as a runtime
+client for the Becki service (https://www.becki.io). Use of this software
+requires a valid paid subscription and is governed by the Becki Terms of
+Service at https://www.becki.io/terms and the End User License Agreement
+at https://www.becki.io/eula.
+
+You are permitted to:
+  - Install this package and run the `becki-mcp` binary on machines you own
+    or control, for personal or business use, in conjunction with a valid
+    Becki subscription tied to your account.
+  - Inspect the compiled JavaScript for security or compatibility purposes.
+
+You are NOT permitted to:
+  - Redistribute this package, its source, or modified versions.
+  - Reverse-engineer, decompile, or extract the binary for purposes of
+    creating a competing product or service.
+  - Use this software with any backend other than the official Becki
+    backend operated by BECKI.IO LLC, except where explicitly authorized
+    in writing.
+  - Remove or modify the copyright notices, the LICENSE file, or any
+    notices embedded in the source.
+
+This software is provided "as-is" without warranty of any kind, express or
+implied. BECKI.IO LLC will not be liable for any damages arising from the
+use or inability to use this software.
+
+For licensing inquiries, contact: legal@becki.io

package/README.md

@@ -0,0 +1,142 @@
+# becki-mcp
+
+**[Becki](https://www.becki.io) Core — cross-platform memory layer for AI tools.**
+
+A Model Context Protocol (MCP) server that gives Claude, Cursor, Codex, ChatGPT,
+and any MCP-compatible client persistent, structured memory across every session,
+project, and machine.
+
+- 🧠 **Structured memory** — decisions, commitments, asks, dead-ends, open loops (not just notes)
+- 🔄 **AI session bootstrap** — auto-indexes your existing Claude Code / Codex / Cursor history
+- 📁 **Project sweeper** — watches your repos, extracts intent from git activity
+- 🌍 **Cross-platform** — Windows, macOS, Linux
+- 🔐 **Auth-scoped** — per-install token, server-issued, revocable from the dashboard
+
+Requires a paid Becki subscription. Sign up at [becki.io/account](https://www.becki.io/account)
+($15/month, monthly billing).
+
+---
+
+## Install
+
+```bash
+npm install -g becki-mcp
+```
+
+Requires **Node.js 20+**. Works on Windows, macOS, and Linux.
+
+## Setup
+
+Generate an install token at [becki.io/account](https://www.becki.io/account), then:
+
+```bash
+becki-mcp init
+```
+
+This will:
+1. Scan common project directories (`~/Documents`, `~/Repos`, `~/Code`, `~/src`, `~/Projects`, `~/Developer`) for git repos
+2. Prompt to register them as Becki projects
+3. Print the MCP config snippet to paste into your AI client
+
+Add custom scan paths with `--scan <path>` (repeatable) or auto-confirm everything with `--yes`.
+
+## Configure your AI client
+
+After `becki-mcp init`, add the printed snippet to your AI client's MCP config:
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
+(Mac) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "becki": {
+      "command": "becki-mcp"
+    }
+  }
+}
+```
+
+**Cursor / Windsurf / Codex CLI / Zed** — same structure, under `mcpServers`.
+
+Restart your AI client. The `becki_*` tools will appear.
+
+## Backfill your AI session history
+
+To ingest the last 90 days of Claude Code / Codex CLI / Cursor sessions:
+
+```bash
+becki-mcp bootstrap
+```
+
+Or specify a custom window:
+
+```bash
+becki-mcp bootstrap 30    # last 30 days
+```
+
+Bootstrap is idempotent — files already processed are tracked in the local
+SQLite cache and skipped on re-run.
+
+## Daily digest
+
+A background daily digest runs automatically when the MCP server is invoked by
+your AI client (it kicks off after the first request and re-runs every 12h).
+You can also run it manually:
+
+```bash
+becki-mcp digest
+```
+
+## Local files
+
+becki-mcp stores configuration and a local cache at:
+
+- **Default:** `~/.becki/` (Windows: `%USERPROFILE%\.becki\`)
+- **Mac with Becki Studio installed:** `~/Library/Application Support/Becki/` (shared with the Mac app)
+- **Override:** set the `BECKI_HOME` env variable
+
+The cache (`cache.db`) is a SQLite file holding:
+- Project registrations
+- AI session index (paths + last-processed sizes for idempotency)
+- Recent vault rows for fast MCP reads
+- Daily digest state
+
+No audio, no transcripts, no model weights. Footprint typically 10–100 MB
+depending on AI history depth.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `becki-mcp` | Run MCP stdio server (used by AI clients — your normal config target) |
+| `becki-mcp init` | First-time setup; register projects + print MCP config snippet |
+| `becki-mcp digest` | Run today's session-digest sweep right now |
+| `becki-mcp bootstrap [N]` | Historical ingest of AI session logs (default 90 days) |
+| `becki-mcp --help` | Show usage |
+
+## Privacy
+
+- Your install token authenticates only to the Becki backend (Supabase) — no third parties.
+- All ingested content goes to **your private vault**. Per-user row-level security enforced at the database level.
+- AI session logs are read locally — only extracted *entities* (decisions / commitments / asks / dead-ends) are sent to the backend, never raw transcripts.
+- Becki uses Anthropic Haiku for extraction and Voyage AI for embeddings. Both are on no-train policies — your data is never used for model training.
+
+## Becki Studio (Mac users)
+
+If you want **meeting capture** (on-device transcription), the native Mac app
+with the **NeuraVault 3D graph**, and the full visual interface, upgrade to
+[Becki Studio](https://www.becki.io/pricing) ($25/month). Studio bundles
+becki-mcp, so you don't need to install it separately.
+
+## Support
+
+- **Docs:** https://www.becki.io
+- **Issues:** https://github.com/bdsantosDEV/becki-vault/issues
+- **Email:** support@becki.io
+
+## License
+
+Copyright © 2026 BECKI.IO LLC. All rights reserved. Use of this package is
+governed by the Becki [Terms of Service](https://www.becki.io/terms) and a
+valid paid subscription. See [LICENSE](./LICENSE) for distribution terms.

package/dist/core/ai-sessions.js

@@ -0,0 +1,325 @@
+// ai-sessions.ts — Cross-platform AI session log indexer for Becki Core
+//                  (#191 sub-task 3). Port of AISessionWatcher.swift.
+//
+// Scans `~/.claude/projects/**/*.jsonl` (Claude Code) and
+// `~/.codex/sessions/**/*.jsonl` (Codex CLI) for AI tool conversations,
+// extracts decisions / commitments / dead-ends / open-loops via the
+// Becki extraction endpoint, and ingests results into NeuraVault.
+//
+// Two entry points:
+//   runDailyDigest()       — daily sweep: settled sessions (1–7 days old,
+//                            >1h since last activity) only
+//   runHistoricalBootstrap — full retroactive sweep on first run
+//                            (optional age-range slider)
+//
+// Idempotency: tracks per-file size in `ai_session_state` (BeckiCache).
+// Re-ingest only when a file grows.
+//
+// MAC-SPECIFIC PIECES PORTED:
+//   NSBackgroundActivityScheduler   → setInterval-based scheduler in runner.ts
+//   NSHomeDirectory + FileManager   → os.homedir() + fs.promises
+//   UserDefaults                    → BeckiCache.config()
+//
+// EXTRACTION CALL: stubbed via the `extract` injection so this module stays
+// transport-agnostic. The real wiring (Becki backend HTTP call or local
+// Anthropic SDK call) happens in runner.ts based on what credentials Core
+// is configured with.
+import { readdir, stat, readFile } from "fs/promises";
+import { join, basename } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+// ── Constants ───────────────────────────────────────────────────────────────
+const MIN_TURNS = 5;
+const MIN_BYTES = 1024;
+const MAX_TRANSCRIPT_CHARS = 40_000;
+const SETTLED_MIN_AGE_MS = 60 * 60 * 1000; // 1h
+const SETTLED_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7d
+const DAILY_TOKEN_CAP_DEFAULT = 80_000; // ~$0.10/day at Haiku rates
+const CONFIG_KEYS = {
+    enabled: "aiSessionWatcher.enabled",
+    lastDigestAt: "aiSessionWatcher.lastDigestAt",
+    dailyBudgetUsed: "aiSessionWatcher.dailyBudgetUsedToday",
+    dailyBudgetDate: "aiSessionWatcher.dailyBudgetDate",
+    dailyTokenCap: "aiSessionWatcher.dailyTokenCapHaiku",
+};
+// ── Discovery ───────────────────────────────────────────────────────────────
+const CLAUDE_DIR = join(homedir(), ".claude", "projects");
+const CODEX_DIR = join(homedir(), ".codex", "sessions");
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursively walk `dir` collecting all `.jsonl` paths. Caps depth at 8 to
+ *  avoid runaway symlink loops on unusual user setups. */
+async function walkJsonl(dir, depth = 0) {
+    if (depth > 8)
+        return [];
+    if (!(await exists(dir)))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const ent of entries) {
+        const full = join(dir, ent.name);
+        if (ent.isDirectory()) {
+            out.push(...(await walkJsonl(full, depth + 1)));
+        }
+        else if (ent.isFile() && full.endsWith(".jsonl")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/** Discover all AI session files on disk (both Claude Code and Codex). */
+export async function discoverAllSessions() {
+    const claudePaths = await walkJsonl(CLAUDE_DIR);
+    const codexPaths = await walkJsonl(CODEX_DIR);
+    const all = [];
+    for (const p of claudePaths) {
+        try {
+            const s = await stat(p);
+            all.push({ path: p, source: "claude-code-session", size: s.size, mtimeMs: s.mtimeMs });
+        }
+        catch { /* skip */ }
+    }
+    for (const p of codexPaths) {
+        try {
+            const s = await stat(p);
+            all.push({ path: p, source: "codex-cli-session", size: s.size, mtimeMs: s.mtimeMs });
+        }
+        catch { /* skip */ }
+    }
+    return all;
+}
+/** Filter to sessions eligible for the daily digest:
+ *    - modified 1h–7d ago (settled, not active)
+ *    - grew since last seen (size strictly greater) */
+export function selectSettled(candidates, cache) {
+    const now = Date.now();
+    return candidates.filter((s) => {
+        const ageMs = now - s.mtimeMs;
+        if (ageMs < SETTLED_MIN_AGE_MS)
+            return false;
+        if (ageMs > SETTLED_MAX_AGE_MS)
+            return false;
+        const prior = cache.getSessionState(s.path);
+        if (prior && s.size <= prior.file_size)
+            return false;
+        return true;
+    });
+}
+/** Parse a single jsonl file into a transcript string. Returns null if the
+ *  session is too small to be worth ingesting. */
+export async function parseSession(path) {
+    let buf;
+    try {
+        buf = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const rawSize = Buffer.byteLength(buf, "utf8");
+    if (rawSize < MIN_BYTES)
+        return null;
+    const lines = buf.split("\n");
+    let transcript = "";
+    let turnCount = 0;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!obj.type)
+            continue;
+        if (obj.type !== "user" && obj.type !== "assistant" && obj.type !== "message")
+            continue;
+        const msg = obj.message;
+        if (!msg?.role)
+            continue;
+        let text = null;
+        if (typeof msg.content === "string") {
+            text = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            const parts = [];
+            for (const part of msg.content) {
+                if (typeof part?.text === "string")
+                    parts.push(part.text);
+            }
+            text = parts.length > 0 ? parts.join("\n") : null;
+        }
+        if (!text || text.length === 0)
+            continue;
+        transcript += `[${msg.role.toUpperCase()}] ${text}\n\n`;
+        turnCount += 1;
+    }
+    if (turnCount < MIN_TURNS)
+        return null;
+    // Tail-cap: when the conversation is huge, the most recent turns are
+    // where the actionable content lives (decisions made today, not from a
+    // 2-week-old debugging session in the same thread).
+    if (transcript.length > MAX_TRANSCRIPT_CHARS) {
+        transcript = transcript.slice(-MAX_TRANSCRIPT_CHARS);
+    }
+    return { transcript, turnCount, charCount: transcript.length, rawSize };
+}
+// ── Slug (must match the Swift toSlug + the index.ts toSlug) ────────────────
+/** Lowercase, replace non-alphanumeric runs with `-`, trim, cap at 60.
+ *  Keep this identical to the Swift `slug(_)` for cross-source dedup. */
+export function toSlug(input) {
+    const lower = input.toLowerCase();
+    const collapsed = lower.replace(/[^a-z0-9]+/g, "-");
+    const trimmed = collapsed.replace(/^-+|-+$/g, "");
+    return trimmed.slice(0, 60);
+}
+/** Stable per-session sourceId: `YYYY-MM-DD-{slugOfSessionFileName}`.
+ *  Matches the Swift convention so server-side
+ *  `(user_id, source_type, source_id)` UNIQUE collides reliably. */
+export function makeSourceId(sessionPath, when = new Date()) {
+    const date = when.toISOString().slice(0, 10);
+    const stem = basename(sessionPath).replace(/\.jsonl$/i, "");
+    return `${date}-${toSlug(stem)}`;
+}
+// ── Token budget ────────────────────────────────────────────────────────────
+/** ~chars/4 token estimate (good enough for budget-tripping decisions). */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function todayKey() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Get-or-reset the daily Haiku budget counter. Resets at UTC date rollover. */
+function ensureBudgetWindow(cache) {
+    const today = todayKey();
+    const lastDate = cache.getConfig(CONFIG_KEYS.dailyBudgetDate);
+    if (lastDate !== today) {
+        cache.setConfig(CONFIG_KEYS.dailyBudgetDate, today);
+        cache.setConfig(CONFIG_KEYS.dailyBudgetUsed, "0");
+    }
+    const used = Number(cache.getConfig(CONFIG_KEYS.dailyBudgetUsed) ?? "0");
+    const cap = Number(cache.getConfig(CONFIG_KEYS.dailyTokenCap) ?? String(DAILY_TOKEN_CAP_DEFAULT));
+    return { used, cap };
+}
+function addBudgetUsage(cache, tokens) {
+    ensureBudgetWindow(cache);
+    const used = Number(cache.getConfig(CONFIG_KEYS.dailyBudgetUsed) ?? "0");
+    cache.setConfig(CONFIG_KEYS.dailyBudgetUsed, String(used + tokens));
+}
+export async function runDigest(opts) {
+    const log = opts.logger ?? (() => { });
+    const out = {
+        processed: 0, skippedSettled: 0, skippedNoGrowth: 0,
+        skippedTooSmall: 0, skippedTokenCap: 0, ingested: 0, errors: 0,
+    };
+    const all = await discoverAllSessions();
+    log(`ai-sessions: discovered ${all.length} session files`);
+    // Apply settlement filter (or skip for bootstrap)
+    let eligible;
+    if (opts.isBootstrap) {
+        const maxAge = (opts.ageWindowDays ?? 90) * 24 * 60 * 60 * 1000;
+        const now = Date.now();
+        eligible = all.filter((s) => {
+            if (now - s.mtimeMs > maxAge)
+                return false;
+            // Bootstrap dedup uses the bootstrap_processed flag, not size.
+            return !opts.cache.isBootstrapProcessed(s.path);
+        });
+    }
+    else {
+        eligible = selectSettled(all, opts.cache);
+        out.skippedSettled = all.length - eligible.length;
+    }
+    log(`ai-sessions: ${eligible.length} eligible for ${opts.isBootstrap ? "bootstrap" : "daily digest"}`);
+    for (const file of eligible) {
+        out.processed += 1;
+        const parsed = await parseSession(file.path);
+        if (!parsed) {
+            out.skippedTooSmall += 1;
+            // Still record file size so we don't re-stat next sweep.
+            opts.cache.recordSessionProcessed(file.path, file.size, opts.isBootstrap === true);
+            continue;
+        }
+        // Token budget check before calling extractor (which costs Haiku tokens).
+        const estimate = estimateTokens(parsed.transcript);
+        const { used, cap } = ensureBudgetWindow(opts.cache);
+        if (used + estimate > cap) {
+            out.skippedTokenCap += 1;
+            log(`ai-sessions: token cap reached (${used}/${cap}); pausing`);
+            break;
+        }
+        let extracted;
+        try {
+            extracted = await opts.extract(parsed.transcript);
+            addBudgetUsage(opts.cache, estimate);
+        }
+        catch (err) {
+            out.errors += 1;
+            log(`ai-sessions: extract failed for ${file.path}: ${err.message}`);
+            continue;
+        }
+        const sourceId = makeSourceId(file.path);
+        const metadata = {
+            session_path: file.path,
+            session_source: file.source,
+            session_turns: parsed.turnCount,
+            session_chars: parsed.charCount,
+            session_mtime_ms: file.mtimeMs,
+        };
+        const ingestBatch = async (items, type) => {
+            for (const content of items) {
+                if (!content?.trim())
+                    continue;
+                try {
+                    await opts.ingest({
+                        type,
+                        content,
+                        sourceType: file.source,
+                        sourceId,
+                        metadata,
+                    });
+                    out.ingested += 1;
+                }
+                catch (err) {
+                    out.errors += 1;
+                    log(`ai-sessions: ingest failed (${type}): ${err.message}`);
+                }
+            }
+        };
+        await ingestBatch(extracted.decisions ?? [], "decision");
+        await ingestBatch(extracted.deadEnds ?? [], "dead_end");
+        await ingestBatch(extracted.commitments ?? [], "commitment");
+        await ingestBatch(extracted.openLoops ?? [], "open_loop");
+        opts.cache.recordSessionProcessed(file.path, file.size, opts.isBootstrap === true);
+    }
+    opts.cache.setConfig(CONFIG_KEYS.lastDigestAt, String(Date.now()));
+    return out;
+}
+// ── Helpers exported for tests / inspection ─────────────────────────────────
+export const _internals = {
+    CLAUDE_DIR,
+    CODEX_DIR,
+    MIN_TURNS,
+    MIN_BYTES,
+    MAX_TRANSCRIPT_CHARS,
+    SETTLED_MIN_AGE_MS,
+    SETTLED_MAX_AGE_MS,
+    CONFIG_KEYS,
+    estimateTokens,
+    todayKey,
+    hashFile: (path, content) => createHash("sha256").update(content).digest("hex").slice(0, 16) + ":" + basename(path),
+};