@stackmemoryai/stackmemory 1.10.5 → 1.14.0

package/dist/src/core/brain/brain-store.js

@@ -0,0 +1,187 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { randomUUID } from "crypto";
+import {
+  BRAIN_TABLE,
+  DEFAULT_BRAIN_LIMIT
+} from "./types.js";
+class BrainStore {
+  db;
+  workspaceId;
+  projectId;
+  constructor(db, scope) {
+    this.db = db;
+    this.projectId = scope.projectId;
+    this.workspaceId = scope.workspaceId ?? "";
+    this.ensureTable();
+  }
+  /** Create the brain_entries table + indexes if they don't exist. */
+  ensureTable() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${BRAIN_TABLE} (
+        entry_id TEXT PRIMARY KEY,
+        workspace_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        agent TEXT NOT NULL DEFAULT 'claude',
+        kind TEXT NOT NULL DEFAULT 'note',
+        title TEXT NOT NULL,
+        summary TEXT NOT NULL DEFAULT '',
+        conclusion TEXT NOT NULL DEFAULT '',
+        tags TEXT NOT NULL DEFAULT '[]',
+        refs TEXT NOT NULL DEFAULT '[]',
+        confidence REAL NOT NULL DEFAULT 0.7,
+        status TEXT NOT NULL DEFAULT 'active',
+        superseded_by TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_brain_project ON ${BRAIN_TABLE}(project_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_brain_workspace ON ${BRAIN_TABLE}(workspace_id, created_at DESC);
+    `);
+  }
+  /** Record (or upsert by entryId) a brain entry. */
+  record(input) {
+    const now = Date.now();
+    const entry = {
+      entryId: input.entryId ?? randomUUID(),
+      workspaceId: this.workspaceId,
+      projectId: this.projectId,
+      agent: input.agent ?? "claude",
+      kind: input.kind ?? "note",
+      title: input.title,
+      summary: input.summary ?? "",
+      conclusion: input.conclusion ?? "",
+      tags: input.tags ?? [],
+      refs: input.refs ?? [],
+      confidence: clamp01(input.confidence ?? 0.7),
+      status: "active",
+      createdAt: input.createdAt ?? now,
+      updatedAt: input.updatedAt ?? now
+    };
+    this.db.prepare(
+      `INSERT INTO ${BRAIN_TABLE}
+           (entry_id, workspace_id, project_id, agent, kind, title, summary,
+            conclusion, tags, refs, confidence, status, superseded_by,
+            created_at, updated_at)
+         VALUES (@entryId, @workspaceId, @projectId, @agent, @kind, @title,
+                 @summary, @conclusion, @tags, @refs, @confidence, @status,
+                 NULL, @createdAt, @updatedAt)
+         ON CONFLICT(entry_id) DO UPDATE SET
+           agent = excluded.agent,
+           kind = excluded.kind,
+           title = excluded.title,
+           summary = excluded.summary,
+           conclusion = excluded.conclusion,
+           tags = excluded.tags,
+           refs = excluded.refs,
+           confidence = excluded.confidence,
+           updated_at = excluded.updated_at`
+    ).run({
+      ...entry,
+      tags: JSON.stringify(entry.tags),
+      refs: JSON.stringify(entry.refs)
+    });
+    return entry;
+  }
+  /** Fetch a single entry by id (or unique prefix). */
+  get(entryId) {
+    const row = this.db.prepare(
+      `SELECT * FROM ${BRAIN_TABLE} WHERE entry_id = ? OR entry_id LIKE ? LIMIT 1`
+    ).get(entryId, `${entryId}%`);
+    return row ? rowToEntry(row) : null;
+  }
+  /** Search entries by scope + free text, newest first. */
+  recall(query = {}) {
+    const where = [];
+    const params = [];
+    if (query.org) {
+      where.push("workspace_id = ?");
+      params.push(this.workspaceId);
+    } else {
+      where.push("project_id = ?");
+      params.push(query.projectId ?? this.projectId);
+    }
+    if (!query.includeSuperseded) {
+      where.push("status = 'active'");
+    }
+    if (query.agent) {
+      where.push("agent = ?");
+      params.push(query.agent);
+    }
+    if (query.kind) {
+      where.push("kind = ?");
+      params.push(query.kind);
+    }
+    if (query.since) {
+      where.push("created_at >= ?");
+      params.push(query.since);
+    }
+    if (query.text) {
+      where.push(
+        "(title LIKE ? OR summary LIKE ? OR conclusion LIKE ? OR tags LIKE ?)"
+      );
+      const like = `%${query.text}%`;
+      params.push(like, like, like, like);
+    }
+    const limit = Math.max(1, query.limit ?? DEFAULT_BRAIN_LIMIT);
+    const rows = this.db.prepare(
+      `SELECT * FROM ${BRAIN_TABLE}
+         WHERE ${where.join(" AND ")}
+         ORDER BY created_at DESC
+         LIMIT ?`
+    ).all(...params, limit);
+    return rows.map(rowToEntry);
+  }
+  /** Mark `oldId` superseded by `newId`. */
+  supersede(oldId, newId) {
+    this.db.prepare(
+      `UPDATE ${BRAIN_TABLE}
+         SET status = 'superseded', superseded_by = ?, updated_at = ?
+         WHERE entry_id = ?`
+    ).run(newId, Date.now(), oldId);
+  }
+  /** Count entries in scope (for status output). */
+  count(org = false) {
+    const col = org ? "workspace_id" : "project_id";
+    const val = org ? this.workspaceId : this.projectId;
+    const row = this.db.prepare(`SELECT COUNT(*) AS n FROM ${BRAIN_TABLE} WHERE ${col} = ?`).get(val);
+    return row.n;
+  }
+}
+function rowToEntry(row) {
+  const entry = {
+    entryId: row.entry_id,
+    workspaceId: row.workspace_id,
+    projectId: row.project_id,
+    agent: row.agent,
+    kind: row.kind,
+    title: row.title,
+    summary: row.summary,
+    conclusion: row.conclusion,
+    tags: safeParse(row.tags),
+    refs: safeParse(row.refs),
+    confidence: row.confidence,
+    status: row.status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+  if (row.superseded_by) entry.supersededBy = row.superseded_by;
+  return entry;
+}
+function safeParse(json) {
+  try {
+    const v = JSON.parse(json);
+    return Array.isArray(v) ? v.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+function clamp01(n) {
+  if (Number.isNaN(n)) return 0.7;
+  return Math.max(0, Math.min(1, n));
+}
+export {
+  BrainStore
+};

package/dist/src/core/brain/brain-sync.js

@@ -0,0 +1,193 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const BRAIN_TABLE = "brain_entries";
+class BrainSync {
+  db;
+  store;
+  config;
+  constructor(db, store, config) {
+    this.db = db;
+    this.store = store;
+    this.config = {
+      timeoutMs: 3e4,
+      batchSize: 200,
+      ...config
+    };
+    this.ensureMeta();
+  }
+  ensureMeta() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS brain_sync_meta (
+        direction TEXT PRIMARY KEY,
+        cursor INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+  }
+  getCursor(direction) {
+    const row = this.db.prepare("SELECT cursor FROM brain_sync_meta WHERE direction = ?").get(direction);
+    return row?.cursor ?? 0;
+  }
+  setCursor(direction, cursor) {
+    this.db.prepare(
+      `INSERT INTO brain_sync_meta (direction, cursor) VALUES (?, ?)
+         ON CONFLICT(direction) DO UPDATE SET cursor = excluded.cursor`
+    ).run(direction, cursor);
+  }
+  /** Push locally-updated entries to the cloud. */
+  async push() {
+    const since = this.getCursor("push");
+    const rows = this.db.prepare(
+      `SELECT * FROM ${BRAIN_TABLE} WHERE updated_at > ? ORDER BY updated_at ASC LIMIT ?`
+    ).all(since, this.config.batchSize);
+    if (rows.length === 0) {
+      return { success: true, pushed: 0, pulled: 0, applied: 0 };
+    }
+    const entries = rows.map(toWireEntry);
+    const maxUpdated = Math.max(...entries.map((e) => e.updatedAt));
+    try {
+      const res = await this.post("/v1/brain/push", {
+        protocolVersion: 1,
+        clientId: this.config.clientId,
+        workspaceId: this.config.workspaceId,
+        projectId: this.config.projectId,
+        since,
+        entries
+      });
+      this.setCursor("push", Math.max(maxUpdated, res.serverCursor ?? 0));
+      return {
+        success: true,
+        pushed: res.accepted ?? entries.length,
+        pulled: 0,
+        applied: 0
+      };
+    } catch (err) {
+      return {
+        success: false,
+        pushed: 0,
+        pulled: 0,
+        applied: 0,
+        error: errMsg(err)
+      };
+    }
+  }
+  /** Pull remote entries and apply them locally (newest-wins). */
+  async pull() {
+    const since = this.getCursor("pull");
+    try {
+      const res = await this.post("/v1/brain/pull", {
+        protocolVersion: 1,
+        clientId: this.config.clientId,
+        workspaceId: this.config.workspaceId,
+        projectId: this.config.projectId,
+        since,
+        limit: this.config.batchSize
+      });
+      const entries = res.entries ?? [];
+      let applied = 0;
+      let maxUpdated = since;
+      for (const remote of entries) {
+        maxUpdated = Math.max(maxUpdated, remote.updatedAt ?? 0);
+        const local = this.store.get(remote.entryId);
+        if (local && local.updatedAt >= (remote.updatedAt ?? 0)) continue;
+        this.store.record({
+          entryId: remote.entryId,
+          agent: remote.agent,
+          kind: remote.kind,
+          title: remote.title,
+          summary: remote.summary,
+          conclusion: remote.conclusion,
+          tags: remote.tags,
+          refs: remote.refs,
+          confidence: remote.confidence,
+          createdAt: remote.createdAt,
+          updatedAt: remote.updatedAt
+        });
+        applied++;
+      }
+      this.setCursor("pull", Math.max(maxUpdated, res.serverCursor ?? 0));
+      return { success: true, pushed: 0, pulled: entries.length, applied };
+    } catch (err) {
+      return {
+        success: false,
+        pushed: 0,
+        pulled: 0,
+        applied: 0,
+        error: errMsg(err)
+      };
+    }
+  }
+  /** Push then pull in one shot. */
+  async sync() {
+    const pushed = await this.push();
+    const pulled = await this.pull();
+    const error = pushed.error ?? pulled.error;
+    return {
+      success: pushed.success && pulled.success,
+      pushed: pushed.pushed,
+      pulled: pulled.pulled,
+      applied: pulled.applied,
+      ...error ? { error } : {}
+    };
+  }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const res = await fetch(`${this.config.endpoint}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-Client-Id": this.config.clientId
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        throw new Error(`${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+function toWireEntry(row) {
+  const parse = (v) => {
+    try {
+      const a = JSON.parse(String(v ?? "[]"));
+      return Array.isArray(a) ? a.map(String) : [];
+    } catch {
+      return [];
+    }
+  };
+  const entry = {
+    entryId: String(row["entry_id"]),
+    workspaceId: String(row["workspace_id"] ?? ""),
+    projectId: String(row["project_id"]),
+    agent: String(row["agent"]),
+    kind: String(row["kind"]),
+    title: String(row["title"]),
+    summary: String(row["summary"] ?? ""),
+    conclusion: String(row["conclusion"] ?? ""),
+    tags: parse(row["tags"]),
+    refs: parse(row["refs"]),
+    confidence: Number(row["confidence"] ?? 0.7),
+    status: String(row["status"] ?? "active"),
+    createdAt: Number(row["created_at"]),
+    updatedAt: Number(row["updated_at"])
+  };
+  if (row["superseded_by"]) entry.supersededBy = String(row["superseded_by"]);
+  return entry;
+}
+function errMsg(err) {
+  if (err instanceof Error) {
+    return err.name === "AbortError" ? "request timed out" : err.message;
+  }
+  return String(err);
+}
+export {
+  BrainSync
+};

package/dist/src/core/brain/index.js

@@ -0,0 +1,78 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { homedir, hostname } from "os";
+import { join } from "path";
+import { existsSync, readFileSync, mkdirSync } from "fs";
+import { createHash } from "crypto";
+import Database from "better-sqlite3";
+import { BrainStore } from "./brain-store.js";
+import { BrainSync } from "./brain-sync.js";
+import { BrainStore as BrainStore2 } from "./brain-store.js";
+import { BrainSync as BrainSync2 } from "./brain-sync.js";
+export * from "./types.js";
+const DEFAULT_ENDPOINT = "https://provenant-api.jpwu03.workers.dev";
+function readAuth() {
+  const cfgPath = join(homedir(), ".stackmemory", "config.json");
+  if (!existsSync(cfgPath)) return {};
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    return cfg.auth ?? {};
+  } catch {
+    return {};
+  }
+}
+function hashId(input) {
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+function resolveScope(projectDir) {
+  const auth = readAuth();
+  const projectId = process.env["PROVENANT_PROJECT_ID"] || auth.projectId || hashId(projectDir);
+  const workspaceId = process.env["PROVENANT_WORKSPACE_ID"] || auth.workspaceId || "";
+  return { projectId, workspaceId };
+}
+function resolveDbPath(projectDir) {
+  const contextDb = join(projectDir, ".stackmemory", "context.db");
+  if (existsSync(contextDb)) return contextDb;
+  const localDb = join(projectDir, ".stackmemory", "stackmemory.db");
+  if (existsSync(localDb)) return localDb;
+  const globalDb = join(homedir(), ".stackmemory", "stackmemory.db");
+  if (existsSync(globalDb)) return globalDb;
+  mkdirSync(join(projectDir, ".stackmemory"), { recursive: true });
+  return contextDb;
+}
+function openBrain(projectDir = process.cwd()) {
+  const { projectId, workspaceId } = resolveScope(projectDir);
+  const dbPath = resolveDbPath(projectDir);
+  const db = new Database(dbPath);
+  const store = new BrainStore(db, { projectId, workspaceId });
+  const auth = readAuth();
+  const apiKey = process.env["PROVENANT_API_KEY"] || auth.apiKey;
+  let sync = null;
+  if (apiKey) {
+    const syncConfig = {
+      endpoint: process.env["PROVENANT_API_URL"] || auth.apiUrl || DEFAULT_ENDPOINT,
+      apiKey,
+      workspaceId,
+      projectId,
+      clientId: hashId(hostname() + projectDir)
+    };
+    sync = new BrainSync(db, store, syncConfig);
+  }
+  return {
+    db,
+    store,
+    projectId,
+    workspaceId,
+    sync,
+    close: () => db.close()
+  };
+}
+export {
+  BrainStore2 as BrainStore,
+  BrainSync2 as BrainSync,
+  openBrain,
+  resolveDbPath,
+  resolveScope
+};

package/dist/src/core/brain/types.js

@@ -0,0 +1,10 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const BRAIN_TABLE = "brain_entries";
+const DEFAULT_BRAIN_LIMIT = 20;
+export {
+  BRAIN_TABLE,
+  DEFAULT_BRAIN_LIMIT
+};

package/dist/src/core/cache/content-cache.js

@@ -0,0 +1,238 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { logger } from "../monitoring/logger.js";
+import { estimateTokens, hashContent } from "./token-estimator.js";
+class ContentCache {
+  db;
+  constructor(db) {
+    this.db = db;
+    this.initializeSchema();
+  }
+  // ------------------------------------------------------------------
+  // Schema
+  // ------------------------------------------------------------------
+  initializeSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS content_cache (
+        hash TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        token_count INTEGER NOT NULL,
+        hit_count INTEGER NOT NULL DEFAULT 0,
+        first_seen INTEGER NOT NULL,
+        last_seen INTEGER NOT NULL,
+        source TEXT NOT NULL DEFAULT '',
+        metadata TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_cache_source ON content_cache(source);
+      CREATE INDEX IF NOT EXISTS idx_cache_last_seen ON content_cache(last_seen);
+    `);
+    const hasFts = this.db.prepare(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name='content_cache_fts'`
+    ).get();
+    if (!hasFts) {
+      this.db.exec(`
+        CREATE VIRTUAL TABLE content_cache_fts
+        USING fts5(content, hash UNINDEXED, content_rowid='rowid');
+      `);
+    }
+    logger.debug("ContentCache: schema initialized");
+  }
+  // ------------------------------------------------------------------
+  // Core operations
+  // ------------------------------------------------------------------
+  /**
+   * Look up content by hash. If it exists, increments hit_count and
+   * returns the saved tokens. Otherwise returns a miss.
+   */
+  lookup(content, source) {
+    const hash = hashContent(content);
+    const row = this.db.prepare("SELECT * FROM content_cache WHERE hash = ?").get(hash);
+    if (!row) {
+      return { hit: false, hash, tokensSaved: 0 };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    this.db.prepare(
+      "UPDATE content_cache SET hit_count = hit_count + 1, last_seen = ? WHERE hash = ?"
+    ).run(now, hash);
+    if (source && source !== row.source) {
+      this.db.prepare("UPDATE content_cache SET source = ? WHERE hash = ?").run(source, hash);
+    }
+    const entry = this.rowToEntry({
+      ...row,
+      hit_count: row.hit_count + 1,
+      last_seen: now,
+      source: source ?? row.source
+    });
+    return {
+      hit: true,
+      hash,
+      entry,
+      tokensSaved: entry.tokenCount
+    };
+  }
+  /**
+   * Insert or update a cache entry. Returns the entry.
+   */
+  put(content, source, metadata) {
+    const hash = hashContent(content);
+    const tokenCount = estimateTokens(content);
+    const now = Math.floor(Date.now() / 1e3);
+    const src = source ?? "";
+    const meta = metadata ? JSON.stringify(metadata) : null;
+    const existing = this.db.prepare("SELECT hash FROM content_cache WHERE hash = ?").get(hash);
+    if (existing) {
+      this.db.prepare(
+        "UPDATE content_cache SET hit_count = hit_count + 1, last_seen = ?, source = ?, metadata = ? WHERE hash = ?"
+      ).run(now, src, meta, hash);
+    } else {
+      this.db.prepare(
+        `INSERT INTO content_cache (hash, content, token_count, hit_count, first_seen, last_seen, source, metadata)
+           VALUES (?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(hash, content, tokenCount, now, now, src, meta);
+      this.db.prepare(`INSERT INTO content_cache_fts (content, hash) VALUES (?, ?)`).run(content, hash);
+    }
+    return this.getEntry(hash);
+  }
+  /**
+   * Retrieve a single entry by hash.
+   */
+  getEntry(hash) {
+    const row = this.db.prepare("SELECT * FROM content_cache WHERE hash = ?").get(hash);
+    return row ? this.rowToEntry(row) : void 0;
+  }
+  /**
+   * Aggregate cache statistics.
+   */
+  getStats() {
+    const agg = this.db.prepare(
+      `SELECT
+           COUNT(*) as total_entries,
+           COALESCE(SUM(token_count), 0) as total_tokens_cached,
+           COALESCE(SUM(hit_count * token_count), 0) as total_tokens_saved,
+           COALESCE(SUM(hit_count), 0) as total_hits,
+           COUNT(*) as total_lookups
+         FROM content_cache`
+    ).get();
+    const totalHits = agg.total_hits;
+    const totalEntries = agg.total_entries;
+    const hitRate = totalHits + totalEntries > 0 ? totalHits / (totalHits + totalEntries) : 0;
+    const topRows = this.db.prepare(
+      `SELECT source, SUM(hit_count * token_count) as tokens_saved
+         FROM content_cache
+         WHERE source != ''
+         GROUP BY source
+         ORDER BY tokens_saved DESC
+         LIMIT 10`
+    ).all();
+    return {
+      totalEntries,
+      totalTokensCached: agg.total_tokens_cached,
+      totalTokensSaved: agg.total_tokens_saved,
+      hitRate,
+      topSources: topRows.map((r) => ({
+        source: r.source,
+        tokensSaved: r.tokens_saved
+      }))
+    };
+  }
+  /**
+   * Remove entries older than the given unix timestamp.
+   * Returns the number of evicted entries.
+   */
+  evict(olderThan) {
+    const cutoff = olderThan ?? Math.floor(Date.now() / 1e3);
+    this.db.prepare(
+      `DELETE FROM content_cache_fts
+         WHERE hash IN (SELECT hash FROM content_cache WHERE last_seen < ?)`
+    ).run(cutoff);
+    const result = this.db.prepare("DELETE FROM content_cache WHERE last_seen < ?").run(cutoff);
+    if (result.changes > 0) {
+      logger.debug(`ContentCache: evicted ${result.changes} entries`);
+    }
+    return result.changes;
+  }
+  /**
+   * Search cached content via FTS5.
+   */
+  search(query, limit = 20) {
+    if (!query.trim()) return [];
+    const sanitized = this.sanitizeFtsQuery(query);
+    const rows = this.db.prepare(
+      `SELECT cc.*
+         FROM content_cache_fts fts
+         JOIN content_cache cc ON cc.hash = fts.hash
+         WHERE content_cache_fts MATCH ?
+         LIMIT ?`
+    ).all(sanitized, limit);
+    return rows.map((r) => this.rowToEntry(r));
+  }
+  /**
+   * Remove all entries.
+   */
+  clear() {
+    this.db.exec("DELETE FROM content_cache_fts");
+    this.db.exec("DELETE FROM content_cache");
+    logger.debug("ContentCache: cleared");
+  }
+  // ------------------------------------------------------------------
+  // Key-based operations (for input-addressed caching, e.g., tool+args → result)
+  // ------------------------------------------------------------------
+  /**
+   * Look up cached result by an explicit key (e.g., "tool:args-hash").
+   * The key is hashed to produce the cache entry hash.
+   */
+  lookupByKey(key, source) {
+    return this.lookup(key, source);
+  }
+  /**
+   * Store a result under an explicit key.
+   * The key is hashed for addressing; the value is stored as content.
+   */
+  putByKey(key, value, source, metadata) {
+    const hash = hashContent(key);
+    const tokenCount = estimateTokens(value);
+    const now = Math.floor(Date.now() / 1e3);
+    const src = source ?? "";
+    const meta = metadata ? JSON.stringify(metadata) : null;
+    const existing = this.db.prepare("SELECT hash FROM content_cache WHERE hash = ?").get(hash);
+    if (existing) {
+      this.db.prepare(
+        "UPDATE content_cache SET content = ?, token_count = ?, hit_count = hit_count + 1, last_seen = ?, source = ?, metadata = ? WHERE hash = ?"
+      ).run(value, tokenCount, now, src, meta, hash);
+    } else {
+      this.db.prepare(
+        `INSERT INTO content_cache (hash, content, token_count, hit_count, first_seen, last_seen, source, metadata)
+           VALUES (?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(hash, value, tokenCount, now, now, src, meta);
+      this.db.prepare(`INSERT INTO content_cache_fts (content, hash) VALUES (?, ?)`).run(value, hash);
+    }
+    return this.getEntry(hash);
+  }
+  // ------------------------------------------------------------------
+  // Helpers
+  // ------------------------------------------------------------------
+  rowToEntry(row) {
+    return {
+      hash: row.hash,
+      content: row.content,
+      tokenCount: row.token_count,
+      hitCount: row.hit_count,
+      firstSeen: row.first_seen,
+      lastSeen: row.last_seen,
+      source: row.source,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0
+    };
+  }
+  sanitizeFtsQuery(query) {
+    const cleaned = query.replace(/['"()*~^{}\[\]]/g, "");
+    const terms = cleaned.split(/\s+/).filter((t) => t && !/^(AND|OR|NOT|NEAR)$/i.test(t));
+    if (terms.length === 0) return '""';
+    return terms.map((t) => `"${t}"`).join(" ");
+  }
+}
+export {
+  ContentCache
+};