@persql/context 0.1.0 → 1.0.0

package/dist/index.cjs

@@ -26,65 +26,63 @@ __export(index_exports, {
   SCHEMA_SQL: () => SCHEMA_SQL,
   SCHEMA_VERSION: () => SCHEMA_VERSION,
   TABLE_PREFIX: () => TABLE_PREFIX,
-  buildByTag: () => buildByTag,
+  buildDetectLegacySchema: () => buildDetectLegacySchema,
+  buildDropLegacy: () => buildDropLegacy,
   buildEdgesAmong: () => buildEdgesAmong,
   buildExtractionMessages: () => buildExtractionMessages,
   buildForget: () => buildForget,
   buildGet: () => buildGet,
+  buildIndex: () => buildIndex,
   buildInit: () => buildInit,
   buildNeighborEntities: () => buildNeighborEntities,
   buildRecall: () => buildRecall,
-  buildRecent: () => buildRecent,
   buildRemember: () => buildRemember,
   buildStats: () => buildStats,
-  buildSupersede: () => buildSupersede,
   buildUpsertEdge: () => buildUpsertEdge,
   buildUpsertEntity: () => buildUpsertEntity,
   context: () => context,
   entityId: () => entityId,
-  normalizeTags: () => normalizeTags,
+  memoryTools: () => memoryTools,
   toFtsQuery: () => toFtsQuery
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/core.ts
-var SCHEMA_VERSION = 1;
+var SCHEMA_VERSION = 2;
 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,
+     name TEXT NOT NULL,
+     description TEXT NOT NULL,
+     type TEXT NOT NULL DEFAULT 'project',
      body TEXT NOT NULL,
-     tags TEXT,
      source TEXT,
      created_at INTEGER NOT NULL,
-     superseded_by TEXT
+     updated_at INTEGER NOT NULL
    )`,
-  `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 UNIQUE INDEX IF NOT EXISTS ${T}memory_name ON ${T}memory(name)`,
+  // External-content FTS on name+description+body. Porter stemmer so
+  // "invoice" recalls "invoicing" without embeddings.
   `CREATE VIRTUAL TABLE IF NOT EXISTS ${T}memory_fts USING fts5(
-     topic, body, tags,
+     name, description, body,
      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);
+     INSERT INTO ${T}memory_fts(rowid, name, description, body)
+     VALUES (new.rowid, new.name, new.description, new.body);
    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);
+     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, name, description, body)
+     VALUES ('delete', old.rowid, old.name, old.description, old.body);
    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);
+     INSERT INTO ${T}memory_fts(${T}memory_fts, rowid, name, description, body)
+     VALUES ('delete', old.rowid, old.name, old.description, old.body);
+     INSERT INTO ${T}memory_fts(rowid, name, description, body)
+     VALUES (new.rowid, new.name, new.description, new.body);
    END`,
   `CREATE TABLE IF NOT EXISTS ${T}entity (
      id TEXT PRIMARY KEY,
@@ -107,15 +105,21 @@ var SCHEMA_SQL = [
 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 buildDetectLegacySchema() {
+  return {
+    sql: `SELECT count(*) AS n FROM pragma_table_info('${T}memory') WHERE name='topic'`,
+    params: []
+  };
 }
+function buildDropLegacy() {
+  return [
+    { sql: `DROP TABLE IF EXISTS ${T}memory_fts`, params: [] },
+    { sql: `DROP TABLE IF EXISTS ${T}memory`, params: [] },
+    { sql: `DROP TABLE IF EXISTS ${T}entity`, params: [] },
+    { sql: `DROP TABLE IF EXISTS ${T}edge`, params: [] }
+  ];
+}
+var FTS_OPERATORS = /* @__PURE__ */ new Set(["and", "or", "not", "near"]);
 function toFtsQuery(input, opts = {}) {
   if (opts.mode === "raw") return input.trim() || null;
   const tokens = (input.match(/[\p{L}\p{N}_]+/gu) ?? []).filter(
@@ -138,103 +142,71 @@ function resolveEntityRef(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";
+var MEMORY_COLS = "id, name, description, type, body, source, created_at AS createdAt, updated_at AS updatedAt";
 function buildRemember(input, now, id) {
   return {
-    sql: `INSERT INTO ${T}memory (id, kind, topic, body, tags, source, created_at, superseded_by)
-          VALUES (?, ?, ?, ?, ?, ?, ?, NULL)`,
+    sql: `INSERT INTO ${T}memory (id, name, description, type, body, source, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(name) DO UPDATE SET
+            description = excluded.description,
+            body        = excluded.body,
+            type        = excluded.type,
+            source      = excluded.source,
+            updated_at  = excluded.updated_at`,
     params: [
       id,
-      input.kind ?? "fact",
-      input.topic ?? null,
+      input.name,
+      input.description,
+      input.type ?? "project",
       input.body,
-      normalizeTags(input.tags),
       input.source ?? null,
+      now,
       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 buildForget(name) {
+  return { sql: `DELETE FROM ${T}memory WHERE name = ?`, params: [name] };
 }
-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);
+function buildGet(name) {
   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
+    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory WHERE name = ?`,
+    params: [name]
   };
 }
-function buildRecent(opts = {}) {
+function buildIndex(opts = {}) {
   const where = [];
   const params = [];
-  if (!opts.includeSuperseded) where.push("superseded_by IS NULL");
-  if (opts.kind) {
-    where.push("kind = ?");
-    params.push(opts.kind);
+  if (opts.type) {
+    where.push("type = ?");
+    params.push(opts.type);
   }
-  params.push(opts.limit ?? 20);
+  params.push(opts.limit ?? 50);
   return {
-    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory
+    sql: `SELECT id, name, description, type, updated_at AS updatedAt FROM ${T}memory
           ${where.length ? "WHERE " + where.join(" AND ") : ""}
-          ORDER BY created_at DESC
-          LIMIT ?`,
+          ORDER BY updated_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);
+function buildRecall(query, opts = {}) {
+  const match = toFtsQuery(query, { operator: opts.operator, mode: opts.mode });
+  if (!match) return null;
   return {
-    sql: `SELECT ${MEMORY_COLS} FROM ${T}memory
-          WHERE ${where.join(" AND ")}
-          ORDER BY created_at DESC
+    sql: `SELECT m.id, m.name, m.description, m.type, m.body, m.source,
+                 m.created_at AS createdAt, m.updated_at AS updatedAt
+          FROM ${T}memory_fts
+          JOIN ${T}memory m ON m.rowid = ${T}memory_fts.rowid
+          WHERE ${T}memory_fts MATCH ?
+          ORDER BY ${T}memory_fts.rank
           LIMIT ?`,
-    params
+    params: [match, opts.limit ?? 8]
   };
 }
 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}memory) AS memories,
             (SELECT count(*) FROM ${T}entity) AS entities,
             (SELECT count(*) FROM ${T}edge) AS edges`,
     params: []
@@ -283,8 +255,7 @@ function buildNeighborEntities(seedId, depth, limit) {
           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.
+    // The seed appears at depth >0 on undirected round-trips — exclude it.
     params: [seedId, depth, seedId, limit]
   };
 }
@@ -300,14 +271,21 @@ function buildEdgesAmong(ids) {
     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.
+var EXTRACTION_SYSTEM_PROMPT = `You extract durable, structured memories from a conversation or document for an AI agent that will recall them across sessions.
 
-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 }.
+Return JSON: { "memories": [...], "entities": [...], "edges": [...] }.
+- memories: facts worth remembering across sessions \u2014 decisions, conventions, constraints, identifiers, preferences, schema details. Each:
+  {
+    "name": string (kebab-case slug, unique key \u2014 e.g. "auth-provider-choice", "todos-table-schema", "user-prefers-metrics"),
+    "description": string (one-liner shown in the always-loaded index),
+    "type": "user"|"feedback"|"project"|"reference",
+    "body": string (full markdown content with all relevant detail)
+  }
+  Types: user=who they are/preferences; feedback=guidance for agents; project=ongoing work/decisions; reference=where to find things.
+- entities: named things \u2014 services, people, tables, repos. Each: { "name": string, "kind"?: string, "body"?: string }
+- edges: relationships between entities. 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.`;
+Be conservative. Use unique, meaningful names. If nothing durable is found, return empty arrays.`;
 function buildExtractionMessages(raw, opts = {}) {
   return [
     { role: "system", content: EXTRACTION_SYSTEM_PROMPT },
@@ -322,16 +300,17 @@ function buildExtractionMessages(raw, opts = {}) {
 var EXTRACTION_JSON_SCHEMA = {
   type: "object",
   properties: {
-    facts: {
+    memories: {
       type: "array",
       items: {
         type: "object",
         properties: {
-          body: { type: "string" },
-          topic: { type: "string" },
-          tags: { type: "array", items: { type: "string" } }
+          name: { type: "string" },
+          description: { type: "string" },
+          type: { type: "string", enum: ["user", "feedback", "project", "reference"] },
+          body: { type: "string" }
         },
-        required: ["body"]
+        required: ["name", "description", "body"]
       }
     },
     entities: {
@@ -377,44 +356,29 @@ var ContextStore = class {
     await this.db.batch(buildInit());
   }
   // --- writes -------------------------------------------------------------
-  /** Store one structured fact/episode/artifact. Returns its id. */
+  /** UPSERT a named memory. Same name → update; new name → insert. */
   async remember(input) {
-    const id = input.id ?? uid("m_");
+    const id = uid("m_");
     const now = Date.now();
-    const stmts = [
-      buildRemember({ ...input, source: input.source ?? this.opts.source }, now, id)
-    ];
-    const sup = input.supersedes ? Array.isArray(input.supersedes) ? input.supersedes : [input.supersedes] : [];
-    for (const old of sup) stmts.push(buildSupersede(old, id));
-    await this.db.transaction(stmts);
-    return id;
-  }
-  /**
-   * Extract durable context from raw text and store it. The LLM runs on the
-   * write path; pass `extract` here or to the constructor (or use the hosted
-   * Context MCP, which runs extraction server-side and meters it).
-   */
-  async rememberRaw(raw, opts = {}) {
-    const extract = opts.extract ?? this.opts.extract;
-    if (!extract) {
-      throw new Error(
-        "ContextStore.rememberRaw needs an extractor: pass { extract } here or to the constructor, or use the hosted PerSQL Context MCP."
-      );
-    }
-    const extracted = await extract(raw, { hint: opts.hint });
-    return this.write(extracted, { source: opts.source });
+    const s = buildRemember(
+      { ...input, source: input.source ?? this.opts.source },
+      now,
+      id
+    );
+    await this.db.query(s.sql, s.params);
   }
-  /** Persist an already-extracted bundle of facts, entities, and edges. */
+  /** Persist an already-extracted bundle of memories, entities, and edges. */
   async write(extracted, opts = {}) {
     const now = Date.now();
     const source = opts.source ?? this.opts.source;
     const stmts = [];
-    const memoryIds = [];
+    const names = [];
     const entityIds = /* @__PURE__ */ new Set();
-    for (const f of extracted.facts ?? []) {
+    for (const m of extracted.memories ?? []) {
+      if (!m?.name || !m?.body) continue;
       const id = uid("m_");
-      memoryIds.push(id);
-      stmts.push(buildRemember({ ...f, source }, now, id));
+      names.push(m.name);
+      stmts.push(buildRemember({ ...m, source }, now, id));
     }
     for (const e of extracted.entities ?? []) {
       stmts.push(buildUpsertEntity(e, now));
@@ -429,19 +393,14 @@ var ContextStore = class {
     }
     if (stmts.length) await this.db.transaction(stmts);
     return {
-      memoryIds,
+      names,
       entityIds: [...entityIds],
       edgeCount: (extracted.edges ?? []).length
     };
   }
-  /** Mark older memory rows as replaced by `newId` (filtered out of recall). */
-  async supersede(oldIds, newId) {
-    const ids = Array.isArray(oldIds) ? oldIds : [oldIds];
-    await this.db.transaction(ids.map((o) => buildSupersede(o, newId)));
-  }
-  /** Hard-delete a memory row. */
-  async forget(id) {
-    const s = buildForget(id);
+  /** Hard-delete a memory row by name. */
+  async forget(name) {
+    const s = buildForget(name);
     await this.db.query(s.sql, s.params);
   }
   /** Add a relationship between two entities (created if absent). */
@@ -457,35 +416,25 @@ var ContextStore = class {
     ]);
   }
   // --- reads (no AI, pure lexical SQL) ------------------------------------
-  /** Keyword recall, BM25-ranked, most relevant first. */
-  async recall(query, opts = {}) {
-    const resolved = { ...opts };
-    if (opts.withinDays != null && opts.sinceMs == null) {
-      resolved.sinceMs = Date.now() - opts.withinDays * 864e5;
-    }
-    const s = buildRecall(query, resolved);
-    if (!s) return [];
+  /** Always-loaded index: name+description+type, newest first. */
+  async index(opts = {}) {
+    const s = buildIndex(opts);
     const { data } = await this.db.query(s.sql, s.params);
     return data;
   }
-  /** Most recent memory rows. */
-  async recent(opts = {}) {
-    const s = buildRecent(opts);
+  /** Fetch one memory by name (with full body). */
+  async get(name) {
+    const s = buildGet(name);
     const { data } = await this.db.query(s.sql, s.params);
-    return data;
+    return data[0] ?? null;
   }
-  /** Memory rows carrying a given tag. */
-  async byTag(tag, opts = {}) {
-    const s = buildByTag(tag, opts);
+  /** Keyword recall, BM25-ranked, most relevant first. */
+  async recall(query, opts = {}) {
+    const s = buildRecall(query, opts);
+    if (!s) return [];
     const { data } = await this.db.query(s.sql, s.params);
     return data;
   }
-  /** Fetch one memory row by id, or null. */
-  async get(id) {
-    const s = buildGet(id);
-    const { data } = await this.db.query(s.sql, s.params);
-    return data[0] ?? null;
-  }
   /** The subgraph around an entity: reachable entities + the edges among them. */
   async neighbors(name, opts = {}) {
     const seed = name.startsWith("e_") ? name : entityId(name);
@@ -503,14 +452,13 @@ var ContextStore = class {
     );
     return { entities, edges };
   }
-  /** Counts: current facts, total facts, entities, edges. */
+  /** Counts: memories, entities, edges. */
   async stats() {
     const s = buildStats();
     const { data } = await this.db.query(s.sql, s.params);
     const r = data[0];
     return {
-      facts: r?.facts ?? 0,
-      factsTotal: r?.facts_total ?? 0,
+      memories: r?.memories ?? 0,
       entities: r?.entities ?? 0,
       edges: r?.edges ?? 0
     };
@@ -519,6 +467,91 @@ var ContextStore = class {
 function context(db, opts) {
   return new ContextStore(db, opts);
 }
+function memoryTools(store) {
+  return [
+    {
+      type: "function",
+      name: "remember_memory",
+      description: "Save or update a named memory. Use for facts worth keeping across sessions: schema details, user preferences, decisions. Same name overwrites the previous entry.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Short kebab-case key, e.g. 'billing-preference'"
+          },
+          description: {
+            type: "string",
+            description: "One-line summary shown in the memory index"
+          },
+          type: {
+            type: "string",
+            enum: ["user", "feedback", "project", "reference"],
+            description: "Memory category"
+          },
+          body: {
+            type: "string",
+            description: "Full content of the memory"
+          }
+        },
+        required: ["name", "description", "body"],
+        additionalProperties: false
+      },
+      invoke: async (input) => {
+        await store.remember({
+          name: String(input.name),
+          description: String(input.description),
+          type: input.type ?? "project",
+          body: String(input.body)
+        });
+        return { saved: input.name };
+      }
+    },
+    {
+      type: "function",
+      name: "recall_memory",
+      description: "Search memories by keyword. Returns the most relevant entries (BM25-ranked). Use when the answer might be in memory before querying a live data source.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Keywords to search for"
+          },
+          limit: {
+            type: "number",
+            description: "Max results (default 10)"
+          }
+        },
+        required: ["query"],
+        additionalProperties: false
+      },
+      invoke: async (input) => {
+        const rows = await store.recall(String(input.query), {
+          limit: typeof input.limit === "number" ? input.limit : 10
+        });
+        return { memories: rows };
+      }
+    },
+    {
+      type: "function",
+      name: "forget_memory",
+      description: "Delete a saved memory by name.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Name of the memory to delete" }
+        },
+        required: ["name"],
+        additionalProperties: false
+      },
+      invoke: async (input) => {
+        await store.forget(String(input.name));
+        return { deleted: input.name };
+      }
+    }
+  ];
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ContextStore,
@@ -527,23 +560,23 @@ function context(db, opts) {
   SCHEMA_SQL,
   SCHEMA_VERSION,
   TABLE_PREFIX,
-  buildByTag,
+  buildDetectLegacySchema,
+  buildDropLegacy,
   buildEdgesAmong,
   buildExtractionMessages,
   buildForget,
   buildGet,
+  buildIndex,
   buildInit,
   buildNeighborEntities,
   buildRecall,
-  buildRecent,
   buildRemember,
   buildStats,
-  buildSupersede,
   buildUpsertEdge,
   buildUpsertEntity,
   context,
   entityId,
-  normalizeTags,
+  memoryTools,
   toFtsQuery
 });
 //# sourceMappingURL=index.cjs.map