@plur-ai/core 0.2.0 → 0.2.2

package/README.md

@@ -1,141 +1,131 @@
 # @plur-ai/core
 
-The engram engine — store, recall, and inject AI memory.
+The engine behind [PLUR](https://plur.ai) — persistent memory for AI agents.
 
-```bash
-npm install @plur-ai/core
-```
+You correct your agent on Monday. On Tuesday, it makes the same mistake. PLUR fixes this. Corrections, preferences, and conventions persist across sessions. Your data stays on your disk as plain YAML. Search runs locally with zero API calls.
 
-```typescript
-import { Plur } from '@plur-ai/core'
+The result: **Haiku with PLUR memory outperforms Opus without it** — 2.6x better on tool routing, at 10x less cost. The bottleneck isn't model intelligence. It's context.
 
-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
-```
+## Why @plur-ai/core
 
-## API
+This is the engine that powers everything. Use it directly when you're building your own agent framework or want programmatic control over memory. If you just want to add memory to Claude Code or Cursor, use [`@plur-ai/mcp`](https://www.npmjs.com/package/@plur-ai/mcp) instead — it wraps this package as MCP tools.
 
-### `new Plur(options?)`
+## Install
 
-```typescript
-const plur = new Plur({ path: '/custom/storage/path' })
+```bash
+npm install @plur-ai/core
 ```
 
-Defaults to `~/Plur/`. Override with `PLUR_PATH` env var or `options.path`.
-
-### `learn(statement, context?)`
-
-Create an engram. Returns the created `Engram`.
+## Quick start
 
 ```typescript
-plur.learn('Always run lint before committing', {
-  type: 'behavioral',       // behavioral | architectural | procedural | terminological
-  scope: 'project:myapp',   // namespace for filtering
-  domain: 'software.git',   // dot-separated domain tag
-  source: 'user-correction',
-})
-```
-
-### `recall(query, options?)`
+import { Plur } from '@plur-ai/core'
 
-Search engrams by keyword/phrase. Returns `Engram[]`, reactivates accessed engrams.
+const plur = new Plur()
 
-```typescript
-const results = plur.recall('deployment process', {
-  scope: 'project:myapp',  // includes global + matching scopes
-  domain: 'software',
-  limit: 10,
-  min_strength: 0.5,
+// Your agent gets corrected — save it
+plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
+  type: 'behavioral',
+  scope: 'project:my-app',
+  domain: 'dev/testing'
 })
-```
 
-### `inject(task, options?)`
+// Next session: recall what was learned (hybrid search, zero cost)
+const results = await plur.recallHybrid('vitest assertion matching')
 
-Select and score engrams within a token budget. Returns directives and considerations as formatted strings, ready to inject into a system prompt.
-
-```typescript
-const { directives, consider, count, tokens_used } = plur.inject('refactor the auth module', {
-  budget: 2000,
-  scope: 'project:myapp',
+// Or inject the best engrams into a system prompt, within a token budget
+const { directives, consider, tokens_used } = plur.inject('Write tests for the user service', {
+  scope: 'project:my-app',
+  budget: 2000
 })
-```
-
-### `feedback(id, signal)`
 
-Rate an engram's usefulness. Adjusts retrieval strength over time.
+// Rate what was useful — the system improves over time
+plur.feedback(results[0].id, 'positive')
 
-```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
+// Sync across machines via git
+plur.sync('git@github.com:you/plur-memory.git')
 ```
 
-### `forget(id, reason?)`
+## How it works
 
-Retire an engram. Sets status to `retired` — history is preserved, engram is excluded from recall and injection.
+Knowledge is stored as **engrams** — small assertions that strengthen with use and decay when irrelevant, modeled on how human memory works (ACT-R activation). The system gets better over time, not just bigger.
 
-```typescript
-plur.forget('ENG-001', 'API changed')
 ```
-
-### `capture(summary, context?)`
-
-Append an episode to the episodic timeline.
-
-```typescript
-plur.capture('Deployed v2.0 to production', {
-  agent: 'claude-code',
-  session_id: 'abc123',
-  channel: 'cli',
-  tags: ['deploy', 'production'],
-})
+You correct your agent  →  engram created       →  YAML on your disk
+Next session starts     →  relevant ones injected →  agent remembers
+You rate the result     →  engram strengthens    →  quality improves
 ```
 
-### `timeline(query?)`
+Search is fully local: BM25 over enriched text + BGE-small-en-v1.5 embeddings + Reciprocal Rank Fusion. **86.7% on LongMemEval** — on par with cloud solutions that charge per query.
+
+## Search modes
+
+Five 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 for exhaustive retrieval |
+
+## Full API
+
+| Method | What it does |
+|--------|-------------|
+| `learn(statement, context?)` | Store an engram (correction, preference, convention, decision) |
+| `recall(query, options?)` | BM25 keyword search — instant, zero cost |
+| `recallHybrid(query, options?)` | BM25 + embeddings merged via RRF — best default |
+| `recallSemantic(query, options?)` | Embedding-only search — meaning over keywords |
+| `recallAsync(query, { llm })` | LLM-assisted semantic filtering |
+| `recallExpanded(query, { llm })` | Query expansion + hybrid + RRF merge |
+| `inject(task, options?)` | Select engrams for a task within a token budget |
+| `feedback(id, signal)` | Rate an engram — trains injection relevance over time |
+| `forget(id, reason?)` | Retire an engram (history preserved) |
+| `sync(remote?)` | Git-based sync across machines |
+| `syncStatus()` | Check sync state without making changes |
+| `capture(summary, context?)` | Record a session event to the episodic timeline |
+| `timeline(query?)` | Query past episodes by time, agent, or search |
+| `ingest(content, options?)` | Extract engram candidates from text via pattern matching |
+| `installPack(source)` | Install a shareable engram pack |
+| `exportPack(engrams, dir, manifest)` | Export engrams as a shareable pack |
+| `listPacks()` | List installed packs |
+| `status()` | System health — counts, storage root, config |
+
+## Storage
+
+Everything is plain YAML. Open it, read it, edit it, version it.
 
-Query the episodic timeline. Returns `Episode[]`.
-
-```typescript
-const episodes = plur.timeline({
-  since: new Date('2025-01-01'),
-  agent: 'claude-code',
-  search: 'deploy',
-})
 ```
-
-### `ingest(content, options?)`
-
-Extract engram candidates from text using pattern matching. Looks for phrases like "we decided", "always", "the convention is", etc.
-
-```typescript
-const candidates = plur.ingest(markdownContent, {
-  extract_only: true,  // preview without saving
-  scope: 'project:myapp',
-  source: 'docs/architecture.md',
-})
-// set extract_only: false (default) to auto-save candidates as engrams
+~/.plur/
+├── engrams.yaml     # learned knowledge
+├── episodes.yaml    # session timeline
+├── candidates.yaml  # pending engrams
+├── config.yaml      # settings
+└── packs/           # installed engram packs
 ```
 
-### `installPack(source)` / `exportPack(...)` / `listPacks()`
+Override the location with `PLUR_PATH` env var or `new Plur({ path: '...' })`.
 
-Share engram collections between agents or users.
+## Benchmark
 
-```typescript
-plur.installPack('/path/to/pack-directory')
-const packs = plur.listPacks()
-plur.exportPack(engrams, './output', { name: 'my-pack', version: '1.0.0' })
-```
+| Metric | Score |
+|--------|-------|
+| LongMemEval overall | **86.7%** |
+| Hit@10 (retrieval) | 93.3% |
+| A/B win rate vs no memory | 89% |
+| House rules accuracy | 100% |
 
-### `status()`
+[Full methodology →](https://plur.ai/benchmark.html)
 
-Return system health.
+## Related packages
 
-```typescript
-const { engram_count, episode_count, pack_count, storage_root } = plur.status()
-```
+| Package | For |
+|---------|-----|
+| [`@plur-ai/mcp`](https://www.npmjs.com/package/@plur-ai/mcp) | Claude Code, Cursor, Windsurf (MCP server) |
+| [`@plur-ai/claw`](https://www.npmjs.com/package/@plur-ai/claw) | OpenClaw (automatic memory plugin) |
 
 ## License
 
-Apache-2.0
+Apache-2.0 · [GitHub](https://github.com/plur-ai/plur) · [plur.ai](https://plur.ai)

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.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",