@plur-ai/core 0.2.0 → 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

@@ -546,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;
@@ -669,6 +684,30 @@ interface TimelineQuery {
 /** 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;
@@ -748,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, engramSearchText };
+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

@@ -759,10 +759,10 @@ function loadCache(cachePath) {
     return {};
   }
 }
-function saveCache(cachePath, cache) {
+function saveCache(cachePath, cache2) {
   const dir = cachePath.substring(0, cachePath.lastIndexOf("/"));
   if (!existsSync5(dir)) mkdirSync2(dir, { recursive: true });
-  writeFileSync3(cachePath, JSON.stringify(cache));
+  writeFileSync3(cachePath, JSON.stringify(cache2));
 }
 function hashStatement(statement) {
   let hash = 0;
@@ -774,18 +774,18 @@ function hashStatement(statement) {
 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 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 (cache[engram.id]?.hash === hash) {
-      engramEmbedding = new Float32Array(cache[engram.id].embedding);
+    if (cache2[engram.id]?.hash === hash) {
+      engramEmbedding = new Float32Array(cache2[engram.id].embedding);
     } else {
       engramEmbedding = await embed(searchText);
-      cache[engram.id] = {
+      cache2[engram.id] = {
         hash,
         embedding: Array.from(engramEmbedding)
       };
@@ -793,7 +793,7 @@ async function embeddingSearch(engrams, query, limit, storagePath) {
     const score = cosineSimilarity(queryEmbedding, engramEmbedding);
     similarities.push({ engram, score });
   }
-  saveCache(cachePath, cache);
+  saveCache(cachePath, cache2);
   similarities.sort((a, b) => b.score - a.score);
   return similarities.slice(0, limit).map((s) => s.engram);
 }
@@ -996,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" },
@@ -1245,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);
@@ -1261,5 +1466,8 @@ var Plur = class {
 };
 export {
   Plur,
-  engramSearchText
+  checkForUpdate,
+  clearVersionCache,
+  engramSearchText,
+  getCachedUpdateCheck
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",