@atomicmemory/core 1.0.0

package/dist/services/extraction.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Memory extraction and AUDN resolution.
+ * Step 1: Extract discrete facts from conversation text.
+ * Step 2: For each fact with similar existing memories, LLM decides:
+ *   Add (new), Update (merge), Delete (outdated), or Noop (skip).
+ * Uses the LLM provider abstraction for model-agnostic operation.
+ */
+import { type ExtractionOptions } from './observation-date-extraction.js';
+export type { ExtractionOptions };
+/** Return the first complete JSON object, tolerating prose before/after it. */
+export declare function extractFirstJsonObject(raw: string): string;
+export interface ExtractedEntity {
+    name: string;
+    type: 'person' | 'tool' | 'project' | 'organization' | 'place' | 'concept';
+}
+export type ExtractedRelationType = 'uses' | 'works_on' | 'works_at' | 'located_in' | 'knows' | 'prefers' | 'created' | 'belongs_to' | 'studies' | 'manages';
+export interface ExtractedRelation {
+    source: string;
+    target: string;
+    type: ExtractedRelationType;
+}
+export interface ExtractedFact {
+    fact: string;
+    headline: string;
+    importance: number;
+    type: 'preference' | 'project' | 'knowledge' | 'person' | 'plan';
+    keywords: string[];
+    entities: ExtractedEntity[];
+    relations: ExtractedRelation[];
+    /** Memory network classification (set post-extraction by classifyNetwork). */
+    network?: 'world' | 'experience' | 'opinion' | 'observation';
+    /** Opinion confidence [0,1], only set when network='opinion'. */
+    opinionConfidence?: number | null;
+}
+export type AUDNAction = 'ADD' | 'UPDATE' | 'DELETE' | 'SUPERSEDE' | 'NOOP' | 'CLARIFY';
+export interface AUDNDecision {
+    action: AUDNAction;
+    targetMemoryId: string | null;
+    updatedContent: string | null;
+    clarificationNote?: string | null;
+    contradictionConfidence: number | null;
+}
+export interface ExistingMemory {
+    id: string;
+    content: string;
+    similarity: number;
+}
+export declare const EXTRACTION_PROMPT = "You are a memory extraction system. Extract discrete, self-contained facts from the conversation below. Each fact should be useful if retrieved months later in a completely different conversation.\n\nRULES:\n- Each fact must be a single, atomic statement.\n- **AGGRESSIVE TECHNOLOGY SPLITTING**: Every named tool, framework, library, or technology MUST become its own separate fact. Never combine multiple technologies into a single fact.\n  WRONG: \"User is building a React project with Tailwind CSS and Supabase.\"\n  RIGHT: Three separate facts:\n    1. \"As of January 2026, user is building a personal finance tracker using React.\"\n    2. \"As of January 2026, user is using Tailwind CSS for styling in the finance tracker project.\"\n    3. \"As of January 2026, user is using Supabase for the backend and database in the finance tracker project.\"\n- If a sentence contains multiple independent attributes of the same project or tool, split them into separate facts.\n- If a sentence contains both a technical choice and who recommended it, extract separate facts for the choice and the recommendation.\n- Each technology fact MUST include the project name, the current date (if available), and the specific role of the technology.\n- Include enough context to be understood in isolation.\n- Replace pronouns with specific names/references.\n- Convert relative times to absolute when possible.\n- Always include dates and timestamps in extracted facts when available (e.g. \"As of January 2026, user prefers Vite\" not just \"User prefers Vite\").\n- If the conversation has a date/session header, use it to anchor facts temporally.\n- **ENTITY-FOCUSED EXTRACTION**: Every named person, institution, organization, specific number, or score mentioned by the user MUST appear in at least one extracted fact. Scan the conversation for these and create dedicated facts:\n  - People: names, roles, relationships (e.g. \"Dr. Chen is user's advisor at Microsoft Research\")\n  - Institutions: universities, companies, labs (e.g. \"User got BS in Computer Science from UC Berkeley\")\n  - Numbers/scores: test scores, percentages, counts (e.g. \"User scored 170 on GRE quant\")\n  - Licenses/certifications: specific names (e.g. \"User plans to use MIT license for dotctl\")\n  - Future plans: specific tools or techniques planned (e.g. \"User plans to add ML classification using TensorFlow.js\")\n  If you find a name, number, or institution in the conversation that is NOT in any extracted fact, you MUST add a fact for it.\n- **CORRECTION/REVISION PRESERVATION**: When the conversation contains an explicit correction, revision, or supersession of a previous statement (e.g. \"Correction:\", \"Actually,\", \"Changed my mind\"), the extracted fact MUST preserve the corrective relationship. Include phrasing like \"instead of Y\", \"replacing Y\", \"corrected from Y\", or \"no longer Y\" so the system can detect the supersession.\n  WRONG: \"User wants PostgreSQL for the production backend.\"\n  RIGHT: \"User wants PostgreSQL for the production backend, replacing the earlier MongoDB choice.\"\n- Skip pleasantries, filler, acknowledgments, and meta-conversation.\n- Skip generic assistant chatter (acknowledgments, \"sure!\", \"got it\", \"as an AI\").\n- DO extract specific factual content from assistant responses: named entities, recommendations with proper nouns, schedules, data tables, creative writing with specific details. Prefix these with \"Assistant mentioned:\" or \"Assistant recommended:\".\n- SHORT INPUTS: Even a single sentence like \"My email is bob@example.com\" contains an extractable fact. Do NOT skip short inputs \u2014 if the user stated something factual, extract it regardless of length.\n- CONTACT INFO: Email addresses, phone numbers, home addresses, and similar personal details are always extractable facts with importance >= 0.5.\n- Rate importance 0.0-1.0:\n  0.0-0.3 = trivial (greeting style, minor preferences)\n  0.4-0.6 = useful (project details, tools mentioned)\n  0.7-0.9 = important (core preferences, key decisions, recurring patterns)\n  1.0 = critical (explicit instructions for future, strong opinions)\n\nCATEGORIES:\n- preference: Likes, dislikes, opinions, style choices\n- project: What the user is building, tools used, architecture decisions\n- knowledge: Patterns learned, problems solved, techniques discovered\n- person: People mentioned, relationships, roles\n- plan: Goals, intentions, scheduled activities, future work\n\nKEYWORDS:\nFor each fact, extract keywords that a keyword search should match. Include:\n- Proper nouns (people, companies, products, tools): \"Jake\", \"Supabase\", \"TanStack Virtual\"\n- Dates and time references: \"January 15 2026\", \"February 5 2026\"\n- Project names and domains: \"fintrack.app\", \"dotctl\"\n- Technical terms that might be lost in paraphrasing: \"tRPC\", \"LoRA\", \"EMNLP\"\n- Organization names: \"Stanford\", \"Microsoft Research\", \"MIT\"\nKeywords preserve the original spelling and casing from the conversation.\n\nHEADLINE:\nFor each fact, write a short headline (max 10 words) that captures the key point.\nThe headline is used as a compact preview when listing memories. It should contain\nthe most important entity and action from the fact.\nExample: \"User prefers Vite over Webpack for all React projects\" \u2192 \"Prefers Vite over Webpack for React\"\n\nENTITIES:\nFor each fact, extract the named entities mentioned. Each entity has:\n- name: The entity's canonical name (e.g. \"Jake\", \"PostgreSQL\", \"Dataflow Inc\")\n- type: One of: person, tool, project, organization, place, concept\nEntity types:\n- person: Named individuals (e.g. \"Jake\", \"Dr. Chen\", \"Sarah\")\n- tool: Software, libraries, frameworks (e.g. \"PostgreSQL\", \"Vite\", \"React\")\n- project: Named projects or products (e.g. \"DataFlow\", \"MealMate\", \"dotctl\")\n- organization: Companies, universities, teams (e.g. \"MIT\", \"Google\", \"Dataflow Inc\")\n- place: Cities, countries, addresses (e.g. \"San Francisco\", \"Berlin\")\n- concept: Abstract concepts, methodologies (e.g. \"microservices\", \"TDD\")\nOnly extract entities explicitly named in the fact. Do not infer entities not mentioned.\n\nRELATIONS:\nFor each fact, extract relationships between entities mentioned in that fact.\nEach relation has:\n- source: Name of the source entity (must match an entity name above)\n- target: Name of the target entity (must match an entity name above)\n- type: One of: uses, works_on, works_at, located_in, knows, prefers, created, belongs_to, studies, manages\nRelation types:\n- uses: Person/project uses a tool/technology\n- works_on: Person works on a project\n- works_at: Person works at an organization\n- located_in: Person/organization is located in a place\n- knows: Person knows another person\n- prefers: Person prefers a tool/concept\n- created: Person created a project/tool\n- belongs_to: Entity belongs to an organization/group\n- studies: Person studies a concept/field\n- manages: Person manages a project/team\nOnly extract relations between entities explicitly mentioned in the fact. If a fact has fewer than 2 entities, return an empty relations array.\n\nOUTPUT FORMAT (JSON):\n{\n  \"memories\": [\n    {\n      \"fact\": \"User prefers Vite over Webpack for all React projects\",\n      \"headline\": \"Prefers Vite over Webpack for React\",\n      \"importance\": 0.7,\n      \"type\": \"preference\",\n      \"keywords\": [\"Vite\", \"Webpack\", \"React\"],\n      \"entities\": [\n        {\"name\": \"Vite\", \"type\": \"tool\"},\n        {\"name\": \"Webpack\", \"type\": \"tool\"},\n        {\"name\": \"React\", \"type\": \"tool\"}\n      ],\n      \"relations\": [\n        {\"source\": \"User\", \"target\": \"Vite\", \"type\": \"prefers\"}\n      ]\n    }\n  ]\n}\n\nIf no extractable facts exist, return: {\"memories\": []}";
+export declare function extractFacts(conversationText: string, options?: ExtractionOptions): Promise<ExtractedFact[]>;
+export declare function resolveAUDN(newFact: string, existingMemories: ExistingMemory[]): Promise<AUDNDecision>;
+export declare function rewriteQuery(query: string): Promise<string>;
+/** Clear the rewrite cache (for testing). */
+export declare function clearRewriteCache(): void;
+/** Get rewrite cache size (for testing/monitoring). */
+export declare function getRewriteCacheSize(): number;
+/** Normalize a raw action string to a valid AUDNAction, defaulting to ADD. */
+export declare function normalizeAction(raw: string | undefined | null): AUDNAction;
+/** Return the default ADD decision (no target, no content). */
+export declare function defaultDecision(): AUDNDecision;
+/** Normalize contradiction confidence: clamp to [0,1] or infer from action. */
+export declare function normalizeConfidence(value: number | null | undefined, rawAction: string, newFact: string): number | null;
+/** Infer conflict confidence from fact text; forceLow=true returns 0.35. */
+export declare function inferConflictConfidence(newFact: string, forceLow: boolean): number;
+/** Normalize and validate extracted entities, filtering out invalid entries. */
+export declare function normalizeExtractedEntities(raw: unknown): ExtractedEntity[];
+/** Normalize and validate extracted relations, filtering out invalid entries. */
+export declare function normalizeExtractedRelations(raw: unknown): ExtractedRelation[];
+/** Truncate a fact to its first ~10 words as a fallback headline. */
+export declare function generateFallbackHeadline(fact: string): string;