@persql/context 0.1.0 → 1.0.0

package/dist/core.d.ts

@@ -1,25 +1,32 @@
 /**
  * @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.
+ * Schema DDL, SQL builders, and the extraction contract shared by the
+ * `@persql/context` SDK (client-side, over `@persql/sdk`) and the hosted
+ * PerSQL Context worker (server-side, over `@persql/ai`). Structured memories
+ * with a name-keyed UPSERT + always-loaded index replace the old episode model.
  *
  * Retrieval is lexical: FTS5 with the porter stemmer, BM25-ranked. No vectors.
  */
-declare const SCHEMA_VERSION = 1;
+declare const SCHEMA_VERSION = 2;
 declare const TABLE_PREFIX = "ctx_";
-type MemoryKind = "fact" | "episode" | "artifact";
+type MemoryType = "user" | "feedback" | "project" | "reference";
 interface MemoryRow {
     id: string;
-    kind: MemoryKind;
-    topic: string | null;
+    name: string;
+    description: string;
+    type: MemoryType;
     body: string;
-    tags: string | null;
     source: string | null;
     createdAt: number;
-    supersededBy: string | null;
+    updatedAt: number;
+}
+interface IndexRow {
+    id: string;
+    name: string;
+    description: string;
+    type: MemoryType;
+    updatedAt: number;
 }
 interface Entity {
     id: string;
@@ -37,13 +44,11 @@ interface Edge {
     createdAt: number;
 }
 interface RememberInput {
+    name: string;
+    description: string;
+    type?: MemoryType;
     body: string;
-    topic?: string;
-    kind?: MemoryKind;
-    tags?: string[] | string;
     source?: string;
-    supersedes?: string | string[];
-    id?: string;
 }
 interface EntityInput {
     name: string;
@@ -59,25 +64,20 @@ interface EdgeInput {
 }
 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;
+    type?: MemoryType;
 }
-/** The shape an extractor (LLM or the hosted worker) returns from raw text. */
+/** Structured memories extracted by an LLM from raw text. */
 interface ExtractedContext {
-    facts?: Array<{
+    memories?: Array<{
+        name: string;
+        description: string;
+        type?: MemoryType;
         body: string;
-        topic?: string;
-        tags?: string[];
-        kind?: MemoryKind;
     }>;
     entities?: EntityInput[];
     edges?: EdgeInput[];
@@ -88,34 +88,39 @@ interface SqlStatement {
 }
 declare const SCHEMA_SQL: string[];
 declare function buildInit(): SqlStatement[];
-declare function normalizeTags(tags?: string[] | string | null): string | null;
+/** Returns a non-zero count when the old (topic-based) schema is present. */
+declare function buildDetectLegacySchema(): SqlStatement;
+/**
+ * Drop all ctx_ tables + triggers so buildInit() can recreate them cleanly.
+ * Run in order — FTS must go first (it references the content table).
+ */
+declare function buildDropLegacy(): SqlStatement[];
 /**
  * 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.
+ * rest as quoted terms. `raw` mode passes a hand-written FTS expression through.
  */
 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;
+/** UPSERT by name — same name overwrites description/body/type/source. */
 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;
+/** Delete a memory by its name slug. */
+declare function buildForget(name: string): SqlStatement;
+/** Fetch one memory row by name, or null if absent. */
+declare function buildGet(name: string): SqlStatement;
+/** Always-loaded index: name+description+type, newest first. */
+declare function buildIndex(opts?: ListOptions): SqlStatement;
+/** BM25 recall across name+description+body. */
 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 const EXTRACTION_SYSTEM_PROMPT = "You extract durable, structured memories from a conversation or document for an AI agent that will recall them across sessions.\n\nReturn JSON: { \"memories\": [...], \"entities\": [...], \"edges\": [...] }.\n- memories: facts worth remembering across sessions \u2014 decisions, conventions, constraints, identifiers, preferences, schema details. Each:\n  {\n    \"name\": string (kebab-case slug, unique key \u2014 e.g. \"auth-provider-choice\", \"todos-table-schema\", \"user-prefers-metrics\"),\n    \"description\": string (one-liner shown in the always-loaded index),\n    \"type\": \"user\"|\"feedback\"|\"project\"|\"reference\",\n    \"body\": string (full markdown content with all relevant detail)\n  }\n  Types: user=who they are/preferences; feedback=guidance for agents; project=ongoing work/decisions; reference=where to find things.\n- entities: named things \u2014 services, people, tables, repos. Each: { \"name\": string, \"kind\"?: string, \"body\"?: string }\n- edges: relationships between entities. Each: { \"src\": name, \"rel\": string, \"dst\": name }\n\nBe conservative. Use unique, meaningful names. If nothing durable is found, return empty arrays.";
 declare function buildExtractionMessages(raw: string, opts?: {
     hint?: string;
 }): Array<{
@@ -125,25 +130,26 @@ declare function buildExtractionMessages(raw: string, opts?: {
 declare const EXTRACTION_JSON_SCHEMA: {
     readonly type: "object";
     readonly properties: {
-        readonly facts: {
+        readonly memories: {
             readonly type: "array";
             readonly items: {
                 readonly type: "object";
                 readonly properties: {
-                    readonly body: {
+                    readonly name: {
                         readonly type: "string";
                     };
-                    readonly topic: {
+                    readonly description: {
                         readonly type: "string";
                     };
-                    readonly tags: {
-                        readonly type: "array";
-                        readonly items: {
-                            readonly type: "string";
-                        };
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["user", "feedback", "project", "reference"];
+                    };
+                    readonly body: {
+                        readonly type: "string";
                     };
                 };
-                readonly required: readonly ["body"];
+                readonly required: readonly ["name", "description", "body"];
             };
         };
         readonly entities: {
@@ -185,4 +191,4 @@ declare const EXTRACTION_JSON_SCHEMA: {
     };
 };
 
-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 };
+export { EXTRACTION_JSON_SCHEMA, EXTRACTION_SYSTEM_PROMPT, type Edge, type EdgeInput, type Entity, type EntityInput, type ExtractedContext, type IndexRow, type ListOptions, type MemoryRow, type MemoryType, type RecallOptions, type RememberInput, SCHEMA_SQL, SCHEMA_VERSION, type SqlStatement, TABLE_PREFIX, buildDetectLegacySchema, buildDropLegacy, buildEdgesAmong, buildExtractionMessages, buildForget, buildGet, buildIndex, buildInit, buildNeighborEntities, buildRecall, buildRemember, buildStats, buildUpsertEdge, buildUpsertEntity, entityId, toFtsQuery };

package/dist/core.js

@@ -4,46 +4,44 @@ import {
   SCHEMA_SQL,
   SCHEMA_VERSION,
   TABLE_PREFIX,
-  buildByTag,
+  buildDetectLegacySchema,
+  buildDropLegacy,
   buildEdgesAmong,
   buildExtractionMessages,
   buildForget,
   buildGet,
+  buildIndex,
   buildInit,
   buildNeighborEntities,
   buildRecall,
-  buildRecent,
   buildRemember,
   buildStats,
-  buildSupersede,
   buildUpsertEdge,
   buildUpsertEntity,
   entityId,
-  normalizeTags,
   toFtsQuery
-} from "./chunk-RMG66FDI.js";
+} from "./chunk-HRHBXOPL.js";
 export {
   EXTRACTION_JSON_SCHEMA,
   EXTRACTION_SYSTEM_PROMPT,
   SCHEMA_SQL,
   SCHEMA_VERSION,
   TABLE_PREFIX,
-  buildByTag,
+  buildDetectLegacySchema,
+  buildDropLegacy,
   buildEdgesAmong,
   buildExtractionMessages,
   buildForget,
   buildGet,
+  buildIndex,
   buildInit,
   buildNeighborEntities,
   buildRecall,
-  buildRecent,
   buildRemember,
   buildStats,
-  buildSupersede,
   buildUpsertEdge,
   buildUpsertEntity,
   entityId,
-  normalizeTags,
   toFtsQuery
 };
 //# sourceMappingURL=core.js.map