@plur-ai/core 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @plur-ai/core
 
-The engram engine — store, recall, and inject AI memory.
+The engram engine — store, recall, and inject AI memory. Local-first, zero API calls for search, plain YAML storage.
 
 ```bash
 npm install @plur-ai/core
@@ -10,9 +10,28 @@ npm install @plur-ai/core
 import { Plur } from '@plur-ai/core'
 
 const plur = new Plur()
-plur.learn('API uses snake_case', { scope: 'project:myapp', type: 'architectural' })
-const injection = plur.inject('fix the endpoint handler', { budget: 2000 })
-console.log(injection.directives) // injected context, ready to prepend
+
+// Learn from a correction
+plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
+  type: 'behavioral',
+  scope: 'project:my-app',
+  domain: 'dev/testing'
+})
+
+// Recall (hybrid: BM25 + embeddings via RRF, zero cost)
+const results = await plur.recallHybrid('vitest assertion matching')
+
+// Inject relevant engrams into agent context
+const { directives, consider, count, tokens_used } = plur.inject('Write tests for the user service', {
+  scope: 'project:my-app',
+  budget: 2000
+})
+
+// Feedback trains the system
+plur.feedback(results[0].id, 'positive')
+
+// Sync across machines
+plur.sync('git@github.com:you/plur-memory.git')
 ```
 
 ## API
@@ -23,11 +42,11 @@ console.log(injection.directives) // injected context, ready to prepend
 const plur = new Plur({ path: '/custom/storage/path' })
 ```
 
-Defaults to `~/Plur/`. Override with `PLUR_PATH` env var or `options.path`.
+Defaults to `~/.plur/`. Override with `PLUR_PATH` env var or `options.path`.
 
 ### `learn(statement, context?)`
 
-Create an engram. Returns the created `Engram`.
+Create an engram. Detects conflicts with existing engrams in the same scope.
 
 ```typescript
 plur.learn('Always run lint before committing', {
@@ -38,14 +57,24 @@ plur.learn('Always run lint before committing', {
 })
 ```
 
-### `recall(query, options?)`
+### Search methods
 
-Search engrams by keyword/phrase. Returns `Engram[]`, reactivates accessed engrams.
+Five search modes, from fastest to most accurate:
+
+| Method | Speed | API calls | Best for |
+|--------|-------|-----------|----------|
+| `recall(query)` | Instant | None | Quick keyword lookup |
+| `recallSemantic(query)` | ~200ms | None | Meaning-based search (local embeddings) |
+| `recallHybrid(query)` | ~200ms | None | **Best default** — BM25 + embeddings via RRF |
+| `recallAsync(query, { llm })` | ~1s | 1 LLM call | LLM-assisted semantic filtering |
+| `recallExpanded(query, { llm })` | ~3s | 3-5 LLM calls | Query expansion + hybrid + RRF merge |
+
+All accept the same options:
 
 ```typescript
-const results = plur.recall('deployment process', {
+const results = await plur.recallHybrid('deployment process', {
   scope: 'project:myapp',  // includes global + matching scopes
-  domain: 'software',
+  domain: 'software',       // prefix match
   limit: 10,
   min_strength: 0.5,
 })
@@ -53,7 +82,7 @@ const results = plur.recall('deployment process', {
 
 ### `inject(task, options?)`
 
-Select and score engrams within a token budget. Returns directives and considerations as formatted strings, ready to inject into a system prompt.
+Select and score engrams within a token budget. Returns formatted strings ready to prepend to a system prompt.
 
 ```typescript
 const { directives, consider, count, tokens_used } = plur.inject('refactor the auth module', {
@@ -64,50 +93,56 @@ const { directives, consider, count, tokens_used } = plur.inject('refactor the a
 
 ### `feedback(id, signal)`
 
-Rate an engram's usefulness. Adjusts retrieval strength over time.
+Rate an engram's usefulness. Trains injection relevance over time.
 
 ```typescript
 plur.feedback('ENG-001', 'positive')   // +0.05 retrieval strength
 plur.feedback('ENG-002', 'negative')   // -0.10 retrieval strength
-plur.feedback('ENG-003', 'neutral')    // signal recorded, no strength change
 ```
 
 ### `forget(id, reason?)`
 
-Retire an engram. Sets status to `retired` — history is preserved, engram is excluded from recall and injection.
+Retire an engram. History preserved, excluded from recall and injection.
 
 ```typescript
 plur.forget('ENG-001', 'API changed')
 ```
 
-### `capture(summary, context?)`
+### `sync(remote?)`
 
-Append an episode to the episodic timeline.
+Git-based sync across machines. Initializes on first call, commits + push/pull on subsequent calls.
 
 ```typescript
-plur.capture('Deployed v2.0 to production', {
-  agent: 'claude-code',
-  session_id: 'abc123',
-  channel: 'cli',
-  tags: ['deploy', 'production'],
-})
+// First time — init repo and push
+plur.sync('git@github.com:you/plur-memory.git')
+
+// Later — commit, pull, push
+plur.sync()
+```
+
+```typescript
+// Check sync status (no changes made)
+const status = plur.syncStatus()
+// { initialized, remote, dirty, branch, ahead, behind }
 ```
 
-### `timeline(query?)`
+### `capture(summary, context?)` / `timeline(query?)`
 
-Query the episodic timeline. Returns `Episode[]`.
+Episodic memory — record what happened, query the timeline.
 
 ```typescript
-const episodes = plur.timeline({
-  since: new Date('2025-01-01'),
+plur.capture('Deployed v2.0 to production', {
   agent: 'claude-code',
-  search: 'deploy',
+  session_id: 'abc123',
+  tags: ['deploy'],
 })
+
+const episodes = plur.timeline({ since: new Date('2025-01-01'), agent: 'claude-code' })
 ```
 
 ### `ingest(content, options?)`
 
-Extract engram candidates from text using pattern matching. Looks for phrases like "we decided", "always", "the convention is", etc.
+Extract engram candidates from text using pattern matching.
 
 ```typescript
 const candidates = plur.ingest(markdownContent, {
@@ -115,7 +150,6 @@ const candidates = plur.ingest(markdownContent, {
   scope: 'project:myapp',
   source: 'docs/architecture.md',
 })
-// set extract_only: false (default) to auto-save candidates as engrams
 ```
 
 ### `installPack(source)` / `exportPack(...)` / `listPacks()`
@@ -130,10 +164,21 @@ plur.exportPack(engrams, './output', { name: 'my-pack', version: '1.0.0' })
 
 ### `status()`
 
-Return system health.
-
 ```typescript
-const { engram_count, episode_count, pack_count, storage_root } = plur.status()
+const { engram_count, episode_count, pack_count, storage_root, config } = plur.status()
+```
+
+## Storage
+
+Everything is plain YAML. Open it, read it, edit it.
+
+```
+~/.plur/
+├── engrams.yaml     # learned knowledge
+├── episodes.yaml    # session timeline
+├── candidates.yaml  # pending engrams
+├── config.yaml      # settings
+└── packs/           # installed engram packs
 ```
 
 ## License

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?: {
@@ -402,6 +546,21 @@ interface PackInfo {
 }
 declare function listPacks(packsDir: string): PackInfo[];
 
+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;
+}
+
 declare const EpisodeSchema: z.ZodObject<{
     id: z.ZodString;
     summary: z.ZodString;
@@ -522,6 +681,33 @@ interface TimelineQuery {
     search?: string;
 }
 
+/** Build searchable text from all engram fields */
+declare function engramSearchText(engram: Engram): string;
+
+/**
+ * Non-blocking version check against npm registry.
+ * Caches result in memory — one fetch per process lifetime.
+ * Never throws or blocks startup.
+ */
+interface VersionCheckResult {
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    checkedAt: number | null;
+}
+/**
+ * Check npm for a newer version. Fetches once, caches forever (process lifetime).
+ * Fire-and-forget: call at startup, read later via getCachedUpdateCheck().
+ */
+declare function checkForUpdate(packageName: string, currentVersion: string, onResult?: (result: VersionCheckResult) => void): Promise<VersionCheckResult>;
+/**
+ * Read the cached version check result. Returns null if checkForUpdate() hasn't
+ * completed yet. This is the zero-cost read path for assemblers.
+ */
+declare function getCachedUpdateCheck(packageName: string): VersionCheckResult | null;
+/** Clear cache (for testing). */
+declare function clearVersionCache(): void;
+
 interface IngestOptions {
     source?: string;
     extract_only?: boolean;
@@ -560,6 +746,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) */
@@ -593,8 +787,12 @@ declare class Plur {
     };
     /** List all installed packs. */
     listPacks(): ReturnType<typeof listPacks>;
+    /** 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;
     /** Return system health info. */
     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 SyncResult, type SyncStatus, type TimelineQuery, type VersionCheckResult, checkForUpdate, clearVersionCache, engramSearchText, getCachedUpdateCheck };

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, cache2) {
+  const dir = cachePath.substring(0, cachePath.lastIndexOf("/"));
+  if (!existsSync5(dir)) mkdirSync2(dir, { recursive: true });
+  writeFileSync3(cachePath, JSON.stringify(cache2));
+}
+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 cache2 = 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 (cache2[engram.id]?.hash === hash) {
+      engramEmbedding = new Float32Array(cache2[engram.id].embedding);
+    } else {
+      engramEmbedding = await embed(searchText);
+      cache2[engram.id] = {
+        hash,
+        embedding: Array.from(engramEmbedding)
+      };
+    }
+    const score = cosineSimilarity(queryEmbedding, engramEmbedding);
+    similarities.push({ engram, score });
+  }
+  saveCache(cachePath, cache2);
+  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";
@@ -718,6 +996,203 @@ ${manifest.description || ""}
   return { path: outputDir, engram_count: engrams.length };
 }
 
+// src/sync.ts
+import { execSync } from "child_process";
+import { existsSync as existsSync7, writeFileSync as writeFileSync5 } from "fs";
+import { join as join4 } from "path";
+var GITIGNORE = `# PLUR \u2014 derived/cache files (regenerated automatically)
+embeddings/
+*.db
+*.sqlite
+exchange/
+`;
+function git(args, cwd) {
+  return execSync(`git ${args}`, { cwd, encoding: "utf8", timeout: 3e4 }).trim();
+}
+function gitSafe(args, cwd) {
+  try {
+    return git(args, cwd);
+  } catch {
+    return null;
+  }
+}
+function isGitRepo(root) {
+  return existsSync7(join4(root, ".git"));
+}
+function hasGitCli() {
+  try {
+    execSync("git --version", { encoding: "utf8", timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getRemote(root) {
+  return gitSafe("remote get-url origin", root);
+}
+function isDirty(root) {
+  const status = gitSafe("status --porcelain", root);
+  return status !== null && status.length > 0;
+}
+function countDiff(root, direction) {
+  const tracking = gitSafe("rev-parse --abbrev-ref @{u}", root);
+  if (!tracking) return 0;
+  const flag = direction === "ahead" ? "left" : "right";
+  const count = gitSafe(`rev-list --${flag}-only --count HEAD...@{u}`, root);
+  return count ? parseInt(count, 10) : 0;
+}
+function getSyncStatus(root) {
+  if (!isGitRepo(root)) {
+    return { initialized: false, remote: null, dirty: false, branch: null, ahead: 0, behind: 0 };
+  }
+  const branch = gitSafe("rev-parse --abbrev-ref HEAD", root);
+  const remote = getRemote(root);
+  if (remote) gitSafe("fetch origin --quiet", root);
+  return {
+    initialized: true,
+    remote,
+    dirty: isDirty(root),
+    branch,
+    ahead: countDiff(root, "ahead"),
+    behind: countDiff(root, "behind")
+  };
+}
+function initRepo(root) {
+  git("init", root);
+  writeFileSync5(join4(root, ".gitignore"), GITIGNORE);
+  git("add -A", root);
+  git('commit -m "Initial PLUR engram store"', root);
+}
+function commitChanges(root) {
+  if (!isDirty(root)) return 0;
+  git("add -A", root);
+  const diff = gitSafe("diff --cached --stat --shortstat", root);
+  const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
+  git(`commit -m "plur sync ${now}"`, root);
+  const match = diff?.match(/(\d+) file/);
+  return match ? parseInt(match[1], 10) : 1;
+}
+function pullRebase(root) {
+  const result = gitSafe("pull --rebase origin main", root);
+  if (result !== null) return true;
+  gitSafe("rebase --abort", root);
+  const mergeResult = gitSafe("pull origin main --no-edit", root);
+  if (mergeResult !== null) return true;
+  git("add -A", root);
+  gitSafe('commit -m "plur sync: merge conflict resolved (kept both)"', root);
+  return true;
+}
+function sync(root, remote) {
+  if (!hasGitCli()) {
+    throw new Error("git is not installed. Install git to enable sync.");
+  }
+  if (!isGitRepo(root)) {
+    initRepo(root);
+    if (remote) {
+      git(`remote add origin ${remote}`, root);
+      const branch = git("rev-parse --abbrev-ref HEAD", root);
+      git(`push -u origin ${branch}`, root);
+      return { action: "initialized", message: `Initialized and pushed to ${remote}`, remote, files_changed: 0 };
+    }
+    return {
+      action: "initialized",
+      message: "Initialized local git repo. Call plur.sync with remote to enable cross-device sync.",
+      remote: null,
+      files_changed: 0
+    };
+  }
+  const existingRemote = getRemote(root);
+  if (remote && !existingRemote) {
+    git(`remote add origin ${remote}`, root);
+    const filesChanged2 = commitChanges(root);
+    const branch = git("rev-parse --abbrev-ref HEAD", root);
+    git(`push -u origin ${branch}`, root);
+    return { action: "synced", message: `Remote added and pushed to ${remote}`, remote, files_changed: filesChanged2 };
+  }
+  if (!existingRemote) {
+    const filesChanged2 = commitChanges(root);
+    if (filesChanged2 === 0) {
+      return { action: "up-to-date", message: 'No changes to commit. Add a remote with plur.sync({ remote: "..." }) to enable cross-device sync.', remote: null, files_changed: 0 };
+    }
+    return { action: "committed", message: `Committed ${filesChanged2} file(s) locally.`, remote: null, files_changed: filesChanged2 };
+  }
+  const filesChanged = commitChanges(root);
+  gitSafe("fetch origin --quiet", root);
+  const behind = countDiff(root, "behind");
+  const aheadBefore = countDiff(root, "ahead");
+  if (behind > 0) {
+    pullRebase(root);
+  }
+  const aheadAfter = countDiff(root, "ahead");
+  if (aheadAfter > 0) {
+    gitSafe("push origin", root);
+  }
+  if (filesChanged === 0 && behind === 0 && aheadBefore === 0) {
+    return { action: "up-to-date", message: "Already in sync.", remote: existingRemote, files_changed: 0 };
+  }
+  const parts = [];
+  if (filesChanged > 0) parts.push(`${filesChanged} file(s) committed`);
+  if (behind > 0) parts.push(`pulled ${behind} remote commit(s)`);
+  if (aheadAfter === 0 && aheadBefore > 0) parts.push("pushed");
+  return {
+    action: "synced",
+    message: `Synced. ${parts.join(", ")}.`,
+    remote: existingRemote,
+    files_changed: filesChanged
+  };
+}
+
+// src/version-check.ts
+var cache = /* @__PURE__ */ new Map();
+async function checkForUpdate(packageName, currentVersion, onResult) {
+  const cached = cache.get(packageName);
+  if (cached) {
+    if (onResult) onResult(cached);
+    return cached;
+  }
+  const result = { current: currentVersion, latest: null, updateAvailable: false, checkedAt: null };
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!res.ok) {
+      cache.set(packageName, result);
+      return result;
+    }
+    const data = await res.json();
+    if (!data.version) {
+      cache.set(packageName, result);
+      return result;
+    }
+    result.latest = data.version;
+    result.updateAvailable = isNewer(data.version, currentVersion);
+    result.checkedAt = Date.now();
+  } catch {
+  }
+  cache.set(packageName, result);
+  if (onResult) onResult(result);
+  return result;
+}
+function getCachedUpdateCheck(packageName) {
+  return cache.get(packageName) ?? null;
+}
+function clearVersionCache() {
+  cache.clear();
+}
+function isNewer(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+  }
+  return false;
+}
+
 // src/index.ts
 var INGEST_PATTERNS = [
   { re: /(?:we decided|the decision is|agreed to)\s+(.+?)\.?$/gim, type: "architectural" },
@@ -798,6 +1273,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);
@@ -943,6 +1442,14 @@ var Plur = class {
   listPacks() {
     return listPacks(this.paths.packs);
   }
+  /** Sync engrams to git. Initializes repo on first call, commits + push/pull on subsequent calls. */
+  sync(remote) {
+    return sync(this.paths.root, remote);
+  }
+  /** Get git sync status without making changes. */
+  syncStatus() {
+    return getSyncStatus(this.paths.root);
+  }
   /** Return system health info. */
   status() {
     const engrams = loadEngrams(this.paths.engrams);
@@ -958,5 +1465,9 @@ var Plur = class {
   }
 };
 export {
-  Plur
+  Plur,
+  checkForUpdate,
+  clearVersionCache,
+  engramSearchText,
+  getCachedUpdateCheck
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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"
   },