@plur-ai/core 0.7.7 → 0.8.2

package/dist/index.d.ts

@@ -1,5 +1,36 @@
 import { z } from 'zod';
 
+interface HistoryEvent {
+    event: 'engram_created' | 'engram_updated' | 'engram_merged' | 'feedback_received' | 'engram_retired' | 'engram_promoted' | 'failure_reported' | 'procedure_evolved';
+    engram_id: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Append a history event to the JSONL file for the current month.
+ * Files are stored in {root}/history/YYYY-MM.jsonl.
+ * Auto-creates the history directory and file on first write.
+ */
+declare function appendHistory(root: string, event: HistoryEvent): void;
+/**
+ * Read history events from a specific month's JSONL file.
+ * Returns empty array if file doesn't exist.
+ */
+declare function readHistory(root: string, yearMonth: string): HistoryEvent[];
+/**
+ * List all available history months (YYYY-MM format).
+ */
+declare function listHistoryMonths(root: string): string[];
+/**
+ * Read all history events for a specific engram, across all months.
+ * Returns events sorted chronologically.
+ */
+declare function readHistoryForEngram(root: string, engramId: string): HistoryEvent[];
+/**
+ * Generate a unique event ID for history entries.
+ */
+declare function generateEventId(): string;
+
 declare const KnowledgeAnchorSchema: z.ZodObject<{
     path: z.ZodString;
     relevance: z.ZodDefault<z.ZodEnum<["primary", "supporting", "example"]>>;
@@ -35,6 +66,16 @@ declare const AssociationSchema: z.ZodObject<{
     strength: number;
     updated_at?: string | undefined;
 }>;
+declare const PreviousVersionRefSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    changed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    event_id: string;
+    changed_at: string;
+}, {
+    event_id: string;
+    changed_at: string;
+}>;
 declare const EngramSchema: z.ZodObject<{
     id: z.ZodString;
     version: z.ZodDefault<z.ZodNumber>;
@@ -57,10 +98,10 @@ declare const EngramSchema: z.ZodObject<{
         cognitive_level: z.ZodEnum<["remember", "understand", "apply", "analyze", "evaluate", "create"]>;
     }, "strip", z.ZodTypeAny, {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
-        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+        cognitive_level: "apply" | "remember" | "evaluate" | "understand" | "analyze" | "create";
     }, {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
-        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+        cognitive_level: "apply" | "remember" | "evaluate" | "understand" | "analyze" | "create";
     }>>;
     domain: z.ZodOptional<z.ZodString>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -262,6 +303,23 @@ declare const EngramSchema: z.ZodObject<{
     structured_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     /** Polarity classification: 'do' for directives, 'dont' for prohibitions, null for unclassified. */
     polarity: z.ZodDefault<z.ZodNullable<z.ZodEnum<["do", "dont"]>>>;
+    content_hash: z.ZodOptional<z.ZodString>;
+    commitment: z.ZodOptional<z.ZodEnum<["exploring", "leaning", "decided", "locked"]>>;
+    locked_at: z.ZodOptional<z.ZodString>;
+    locked_reason: z.ZodOptional<z.ZodString>;
+    engram_version: z.ZodDefault<z.ZodNumber>;
+    previous_version_ref: z.ZodOptional<z.ZodObject<{
+        event_id: z.ZodString;
+        changed_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        event_id: string;
+        changed_at: string;
+    }, {
+        event_id: string;
+        changed_at: string;
+    }>>;
+    episode_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    summary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -301,6 +359,8 @@ declare const EngramSchema: z.ZodObject<{
         neutral: number;
     };
     polarity: "do" | "dont" | null;
+    engram_version: number;
+    episode_ids: string[];
     rationale?: string | undefined;
     contraindications?: string[] | undefined;
     source?: string | undefined;
@@ -313,7 +373,7 @@ declare const EngramSchema: z.ZodObject<{
     } | undefined;
     knowledge_type?: {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
-        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+        cognitive_level: "apply" | "remember" | "evaluate" | "understand" | "analyze" | "create";
     } | undefined;
     domain?: string | undefined;
     relations?: {
@@ -356,6 +416,15 @@ declare const EngramSchema: z.ZodObject<{
         fitness_score?: number | undefined;
     } | undefined;
     structured_data?: Record<string, unknown> | undefined;
+    content_hash?: string | undefined;
+    commitment?: "locked" | "decided" | "leaning" | "exploring" | undefined;
+    locked_at?: string | undefined;
+    locked_reason?: string | undefined;
+    previous_version_ref?: {
+        event_id: string;
+        changed_at: string;
+    } | undefined;
+    summary?: string | undefined;
 }, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -381,7 +450,7 @@ declare const EngramSchema: z.ZodObject<{
     } | undefined;
     knowledge_type?: {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
-        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+        cognitive_level: "apply" | "remember" | "evaluate" | "understand" | "analyze" | "create";
     } | undefined;
     domain?: string | undefined;
     tags?: string[] | undefined;
@@ -450,197 +519,22 @@ declare const EngramSchema: z.ZodObject<{
     } | undefined;
     structured_data?: Record<string, unknown> | undefined;
     polarity?: "do" | "dont" | null | undefined;
+    content_hash?: string | undefined;
+    commitment?: "locked" | "decided" | "leaning" | "exploring" | undefined;
+    locked_at?: string | undefined;
+    locked_reason?: string | undefined;
+    engram_version?: number | undefined;
+    previous_version_ref?: {
+        event_id: string;
+        changed_at: string;
+    } | undefined;
+    episode_ids?: string[] | undefined;
+    summary?: string | undefined;
 }>;
 type Engram = z.infer<typeof EngramSchema>;
 type KnowledgeAnchor = z.infer<typeof KnowledgeAnchorSchema>;
 type Association = z.infer<typeof AssociationSchema>;
-
-declare const PackManifestSchema: z.ZodObject<{
-    name: z.ZodString;
-    version: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    creator: z.ZodOptional<z.ZodString>;
-    license: z.ZodDefault<z.ZodString>;
-    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    metadata: z.ZodOptional<z.ZodObject<{
-        id: z.ZodOptional<z.ZodString>;
-        injection_policy: z.ZodDefault<z.ZodEnum<["on_match", "on_request", "always"]>>;
-        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        domain: z.ZodOptional<z.ZodString>;
-        engram_count: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        injection_policy: "on_match" | "on_request" | "always";
-        match_terms: string[];
-        id?: string | undefined;
-        domain?: string | undefined;
-        engram_count?: number | undefined;
-    }, {
-        id?: string | undefined;
-        domain?: string | undefined;
-        injection_policy?: "on_match" | "on_request" | "always" | undefined;
-        match_terms?: string[] | undefined;
-        engram_count?: number | undefined;
-    }>>;
-    'x-datacore': z.ZodOptional<z.ZodObject<{
-        id: z.ZodString;
-        injection_policy: z.ZodEnum<["on_match", "on_request"]>;
-        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        domain: z.ZodOptional<z.ZodString>;
-        engram_count: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        injection_policy: "on_match" | "on_request";
-        match_terms: string[];
-        engram_count: number;
-        domain?: string | undefined;
-    }, {
-        id: string;
-        injection_policy: "on_match" | "on_request";
-        engram_count: number;
-        domain?: string | undefined;
-        match_terms?: string[] | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    version: string;
-    tags: string[];
-    license: string;
-    name: string;
-    description?: string | undefined;
-    creator?: string | undefined;
-    metadata?: {
-        injection_policy: "on_match" | "on_request" | "always";
-        match_terms: string[];
-        id?: string | undefined;
-        domain?: string | undefined;
-        engram_count?: number | undefined;
-    } | undefined;
-    'x-datacore'?: {
-        id: string;
-        injection_policy: "on_match" | "on_request";
-        match_terms: string[];
-        engram_count: number;
-        domain?: string | undefined;
-    } | undefined;
-}, {
-    version: string;
-    name: string;
-    tags?: string[] | undefined;
-    license?: string | undefined;
-    description?: string | undefined;
-    creator?: string | undefined;
-    metadata?: {
-        id?: string | undefined;
-        domain?: string | undefined;
-        injection_policy?: "on_match" | "on_request" | "always" | undefined;
-        match_terms?: string[] | undefined;
-        engram_count?: number | undefined;
-    } | undefined;
-    'x-datacore'?: {
-        id: string;
-        injection_policy: "on_match" | "on_request";
-        engram_count: number;
-        domain?: string | undefined;
-        match_terms?: string[] | undefined;
-    } | undefined;
-}>;
-type PackManifest = z.infer<typeof PackManifestSchema>;
-
-interface RegistryEntry {
-    name: string;
-    installed_at: string;
-    source: string;
-    integrity: string;
-    version?: string;
-    creator?: string;
-}
-interface PreviewResult {
-    manifest: PackManifest;
-    engram_count: number;
-    engrams: Array<{
-        id: string;
-        type: string;
-        statement: string;
-        domain?: string;
-        tags: string[];
-    }>;
-    security: PrivacyScanResult;
-    warnings: string[];
-}
-declare function previewPack(source: string): PreviewResult;
-interface InstallResult {
-    installed: number;
-    name: string;
-    conflicts: ConflictItem[];
-    security: PrivacyScanResult;
-    registry: RegistryEntry;
-}
-interface ConflictItem {
-    pack_engram_id: string;
-    pack_statement: string;
-    existing_engram_id: string;
-    existing_statement: string;
-    type: 'contradiction' | 'duplicate';
-}
-declare function installPack(packsDir: string, source: string, existingEngrams?: Engram[]): InstallResult;
-interface UninstallResult {
-    name: string;
-    removed: boolean;
-    engram_count: number;
-}
-declare function uninstallPack(packsDir: string, name: string): UninstallResult;
-interface PackInfo {
-    name: string;
-    path: string;
-    engram_count: number;
-    manifest?: PackManifest;
-    integrity?: string;
-    installed_at?: string;
-    source?: string;
-    integrity_ok?: boolean;
-}
-declare function listPacks(packsDir: string): PackInfo[];
-interface ExportOptions {
-    name: string;
-    version: string;
-    description?: string;
-    creator?: string;
-    domain?: string;
-    scope?: string;
-    tags?: string[];
-    type?: string;
-}
-interface PrivacyScanResult {
-    clean: boolean;
-    issues: PrivacyIssue[];
-}
-interface PrivacyIssue {
-    engram_id: string;
-    type: 'secret' | 'private_visibility' | 'personal_path' | 'email' | 'ip_address';
-    detail: string;
-}
-interface ExportResult {
-    path: string;
-    engram_count: number;
-    privacy: PrivacyScanResult;
-    match_terms: string[];
-    integrity: string;
-}
-declare function exportPack(engrams: Engram[], outputDir: string, manifest: ExportOptions): ExportResult;
-
-interface SyncStatus {
-    initialized: boolean;
-    remote: string | null;
-    dirty: boolean;
-    branch: string | null;
-    ahead: number;
-    behind: number;
-}
-interface SyncResult {
-    action: 'initialized' | 'committed' | 'synced' | 'up-to-date';
-    message: string;
-    remote: string | null;
-    files_changed: number;
-}
+type PreviousVersionRef = z.infer<typeof PreviousVersionRefSchema>;
 
 declare const EpisodeSchema: z.ZodObject<{
     id: z.ZodString;
@@ -706,8 +600,32 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget?: number | undefined;
         co_access?: boolean | undefined;
     }>>>;
+    dedup: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        threshold: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["llm", "cosine", "off"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        mode?: "llm" | "cosine" | "off" | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        mode?: "llm" | "cosine" | "off" | undefined;
+    }>>>;
+    decay_baseline: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     allow_secrets: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     index: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    storage: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodDefault<z.ZodEnum<["yaml", "sqlite"]>>>;
+        path: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        path?: string | undefined;
+        backend?: "yaml" | "sqlite" | undefined;
+    }, {
+        path?: string | undefined;
+        backend?: "yaml" | "sqlite" | undefined;
+    }>>>;
     stores: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodString;
@@ -724,6 +642,30 @@ declare const PlurConfigSchema: z.ZodObject<{
         shared?: boolean | undefined;
         readonly?: boolean | undefined;
     }>, "many">>>;
+    llm: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        dedup_tier: z.ZodOptional<z.ZodDefault<z.ZodEnum<["fast", "balanced", "thorough"]>>>;
+        profile_tier: z.ZodOptional<z.ZodDefault<z.ZodEnum<["fast", "balanced", "thorough"]>>>;
+        meta_tier: z.ZodOptional<z.ZodDefault<z.ZodEnum<["fast", "balanced", "thorough"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        dedup_tier?: "fast" | "balanced" | "thorough" | undefined;
+        profile_tier?: "fast" | "balanced" | "thorough" | undefined;
+        meta_tier?: "fast" | "balanced" | "thorough" | undefined;
+    }, {
+        dedup_tier?: "fast" | "balanced" | "thorough" | undefined;
+        profile_tier?: "fast" | "balanced" | "thorough" | undefined;
+        meta_tier?: "fast" | "balanced" | "thorough" | undefined;
+    }>>>;
+    profile: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        cache_ttl_hours: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        cache_ttl_hours?: number | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        cache_ttl_hours?: number | undefined;
+    }>>>;
+    registry_url: z.ZodOptional<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     auto_learn?: boolean | undefined;
     auto_capture?: boolean | undefined;
@@ -736,14 +678,34 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget: number;
         co_access: boolean;
     } | undefined;
+    llm?: {
+        dedup_tier?: "fast" | "balanced" | "thorough" | undefined;
+        profile_tier?: "fast" | "balanced" | "thorough" | undefined;
+        meta_tier?: "fast" | "balanced" | "thorough" | undefined;
+    } | undefined;
+    dedup?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        mode?: "llm" | "cosine" | "off" | undefined;
+    } | undefined;
+    decay_baseline?: string | undefined;
     allow_secrets?: boolean | undefined;
     index?: boolean | undefined;
+    storage?: {
+        path?: string | undefined;
+        backend?: "yaml" | "sqlite" | undefined;
+    } | undefined;
     stores?: {
         path: string;
         scope: string;
         shared: boolean;
         readonly: boolean;
     }[] | undefined;
+    profile?: {
+        enabled?: boolean | undefined;
+        cache_ttl_hours?: number | undefined;
+    } | undefined;
+    registry_url?: string | undefined;
 }, {
     auto_learn?: boolean | undefined;
     auto_capture?: boolean | undefined;
@@ -756,17 +718,127 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget?: number | undefined;
         co_access?: boolean | undefined;
     } | undefined;
+    llm?: {
+        dedup_tier?: "fast" | "balanced" | "thorough" | undefined;
+        profile_tier?: "fast" | "balanced" | "thorough" | undefined;
+        meta_tier?: "fast" | "balanced" | "thorough" | undefined;
+    } | undefined;
+    dedup?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        mode?: "llm" | "cosine" | "off" | undefined;
+    } | undefined;
+    decay_baseline?: string | undefined;
     allow_secrets?: boolean | undefined;
     index?: boolean | undefined;
+    storage?: {
+        path?: string | undefined;
+        backend?: "yaml" | "sqlite" | undefined;
+    } | undefined;
     stores?: {
         path: string;
         scope: string;
         shared?: boolean | undefined;
         readonly?: boolean | undefined;
     }[] | undefined;
+    profile?: {
+        enabled?: boolean | undefined;
+        cache_ttl_hours?: number | undefined;
+    } | undefined;
+    registry_url?: string | undefined;
 }>;
 type PlurConfig = z.infer<typeof PlurConfigSchema>;
 
+declare const PackManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    creator: z.ZodOptional<z.ZodString>;
+    license: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        injection_policy: z.ZodDefault<z.ZodEnum<["on_match", "on_request", "always"]>>;
+        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        domain: z.ZodOptional<z.ZodString>;
+        engram_count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        injection_policy: "on_match" | "on_request" | "always";
+        match_terms: string[];
+        id?: string | undefined;
+        domain?: string | undefined;
+        engram_count?: number | undefined;
+    }, {
+        id?: string | undefined;
+        domain?: string | undefined;
+        injection_policy?: "on_match" | "on_request" | "always" | undefined;
+        match_terms?: string[] | undefined;
+        engram_count?: number | undefined;
+    }>>;
+    'x-datacore': z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        injection_policy: z.ZodEnum<["on_match", "on_request"]>;
+        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        domain: z.ZodOptional<z.ZodString>;
+        engram_count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        match_terms: string[];
+        engram_count: number;
+        domain?: string | undefined;
+    }, {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        engram_count: number;
+        domain?: string | undefined;
+        match_terms?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    tags: string[];
+    license: string;
+    name: string;
+    description?: string | undefined;
+    creator?: string | undefined;
+    metadata?: {
+        injection_policy: "on_match" | "on_request" | "always";
+        match_terms: string[];
+        id?: string | undefined;
+        domain?: string | undefined;
+        engram_count?: number | undefined;
+    } | undefined;
+    'x-datacore'?: {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        match_terms: string[];
+        engram_count: number;
+        domain?: string | undefined;
+    } | undefined;
+}, {
+    version: string;
+    name: string;
+    tags?: string[] | undefined;
+    license?: string | undefined;
+    description?: string | undefined;
+    creator?: string | undefined;
+    metadata?: {
+        id?: string | undefined;
+        domain?: string | undefined;
+        injection_policy?: "on_match" | "on_request" | "always" | undefined;
+        match_terms?: string[] | undefined;
+        engram_count?: number | undefined;
+    } | undefined;
+    'x-datacore'?: {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        engram_count: number;
+        domain?: string | undefined;
+        match_terms?: string[] | undefined;
+    } | undefined;
+}>;
+type PackManifest = z.infer<typeof PackManifestSchema>;
+
 interface LearnContext {
     type?: 'behavioral' | 'terminological' | 'procedural' | 'architectural';
     scope?: string;
@@ -786,12 +858,53 @@ interface LearnContext {
     };
     abstract?: string | null;
     derived_from?: string | null;
+    /** Commitment level. Defaults to 'leaning' for new engrams. */
+    commitment?: 'exploring' | 'leaning' | 'decided' | 'locked';
+    /** Reason for locking (required when commitment='locked'). */
+    locked_reason?: string;
+    /** Explicit memory_class override (SP2 Idea 3). Auto-set from type if not provided. */
+    memory_class?: 'semantic' | 'episodic' | 'procedural' | 'metacognitive';
+    /** Current session episode ID for episodic anchoring (SP2 Idea 24). */
+    session_episode_id?: string;
+}
+/** Extended context for async learn with LLM dedup. */
+interface LearnAsyncContext extends LearnContext {
+    llm?: LlmFunction;
+    budget?: RecallBudget;
+    caller_session_id?: string;
+}
+type DedupDecision = 'ADD' | 'UPDATE' | 'MERGE' | 'NOOP';
+interface DedupConfig {
+    enabled?: boolean;
+    threshold?: number;
+    mode?: 'llm' | 'cosine' | 'off';
+}
+interface LearnAsyncResult {
+    engram: Engram;
+    decision: DedupDecision;
+    existing_id?: string;
+    tensions?: string[];
+}
+interface LearnBatchResult {
+    results: LearnAsyncResult[];
+    stats: {
+        added: number;
+        updated: number;
+        merged: number;
+        noops: number;
+    };
 }
 /**
  * Function that calls an LLM. Model-agnostic — consumer provides this.
  * Takes a prompt, returns the LLM's text response.
  */
 type LlmFunction = (prompt: string) => Promise<string>;
+/** Budget constraints for bounded sub-agent expansion (Idea 16). */
+interface RecallBudget {
+    max_tokens?: number;
+    max_results?: number;
+    ttl_seconds?: number;
+}
 interface RecallOptions {
     scope?: string;
     domain?: string;
@@ -801,6 +914,13 @@ interface RecallOptions {
     mode?: 'fast' | 'agentic';
     /** LLM function for agentic mode. Required when mode='agentic'. */
     llm?: LlmFunction;
+    budget?: RecallBudget;
+    caller_session_id?: string;
+}
+interface BoundedRecallResult {
+    results: Engram[];
+    truncated: boolean;
+    strategy_used?: string;
 }
 interface InjectOptions {
     budget?: number;
@@ -829,6 +949,110 @@ interface TimelineQuery {
     search?: string;
 }
 
+type SearchStrategy = 'bm25' | 'hybrid' | 'expanded' | 'agentic';
+interface AutoSearchResult {
+    results: Engram[];
+    strategy_used: SearchStrategy;
+}
+declare function recallAuto(engrams: Engram[], query: string, limit: number, storagePath?: string, llm?: LlmFunction): Promise<AutoSearchResult>;
+
+interface RegistryEntry {
+    name: string;
+    installed_at: string;
+    source: string;
+    integrity: string;
+    version?: string;
+    creator?: string;
+}
+interface PreviewResult {
+    manifest: PackManifest;
+    engram_count: number;
+    engrams: Array<{
+        id: string;
+        type: string;
+        statement: string;
+        domain?: string;
+        tags: string[];
+    }>;
+    security: PrivacyScanResult;
+    warnings: string[];
+}
+declare function previewPack(source: string): PreviewResult;
+interface InstallResult {
+    installed: number;
+    name: string;
+    conflicts: ConflictItem[];
+    security: PrivacyScanResult;
+    registry: RegistryEntry;
+}
+interface ConflictItem {
+    pack_engram_id: string;
+    pack_statement: string;
+    existing_engram_id: string;
+    existing_statement: string;
+    type: 'contradiction' | 'duplicate';
+}
+declare function installPack(packsDir: string, source: string, existingEngrams?: Engram[]): InstallResult;
+interface UninstallResult {
+    name: string;
+    removed: boolean;
+    engram_count: number;
+}
+declare function uninstallPack(packsDir: string, name: string): UninstallResult;
+interface PackInfo {
+    name: string;
+    path: string;
+    engram_count: number;
+    manifest?: PackManifest;
+    integrity?: string;
+    installed_at?: string;
+    source?: string;
+    integrity_ok?: boolean;
+}
+declare function listPacks(packsDir: string): PackInfo[];
+interface ExportOptions {
+    name: string;
+    version: string;
+    description?: string;
+    creator?: string;
+    domain?: string;
+    scope?: string;
+    tags?: string[];
+    type?: string;
+}
+interface PrivacyScanResult {
+    clean: boolean;
+    issues: PrivacyIssue[];
+}
+interface PrivacyIssue {
+    engram_id: string;
+    type: 'secret' | 'private_visibility' | 'personal_path' | 'email' | 'ip_address';
+    detail: string;
+}
+interface ExportResult {
+    path: string;
+    engram_count: number;
+    privacy: PrivacyScanResult;
+    match_terms: string[];
+    integrity: string;
+}
+declare function exportPack(engrams: Engram[], outputDir: string, manifest: ExportOptions): ExportResult;
+
+interface SyncStatus {
+    initialized: boolean;
+    remote: string | null;
+    dirty: boolean;
+    branch: string | null;
+    ahead: number;
+    behind: number;
+}
+interface SyncResult {
+    action: 'initialized' | 'committed' | 'synced' | 'up-to-date';
+    message: string;
+    remote: string | null;
+    files_changed: number;
+}
+
 interface TypedRole {
     role: string;
     domain_instance: string;
@@ -1286,6 +1510,143 @@ declare function generateGuardrails(): string;
 /** Build searchable text from all engram fields */
 declare function engramSearchText(engram: Engram): string;
 
+/**
+ * Fresh tail boost (Idea 13)
+ *
+ * Engrams created in last 7 days get a retrieval_strength boost.
+ * Day 0: +0.2, Day 7: +0.0 (linear decay)
+ *
+ * ONLY applies to commitment='exploring' or 'leaning' (F14).
+ * Decided/locked engrams don't need the boost (already high priority).
+ *
+ * Applied at scoring time, NOT stored on the engram.
+ */
+declare function freshTailBoost(createdAt: string, commitment?: string, now?: Date): number;
+
+declare function needsSummary(statement: string, cognitiveLevel?: string): boolean;
+declare function generateSummary(statement: string): string;
+declare function autoSummary(statement: string, cognitiveLevel?: string): string | undefined;
+
+type ModelTier = 'fast' | 'balanced' | 'thorough';
+interface LlmTierConfig {
+    dedup_tier?: ModelTier;
+    profile_tier?: ModelTier;
+    meta_tier?: ModelTier;
+}
+declare function selectModel(tier: ModelTier, customMap?: Partial<Record<ModelTier, string>>): string;
+declare function resolveOperationTier(operation: 'dedup' | 'profile' | 'meta', config?: LlmTierConfig): ModelTier;
+declare function selectModelForOperation(operation: 'dedup' | 'profile' | 'meta', config?: LlmTierConfig, customMap?: Partial<Record<ModelTier, string>>): string;
+
+interface ProfileCache {
+    profile: string;
+    generated_at: string;
+    engram_count: number;
+    dirty: boolean;
+}
+declare function loadProfileCache(storagePath: string): ProfileCache | null;
+declare function saveProfileCache(storagePath: string, cache: ProfileCache): void;
+declare function markProfileDirty(storagePath: string): void;
+declare function profileNeedsRegeneration(cache: ProfileCache | null, cacheTtlHours?: number): boolean;
+declare function generateProfile(engrams: Engram[], llm: LlmFunction, storagePath: string, cacheTtlHours?: number): Promise<string | null>;
+declare function getProfileForInjection(storagePath: string): string | null;
+
+type ScoredEngram = Engram & {
+    keyword_match: number;
+    raw_score: number;
+    score: number;
+};
+type AgentEngram = Omit<ScoredEngram, 'associations'>;
+type WireEngram = Omit<AgentEngram, 'keyword_match' | 'raw_score' | 'score'> & {
+    confidence_score: number;
+};
+/** Injection layer for progressive disclosure (Idea 10) */
+type InjectionLayer = 1 | 2 | 3;
+declare function formatLayer1(engram: WireEngram): string;
+declare function formatLayer2(engram: WireEngram): string;
+declare function formatLayer3(engram: WireEngram): string;
+declare function assignLayer(bucket: 'directives' | 'constraints' | 'consider'): InjectionLayer;
+declare function formatWithLayer(engrams: WireEngram[], layer: InjectionLayer): string;
+
+/**
+ * Normalize a statement for hash comparison:
+ * - lowercase
+ * - collapse whitespace
+ * - strip punctuation
+ */
+declare function normalizeStatement(statement: string): string;
+/**
+ * Compute SHA256 content hash of a normalized statement.
+ * Used for fast exact-duplicate detection (Idea 29).
+ */
+declare function computeContentHash(statement: string): string;
+
+/**
+ * Build the LLM prompt for deduplication decision (Ideas 1 + 2 + 19).
+ * Asks the LLM to compare new statement against existing candidates and decide:
+ * ADD, UPDATE, MERGE, or NOOP — plus richness comparison and tension detection.
+ */
+declare function buildDedupPrompt(newStatement: string, candidates: Array<{
+    id: string;
+    statement: string;
+    type: string;
+    domain?: string;
+}>): string;
+/**
+ * Build a batch dedup prompt for multiple candidates at once (learnBatch).
+ */
+declare function buildBatchDedupPrompt(statements: string[], existingEngrams: Array<{
+    id: string;
+    statement: string;
+    type: string;
+    domain?: string;
+}>): string;
+/**
+ * Parse the LLM response from a dedup prompt.
+ */
+declare function parseDedupResponse(response: string): {
+    decision: DedupDecision;
+    target_id: string | null;
+    conflicts: string[];
+    reason: string;
+};
+
+interface Migration {
+    id: string;
+    description: string;
+    up(engrams: Engram[]): Engram[];
+    down(engrams: Engram[]): Engram[];
+}
+
+/** All registered migrations, ordered by ID. */
+declare const ALL_MIGRATIONS: Migration[];
+/** Current schema version after all migrations have run. */
+declare const CURRENT_SCHEMA_VERSION: number;
+interface MigrationResult {
+    applied: string[];
+    schema_version: number;
+    backup_path: string | null;
+}
+/** Read schema_version from config.yaml. Defaults to 0 if not present. */
+declare function getSchemaVersion(configPath: string): number;
+/** Write schema_version to config.yaml, preserving other fields. */
+declare function setSchemaVersion(configPath: string, version: number): void;
+/**
+ * Run pending migrations on engrams.yaml.
+ * - Checks schema_version in config
+ * - Creates backup before running
+ * - Applies each pending migration in order
+ * - Rolls back to backup if any migration fails
+ * - Updates schema_version after success
+ */
+declare function runMigrations(engramsPath: string, configPath: string, options?: {
+    dryRun?: boolean;
+}): MigrationResult;
+/**
+ * Roll back migrations to a target version.
+ * Applies down() for each migration in reverse from current to target.
+ */
+declare function rollbackMigrations(engramsPath: string, configPath: string, targetVersion: number): MigrationResult;
+
 interface SecretMatch {
     pattern: string;
     match: string;
@@ -1332,6 +1693,98 @@ declare class IndexedStorage {
     close(): void;
 }
 
+/**
+ * Abstract storage interface for engram persistence.
+ * Search/retrieval stays in fts.ts, embeddings.ts, hybrid-search.ts.
+ * The store is about persistence only.
+ */
+
+interface EngramStore {
+    /** Load all engrams from the store. */
+    load(): Promise<Engram[]>;
+    /** Replace all engrams in the store (full save). */
+    save(engrams: Engram[]): Promise<void>;
+    /** Append a single engram. For YAML, this does load+append+save. */
+    append(engram: Engram): Promise<void>;
+    /** Get a single engram by ID. Returns null if not found. */
+    getById(id: string): Promise<Engram | null>;
+    /** Remove an engram by ID. Returns true if found and removed. */
+    remove(id: string): Promise<boolean>;
+    /** Count engrams, optionally filtered by status. */
+    count(filter?: {
+        status?: string;
+    }): Promise<number>;
+    /** Close any open resources (e.g., database connections). */
+    close(): Promise<void>;
+}
+/** Backend type identifier. */
+type StorageBackend = 'yaml' | 'sqlite';
+
+declare class YamlStore implements EngramStore {
+    private filePath;
+    constructor(filePath: string);
+    load(): Promise<Engram[]>;
+    save(engrams: Engram[]): Promise<void>;
+    append(engram: Engram): Promise<void>;
+    getById(id: string): Promise<Engram | null>;
+    remove(id: string): Promise<boolean>;
+    count(filter?: {
+        status?: string;
+    }): Promise<number>;
+    close(): Promise<void>;
+    /** Raw load without validation — for internal mutate-and-save operations. */
+    private _loadRaw;
+}
+
+declare class SqliteStore implements EngramStore {
+    private dbPath;
+    private db;
+    constructor(dbPath: string);
+    private getDb;
+    load(): Promise<Engram[]>;
+    save(engrams: Engram[]): Promise<void>;
+    append(engram: Engram): Promise<void>;
+    getById(id: string): Promise<Engram | null>;
+    remove(id: string): Promise<boolean>;
+    count(filter?: {
+        status?: string;
+    }): Promise<number>;
+    close(): Promise<void>;
+    /** Import engrams from an array (e.g., from YAML migration). */
+    importFrom(engrams: Engram[]): Promise<void>;
+    /** Export all engrams as an array (e.g., for YAML migration). */
+    exportAll(): Promise<Engram[]>;
+}
+
+interface StorageConfig {
+    backend: StorageBackend;
+    path: string;
+}
+/**
+ * Create an EngramStore based on the storage configuration.
+ * Default: YamlStore at {path}/engrams.yaml
+ */
+declare function createStore(config: StorageConfig): EngramStore;
+/**
+ * Migrate data from one backend to another.
+ * Loads all engrams from source, saves to target.
+ */
+declare function migrateStore(from: EngramStore, to: EngramStore): Promise<number>;
+
+interface AsyncLockOptions {
+    maxRetries?: number;
+    baseDelay?: number;
+    staleThreshold?: number;
+}
+/**
+ * Async file-based exclusive lock using O_EXCL.
+ * Retries with exponential backoff (async sleep, not busy-wait).
+ */
+declare function withAsyncLock<T>(filePath: string, fn: () => Promise<T>, options?: AsyncLockOptions): Promise<T>;
+
+/** Atomic write: write to temp file then rename (prevents corruption on crash). */
+declare function asyncAtomicWrite(filePath: string, content: string): Promise<void>;
+
 /**
  * Non-blocking version check against npm registry.
  * Caches result in memory — one fetch per process lifetime.
@@ -1373,12 +1826,19 @@ interface StatusResult {
     pack_count: number;
     storage_root: string;
     config: PlurConfig;
+    locked_count?: number;
+    tension_count?: number;
+    versioned_engram_count?: number;
 }
+/** Commitment level scoring multipliers for injection priority (Idea 6). */
+declare const COMMITMENT_MULTIPLIER: Record<string, number>;
 declare class Plur {
     private paths;
     private config;
     private indexedStorage;
     private _engramCache;
+    private _llmFailureCount;
+    private _llmDisabledUntil;
     constructor(options?: {
         path?: string;
     });
@@ -1392,8 +1852,24 @@ declare class Plur {
     private _loadCached;
     /** Find which store owns an engram by ID. For namespaced IDs, strips prefix to find in store. */
     private _findEngramStore;
-    /** Create engram, detect conflicts, save. Returns the created engram. */
+    /** Content hash fast-path dedup. */
+    private _hashDedup;
+    private _isLlmDedupAvailable;
+    private _recordLlmFailure;
+    private _recordLlmSuccess;
+    /** Create engram with content hash + commitment + cognitive level.
+     * Fast-path hash dedup returns existing on exact match.
+     */
     learn(statement: string, context?: LearnContext): Engram;
+    /** Build deps for learn-async module. */
+    private _learnAsyncDeps;
+    /** Async learn with LLM-driven deduplication (Ideas 1+2+19). */
+    learnAsync(statement: string, context?: LearnAsyncContext): Promise<LearnAsyncResult>;
+    /** Batch learn with LLM dedup. */
+    learnBatch(statements: Array<{
+        statement: string;
+        context?: LearnAsyncContext;
+    }>, llm?: LlmFunction): Promise<LearnBatchResult>;
     /**
      * Search engrams, filter by scope/domain/strength, reactivate accessed.
      * Supports two modes:
@@ -1414,6 +1890,7 @@ declare class Plur {
     recallExpanded(query: string, options: RecallOptions & {
         llm: LlmFunction;
     }): Promise<Engram[]>;
+    recallAutoSearch(query: string, options?: RecallOptions): Promise<AutoSearchResult>;
     /** Get a single engram by ID, regardless of status. Searches primary + all stores. */
     getById(id: string): Engram | null;
     /** List all active engrams, optionally filtered by scope/domain. No search — returns all matches. */
@@ -1474,10 +1951,33 @@ declare class Plur {
     }): ReturnType<typeof exportPack>;
     /** List all installed packs (with integrity hashes). */
     listPacks(): ReturnType<typeof listPacks>;
+    /** Get the PLUR storage root path. */
+    getStorageRoot(): string;
     /** Sync engrams to git. Initializes repo on first call, commits + push/pull on subsequent calls. */
     sync(remote?: string): SyncResult;
     /** Get git sync status without making changes. */
     syncStatus(): SyncStatus;
+    /**
+     * Promote an episode to an episodic engram (SP2 Idea 3).
+     * Creates a new engram with memory_class='episodic' from an episode's summary.
+     */
+    episodeToEngram(episodeId: string, context?: Omit<LearnContext, 'memory_class'>): Engram;
+    /**
+     * Get history events for a specific engram (SP2 Idea 7).
+     * Returns all events across all months for the given engram ID.
+     */
+    getEngramHistory(engramId: string): HistoryEvent[];
+    /**
+     * Report a failure for a procedural engram (SP2 Idea 18).
+     * If LLM is provided, generates an improved procedure and updates the engram.
+     * Without LLM, logs the failure without rewriting.
+     * Returns the updated engram and the failure episode.
+     */
+    reportFailure(engramId: string, failureContext: string, llm?: LlmFunction): Promise<{
+        engram: Engram;
+        episode: Episode;
+        evolved: boolean;
+    }>;
     /** Return system health info. */
     status(): StatusResult;
     /** Register an additional engram store. */
@@ -1495,4 +1995,4 @@ declare class Plur {
     }>;
 }
 
-export { type AlignmentResult, type Association, type CaptureContext, type DomainCoverage, DomainCoverageSchema, type Engram, type EngramCluster, type Episode, type EvidenceEntry, EvidenceEntrySchema, type ExtractOptions, type ExtractionResult, type Falsification, FalsificationSchema, type HierarchyPosition, HierarchyPositionSchema, IndexedStorage, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type MemberAlignment, type MetaConfidence, MetaConfidenceSchema, type MetaField, MetaFieldSchema, PLATITUDE_PATTERNS, type PackManifest, Plur, type PlurConfig, type PlurPaths, type PreviewResult, type PrivacyIssue, type PrivacyScanResult, type RecallOptions, type RegistryEntry, type RelationalAnalysis, type RelationalTriple, SessionBreadcrumbs, type StatusResult, type StoreEntry, type StructuralTemplate, StructuralTemplateSchema, type SyncResult, type SyncStatus, type TimelineQuery, type TypedRole, type ValidationResult, type VersionCheckResult, alignCluster, analyzeStructure, checkForUpdate, classifyPolarity, clearVersionCache, clusterByStructure, computeConfidence, computeMetaConfidence, confidenceBand, detectPlurStorage, detectSecrets, engramSearchText, extractMetaEngrams, formulateMetaEngram, generateGuardrails, getCachedUpdateCheck, isPlatitude, organizeHierarchy, tokenSimilarity, validateMetaEngram };
+export { ALL_MIGRATIONS, type AlignmentResult, type Association, type AutoSearchResult, type BoundedRecallResult, COMMITMENT_MULTIPLIER, CURRENT_SCHEMA_VERSION, type CaptureContext, type DedupConfig, type DedupDecision, type DomainCoverage, DomainCoverageSchema, type Engram, type EngramCluster, type EngramStore, type Episode, type EvidenceEntry, EvidenceEntrySchema, type ExtractOptions, type ExtractionResult, type Falsification, FalsificationSchema, type HierarchyPosition, HierarchyPositionSchema, type HistoryEvent, IndexedStorage, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionLayer, type InjectionResult, type KnowledgeAnchor, type LearnAsyncContext, type LearnAsyncResult, type LearnBatchResult, type LearnContext, type LlmFunction, type LlmTierConfig, type MemberAlignment, type MetaConfidence, MetaConfidenceSchema, type MetaField, MetaFieldSchema, type Migration, type MigrationResult, type ModelTier, PLATITUDE_PATTERNS, type PackManifest, Plur, type PlurConfig, type PlurPaths, type PreviewResult, type PreviousVersionRef, type PrivacyIssue, type PrivacyScanResult, type ProfileCache, type RecallBudget, type RecallOptions, type RegistryEntry, type RelationalAnalysis, type RelationalTriple, type SearchStrategy, SessionBreadcrumbs, SqliteStore, type StatusResult, type StorageBackend, type StorageConfig, type StoreEntry, type StructuralTemplate, StructuralTemplateSchema, type SyncResult, type SyncStatus, type TimelineQuery, type TypedRole, type ValidationResult, type VersionCheckResult, YamlStore, alignCluster, analyzeStructure, appendHistory, assignLayer, asyncAtomicWrite, autoSummary, buildBatchDedupPrompt, buildDedupPrompt, checkForUpdate, classifyPolarity, clearVersionCache, clusterByStructure, computeConfidence, computeContentHash, computeMetaConfidence, confidenceBand, createStore, detectPlurStorage, detectSecrets, engramSearchText, extractMetaEngrams, formatLayer1, formatLayer2, formatLayer3, formatWithLayer, formulateMetaEngram, freshTailBoost, generateEventId, generateGuardrails, generateProfile, generateSummary, getCachedUpdateCheck, getProfileForInjection, getSchemaVersion, isPlatitude, listHistoryMonths, loadProfileCache, markProfileDirty, migrateStore, needsSummary, normalizeStatement, organizeHierarchy, parseDedupResponse, profileNeedsRegeneration, readHistory, readHistoryForEngram, recallAuto, resolveOperationTier, rollbackMigrations, runMigrations, saveProfileCache, selectModel, selectModelForOperation, setSchemaVersion, tokenSimilarity, validateMetaEngram, withAsyncLock };