@persql/context 0.1.0

package/dist/core.cjs

@@ -0,0 +1,384 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  EXTRACTION_JSON_SCHEMA: () => EXTRACTION_JSON_SCHEMA,
+  EXTRACTION_SYSTEM_PROMPT: () => EXTRACTION_SYSTEM_PROMPT,
+  SCHEMA_SQL: () => SCHEMA_SQL,
+  SCHEMA_VERSION: () => SCHEMA_VERSION,
+  TABLE_PREFIX: () => TABLE_PREFIX,
+  buildByTag: () => buildByTag,
+  buildEdgesAmong: () => buildEdgesAmong,
+  buildExtractionMessages: () => buildExtractionMessages,
+  buildForget: () => buildForget,
+  buildGet: () => buildGet,
+  buildInit: () => buildInit,
+  buildNeighborEntities: () => buildNeighborEntities,
+  buildRecall: () => buildRecall,
+  buildRecent: () => buildRecent,
+  buildRemember: () => buildRemember,
+  buildStats: () => buildStats,
+  buildSupersede: () => buildSupersede,
+  buildUpsertEdge: () => buildUpsertEdge,
+  buildUpsertEntity: () => buildUpsertEntity,
+  entityId: () => entityId,
+  normalizeTags: () => normalizeTags,
+  toFtsQuery: () => toFtsQuery
+});
+module.exports = __toCommonJS(core_exports);
+var SCHEMA_VERSION = 1;
+var TABLE_PREFIX = "ctx_";
+var T = TABLE_PREFIX;
+var SCHEMA_SQL = [
+  `CREATE TABLE IF NOT EXISTS ${T}memory (
+     id TEXT PRIMARY KEY,
+     kind TEXT NOT NULL DEFAULT 'fact',
+     topic TEXT,
+     body TEXT NOT NULL,
+     tags TEXT,
+     source TEXT,
+     created_at INTEGER NOT NULL,
+     superseded_by TEXT
+   )`,
+  `CREATE INDEX IF NOT EXISTS ${T}memory_kind ON ${T}memory(kind)`,
+  `CREATE INDEX IF NOT EXISTS ${T}memory_created ON ${T}memory(created_at)`,
+  `CREATE INDEX IF NOT EXISTS ${T}memory_superseded ON ${T}memory(superseded_by)`,
+  // External-content FTS index: body text is not duplicated, only indexed.
+  // Porter stemmer so "invoice" recalls "invoicing" without embeddings.
+  `CREATE VIRTUAL TABLE IF NOT EXISTS ${T}memory_fts USING fts5(
+     topic, body, tags,
+     content='${T}memory', content_rowid='rowid',
+     tokenize='porter unicode61'
+   )`,
+  `CREATE TRIGGER IF NOT EXISTS ${T}memory_ai AFTER INSERT ON ${T}memory BEGIN
+     INSERT INTO ${T}memory_fts(rowid, topic, body, tags)
+     VALUES (new.rowid, new.topic, new.body, new.tags);
+   END`,
+  `CREATE TRIGGER IF NOT EXISTS ${T}memory_ad AFTER DELETE ON ${T}memory BEGIN
+     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, topic, body, tags)
+     VALUES ('delete', old.rowid, old.topic, old.body, old.tags);
+   END`,
+  `CREATE TRIGGER IF NOT EXISTS ${T}memory_au AFTER UPDATE ON ${T}memory BEGIN
+     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, topic, body, tags)
+     VALUES ('delete', old.rowid, old.topic, old.body, old.tags);
+     INSERT INTO ${T}memory_fts(rowid, topic, body, tags)
+     VALUES (new.rowid, new.topic, new.body, new.tags);
+   END`,
+  `CREATE TABLE IF NOT EXISTS ${T}entity (
+     id TEXT PRIMARY KEY,
+     name TEXT NOT NULL,
+     kind TEXT,
+     body TEXT,
+     created_at INTEGER NOT NULL
+   )`,
+  `CREATE TABLE IF NOT EXISTS ${T}edge (
+     id TEXT PRIMARY KEY,
+     src TEXT NOT NULL,
+     rel TEXT NOT NULL,
+     dst TEXT NOT NULL,
+     source TEXT,
+     created_at INTEGER NOT NULL
+   )`,
+  `CREATE INDEX IF NOT EXISTS ${T}edge_src ON ${T}edge(src)`,
+  `CREATE INDEX IF NOT EXISTS ${T}edge_dst ON ${T}edge(dst)`
+];
+function buildInit() {
+  return SCHEMA_SQL.map((sql) => ({ sql, params: [] }));
+}
+var FTS_OPERATORS = /* @__PURE__ */ new Set(["and", "or", "not", "near"]);
+function normalizeTags(tags) {
+  if (!tags) return null;
+  const arr = Array.isArray(tags) ? tags : String(tags).split(/[,\s]+/);
+  const norm = Array.from(
+    new Set(arr.map((t) => t.trim().toLowerCase()).filter(Boolean))
+  );
+  return norm.length ? norm.join(" ") : null;
+}
+function toFtsQuery(input, opts = {}) {
+  if (opts.mode === "raw") return input.trim() || null;
+  const tokens = (input.match(/[\p{L}\p{N}_]+/gu) ?? []).filter(
+    (t) => !FTS_OPERATORS.has(t.toLowerCase())
+  );
+  if (!tokens.length) return null;
+  const joiner = opts.operator === "and" ? " AND " : " OR ";
+  return tokens.map((t) => `"${t}"`).join(joiner);
+}
+function slugId(prefix, s) {
+  const base = s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 96);
+  return prefix + (base || "x");
+}
+function entityId(name) {
+  return slugId("e_", name);
+}
+function resolveEntityRef(ref) {
+  return ref.startsWith("e_") ? ref : entityId(ref);
+}
+function edgeId(srcId, rel, dstId) {
+  return slugId("x_", `${srcId}|${rel}|${dstId}`);
+}
+var MEMORY_COLS = "id, kind, topic, body, tags, source, created_at AS createdAt, superseded_by AS supersededBy";
+function buildRemember(input, now, id) {
+  return {
+    sql: `INSERT INTO ${T}memory (id, kind, topic, body, tags, source, created_at, superseded_by)
+          VALUES (?, ?, ?, ?, ?, ?, ?, NULL)`,
+    params: [
+      id,
+      input.kind ?? "fact",
+      input.topic ?? null,
+      input.body,
+      normalizeTags(input.tags),
+      input.source ?? null,
+      now
+    ]
+  };
+}
+function buildSupersede(oldId, newId) {
+  return {
+    sql: `UPDATE ${T}memory SET superseded_by = ? WHERE id = ? AND superseded_by IS NULL`,
+    params: [newId, oldId]
+  };
+}
+function buildForget(id) {
+  return { sql: `DELETE FROM ${T}memory WHERE id = ?`, params: [id] };
+}
+function buildGet(id) {
+  return {
+    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory WHERE id = ?`,
+    params: [id]
+  };
+}
+function buildRecall(query, opts = {}) {
+  const match = toFtsQuery(query, { operator: opts.operator, mode: opts.mode });
+  if (!match) return null;
+  const where = [`${T}memory_fts MATCH ?`];
+  const params = [match];
+  if (!opts.includeSuperseded) where.push("m.superseded_by IS NULL");
+  if (opts.kind) {
+    where.push("m.kind = ?");
+    params.push(opts.kind);
+  }
+  if (opts.sinceMs != null) {
+    where.push("m.created_at >= ?");
+    params.push(opts.sinceMs);
+  }
+  params.push(opts.limit ?? 8);
+  return {
+    sql: `SELECT m.id, m.kind, m.topic, m.body, m.tags, m.source,
+                 m.created_at AS createdAt, m.superseded_by AS supersededBy
+          FROM ${T}memory_fts
+          JOIN ${T}memory m ON m.rowid = ${T}memory_fts.rowid
+          WHERE ${where.join(" AND ")}
+          ORDER BY ${T}memory_fts.rank
+          LIMIT ?`,
+    params
+  };
+}
+function buildRecent(opts = {}) {
+  const where = [];
+  const params = [];
+  if (!opts.includeSuperseded) where.push("superseded_by IS NULL");
+  if (opts.kind) {
+    where.push("kind = ?");
+    params.push(opts.kind);
+  }
+  params.push(opts.limit ?? 20);
+  return {
+    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory
+          ${where.length ? "WHERE " + where.join(" AND ") : ""}
+          ORDER BY created_at DESC
+          LIMIT ?`,
+    params
+  };
+}
+function buildByTag(tag, opts = {}) {
+  const t = tag.trim().toLowerCase();
+  const where = ["(' ' || COALESCE(tags, '') || ' ') LIKE ?"];
+  const params = [`% ${t} %`];
+  if (!opts.includeSuperseded) where.push("superseded_by IS NULL");
+  if (opts.kind) {
+    where.push("kind = ?");
+    params.push(opts.kind);
+  }
+  params.push(opts.limit ?? 20);
+  return {
+    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory
+          WHERE ${where.join(" AND ")}
+          ORDER BY created_at DESC
+          LIMIT ?`,
+    params
+  };
+}
+function buildStats() {
+  return {
+    sql: `SELECT
+            (SELECT count(*) FROM ${T}memory WHERE superseded_by IS NULL) AS facts,
+            (SELECT count(*) FROM ${T}memory) AS facts_total,
+            (SELECT count(*) FROM ${T}entity) AS entities,
+            (SELECT count(*) FROM ${T}edge) AS edges`,
+    params: []
+  };
+}
+function buildUpsertEntity(e, now) {
+  const id = e.id ?? entityId(e.name);
+  return {
+    sql: `INSERT INTO ${T}entity (id, name, kind, body, created_at)
+          VALUES (?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET
+            name = excluded.name,
+            kind = COALESCE(excluded.kind, ${T}entity.kind),
+            body = COALESCE(excluded.body, ${T}entity.body)`,
+    params: [id, e.name, e.kind ?? null, e.body ?? null, now]
+  };
+}
+function buildUpsertEdge(e, now) {
+  const srcId = resolveEntityRef(e.src);
+  const dstId = resolveEntityRef(e.dst);
+  const id = edgeId(srcId, e.rel, dstId);
+  return {
+    sql: `INSERT INTO ${T}edge (id, src, rel, dst, source, created_at)
+          VALUES (?, ?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET
+            source = COALESCE(excluded.source, ${T}edge.source)`,
+    params: [id, srcId, e.rel, dstId, e.source ?? null, now]
+  };
+}
+function buildNeighborEntities(seedId, depth, limit) {
+  return {
+    sql: `WITH RECURSIVE reach(id, depth) AS (
+            SELECT ?, 0
+            UNION
+            SELECT CASE WHEN e.src = reach.id THEN e.dst ELSE e.src END,
+                   reach.depth + 1
+            FROM reach
+            JOIN ${T}edge e ON (e.src = reach.id OR e.dst = reach.id)
+            WHERE reach.depth < ?
+          )
+          SELECT en.id, en.name, en.kind, en.body,
+                 en.created_at AS createdAt, MIN(reach.depth) AS depth
+          FROM reach
+          JOIN ${T}entity en ON en.id = reach.id
+          WHERE reach.depth > 0 AND en.id <> ?
+          GROUP BY en.id
+          ORDER BY depth, en.name
+          LIMIT ?`,
+    // The seed reappears at depth >0 via a round-trip on undirected edges;
+    // exclude it explicitly so it isn't listed as its own neighbor.
+    params: [seedId, depth, seedId, limit]
+  };
+}
+function buildEdgesAmong(ids) {
+  if (!ids.length) {
+    return { sql: `SELECT id, src, rel, dst, source, created_at AS createdAt FROM ${T}edge WHERE 0`, params: [] };
+  }
+  const ph = ids.map(() => "?").join(", ");
+  return {
+    sql: `SELECT id, src, rel, dst, source, created_at AS createdAt
+          FROM ${T}edge
+          WHERE src IN (${ph}) AND dst IN (${ph})`,
+    params: [...ids, ...ids]
+  };
+}
+var EXTRACTION_SYSTEM_PROMPT = `You extract durable, shareable context from raw text for a team of AI agents that will read it later by keyword.
+
+Return JSON: { "facts": [...], "entities": [...], "edges": [...] }.
+- facts: atomic, self-contained statements worth remembering across sessions \u2014 decisions, conventions, constraints, identifiers, preferences. Each: { "body": string, "topic"?: string, "tags"?: string[] }. Prefer specific and stable over transient chatter.
+- entities: named things \u2014 services, people, tables, repos, concepts. Each: { "name": string, "kind"?: string, "body"?: short description }.
+- edges: relationships between entities, referencing entity names. Each: { "src": name, "rel": string, "dst": name }.
+
+Be conservative: omit anything ephemeral or low-value. Use lowercase tags. If nothing is worth keeping, return empty arrays.`;
+function buildExtractionMessages(raw, opts = {}) {
+  return [
+    { role: "system", content: EXTRACTION_SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: (opts.hint ? `Context: ${opts.hint}
+
+` : "") + raw
+    }
+  ];
+}
+var EXTRACTION_JSON_SCHEMA = {
+  type: "object",
+  properties: {
+    facts: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          body: { type: "string" },
+          topic: { type: "string" },
+          tags: { type: "array", items: { type: "string" } }
+        },
+        required: ["body"]
+      }
+    },
+    entities: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          kind: { type: "string" },
+          body: { type: "string" }
+        },
+        required: ["name"]
+      }
+    },
+    edges: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          src: { type: "string" },
+          rel: { type: "string" },
+          dst: { type: "string" }
+        },
+        required: ["src", "rel", "dst"]
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EXTRACTION_JSON_SCHEMA,
+  EXTRACTION_SYSTEM_PROMPT,
+  SCHEMA_SQL,
+  SCHEMA_VERSION,
+  TABLE_PREFIX,
+  buildByTag,
+  buildEdgesAmong,
+  buildExtractionMessages,
+  buildForget,
+  buildGet,
+  buildInit,
+  buildNeighborEntities,
+  buildRecall,
+  buildRecent,
+  buildRemember,
+  buildStats,
+  buildSupersede,
+  buildUpsertEdge,
+  buildUpsertEntity,
+  entityId,
+  normalizeTags,
+  toFtsQuery
+});
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts"],"sourcesContent":["/**\n * @persql/context/core — zero-runtime-dependency engine.\n *\n * Schema DDL, SQL builders, and the extraction/compaction contracts shared by\n * the `@persql/context` SDK (client-side, over `@persql/sdk`) and the hosted\n * PerSQL Context worker (server-side, over `@persql/ai`). Keeping both sides on\n * the same builders means client-recall and server-recall can never drift.\n *\n * Retrieval is lexical: FTS5 with the porter stemmer, BM25-ranked. No vectors.\n */\n\nexport const SCHEMA_VERSION = 1;\nexport const TABLE_PREFIX = \"ctx_\";\nconst T = TABLE_PREFIX;\n\nexport type MemoryKind = \"fact\" | \"episode\" | \"artifact\";\n\nexport interface MemoryRow {\n  id: string;\n  kind: MemoryKind;\n  topic: string | null;\n  body: string;\n  tags: string | null;\n  source: string | null;\n  createdAt: number;\n  supersededBy: string | null;\n}\n\nexport interface Entity {\n  id: string;\n  name: string;\n  kind: string | null;\n  body: string | null;\n  createdAt: number;\n}\n\nexport interface Edge {\n  id: string;\n  src: string;\n  rel: string;\n  dst: string;\n  source: string | null;\n  createdAt: number;\n}\n\nexport interface RememberInput {\n  body: string;\n  topic?: string;\n  kind?: MemoryKind;\n  tags?: string[] | string;\n  source?: string;\n  supersedes?: string | string[];\n  id?: string;\n}\n\nexport interface EntityInput {\n  name: string;\n  kind?: string;\n  body?: string;\n  id?: string;\n}\n\nexport interface EdgeInput {\n  src: string;\n  rel: string;\n  dst: string;\n  source?: string;\n}\n\nexport interface RecallOptions {\n  limit?: number;\n  kind?: MemoryKind;\n  operator?: \"or\" | \"and\";\n  mode?: \"terms\" | \"raw\";\n  sinceMs?: number;\n  withinDays?: number;\n  includeSuperseded?: boolean;\n}\n\nexport interface ListOptions {\n  limit?: number;\n  kind?: MemoryKind;\n  includeSuperseded?: boolean;\n}\n\n/** The shape an extractor (LLM or the hosted worker) returns from raw text. */\nexport interface ExtractedContext {\n  facts?: Array<{ body: string; topic?: string; tags?: string[]; kind?: MemoryKind }>;\n  entities?: EntityInput[];\n  edges?: EdgeInput[];\n}\n\nexport interface SqlStatement {\n  sql: string;\n  params: unknown[];\n}\n\n// ---------------------------------------------------------------------------\n// Schema\n// ---------------------------------------------------------------------------\n\nexport const SCHEMA_SQL: string[] = [\n  `CREATE TABLE IF NOT EXISTS ${T}memory (\n     id TEXT PRIMARY KEY,\n     kind TEXT NOT NULL DEFAULT 'fact',\n     topic TEXT,\n     body TEXT NOT NULL,\n     tags TEXT,\n     source TEXT,\n     created_at INTEGER NOT NULL,\n     superseded_by TEXT\n   )`,\n  `CREATE INDEX IF NOT EXISTS ${T}memory_kind ON ${T}memory(kind)`,\n  `CREATE INDEX IF NOT EXISTS ${T}memory_created ON ${T}memory(created_at)`,\n  `CREATE INDEX IF NOT EXISTS ${T}memory_superseded ON ${T}memory(superseded_by)`,\n  // External-content FTS index: body text is not duplicated, only indexed.\n  // Porter stemmer so \"invoice\" recalls \"invoicing\" without embeddings.\n  `CREATE VIRTUAL TABLE IF NOT EXISTS ${T}memory_fts USING fts5(\n     topic, body, tags,\n     content='${T}memory', content_rowid='rowid',\n     tokenize='porter unicode61'\n   )`,\n  `CREATE TRIGGER IF NOT EXISTS ${T}memory_ai AFTER INSERT ON ${T}memory BEGIN\n     INSERT INTO ${T}memory_fts(rowid, topic, body, tags)\n     VALUES (new.rowid, new.topic, new.body, new.tags);\n   END`,\n  `CREATE TRIGGER IF NOT EXISTS ${T}memory_ad AFTER DELETE ON ${T}memory BEGIN\n     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, topic, body, tags)\n     VALUES ('delete', old.rowid, old.topic, old.body, old.tags);\n   END`,\n  `CREATE TRIGGER IF NOT EXISTS ${T}memory_au AFTER UPDATE ON ${T}memory BEGIN\n     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, topic, body, tags)\n     VALUES ('delete', old.rowid, old.topic, old.body, old.tags);\n     INSERT INTO ${T}memory_fts(rowid, topic, body, tags)\n     VALUES (new.rowid, new.topic, new.body, new.tags);\n   END`,\n  `CREATE TABLE IF NOT EXISTS ${T}entity (\n     id TEXT PRIMARY KEY,\n     name TEXT NOT NULL,\n     kind TEXT,\n     body TEXT,\n     created_at INTEGER NOT NULL\n   )`,\n  `CREATE TABLE IF NOT EXISTS ${T}edge (\n     id TEXT PRIMARY KEY,\n     src TEXT NOT NULL,\n     rel TEXT NOT NULL,\n     dst TEXT NOT NULL,\n     source TEXT,\n     created_at INTEGER NOT NULL\n   )`,\n  `CREATE INDEX IF NOT EXISTS ${T}edge_src ON ${T}edge(src)`,\n  `CREATE INDEX IF NOT EXISTS ${T}edge_dst ON ${T}edge(dst)`,\n];\n\nexport function buildInit(): SqlStatement[] {\n  return SCHEMA_SQL.map((sql) => ({ sql, params: [] }));\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nconst FTS_OPERATORS = new Set([\"and\", \"or\", \"not\", \"near\"]);\n\nexport function normalizeTags(tags?: string[] | string | null): string | null {\n  if (!tags) return null;\n  const arr = Array.isArray(tags) ? tags : String(tags).split(/[,\\s]+/);\n  const norm = Array.from(\n    new Set(arr.map((t) => t.trim().toLowerCase()).filter(Boolean))\n  );\n  return norm.length ? norm.join(\" \") : null;\n}\n\n/**\n * Turn arbitrary user text into a safe FTS5 MATCH expression. `terms` mode\n * (default) extracts word tokens, drops bare boolean operators, and ORs the\n * rest as quoted terms — so a caller can paste \"invoice OR billing\" or just\n * \"invoice billing\" and neither crashes the parser nor injects FTS syntax.\n * `raw` mode passes a hand-written FTS expression through untouched.\n */\nexport function toFtsQuery(\n  input: string,\n  opts: { operator?: \"or\" | \"and\"; mode?: \"terms\" | \"raw\" } = {}\n): string | null {\n  if (opts.mode === \"raw\") return input.trim() || null;\n  const tokens = (input.match(/[\\p{L}\\p{N}_]+/gu) ?? []).filter(\n    (t) => !FTS_OPERATORS.has(t.toLowerCase())\n  );\n  if (!tokens.length) return null;\n  const joiner = opts.operator === \"and\" ? \" AND \" : \" OR \";\n  return tokens.map((t) => `\"${t}\"`).join(joiner);\n}\n\nfunction slugId(prefix: string, s: string): string {\n  const base = s\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\")\n    .slice(0, 96);\n  return prefix + (base || \"x\");\n}\n\n/** Deterministic id for an entity, keyed on its name (case-insensitive). */\nexport function entityId(name: string): string {\n  return slugId(\"e_\", name);\n}\n\nfunction resolveEntityRef(ref: string): string {\n  return ref.startsWith(\"e_\") ? ref : entityId(ref);\n}\n\nfunction edgeId(srcId: string, rel: string, dstId: string): string {\n  return slugId(\"x_\", `${srcId}|${rel}|${dstId}`);\n}\n\nconst MEMORY_COLS =\n  \"id, kind, topic, body, tags, source, created_at AS createdAt, superseded_by AS supersededBy\";\n\n// ---------------------------------------------------------------------------\n// Memory builders\n// ---------------------------------------------------------------------------\n\nexport function buildRemember(\n  input: RememberInput,\n  now: number,\n  id: string\n): SqlStatement {\n  return {\n    sql: `INSERT INTO ${T}memory (id, kind, topic, body, tags, source, created_at, superseded_by)\n          VALUES (?, ?, ?, ?, ?, ?, ?, NULL)`,\n    params: [\n      id,\n      input.kind ?? \"fact\",\n      input.topic ?? null,\n      input.body,\n      normalizeTags(input.tags),\n      input.source ?? null,\n      now,\n    ],\n  };\n}\n\nexport function buildSupersede(oldId: string, newId: string): SqlStatement {\n  return {\n    sql: `UPDATE ${T}memory SET superseded_by = ? WHERE id = ? AND superseded_by IS NULL`,\n    params: [newId, oldId],\n  };\n}\n\nexport function buildForget(id: string): SqlStatement {\n  return { sql: `DELETE FROM ${T}memory WHERE id = ?`, params: [id] };\n}\n\nexport function buildGet(id: string): SqlStatement {\n  return {\n    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory WHERE id = ?`,\n    params: [id],\n  };\n}\n\nexport function buildRecall(\n  query: string,\n  opts: RecallOptions = {}\n): SqlStatement | null {\n  const match = toFtsQuery(query, { operator: opts.operator, mode: opts.mode });\n  if (!match) return null;\n  const where: string[] = [`${T}memory_fts MATCH ?`];\n  const params: unknown[] = [match];\n  if (!opts.includeSuperseded) where.push(\"m.superseded_by IS NULL\");\n  if (opts.kind) {\n    where.push(\"m.kind = ?\");\n    params.push(opts.kind);\n  }\n  if (opts.sinceMs != null) {\n    where.push(\"m.created_at >= ?\");\n    params.push(opts.sinceMs);\n  }\n  params.push(opts.limit ?? 8);\n  return {\n    sql: `SELECT m.id, m.kind, m.topic, m.body, m.tags, m.source,\n                 m.created_at AS createdAt, m.superseded_by AS supersededBy\n          FROM ${T}memory_fts\n          JOIN ${T}memory m ON m.rowid = ${T}memory_fts.rowid\n          WHERE ${where.join(\" AND \")}\n          ORDER BY ${T}memory_fts.rank\n          LIMIT ?`,\n    params,\n  };\n}\n\nexport function buildRecent(opts: ListOptions = {}): SqlStatement {\n  const where: string[] = [];\n  const params: unknown[] = [];\n  if (!opts.includeSuperseded) where.push(\"superseded_by IS NULL\");\n  if (opts.kind) {\n    where.push(\"kind = ?\");\n    params.push(opts.kind);\n  }\n  params.push(opts.limit ?? 20);\n  return {\n    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory\n          ${where.length ? \"WHERE \" + where.join(\" AND \") : \"\"}\n          ORDER BY created_at DESC\n          LIMIT ?`,\n    params,\n  };\n}\n\nexport function buildByTag(tag: string, opts: ListOptions = {}): SqlStatement {\n  const t = tag.trim().toLowerCase();\n  const where: string[] = [\"(' ' || COALESCE(tags, '') || ' ') LIKE ?\"];\n  const params: unknown[] = [`% ${t} %`];\n  if (!opts.includeSuperseded) where.push(\"superseded_by IS NULL\");\n  if (opts.kind) {\n    where.push(\"kind = ?\");\n    params.push(opts.kind);\n  }\n  params.push(opts.limit ?? 20);\n  return {\n    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory\n          WHERE ${where.join(\" AND \")}\n          ORDER BY created_at DESC\n          LIMIT ?`,\n    params,\n  };\n}\n\nexport function buildStats(): SqlStatement {\n  return {\n    sql: `SELECT\n            (SELECT count(*) FROM ${T}memory WHERE superseded_by IS NULL) AS facts,\n            (SELECT count(*) FROM ${T}memory) AS facts_total,\n            (SELECT count(*) FROM ${T}entity) AS entities,\n            (SELECT count(*) FROM ${T}edge) AS edges`,\n    params: [],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Graph builders\n// ---------------------------------------------------------------------------\n\nexport function buildUpsertEntity(e: EntityInput, now: number): SqlStatement {\n  const id = e.id ?? entityId(e.name);\n  return {\n    sql: `INSERT INTO ${T}entity (id, name, kind, body, created_at)\n          VALUES (?, ?, ?, ?, ?)\n          ON CONFLICT(id) DO UPDATE SET\n            name = excluded.name,\n            kind = COALESCE(excluded.kind, ${T}entity.kind),\n            body = COALESCE(excluded.body, ${T}entity.body)`,\n    params: [id, e.name, e.kind ?? null, e.body ?? null, now],\n  };\n}\n\nexport function buildUpsertEdge(e: EdgeInput, now: number): SqlStatement {\n  const srcId = resolveEntityRef(e.src);\n  const dstId = resolveEntityRef(e.dst);\n  const id = edgeId(srcId, e.rel, dstId);\n  return {\n    sql: `INSERT INTO ${T}edge (id, src, rel, dst, source, created_at)\n          VALUES (?, ?, ?, ?, ?, ?)\n          ON CONFLICT(id) DO UPDATE SET\n            source = COALESCE(excluded.source, ${T}edge.source)`,\n    params: [id, srcId, e.rel, dstId, e.source ?? null, now],\n  };\n}\n\n/** Entities reachable from a seed within `depth` hops (seed excluded). */\nexport function buildNeighborEntities(\n  seedId: string,\n  depth: number,\n  limit: number\n): SqlStatement {\n  return {\n    sql: `WITH RECURSIVE reach(id, depth) AS (\n            SELECT ?, 0\n            UNION\n            SELECT CASE WHEN e.src = reach.id THEN e.dst ELSE e.src END,\n                   reach.depth + 1\n            FROM reach\n            JOIN ${T}edge e ON (e.src = reach.id OR e.dst = reach.id)\n            WHERE reach.depth < ?\n          )\n          SELECT en.id, en.name, en.kind, en.body,\n                 en.created_at AS createdAt, MIN(reach.depth) AS depth\n          FROM reach\n          JOIN ${T}entity en ON en.id = reach.id\n          WHERE reach.depth > 0 AND en.id <> ?\n          GROUP BY en.id\n          ORDER BY depth, en.name\n          LIMIT ?`,\n    // The seed reappears at depth >0 via a round-trip on undirected edges;\n    // exclude it explicitly so it isn't listed as its own neighbor.\n    params: [seedId, depth, seedId, limit],\n  };\n}\n\nexport function buildEdgesAmong(ids: string[]): SqlStatement {\n  if (!ids.length) {\n    return { sql: `SELECT id, src, rel, dst, source, created_at AS createdAt FROM ${T}edge WHERE 0`, params: [] };\n  }\n  const ph = ids.map(() => \"?\").join(\", \");\n  return {\n    sql: `SELECT id, src, rel, dst, source, created_at AS createdAt\n          FROM ${T}edge\n          WHERE src IN (${ph}) AND dst IN (${ph})`,\n    params: [...ids, ...ids],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Extraction / compaction contracts (used by the hosted worker + documented\n// for bring-your-own-LLM callers; kept here so the prompt is versioned with\n// the schema it has to populate).\n// ---------------------------------------------------------------------------\n\nexport const EXTRACTION_SYSTEM_PROMPT = `You extract durable, shareable context from raw text for a team of AI agents that will read it later by keyword.\n\nReturn JSON: { \"facts\": [...], \"entities\": [...], \"edges\": [...] }.\n- facts: atomic, self-contained statements worth remembering across sessions — decisions, conventions, constraints, identifiers, preferences. Each: { \"body\": string, \"topic\"?: string, \"tags\"?: string[] }. Prefer specific and stable over transient chatter.\n- entities: named things — services, people, tables, repos, concepts. Each: { \"name\": string, \"kind\"?: string, \"body\"?: short description }.\n- edges: relationships between entities, referencing entity names. Each: { \"src\": name, \"rel\": string, \"dst\": name }.\n\nBe conservative: omit anything ephemeral or low-value. Use lowercase tags. If nothing is worth keeping, return empty arrays.`;\n\nexport function buildExtractionMessages(\n  raw: string,\n  opts: { hint?: string } = {}\n): Array<{ role: \"system\" | \"user\"; content: string }> {\n  return [\n    { role: \"system\", content: EXTRACTION_SYSTEM_PROMPT },\n    {\n      role: \"user\",\n      content: (opts.hint ? `Context: ${opts.hint}\\n\\n` : \"\") + raw,\n    },\n  ];\n}\n\nexport const EXTRACTION_JSON_SCHEMA = {\n  type: \"object\",\n  properties: {\n    facts: {\n      type: \"array\",\n      items: {\n        type: \"object\",\n        properties: {\n          body: { type: \"string\" },\n          topic: { type: \"string\" },\n          tags: { type: \"array\", items: { type: \"string\" } },\n        },\n        required: [\"body\"],\n      },\n    },\n    entities: {\n      type: \"array\",\n      items: {\n        type: \"object\",\n        properties: {\n          name: { type: \"string\" },\n          kind: { type: \"string\" },\n          body: { type: \"string\" },\n        },\n        required: [\"name\"],\n      },\n    },\n    edges: {\n      type: \"array\",\n      items: {\n        type: \"object\",\n        properties: {\n          src: { type: \"string\" },\n          rel: { type: \"string\" },\n          dst: { type: \"string\" },\n        },\n        required: [\"src\", \"rel\", \"dst\"],\n      },\n    },\n  },\n} as const;\n"],"mappings":"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","names":[]}

package/dist/core.d.cts

@@ -0,0 +1,188 @@
+/**
+ * @persql/context/core — zero-runtime-dependency engine.
+ *
+ * Schema DDL, SQL builders, and the extraction/compaction contracts shared by
+ * the `@persql/context` SDK (client-side, over `@persql/sdk`) and the hosted
+ * PerSQL Context worker (server-side, over `@persql/ai`). Keeping both sides on
+ * the same builders means client-recall and server-recall can never drift.
+ *
+ * Retrieval is lexical: FTS5 with the porter stemmer, BM25-ranked. No vectors.
+ */
+declare const SCHEMA_VERSION = 1;
+declare const TABLE_PREFIX = "ctx_";
+type MemoryKind = "fact" | "episode" | "artifact";
+interface MemoryRow {
+    id: string;
+    kind: MemoryKind;
+    topic: string | null;
+    body: string;
+    tags: string | null;
+    source: string | null;
+    createdAt: number;
+    supersededBy: string | null;
+}
+interface Entity {
+    id: string;
+    name: string;
+    kind: string | null;
+    body: string | null;
+    createdAt: number;
+}
+interface Edge {
+    id: string;
+    src: string;
+    rel: string;
+    dst: string;
+    source: string | null;
+    createdAt: number;
+}
+interface RememberInput {
+    body: string;
+    topic?: string;
+    kind?: MemoryKind;
+    tags?: string[] | string;
+    source?: string;
+    supersedes?: string | string[];
+    id?: string;
+}
+interface EntityInput {
+    name: string;
+    kind?: string;
+    body?: string;
+    id?: string;
+}
+interface EdgeInput {
+    src: string;
+    rel: string;
+    dst: string;
+    source?: string;
+}
+interface RecallOptions {
+    limit?: number;
+    kind?: MemoryKind;
+    operator?: "or" | "and";
+    mode?: "terms" | "raw";
+    sinceMs?: number;
+    withinDays?: number;
+    includeSuperseded?: boolean;
+}
+interface ListOptions {
+    limit?: number;
+    kind?: MemoryKind;
+    includeSuperseded?: boolean;
+}
+/** The shape an extractor (LLM or the hosted worker) returns from raw text. */
+interface ExtractedContext {
+    facts?: Array<{
+        body: string;
+        topic?: string;
+        tags?: string[];
+        kind?: MemoryKind;
+    }>;
+    entities?: EntityInput[];
+    edges?: EdgeInput[];
+}
+interface SqlStatement {
+    sql: string;
+    params: unknown[];
+}
+declare const SCHEMA_SQL: string[];
+declare function buildInit(): SqlStatement[];
+declare function normalizeTags(tags?: string[] | string | null): string | null;
+/**
+ * Turn arbitrary user text into a safe FTS5 MATCH expression. `terms` mode
+ * (default) extracts word tokens, drops bare boolean operators, and ORs the
+ * rest as quoted terms — so a caller can paste "invoice OR billing" or just
+ * "invoice billing" and neither crashes the parser nor injects FTS syntax.
+ * `raw` mode passes a hand-written FTS expression through untouched.
+ */
+declare function toFtsQuery(input: string, opts?: {
+    operator?: "or" | "and";
+    mode?: "terms" | "raw";
+}): string | null;
+/** Deterministic id for an entity, keyed on its name (case-insensitive). */
+declare function entityId(name: string): string;
+declare function buildRemember(input: RememberInput, now: number, id: string): SqlStatement;
+declare function buildSupersede(oldId: string, newId: string): SqlStatement;
+declare function buildForget(id: string): SqlStatement;
+declare function buildGet(id: string): SqlStatement;
+declare function buildRecall(query: string, opts?: RecallOptions): SqlStatement | null;
+declare function buildRecent(opts?: ListOptions): SqlStatement;
+declare function buildByTag(tag: string, opts?: ListOptions): SqlStatement;
+declare function buildStats(): SqlStatement;
+declare function buildUpsertEntity(e: EntityInput, now: number): SqlStatement;
+declare function buildUpsertEdge(e: EdgeInput, now: number): SqlStatement;
+/** Entities reachable from a seed within `depth` hops (seed excluded). */
+declare function buildNeighborEntities(seedId: string, depth: number, limit: number): SqlStatement;
+declare function buildEdgesAmong(ids: string[]): SqlStatement;
+declare const EXTRACTION_SYSTEM_PROMPT = "You extract durable, shareable context from raw text for a team of AI agents that will read it later by keyword.\n\nReturn JSON: { \"facts\": [...], \"entities\": [...], \"edges\": [...] }.\n- facts: atomic, self-contained statements worth remembering across sessions \u2014 decisions, conventions, constraints, identifiers, preferences. Each: { \"body\": string, \"topic\"?: string, \"tags\"?: string[] }. Prefer specific and stable over transient chatter.\n- entities: named things \u2014 services, people, tables, repos, concepts. Each: { \"name\": string, \"kind\"?: string, \"body\"?: short description }.\n- edges: relationships between entities, referencing entity names. Each: { \"src\": name, \"rel\": string, \"dst\": name }.\n\nBe conservative: omit anything ephemeral or low-value. Use lowercase tags. If nothing is worth keeping, return empty arrays.";
+declare function buildExtractionMessages(raw: string, opts?: {
+    hint?: string;
+}): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+declare const EXTRACTION_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly facts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly body: {
+                        readonly type: "string";
+                    };
+                    readonly topic: {
+                        readonly type: "string";
+                    };
+                    readonly tags: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["body"];
+            };
+        };
+        readonly entities: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["name"];
+            };
+        };
+        readonly edges: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly src: {
+                        readonly type: "string";
+                    };
+                    readonly rel: {
+                        readonly type: "string";
+                    };
+                    readonly dst: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["src", "rel", "dst"];
+            };
+        };
+    };
+};
+
+export { EXTRACTION_JSON_SCHEMA, EXTRACTION_SYSTEM_PROMPT, type Edge, type EdgeInput, type Entity, type EntityInput, type ExtractedContext, type ListOptions, type MemoryKind, type MemoryRow, type RecallOptions, type RememberInput, SCHEMA_SQL, SCHEMA_VERSION, type SqlStatement, TABLE_PREFIX, buildByTag, buildEdgesAmong, buildExtractionMessages, buildForget, buildGet, buildInit, buildNeighborEntities, buildRecall, buildRecent, buildRemember, buildStats, buildSupersede, buildUpsertEdge, buildUpsertEntity, entityId, normalizeTags, toFtsQuery };