@plur-ai/core 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -48,6 +48,9 @@ declare const EngramSchema: z.ZodObject<{
     contraindications: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     source_patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     derivation_count: z.ZodDefault<z.ZodNumber>;
+    pack: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    abstract: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    derived_from: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     knowledge_type: z.ZodOptional<z.ZodObject<{
         memory_class: z.ZodEnum<["semantic", "episodic", "procedural", "metacognitive"]>;
         cognitive_level: z.ZodEnum<["remember", "understand", "apply", "analyze", "evaluate", "create"]>;
@@ -59,6 +62,23 @@ declare const EngramSchema: z.ZodObject<{
         cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
     }>>;
     domain: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    activation: z.ZodDefault<z.ZodObject<{
+        retrieval_strength: z.ZodNumber;
+        storage_strength: z.ZodNumber;
+        frequency: z.ZodNumber;
+        last_accessed: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    }, {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    }>>;
     relations: z.ZodOptional<z.ZodObject<{
         broader: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         narrower: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -75,21 +95,56 @@ declare const EngramSchema: z.ZodObject<{
         related?: string[] | undefined;
         conflicts?: string[] | undefined;
     }>>;
-    activation: z.ZodDefault<z.ZodObject<{
-        retrieval_strength: z.ZodNumber;
-        storage_strength: z.ZodNumber;
-        frequency: z.ZodNumber;
-        last_accessed: z.ZodString;
+    associations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        target_type: z.ZodEnum<["engram", "document"]>;
+        target: z.ZodString;
+        strength: z.ZodNumber;
+        type: z.ZodEnum<["semantic", "temporal", "causal", "co_accessed"]>;
+        updated_at: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        retrieval_strength: number;
-        storage_strength: number;
-        frequency: number;
-        last_accessed: string;
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
     }, {
-        retrieval_strength: number;
-        storage_strength: number;
-        frequency: number;
-        last_accessed: string;
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }>, "many">>;
+    knowledge_anchors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        relevance: z.ZodDefault<z.ZodEnum<["primary", "supporting", "example"]>>;
+        snippet: z.ZodOptional<z.ZodString>;
+        snippet_extracted_at: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        relevance: "primary" | "supporting" | "example";
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }, {
+        path: string;
+        relevance?: "primary" | "supporting" | "example" | undefined;
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }>, "many">>;
+    dual_coding: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        example: z.ZodOptional<z.ZodString>;
+        analogy: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }>, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }, {
+        example?: string | undefined;
+        analogy?: string | undefined;
     }>>;
     provenance: z.ZodOptional<z.ZodObject<{
         origin: z.ZodString;
@@ -120,61 +175,90 @@ declare const EngramSchema: z.ZodObject<{
         negative?: number | undefined;
         neutral?: number | undefined;
     }>>;
-    knowledge_anchors: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        relevance: z.ZodDefault<z.ZodEnum<["primary", "supporting", "example"]>>;
-        snippet: z.ZodOptional<z.ZodString>;
-        snippet_extracted_at: z.ZodOptional<z.ZodString>;
+    /** Typed entity references extracted from statement. Enables graph queries. */
+    entities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["person", "organization", "technology", "concept", "project", "tool", "place", "event", "standard", "other"]>;
+        uri: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        path: string;
-        relevance: "primary" | "supporting" | "example";
-        snippet?: string | undefined;
-        snippet_extracted_at?: string | undefined;
+        type: "person" | "organization" | "technology" | "concept" | "project" | "tool" | "place" | "event" | "standard" | "other";
+        name: string;
+        uri?: string | undefined;
     }, {
-        path: string;
-        relevance?: "primary" | "supporting" | "example" | undefined;
-        snippet?: string | undefined;
-        snippet_extracted_at?: string | undefined;
+        type: "person" | "organization" | "technology" | "concept" | "project" | "tool" | "place" | "event" | "standard" | "other";
+        name: string;
+        uri?: string | undefined;
     }>, "many">>;
-    associations: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        target_type: z.ZodEnum<["engram", "document"]>;
-        target: z.ZodString;
-        strength: z.ZodNumber;
-        type: z.ZodEnum<["semantic", "temporal", "causal", "co_accessed"]>;
-        updated_at: z.ZodOptional<z.ZodString>;
+    /** Temporal validity window. When is this knowledge true? */
+    temporal: z.ZodOptional<z.ZodObject<{
+        learned_at: z.ZodString;
+        valid_from: z.ZodOptional<z.ZodString>;
+        valid_until: z.ZodOptional<z.ZodString>;
+        ingested_at: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        type: "semantic" | "temporal" | "causal" | "co_accessed";
-        target_type: "engram" | "document";
-        target: string;
-        strength: number;
-        updated_at?: string | undefined;
+        learned_at: string;
+        valid_from?: string | undefined;
+        valid_until?: string | undefined;
+        ingested_at?: string | undefined;
     }, {
-        type: "semantic" | "temporal" | "causal" | "co_accessed";
-        target_type: "engram" | "document";
-        target: string;
-        strength: number;
-        updated_at?: string | undefined;
-    }>, "many">>;
-    dual_coding: z.ZodOptional<z.ZodEffects<z.ZodObject<{
-        example: z.ZodOptional<z.ZodString>;
-        analogy: z.ZodOptional<z.ZodString>;
+        learned_at: string;
+        valid_from?: string | undefined;
+        valid_until?: string | undefined;
+        ingested_at?: string | undefined;
+    }>>;
+    /** Automatic usage tracking. Injections, hits, misses. */
+    usage: z.ZodOptional<z.ZodObject<{
+        injections: z.ZodDefault<z.ZodNumber>;
+        hits: z.ZodDefault<z.ZodNumber>;
+        misses: z.ZodDefault<z.ZodNumber>;
+        last_hit_at: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        example?: string | undefined;
-        analogy?: string | undefined;
+        injections: number;
+        hits: number;
+        misses: number;
+        last_hit_at?: string | undefined;
     }, {
-        example?: string | undefined;
-        analogy?: string | undefined;
-    }>, {
-        example?: string | undefined;
-        analogy?: string | undefined;
+        injections?: number | undefined;
+        hits?: number | undefined;
+        misses?: number | undefined;
+        last_hit_at?: string | undefined;
+    }>>;
+    /** Episodic context: emotional weight, confidence, trigger. */
+    episodic: z.ZodOptional<z.ZodObject<{
+        emotional_weight: z.ZodDefault<z.ZodNumber>;
+        confidence: z.ZodDefault<z.ZodNumber>;
+        trigger_context: z.ZodOptional<z.ZodString>;
+        journal_ref: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        emotional_weight: number;
+        confidence: number;
+        trigger_context?: string | undefined;
+        journal_ref?: string | undefined;
     }, {
-        example?: string | undefined;
-        analogy?: string | undefined;
+        emotional_weight?: number | undefined;
+        confidence?: number | undefined;
+        trigger_context?: string | undefined;
+        journal_ref?: string | undefined;
     }>>;
-    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    pack: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    abstract: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    derived_from: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Exchange marketplace metadata: fitness, adoption, diversity. */
+    exchange: z.ZodOptional<z.ZodObject<{
+        fitness_score: z.ZodOptional<z.ZodNumber>;
+        environmental_diversity: z.ZodDefault<z.ZodNumber>;
+        adoption_count: z.ZodDefault<z.ZodNumber>;
+        contradiction_rate: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        environmental_diversity: number;
+        adoption_count: number;
+        contradiction_rate: number;
+        fitness_score?: number | undefined;
+    }, {
+        fitness_score?: number | undefined;
+        environmental_diversity?: number | undefined;
+        adoption_count?: number | undefined;
+        contradiction_rate?: number | undefined;
+    }>>;
+    /** Extensible key-value data for domain-specific fields. */
+    structured_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -185,23 +269,16 @@ declare const EngramSchema: z.ZodObject<{
     visibility: "private" | "public" | "template";
     statement: string;
     derivation_count: number;
+    pack: string | null;
+    abstract: string | null;
+    derived_from: string | null;
+    tags: string[];
     activation: {
         retrieval_strength: number;
         storage_strength: number;
         frequency: number;
         last_accessed: string;
     };
-    feedback_signals: {
-        positive: number;
-        negative: number;
-        neutral: number;
-    };
-    knowledge_anchors: {
-        path: string;
-        relevance: "primary" | "supporting" | "example";
-        snippet?: string | undefined;
-        snippet_extracted_at?: string | undefined;
-    }[];
     associations: {
         type: "semantic" | "temporal" | "causal" | "co_accessed";
         target_type: "engram" | "document";
@@ -209,13 +286,26 @@ declare const EngramSchema: z.ZodObject<{
         strength: number;
         updated_at?: string | undefined;
     }[];
-    tags: string[];
-    pack: string | null;
-    abstract: string | null;
-    derived_from: string | null;
+    knowledge_anchors: {
+        path: string;
+        relevance: "primary" | "supporting" | "example";
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }[];
+    feedback_signals: {
+        positive: number;
+        negative: number;
+        neutral: number;
+    };
     rationale?: string | undefined;
     contraindications?: string[] | undefined;
     source_patterns?: string[] | undefined;
+    episodic?: {
+        emotional_weight: number;
+        confidence: number;
+        trigger_context?: string | undefined;
+        journal_ref?: string | undefined;
+    } | undefined;
     knowledge_type?: {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
         cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
@@ -227,16 +317,40 @@ declare const EngramSchema: z.ZodObject<{
         related: string[];
         conflicts: string[];
     } | undefined;
+    temporal?: {
+        learned_at: string;
+        valid_from?: string | undefined;
+        valid_until?: string | undefined;
+        ingested_at?: string | undefined;
+    } | undefined;
+    dual_coding?: {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    } | undefined;
     provenance?: {
         origin: string;
         chain: string[];
         signature: string | null;
         license: string;
     } | undefined;
-    dual_coding?: {
-        example?: string | undefined;
-        analogy?: string | undefined;
+    entities?: {
+        type: "person" | "organization" | "technology" | "concept" | "project" | "tool" | "place" | "event" | "standard" | "other";
+        name: string;
+        uri?: string | undefined;
+    }[] | undefined;
+    usage?: {
+        injections: number;
+        hits: number;
+        misses: number;
+        last_hit_at?: string | undefined;
     } | undefined;
+    exchange?: {
+        environmental_diversity: number;
+        adoption_count: number;
+        contradiction_rate: number;
+        fitness_score?: number | undefined;
+    } | undefined;
+    structured_data?: Record<string, unknown> | undefined;
 }, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -250,22 +364,55 @@ declare const EngramSchema: z.ZodObject<{
     contraindications?: string[] | undefined;
     source_patterns?: string[] | undefined;
     derivation_count?: number | undefined;
+    pack?: string | null | undefined;
+    abstract?: string | null | undefined;
+    derived_from?: string | null | undefined;
+    episodic?: {
+        emotional_weight?: number | undefined;
+        confidence?: number | undefined;
+        trigger_context?: string | undefined;
+        journal_ref?: string | undefined;
+    } | undefined;
     knowledge_type?: {
         memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
         cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
     } | undefined;
     domain?: string | undefined;
+    tags?: string[] | undefined;
+    activation?: {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    } | undefined;
     relations?: {
         broader?: string[] | undefined;
         narrower?: string[] | undefined;
         related?: string[] | undefined;
         conflicts?: string[] | undefined;
     } | undefined;
-    activation?: {
-        retrieval_strength: number;
-        storage_strength: number;
-        frequency: number;
-        last_accessed: string;
+    temporal?: {
+        learned_at: string;
+        valid_from?: string | undefined;
+        valid_until?: string | undefined;
+        ingested_at?: string | undefined;
+    } | undefined;
+    associations?: {
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }[] | undefined;
+    knowledge_anchors?: {
+        path: string;
+        relevance?: "primary" | "supporting" | "example" | undefined;
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }[] | undefined;
+    dual_coding?: {
+        example?: string | undefined;
+        analogy?: string | undefined;
     } | undefined;
     provenance?: {
         origin: string;
@@ -278,27 +425,24 @@ declare const EngramSchema: z.ZodObject<{
         negative?: number | undefined;
         neutral?: number | undefined;
     } | undefined;
-    knowledge_anchors?: {
-        path: string;
-        relevance?: "primary" | "supporting" | "example" | undefined;
-        snippet?: string | undefined;
-        snippet_extracted_at?: string | undefined;
-    }[] | undefined;
-    associations?: {
-        type: "semantic" | "temporal" | "causal" | "co_accessed";
-        target_type: "engram" | "document";
-        target: string;
-        strength: number;
-        updated_at?: string | undefined;
+    entities?: {
+        type: "person" | "organization" | "technology" | "concept" | "project" | "tool" | "place" | "event" | "standard" | "other";
+        name: string;
+        uri?: string | undefined;
     }[] | undefined;
-    dual_coding?: {
-        example?: string | undefined;
-        analogy?: string | undefined;
+    usage?: {
+        injections?: number | undefined;
+        hits?: number | undefined;
+        misses?: number | undefined;
+        last_hit_at?: string | undefined;
     } | undefined;
-    tags?: string[] | undefined;
-    pack?: string | null | undefined;
-    abstract?: string | null | undefined;
-    derived_from?: string | null | undefined;
+    exchange?: {
+        fitness_score?: number | undefined;
+        environmental_diversity?: number | undefined;
+        adoption_count?: number | undefined;
+        contradiction_rate?: number | undefined;
+    } | undefined;
+    structured_data?: Record<string, unknown> | undefined;
 }>;
 type Engram = z.infer<typeof EngramSchema>;
 type KnowledgeAnchor = z.infer<typeof KnowledgeAnchorSchema>;
@@ -351,8 +495,8 @@ declare const PackManifestSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     version: string;
-    license: string;
     tags: string[];
+    license: string;
     name: string;
     description?: string | undefined;
     creator?: string | undefined;
@@ -373,8 +517,8 @@ declare const PackManifestSchema: z.ZodObject<{
 }, {
     version: string;
     name: string;
-    license?: string | undefined;
     tags?: string[] | undefined;
+    license?: string | undefined;
     description?: string | undefined;
     creator?: string | undefined;
     metadata?: {
@@ -522,6 +666,9 @@ interface TimelineQuery {
     search?: string;
 }
 
+/** Build searchable text from all engram fields */
+declare function engramSearchText(engram: Engram): string;
+
 interface IngestOptions {
     source?: string;
     extract_only?: boolean;
@@ -560,6 +707,14 @@ declare class Plur {
     recallAsync(query: string, options: RecallOptions & {
         llm: LlmFunction;
     }): Promise<Engram[]>;
+    /** Search engrams using local embeddings (transformers.js). Async, no API calls. */
+    recallSemantic(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Promise<Engram[]>;
+    /** Hybrid search: BM25 + embeddings merged via Reciprocal Rank Fusion. Async, no API calls. */
+    recallHybrid(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Promise<Engram[]>;
+    /** Expanded search: LLM query expansion + hybrid search + RRF merge. Opt-in, requires LLM function. */
+    recallExpanded(query: string, options: RecallOptions & {
+        llm: LlmFunction;
+    }): Promise<Engram[]>;
     /** Filter engrams by scope/domain/strength (shared by both modes) */
     private _filterEngrams;
     /** Reactivate accessed engrams (bump retrieval strength, frequency, last_accessed) */
@@ -597,4 +752,4 @@ declare class Plur {
     status(): StatusResult;
 }
 
-export { type Association, type CaptureContext, type Engram, type Episode, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type PackManifest, Plur, type PlurConfig, type RecallOptions, type StatusResult, type TimelineQuery };
+export { type Association, type CaptureContext, type Engram, type Episode, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type PackManifest, Plur, type PlurConfig, type RecallOptions, type StatusResult, type TimelineQuery, engramSearchText };

package/dist/index.js

@@ -102,7 +102,48 @@ var FeedbackSignalsSchema = z2.object({
   negative: z2.number().int().default(0),
   neutral: z2.number().int().default(0)
 });
+var EntityRefSchema = z2.object({
+  name: z2.string(),
+  type: z2.enum([
+    "person",
+    "organization",
+    "technology",
+    "concept",
+    "project",
+    "tool",
+    "place",
+    "event",
+    "standard",
+    "other"
+  ]),
+  uri: z2.string().url().optional()
+});
+var TemporalSchema = z2.object({
+  learned_at: z2.string(),
+  valid_from: z2.string().optional(),
+  valid_until: z2.string().optional(),
+  ingested_at: z2.string().optional()
+});
+var UsageStatsSchema = z2.object({
+  injections: z2.number().int().default(0),
+  hits: z2.number().int().default(0),
+  misses: z2.number().int().default(0),
+  last_hit_at: z2.string().optional()
+});
+var EpisodicFieldsSchema = z2.object({
+  emotional_weight: z2.number().int().min(1).max(10).default(5),
+  confidence: z2.number().int().min(1).max(10).default(5),
+  trigger_context: z2.string().optional(),
+  journal_ref: z2.string().optional()
+});
+var ExchangeMetadataSchema = z2.object({
+  fitness_score: z2.number().min(0).max(1).optional(),
+  environmental_diversity: z2.number().int().default(0),
+  adoption_count: z2.number().int().default(0),
+  contradiction_rate: z2.number().min(0).max(1).default(0)
+});
 var EngramSchema = z2.object({
+  // Identity
   id: z2.string().regex(/^(ENG|ABS)-[A-Za-z0-9-]+$/),
   version: z2.number().int().min(1).default(2),
   status: z2.enum(["active", "dormant", "retired", "candidate"]),
@@ -110,24 +151,49 @@ var EngramSchema = z2.object({
   type: z2.enum(["behavioral", "terminological", "procedural", "architectural"]),
   scope: z2.string(),
   visibility: z2.enum(["private", "public", "template"]).default("private"),
+  // Content
   statement: z2.string().min(1),
   rationale: z2.string().optional(),
   contraindications: z2.array(z2.string()).optional(),
+  // Lineage
   source_patterns: z2.array(z2.string()).optional(),
   derivation_count: z2.number().int().min(0).default(1),
+  pack: z2.string().nullable().default(null),
+  abstract: z2.string().nullable().default(null),
+  derived_from: z2.string().nullable().default(null),
+  // Classification
   knowledge_type: KnowledgeTypeSchema.optional(),
   domain: z2.string().optional(),
+  tags: z2.array(z2.string()).default([]),
+  // Activation (ACT-R model)
+  activation: ActivationSchema.default({
+    retrieval_strength: 0.7,
+    storage_strength: 1,
+    frequency: 0,
+    last_accessed: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  }),
+  // Relations & grounding
   relations: RelationsSchema.optional(),
-  activation: ActivationSchema.default({ retrieval_strength: 0.7, storage_strength: 1, frequency: 0, last_accessed: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) }),
-  provenance: ProvenanceSchema.optional(),
-  feedback_signals: FeedbackSignalsSchema.default({ positive: 0, negative: 0, neutral: 0 }),
-  knowledge_anchors: z2.array(KnowledgeAnchorSchema).default([]),
   associations: z2.array(AssociationSchema).default([]),
+  knowledge_anchors: z2.array(KnowledgeAnchorSchema).default([]),
   dual_coding: DualCodingSchema.optional(),
-  tags: z2.array(z2.string()).default([]),
-  pack: z2.string().nullable().default(null),
-  abstract: z2.string().nullable().default(null),
-  derived_from: z2.string().nullable().default(null)
+  // Provenance
+  provenance: ProvenanceSchema.optional(),
+  // Feedback
+  feedback_signals: FeedbackSignalsSchema.default({ positive: 0, negative: 0, neutral: 0 }),
+  // === NEW OPTIONAL FIELDS (v2.1) ===
+  /** Typed entity references extracted from statement. Enables graph queries. */
+  entities: z2.array(EntityRefSchema).optional(),
+  /** Temporal validity window. When is this knowledge true? */
+  temporal: TemporalSchema.optional(),
+  /** Automatic usage tracking. Injections, hits, misses. */
+  usage: UsageStatsSchema.optional(),
+  /** Episodic context: emotional weight, confidence, trigger. */
+  episodic: EpisodicFieldsSchema.optional(),
+  /** Exchange marketplace metadata: fitness, adoption, diversity. */
+  exchange: ExchangeMetadataSchema.optional(),
+  /** Extensible key-value data for domain-specific fields. */
+  structured_data: z2.record(z2.string(), z2.unknown()).optional()
 });
 
 // src/schemas/pack.ts
@@ -275,11 +341,25 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
 function ftsTokenize(text) {
   return text.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 2).filter((w) => !STOP_WORDS.has(w));
 }
+function engramSearchText(engram) {
+  const parts = [engram.statement];
+  if (engram.domain) parts.push(engram.domain.replace(/\./g, " "));
+  if (engram.tags.length > 0) parts.push(engram.tags.join(" "));
+  if (engram.entities) {
+    for (const e of engram.entities) {
+      parts.push(e.name);
+      if (e.type !== "other") parts.push(e.type);
+    }
+  }
+  if (engram.temporal) {
+    if (engram.temporal.valid_from) parts.push(engram.temporal.valid_from);
+    if (engram.temporal.valid_until) parts.push(engram.temporal.valid_until);
+  }
+  if (engram.rationale) parts.push(engram.rationale);
+  return parts.join(" ");
+}
 function ftsScore(engram, queryTokens) {
-  const statementTokens = ftsTokenize(engram.statement);
-  const domainTokens = engram.domain ? ftsTokenize(engram.domain.replace(/\./g, " ")) : [];
-  const tagTokens = engram.tags.map((t) => t.toLowerCase());
-  const allTerms = [...statementTokens, ...domainTokens, ...tagTokens];
+  const allTerms = ftsTokenize(engramSearchText(engram));
   let matches = 0;
   for (const qt of queryTokens) {
     if (allTerms.some((t) => t.includes(qt) || qt.includes(t))) matches++;
@@ -608,7 +688,14 @@ async function agenticSearch(engrams, query, limit, llm) {
   return agenticRerank(candidates, query, limit, llm);
 }
 async function agenticRerank(candidates, query, limit, llm) {
-  const numbered = candidates.map((e, i) => `${i + 1}. [${e.id}] ${e.statement}`).join("\n");
+  const numbered = candidates.map((e, i) => {
+    const extra = [];
+    if (e.entities?.length) extra.push(`entities: ${e.entities.map((x) => x.name).join(", ")}`);
+    if (e.temporal?.valid_from) extra.push(`valid from: ${e.temporal.valid_from}`);
+    if (e.temporal?.valid_until) extra.push(`valid until: ${e.temporal.valid_until}`);
+    const suffix = extra.length > 0 ? ` (${extra.join("; ")})` : "";
+    return `${i + 1}. [${e.id}] ${e.statement}${suffix}`;
+  }).join("\n");
   const prompt = `You are a memory retrieval system. Given a query and a list of memories, select the ${limit} most relevant memories. Return ONLY the numbers of the relevant memories, comma-separated, in order of relevance (most relevant first).
 
 Query: "${query}"
@@ -641,6 +728,197 @@ Rules:
   }
 }
 
+// src/embeddings.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+var embedPipeline = null;
+async function getEmbedder() {
+  if (!embedPipeline) {
+    const { pipeline } = await import("@huggingface/transformers");
+    embedPipeline = await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5", {
+      dtype: "fp32"
+    });
+  }
+  return embedPipeline;
+}
+async function embed(text) {
+  const embedder = await getEmbedder();
+  const result = await embedder(text, { pooling: "cls", normalize: true });
+  return new Float32Array(result.data);
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}
+function loadCache(cachePath) {
+  if (!existsSync5(cachePath)) return {};
+  try {
+    return JSON.parse(readFileSync4(cachePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveCache(cachePath, cache) {
+  const dir = cachePath.substring(0, cachePath.lastIndexOf("/"));
+  if (!existsSync5(dir)) mkdirSync2(dir, { recursive: true });
+  writeFileSync3(cachePath, JSON.stringify(cache));
+}
+function hashStatement(statement) {
+  let hash = 0;
+  for (let i = 0; i < statement.length; i++) {
+    hash = (hash << 5) - hash + statement.charCodeAt(i) | 0;
+  }
+  return hash.toString(36);
+}
+async function embeddingSearch(engrams, query, limit, storagePath) {
+  if (engrams.length === 0) return [];
+  const cachePath = storagePath ? join2(storagePath, ".embeddings-cache.json") : ".embeddings-cache.json";
+  const cache = loadCache(cachePath);
+  const queryEmbedding = await embed(query);
+  const similarities = [];
+  for (const engram of engrams) {
+    const searchText = engramSearchText(engram);
+    const hash = hashStatement(searchText);
+    let engramEmbedding;
+    if (cache[engram.id]?.hash === hash) {
+      engramEmbedding = new Float32Array(cache[engram.id].embedding);
+    } else {
+      engramEmbedding = await embed(searchText);
+      cache[engram.id] = {
+        hash,
+        embedding: Array.from(engramEmbedding)
+      };
+    }
+    const score = cosineSimilarity(queryEmbedding, engramEmbedding);
+    similarities.push({ engram, score });
+  }
+  saveCache(cachePath, cache);
+  similarities.sort((a, b) => b.score - a.score);
+  return similarities.slice(0, limit).map((s) => s.engram);
+}
+
+// src/hybrid-search.ts
+function rrfMerge(resultSets, k = 60) {
+  const scores = /* @__PURE__ */ new Map();
+  for (const results of resultSets) {
+    for (let rank = 0; rank < results.length; rank++) {
+      const engram = results[rank];
+      const existing = scores.get(engram.id);
+      const rrfScore = 1 / (k + rank + 1);
+      if (existing) {
+        existing.score += rrfScore;
+      } else {
+        scores.set(engram.id, { engram, score: rrfScore });
+      }
+    }
+  }
+  return Array.from(scores.values()).sort((a, b) => b.score - a.score).map((s) => s.engram);
+}
+var AGGREGATION_PATTERNS = [
+  /how many/i,
+  /how much/i,
+  /total (?:number|amount|cost|time|hours|days|spent)/i,
+  /all (?:the|my)/i,
+  /every (?:time|instance)/i,
+  /(?:count|sum|add up|combine|altogether)/i,
+  /in the (?:past|last) (?:week|month|year|few)/i,
+  /did I (?:attend|visit|go to|buy|spend|do)/i
+];
+function isAggregationQuery(query) {
+  return AGGREGATION_PATTERNS.some((p) => p.test(query));
+}
+async function hybridSearch(engrams, query, limit, storagePath) {
+  if (engrams.length === 0) return [];
+  const exhaustive = isAggregationQuery(query);
+  const effectiveLimit = exhaustive ? Math.max(limit, 50) : limit;
+  const bm25Limit = Math.min(engrams.length, exhaustive ? effectiveLimit * 5 : effectiveLimit * 3);
+  const embLimit = Math.min(engrams.length, exhaustive ? effectiveLimit * 3 : effectiveLimit * 2);
+  const [bm25Results, embResults] = await Promise.all([
+    Promise.resolve(searchEngrams(engrams, query, bm25Limit)),
+    embeddingSearch(engrams, query, embLimit, storagePath)
+  ]);
+  const merged = rrfMerge([bm25Results, embResults]);
+  return merged.slice(0, effectiveLimit);
+}
+
+// src/query-expansion.ts
+var EXPANSION_PROMPT = `You are a search query expander. Given a user query, generate 3 alternative search queries that capture the same intent but use different words, synonyms, or related concepts.
+
+Return ONLY the 3 queries, one per line, nothing else. No numbering, no explanations.
+
+Query: "{query}"`;
+var AGGREGATION_EXPANSION_PROMPT = `You are a search query expander for an aggregation query. The user wants to COUNT or TOTAL something across multiple conversations. Generate 5 search queries that will find ALL individual instances \u2014 each query should target a different way the item might have been mentioned.
+
+For example, if the query is "How many weddings did I attend?", generate queries like:
+- wedding ceremony attended
+- went to wedding reception
+- wedding invitation RSVP
+- marriage celebration
+- attended wedding of
+
+Return ONLY the 5 queries, one per line. No numbering, no explanations.
+
+Query: "{query}"`;
+var AGGREGATION_PATTERNS2 = [
+  /how many/i,
+  /how much/i,
+  /total (?:number|amount|cost|time|hours|days|spent)/i,
+  /all (?:the|my)/i,
+  /every (?:time|instance)/i,
+  /(?:count|sum|add up|combine|altogether)/i,
+  /in the (?:past|last) (?:week|month|year|few)/i,
+  /did I (?:attend|visit|go to|buy|spend|do)/i
+];
+function isAggregationQuery2(query) {
+  return AGGREGATION_PATTERNS2.some((p) => p.test(query));
+}
+function parseVariants(response, original) {
+  const variants = response.split("\n").map((line) => line.replace(/^\d+[\.\)]\s*/, "").trim()).filter((line) => line.length > 3 && line.length < 200).slice(0, 3);
+  return [original, ...variants];
+}
+function rrfMerge2(resultSets, k = 60) {
+  const scores = /* @__PURE__ */ new Map();
+  for (const results of resultSets) {
+    for (let rank = 0; rank < results.length; rank++) {
+      const engram = results[rank];
+      const existing = scores.get(engram.id);
+      const rrfScore = 1 / (k + rank + 1);
+      if (existing) {
+        existing.score += rrfScore;
+      } else {
+        scores.set(engram.id, { engram, score: rrfScore });
+      }
+    }
+  }
+  return Array.from(scores.values()).sort((a, b) => b.score - a.score).map((s) => s.engram);
+}
+async function expandedSearch(engrams, query, limit, llm, storagePath) {
+  if (engrams.length === 0) return [];
+  const aggregation = isAggregationQuery2(query);
+  let variants;
+  try {
+    const promptTemplate = aggregation ? AGGREGATION_EXPANSION_PROMPT : EXPANSION_PROMPT;
+    const prompt = promptTemplate.replace("{query}", query);
+    const response = await llm(prompt);
+    variants = parseVariants(response, query);
+    if (aggregation) {
+      const extra = response.split("\n").map((line) => line.replace(/^\d+[\.\)]\s*/, "").trim()).filter((line) => line.length > 3 && line.length < 200).slice(0, 5);
+      variants = [query, ...extra];
+    }
+  } catch {
+    variants = [query];
+  }
+  const perVariantLimit = aggregation ? Math.max(limit, 50) : limit;
+  const searchPromises = variants.map(
+    (v) => hybridSearch(engrams, v, perVariantLimit, storagePath)
+  );
+  const resultSets = await Promise.all(searchPromises);
+  const merged = rrfMerge2(resultSets);
+  const effectiveLimit = aggregation ? Math.max(limit, 50) : limit;
+  return merged.slice(0, effectiveLimit);
+}
+
 // src/packs.ts
 import * as fs2 from "fs";
 import * as path from "path";
@@ -798,6 +1076,30 @@ var Plur = class {
     this._reactivateResults(results);
     return results;
   }
+  /** Search engrams using local embeddings (transformers.js). Async, no API calls. */
+  async recallSemantic(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const results = await embeddingSearch(filtered, query, limit, this.paths.root);
+    this._reactivateResults(results);
+    return results;
+  }
+  /** Hybrid search: BM25 + embeddings merged via Reciprocal Rank Fusion. Async, no API calls. */
+  async recallHybrid(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const results = await hybridSearch(filtered, query, limit, this.paths.root);
+    this._reactivateResults(results);
+    return results;
+  }
+  /** Expanded search: LLM query expansion + hybrid search + RRF merge. Opt-in, requires LLM function. */
+  async recallExpanded(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const results = await expandedSearch(filtered, query, limit, options.llm, this.paths.root);
+    this._reactivateResults(results);
+    return results;
+  }
   /** Filter engrams by scope/domain/strength (shared by both modes) */
   _filterEngrams(options) {
     let engrams = loadEngrams(this.paths.engrams);
@@ -958,5 +1260,6 @@ var Plur = class {
   }
 };
 export {
-  Plur
+  Plur,
+  engramSearchText
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,7 @@
     "dist"
   ],
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "js-yaml": "^4.1.0",
     "zod": "^3.23.0"
   },