@plur-ai/core 0.1.0

package/dist/index.js

@@ -0,0 +1,962 @@
+// src/storage.ts
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function detectPlurStorage(explicitPath) {
+  const root = explicitPath || process.env.PLUR_PATH || join(homedir(), ".plur");
+  if (!existsSync(root)) mkdirSync(root, { recursive: true });
+  const packsDir = join(root, "packs");
+  if (!existsSync(packsDir)) mkdirSync(packsDir, { recursive: true });
+  return {
+    root,
+    engrams: join(root, "engrams.yaml"),
+    episodes: join(root, "episodes.yaml"),
+    candidates: join(root, "candidates.yaml"),
+    packs: packsDir,
+    exchange: join(root, "exchange"),
+    config: join(root, "config.yaml")
+  };
+}
+
+// src/config.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import yaml from "js-yaml";
+
+// src/schemas/config.ts
+import { z } from "zod";
+var PlurConfigSchema = z.object({
+  auto_learn: z.boolean().default(true),
+  auto_capture: z.boolean().default(true),
+  injection_budget: z.number().default(2e3),
+  decay_enabled: z.boolean().default(true),
+  decay_threshold: z.number().default(0.15),
+  packs: z.array(z.string()).default([]),
+  injection: z.object({
+    spread_cap: z.number().default(3),
+    spread_budget: z.number().default(480),
+    co_access: z.boolean().default(true)
+  }).default({})
+}).partial();
+
+// src/config.ts
+function loadConfig(configPath) {
+  if (!existsSync2(configPath)) return PlurConfigSchema.parse({});
+  try {
+    const raw = yaml.load(readFileSync(configPath, "utf8"));
+    return PlurConfigSchema.parse(raw ?? {});
+  } catch {
+    return PlurConfigSchema.parse({});
+  }
+}
+
+// src/engrams.ts
+import * as fs from "fs";
+import * as yaml2 from "js-yaml";
+
+// src/schemas/engram.ts
+import { z as z2 } from "zod";
+var ActivationSchema = z2.object({
+  retrieval_strength: z2.number().min(0).max(1),
+  storage_strength: z2.number().min(0).max(1),
+  frequency: z2.number().int().min(0),
+  last_accessed: z2.string()
+});
+var KnowledgeTypeSchema = z2.object({
+  memory_class: z2.enum(["semantic", "episodic", "procedural", "metacognitive"]),
+  cognitive_level: z2.enum(["remember", "understand", "apply", "analyze", "evaluate", "create"])
+});
+var KnowledgeAnchorSchema = z2.object({
+  path: z2.string(),
+  relevance: z2.enum(["primary", "supporting", "example"]).default("supporting"),
+  snippet: z2.string().max(200).optional(),
+  snippet_extracted_at: z2.string().optional()
+});
+var AssociationSchema = z2.object({
+  target_type: z2.enum(["engram", "document"]),
+  target: z2.string(),
+  strength: z2.number().min(0).max(0.95),
+  type: z2.enum(["semantic", "temporal", "causal", "co_accessed"]),
+  updated_at: z2.string().optional()
+});
+var DualCodingSchema = z2.object({
+  example: z2.string().optional(),
+  analogy: z2.string().optional()
+}).refine(
+  (d) => d.example || d.analogy,
+  "At least one of example or analogy must be provided"
+);
+var RelationsSchema = z2.object({
+  broader: z2.array(z2.string()).default([]),
+  narrower: z2.array(z2.string()).default([]),
+  related: z2.array(z2.string()).default([]),
+  conflicts: z2.array(z2.string()).default([])
+});
+var ProvenanceSchema = z2.object({
+  origin: z2.string(),
+  chain: z2.array(z2.string()).default([]),
+  signature: z2.string().nullable().default(null),
+  license: z2.string().default("cc-by-sa-4.0")
+});
+var FeedbackSignalsSchema = z2.object({
+  positive: z2.number().int().default(0),
+  negative: z2.number().int().default(0),
+  neutral: z2.number().int().default(0)
+});
+var EngramSchema = z2.object({
+  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"]),
+  consolidated: z2.boolean().default(false),
+  type: z2.enum(["behavioral", "terminological", "procedural", "architectural"]),
+  scope: z2.string(),
+  visibility: z2.enum(["private", "public", "template"]).default("private"),
+  statement: z2.string().min(1),
+  rationale: z2.string().optional(),
+  contraindications: z2.array(z2.string()).optional(),
+  source_patterns: z2.array(z2.string()).optional(),
+  derivation_count: z2.number().int().min(0).default(1),
+  knowledge_type: KnowledgeTypeSchema.optional(),
+  domain: z2.string().optional(),
+  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([]),
+  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)
+});
+
+// src/schemas/pack.ts
+import { z as z3 } from "zod";
+var PackManifestSchema = z3.object({
+  name: z3.string(),
+  version: z3.string(),
+  description: z3.string().optional(),
+  creator: z3.string().optional(),
+  license: z3.string().default("cc-by-sa-4.0"),
+  tags: z3.array(z3.string()).default([]),
+  metadata: z3.object({
+    id: z3.string().optional(),
+    injection_policy: z3.enum(["on_match", "on_request", "always"]).default("on_match"),
+    match_terms: z3.array(z3.string()).default([]),
+    domain: z3.string().optional(),
+    engram_count: z3.number().optional()
+  }).optional(),
+  "x-datacore": z3.object({
+    id: z3.string(),
+    injection_policy: z3.enum(["on_match", "on_request"]),
+    match_terms: z3.array(z3.string()).default([]),
+    domain: z3.string().optional(),
+    engram_count: z3.number().int().min(0)
+  }).optional()
+});
+
+// src/logger.ts
+var level = process.env.PLUR_LOG_LEVEL || "warning";
+var levels = { debug: 0, info: 1, warning: 2, error: 3 };
+var threshold = levels[level] ?? 2;
+var logger = {
+  debug: (...args) => {
+    if (threshold <= 0) console.error("[plur:debug]", ...args);
+  },
+  info: (...args) => {
+    if (threshold <= 1) console.error("[plur:info]", ...args);
+  },
+  warning: (...args) => {
+    if (threshold <= 2) console.error("[plur:warning]", ...args);
+  },
+  error: (...args) => {
+    if (threshold <= 3) console.error("[plur:error]", ...args);
+  }
+};
+
+// src/engrams.ts
+function loadEngrams(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  try {
+    const raw = yaml2.load(fs.readFileSync(filePath, "utf8"));
+    if (!raw?.engrams || !Array.isArray(raw.engrams)) return [];
+    const valid = [];
+    let skipped = 0;
+    for (const entry of raw.engrams) {
+      const result = EngramSchema.safeParse(entry);
+      if (result.success) valid.push(result.data);
+      else skipped++;
+    }
+    if (skipped > 0) logger.warning(`Skipped ${skipped} invalid engram(s) in ${filePath}`);
+    return valid;
+  } catch (err) {
+    logger.error(`Failed to parse engrams file ${filePath}: ${err}`);
+    return [];
+  }
+}
+function saveEngrams(filePath, engrams) {
+  const content = yaml2.dump({ engrams }, { lineWidth: 120, noRefs: true, quotingType: '"' });
+  fs.writeFileSync(filePath, content);
+}
+function parseSkillMdFrontmatter(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) throw new Error(`No frontmatter found in ${filePath}`);
+  return yaml2.load(match[1]);
+}
+function loadPack(packDir) {
+  const skillMdPath = `${packDir}/SKILL.md`;
+  const manifestYamlPath = `${packDir}/manifest.yaml`;
+  const engramsPath = `${packDir}/engrams.yaml`;
+  let rawManifest;
+  if (fs.existsSync(skillMdPath)) {
+    rawManifest = parseSkillMdFrontmatter(skillMdPath);
+  } else if (fs.existsSync(manifestYamlPath)) {
+    rawManifest = yaml2.load(fs.readFileSync(manifestYamlPath, "utf8"));
+  } else {
+    throw new Error(`No SKILL.md or manifest.yaml found in ${packDir}`);
+  }
+  const manifest = PackManifestSchema.parse(rawManifest);
+  const engrams = loadEngrams(engramsPath);
+  return { manifest, engrams };
+}
+function loadAllPacks(packsDir) {
+  if (!fs.existsSync(packsDir)) return [];
+  const packs = [];
+  for (const entry of fs.readdirSync(packsDir)) {
+    const packDir = `${packsDir}/${entry}`;
+    if (!fs.statSync(packDir).isDirectory()) continue;
+    if (!fs.existsSync(`${packDir}/SKILL.md`) && !fs.existsSync(`${packDir}/manifest.yaml`)) continue;
+    try {
+      packs.push(loadPack(packDir));
+    } catch (err) {
+      logger.warning(`Failed to load pack ${entry}: ${err}`);
+    }
+  }
+  return packs;
+}
+function generateEngramId(existing) {
+  const now = /* @__PURE__ */ new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const prefix = `ENG-${date.slice(0, 4)}-${date.slice(4)}-`;
+  const existingNums = existing.filter((e) => e.id.startsWith(prefix)).map((e) => parseInt(e.id.slice(prefix.length), 10)).filter((n) => !isNaN(n));
+  const next = existingNums.length > 0 ? Math.max(...existingNums) + 1 : 1;
+  return `${prefix}${String(next).padStart(3, "0")}`;
+}
+
+// src/fts.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "that",
+  "this",
+  "with",
+  "from",
+  "are",
+  "was",
+  "were",
+  "been",
+  "have",
+  "has",
+  "not",
+  "but",
+  "its",
+  "you",
+  "your",
+  "can",
+  "will",
+  "should",
+  "would",
+  "could",
+  "may",
+  "might"
+]);
+function ftsTokenize(text) {
+  return text.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 2).filter((w) => !STOP_WORDS.has(w));
+}
+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];
+  let matches = 0;
+  for (const qt of queryTokens) {
+    if (allTerms.some((t) => t.includes(qt) || qt.includes(t))) matches++;
+  }
+  return queryTokens.length > 0 ? matches / queryTokens.length : 0;
+}
+function searchEngrams(engrams, query, limit = 20) {
+  const queryTokens = ftsTokenize(query);
+  if (queryTokens.length === 0) return [];
+  return engrams.map((e) => ({ engram: e, score: ftsScore(e, queryTokens) })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((r) => r.engram);
+}
+
+// src/decay.ts
+var DECAY_RATE = 0.05;
+var FLOOR = 0.05;
+var MS_PER_DAY = 864e5;
+function decayedStrength(retrievalStrength, daysSinceAccess, lambda = DECAY_RATE) {
+  return FLOOR + (retrievalStrength - FLOOR) * Math.exp(-lambda * daysSinceAccess);
+}
+function daysSince(lastAccessed, now) {
+  const last = new Date(lastAccessed);
+  const current = now || /* @__PURE__ */ new Date();
+  return Math.max(0, Math.floor((current.getTime() - last.getTime()) / MS_PER_DAY));
+}
+function reactivate(currentStrength) {
+  return Math.min(1, currentStrength + 0.1);
+}
+function decayedCoAccessStrength(strength, daysSinceUpdate, lambda = 0.01) {
+  const floor = 0.02;
+  return floor + (strength - floor) * Math.exp(-lambda * daysSinceUpdate);
+}
+
+// src/inject.ts
+var DEFAULT_MAX_TOKENS = 8e3;
+var DEFAULT_MIN_RELEVANCE = 0.3;
+var MAX_PER_PACK = 5;
+var MAX_PER_DOMAIN = 10;
+var DIP19_CONSIDER_MAX = 5;
+var DIP19_CONSIDER_BUDGET = 200;
+function getPackMetadata(manifest) {
+  const meta = manifest["x-datacore"] || manifest.metadata;
+  return {
+    injection_policy: meta?.injection_policy ?? "on_match",
+    match_terms: meta?.match_terms ?? []
+  };
+}
+function estimateTokens(engram) {
+  const { keyword_match: _km, raw_score: _rs, score: _s, associations: _a, ...wire } = engram;
+  const serialized = JSON.stringify(wire);
+  return Math.ceil(serialized.length / 4);
+}
+function tokenize(text) {
+  return new Set(text.toLowerCase().split(/\W+/).filter((w) => w.length > 2));
+}
+function anchorBoost(engram, taskWords) {
+  if (!engram.knowledge_anchors?.length) return 0;
+  const threshold2 = taskWords.size <= 1 ? 1 : 2;
+  let boost = 0;
+  for (const anchor of engram.knowledge_anchors) {
+    if (!anchor.snippet) continue;
+    const snippetWords = tokenize(anchor.snippet);
+    let overlap = 0;
+    for (const word of taskWords) {
+      if (snippetWords.has(word)) overlap++;
+    }
+    if (overlap >= threshold2) boost += 0.5;
+  }
+  return Math.min(boost, 2);
+}
+function flattenRelations(engram) {
+  if (!engram.relations) return [];
+  const associations = [];
+  for (const id of engram.relations.broader) {
+    associations.push({ target_type: "engram", target: id, type: "semantic", strength: 0.5 });
+  }
+  for (const id of engram.relations.narrower) {
+    associations.push({ target_type: "engram", target: id, type: "semantic", strength: 0.5 });
+  }
+  for (const id of engram.relations.related) {
+    associations.push({ target_type: "engram", target: id, type: "semantic", strength: 0.5 });
+  }
+  return associations;
+}
+function stripAssociations(engram) {
+  const { associations: _, ...rest } = engram;
+  return rest;
+}
+function stripScoring(engram) {
+  const { keyword_match: _, raw_score: _r, score: _s, ...rest } = engram;
+  return rest;
+}
+function scoreEngram(engram, promptLower, promptWords, packMatchTerms, scopeFilter, isPack) {
+  if (scopeFilter) {
+    if (scopeFilter === "global") {
+      if (engram.scope !== "global") return 0;
+    } else if (!engram.scope.startsWith(scopeFilter) && engram.scope !== "global") {
+      return 0;
+    }
+  }
+  let termHits = 0;
+  for (const term of packMatchTerms) {
+    if (promptLower.includes(term.toLowerCase())) termHits++;
+  }
+  for (const tag of engram.tags) {
+    if (promptWords.has(tag.toLowerCase())) termHits++;
+  }
+  if (engram.domain) {
+    for (const part of engram.domain.split(/[./]/)) {
+      if (promptWords.has(part.toLowerCase())) termHits++;
+    }
+  }
+  const statementWords = new Set(engram.statement.toLowerCase().split(/\W+/).filter((w) => w.length > 2));
+  for (const word of promptWords) {
+    if (statementWords.has(word)) termHits += 0.5;
+  }
+  if (termHits === 0) return 0;
+  const rs = isPack ? engram.activation.retrieval_strength : decayedStrength(engram.activation.retrieval_strength, daysSince(engram.activation.last_accessed));
+  let score = termHits * rs;
+  const feedback = engram.feedback_signals;
+  if (feedback) {
+    const netFeedback = feedback.positive - feedback.negative;
+    if (netFeedback > 0) score *= 1 + Math.min(netFeedback * 0.05, 0.3);
+    else if (netFeedback < 0) score *= Math.max(1 + netFeedback * 0.1, 0.5);
+  }
+  if (engram.consolidated) score *= 1.1;
+  return score;
+}
+function fillTokenBudget(scored, maxTokens) {
+  const result = [];
+  const packCounts = /* @__PURE__ */ new Map();
+  const domainCounts = /* @__PURE__ */ new Map();
+  let tokensUsed = 0;
+  for (const engram of scored) {
+    const cost = estimateTokens(engram);
+    if (tokensUsed + cost > maxTokens) continue;
+    const pack = engram.pack ?? "__personal__";
+    const packCount = packCounts.get(pack) ?? 0;
+    if (packCount >= MAX_PER_PACK && pack !== "__personal__") continue;
+    const domain = engram.domain ?? "__none__";
+    const topDomain = domain.split(".")[0];
+    const domainCount = domainCounts.get(topDomain) ?? 0;
+    if (domainCount >= MAX_PER_DOMAIN) continue;
+    result.push(engram);
+    tokensUsed += cost;
+    packCounts.set(pack, packCount + 1);
+    domainCounts.set(topDomain, domainCount + 1);
+  }
+  return { selected: result, tokens_used: tokensUsed };
+}
+function selectAndSpread(ctx, personalEngrams, packs, config) {
+  const spreadCap = config?.spread_cap ?? 3;
+  const spreadBudget = config?.spread_budget ?? 480;
+  const promptLower = ctx.prompt.toLowerCase();
+  const promptWords = new Set(promptLower.split(/\W+/).filter((w) => w.length > 2));
+  const maxTokens = ctx.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const minRelevance = ctx.minRelevance ?? DEFAULT_MIN_RELEVANCE;
+  const engramMap = /* @__PURE__ */ new Map();
+  const scored = [];
+  for (const engram of personalEngrams) {
+    if (engram.status !== "active") continue;
+    engramMap.set(engram.id, engram);
+    const raw = scoreEngram(engram, promptLower, promptWords, [], ctx.scope, false);
+    if (raw > 0) {
+      scored.push({ ...engram, keyword_match: raw, raw_score: raw, score: raw });
+    }
+  }
+  for (const pack of packs) {
+    const packMeta = getPackMetadata(pack.manifest);
+    if (packMeta.injection_policy === "on_request") continue;
+    const matchTerms = packMeta.match_terms;
+    for (const engram of pack.engrams) {
+      if (engram.status !== "active") continue;
+      engramMap.set(engram.id, engram);
+      const raw = scoreEngram(engram, promptLower, promptWords, matchTerms, ctx.scope, true);
+      if (raw > 0) {
+        scored.push({ ...engram, keyword_match: raw, raw_score: raw, score: raw });
+      }
+    }
+  }
+  const maxKm = Math.max(...scored.map((e) => e.keyword_match), 1);
+  for (const e of scored) {
+    e.keyword_match = e.keyword_match / maxKm * 10;
+  }
+  const aBoosts = /* @__PURE__ */ new Map();
+  for (const e of scored) {
+    const aBoost = anchorBoost(e, promptWords);
+    aBoosts.set(e.id, aBoost);
+    e.score = e.keyword_match + aBoost;
+  }
+  const filtered = scored.filter((s) => s.score >= minRelevance);
+  filtered.sort((a, b) => b.score - a.score);
+  const { selected: directives, tokens_used: directiveTokens } = fillTokenBudget(filtered, maxTokens);
+  const directiveIds = new Set(directives.map((e) => e.id));
+  const directivePackCounts = /* @__PURE__ */ new Map();
+  for (const e of directives) {
+    const pack = e.pack ?? "__personal__";
+    directivePackCounts.set(pack, (directivePackCounts.get(pack) ?? 0) + 1);
+  }
+  const dip19Remainder = filtered.filter((e) => {
+    if (directiveIds.has(e.id)) return false;
+    const pack = e.pack ?? "__personal__";
+    if (pack !== "__personal__" && (directivePackCounts.get(pack) ?? 0) >= MAX_PER_PACK) return false;
+    return true;
+  });
+  const { selected: dip19Consider } = fillTokenBudget(
+    dip19Remainder,
+    DIP19_CONSIDER_BUDGET
+  );
+  const dip19Pool = dip19Consider.slice(0, DIP19_CONSIDER_MAX);
+  const dip19PoolTokens = dip19Pool.reduce((acc, e) => acc + estimateTokens(e), 0);
+  if (directives.length === 0 && dip19Pool.length === 0) {
+    return {
+      directives: [],
+      consider: [],
+      tokens_used: { directives: 0, consider: 0 }
+    };
+  }
+  const maxFirstPass = Math.max(...directives.map((e) => e.score), 1);
+  const visited = new Set(directives.map((e) => e.id));
+  for (const e of dip19Pool) visited.add(e.id);
+  const spreadCandidates = [];
+  let spreadTokens = 0;
+  for (const directive of directives) {
+    const assocs = directive.associations?.length ? directive.associations : flattenRelations(directive);
+    for (const assoc of assocs) {
+      if (assoc.target_type !== "engram") continue;
+      if (visited.has(assoc.target)) continue;
+      const target = engramMap.get(assoc.target);
+      if (!target || target.status !== "active") continue;
+      const effectiveStrength = assoc.type === "co_accessed" && assoc.updated_at ? decayedCoAccessStrength(assoc.strength, daysSince(assoc.updated_at)) : assoc.strength;
+      if (effectiveStrength <= 0) continue;
+      const spreadScore = directive.score / maxFirstPass * effectiveStrength;
+      if (spreadScore < minRelevance * 0.5) continue;
+      const spreadEngram = {
+        ...target,
+        keyword_match: 0,
+        raw_score: 0,
+        score: spreadScore
+      };
+      const cost = estimateTokens(spreadEngram);
+      if (spreadTokens + cost > spreadBudget) continue;
+      if (spreadCandidates.length >= spreadCap) break;
+      spreadCandidates.push(spreadEngram);
+      spreadTokens += cost;
+      visited.add(assoc.target);
+    }
+  }
+  const allConsider = [...dip19Pool, ...spreadCandidates];
+  const agentDirectives = directives.map(stripAssociations);
+  const agentConsider = allConsider.map(stripAssociations);
+  const wireDirectives = agentDirectives.map(stripScoring);
+  const wireConsider = agentConsider.map(stripScoring);
+  const considerTokens = dip19PoolTokens + spreadTokens;
+  return {
+    directives: wireDirectives,
+    consider: wireConsider,
+    tokens_used: { directives: directiveTokens, consider: considerTokens }
+  };
+}
+
+// src/episodes.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import yaml3 from "js-yaml";
+function generateEpisodeId() {
+  const ts = Date.now();
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `EP-${ts}-${rand}`;
+}
+function captureEpisode(path2, summary, context) {
+  const episodes = loadEpisodes(path2);
+  const episode = {
+    id: generateEpisodeId(),
+    summary,
+    agent: context?.agent,
+    channel: context?.channel,
+    session_id: context?.session_id,
+    tags: context?.tags,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  episodes.push(episode);
+  writeFileSync2(path2, yaml3.dump(episodes, { lineWidth: 120, noRefs: true }), "utf8");
+  return episode;
+}
+function queryTimeline(path2, query) {
+  let episodes = loadEpisodes(path2);
+  if (query?.since) episodes = episodes.filter((e) => new Date(e.timestamp) >= query.since);
+  if (query?.until) episodes = episodes.filter((e) => new Date(e.timestamp) <= query.until);
+  if (query?.agent) episodes = episodes.filter((e) => e.agent === query.agent);
+  if (query?.channel) episodes = episodes.filter((e) => e.channel === query.channel);
+  if (query?.search) {
+    const terms = query.search.toLowerCase().split(/\s+/);
+    episodes = episodes.filter((e) => terms.some((t) => e.summary.toLowerCase().includes(t)));
+  }
+  return episodes;
+}
+function loadEpisodes(path2) {
+  if (!existsSync4(path2)) return [];
+  try {
+    const raw = yaml3.load(readFileSync3(path2, "utf8"));
+    return Array.isArray(raw) ? raw : [];
+  } catch {
+    return [];
+  }
+}
+
+// src/conflict.ts
+function detectConflicts(newEngram, existing, threshold2 = 0.4) {
+  const newScope = newEngram.scope || "global";
+  const newTokens = ftsTokenize(newEngram.statement);
+  if (newTokens.length === 0) return [];
+  return existing.filter((e) => {
+    if (e.status !== "active") return false;
+    if ((e.scope || "global") !== newScope) return false;
+    const score = ftsScore(e, newTokens);
+    return score >= threshold2;
+  });
+}
+
+// src/agentic-search.ts
+async function agenticSearch(engrams, query, limit, llm) {
+  const candidates = searchEngrams(engrams, query, Math.min(30, engrams.length));
+  if (candidates.length === 0) return [];
+  if (candidates.length <= limit) {
+    return agenticRerank(candidates, 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 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}"
+
+Memories:
+${numbered}
+
+Rules:
+- Select at most ${limit} memories
+- Only select memories that are actually relevant to answering the query
+- If fewer than ${limit} memories are relevant, return fewer
+- Return ONLY comma-separated numbers, nothing else (e.g., "3,7,1,12")
+- If no memories are relevant, return "none"`;
+  try {
+    const response = await llm(prompt);
+    const text = response.trim();
+    if (text.toLowerCase() === "none") return [];
+    const indices = text.split(",").map((s) => parseInt(s.trim(), 10) - 1).filter((i) => !isNaN(i) && i >= 0 && i < candidates.length);
+    const seen = /* @__PURE__ */ new Set();
+    const unique = [];
+    for (const i of indices) {
+      if (!seen.has(i)) {
+        seen.add(i);
+        unique.push(i);
+      }
+    }
+    return unique.slice(0, limit).map((i) => candidates[i]);
+  } catch {
+    return candidates.slice(0, limit);
+  }
+}
+
+// src/packs.ts
+import * as fs2 from "fs";
+import * as path from "path";
+import yaml4 from "js-yaml";
+function installPack(packsDir, source) {
+  if (!fs2.existsSync(source)) throw new Error(`Pack source not found: ${source}`);
+  const sourceName = path.basename(source);
+  const destDir = path.join(packsDir, sourceName);
+  if (!fs2.existsSync(destDir)) fs2.mkdirSync(destDir, { recursive: true });
+  const files = fs2.readdirSync(source);
+  let copied = 0;
+  for (const file of files) {
+    const srcPath = path.join(source, file);
+    const destPath = path.join(destDir, file);
+    if (fs2.statSync(srcPath).isFile()) {
+      fs2.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+  const engramsPath = path.join(destDir, "engrams.yaml");
+  const engrams = fs2.existsSync(engramsPath) ? loadEngrams(engramsPath) : [];
+  return { installed: engrams.length, name: sourceName };
+}
+function listPacks(packsDir) {
+  if (!fs2.existsSync(packsDir)) return [];
+  const result = [];
+  for (const entry of fs2.readdirSync(packsDir)) {
+    const packDir = path.join(packsDir, entry);
+    if (!fs2.statSync(packDir).isDirectory()) continue;
+    try {
+      const pack = loadPack(packDir);
+      result.push({
+        name: pack.manifest.name,
+        path: packDir,
+        engram_count: pack.engrams.length,
+        manifest: pack.manifest
+      });
+    } catch {
+      const engramsPath = path.join(packDir, "engrams.yaml");
+      const engrams = fs2.existsSync(engramsPath) ? loadEngrams(engramsPath) : [];
+      result.push({
+        name: entry,
+        path: packDir,
+        engram_count: engrams.length
+      });
+    }
+  }
+  return result;
+}
+function exportPack(engrams, outputDir, manifest) {
+  if (!fs2.existsSync(outputDir)) fs2.mkdirSync(outputDir, { recursive: true });
+  const frontmatter = yaml4.dump({
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    creator: manifest.creator,
+    metadata: {
+      injection_policy: "on_match",
+      match_terms: [],
+      engram_count: engrams.length
+    }
+  });
+  fs2.writeFileSync(
+    path.join(outputDir, "SKILL.md"),
+    `---
+${frontmatter}---
+
+# ${manifest.name}
+
+${manifest.description || ""}
+`
+  );
+  const content = yaml4.dump({ engrams }, { lineWidth: 120, noRefs: true, quotingType: '"' });
+  fs2.writeFileSync(path.join(outputDir, "engrams.yaml"), content);
+  return { path: outputDir, engram_count: engrams.length };
+}
+
+// src/index.ts
+var INGEST_PATTERNS = [
+  { re: /(?:we decided|the decision is|agreed to)\s+(.+?)\.?$/gim, type: "architectural" },
+  { re: /(?:always|never|must|should)\s+(.+?)\.?$/gim, type: "behavioral" },
+  { re: /(?:the convention is|the rule is|the pattern is)\s+(.+?)\.?$/gim, type: "procedural" },
+  { re: /(?:use|prefer)\s+(\w+)\s+(?:for|over|instead of)\s+(.+?)\.?$/gim, type: "behavioral" },
+  { re: /(?:important|note|remember):\s*(.+?)\.?$/gim, type: "behavioral" }
+];
+var Plur = class {
+  paths;
+  config;
+  constructor(options) {
+    this.paths = detectPlurStorage(options?.path);
+    this.config = loadConfig(this.paths.config);
+  }
+  /** Create engram, detect conflicts, save. Returns the created engram. */
+  learn(statement, context) {
+    const engrams = loadEngrams(this.paths.engrams);
+    const id = generateEngramId(engrams);
+    const scope = context?.scope ?? "global";
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const conflictingEngrams = detectConflicts({ statement, scope }, engrams);
+    const conflictIds = conflictingEngrams.map((e) => e.id);
+    const engram = {
+      id,
+      version: 2,
+      status: "active",
+      consolidated: false,
+      type: context?.type ?? "behavioral",
+      scope,
+      visibility: "private",
+      statement,
+      domain: context?.domain,
+      activation: {
+        retrieval_strength: 0.7,
+        storage_strength: 1,
+        frequency: 0,
+        last_accessed: now.slice(0, 10)
+      },
+      feedback_signals: { positive: 0, negative: 0, neutral: 0 },
+      knowledge_anchors: [],
+      associations: [],
+      derivation_count: 1,
+      tags: [],
+      pack: null,
+      abstract: null,
+      derived_from: null,
+      relations: conflictIds.length > 0 ? {
+        broader: [],
+        narrower: [],
+        related: [],
+        conflicts: conflictIds
+      } : void 0
+    };
+    engrams.push(engram);
+    saveEngrams(this.paths.engrams, engrams);
+    return engram;
+  }
+  /**
+   * Search engrams, filter by scope/domain/strength, reactivate accessed.
+   * Supports two modes:
+   *   - 'fast' (default): BM25 keyword search, instant, no API calls
+   *   - 'agentic': LLM-assisted semantic search, higher accuracy, requires llm function
+   */
+  /** Search engrams using fast BM25 keyword matching. Sync, no API calls. */
+  recall(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const results = searchEngrams(filtered, query, limit);
+    this._reactivateResults(results);
+    return results;
+  }
+  /** Search engrams using LLM-assisted semantic filtering. Async, requires llm function. */
+  async recallAsync(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const results = await agenticSearch(filtered, query, limit, options.llm);
+    this._reactivateResults(results);
+    return results;
+  }
+  /** Filter engrams by scope/domain/strength (shared by both modes) */
+  _filterEngrams(options) {
+    let engrams = loadEngrams(this.paths.engrams);
+    engrams = engrams.filter((e) => e.status === "active");
+    if (options?.domain) {
+      engrams = engrams.filter((e) => e.domain?.startsWith(options.domain));
+    }
+    if (options?.min_strength !== void 0) {
+      engrams = engrams.filter((e) => e.activation.retrieval_strength >= options.min_strength);
+    }
+    if (options?.scope) {
+      const scope = options.scope;
+      engrams = engrams.filter(
+        (e) => e.scope === "global" || e.scope === scope || e.scope.startsWith(scope)
+      );
+    }
+    return engrams;
+  }
+  /** Reactivate accessed engrams (bump retrieval strength, frequency, last_accessed) */
+  _reactivateResults(results) {
+    if (results.length === 0) return;
+    const allEngrams = loadEngrams(this.paths.engrams);
+    const resultIds = new Set(results.map((e) => e.id));
+    let modified = false;
+    for (const e of allEngrams) {
+      if (resultIds.has(e.id)) {
+        e.activation.retrieval_strength = reactivate(e.activation.retrieval_strength);
+        e.activation.last_accessed = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+        e.activation.frequency += 1;
+        modified = true;
+      }
+    }
+    if (modified) saveEngrams(this.paths.engrams, allEngrams);
+  }
+  /** Scored injection within token budget. Returns formatted strings. */
+  inject(task, options) {
+    const engrams = loadEngrams(this.paths.engrams);
+    const packs = loadAllPacks(this.paths.packs);
+    const budget = options?.budget ?? this.config.injection_budget ?? 2e3;
+    const result = selectAndSpread(
+      {
+        prompt: task,
+        scope: options?.scope,
+        maxTokens: budget
+      },
+      engrams,
+      packs,
+      {
+        spread_cap: this.config.injection?.spread_cap,
+        spread_budget: this.config.injection?.spread_budget
+      }
+    );
+    const formatEngrams = (wires) => {
+      if (wires.length === 0) return "";
+      return wires.map((e) => `[${e.id}] ${e.statement}`).join("\n");
+    };
+    const directivesStr = formatEngrams(result.directives);
+    const considerStr = formatEngrams(result.consider);
+    const count = result.directives.length + result.consider.length;
+    const tokensUsed = result.tokens_used.directives + result.tokens_used.consider;
+    return {
+      directives: directivesStr,
+      consider: considerStr,
+      count,
+      tokens_used: tokensUsed
+    };
+  }
+  /** Update feedback_signals and adjust retrieval_strength. */
+  feedback(id, signal) {
+    const engrams = loadEngrams(this.paths.engrams);
+    const engram = engrams.find((e) => e.id === id);
+    if (!engram) throw new Error(`Engram not found: ${id}`);
+    if (!engram.feedback_signals) {
+      engram.feedback_signals = { positive: 0, negative: 0, neutral: 0 };
+    }
+    engram.feedback_signals[signal] += 1;
+    if (signal === "positive") {
+      engram.activation.retrieval_strength = Math.min(1, engram.activation.retrieval_strength + 0.05);
+    } else if (signal === "negative") {
+      engram.activation.retrieval_strength = Math.max(0, engram.activation.retrieval_strength - 0.1);
+    }
+    saveEngrams(this.paths.engrams, engrams);
+  }
+  /** Set engram status to 'retired'. */
+  forget(id, reason) {
+    const engrams = loadEngrams(this.paths.engrams);
+    const engram = engrams.find((e) => e.id === id);
+    if (!engram) throw new Error(`Engram not found: ${id}`);
+    engram.status = "retired";
+    if (reason && !engram.rationale) {
+      engram.rationale = `Retired: ${reason}`;
+    }
+    saveEngrams(this.paths.engrams, engrams);
+  }
+  /** Capture an episodic memory. */
+  capture(summary, context) {
+    return captureEpisode(this.paths.episodes, summary, context);
+  }
+  /** Query the episode timeline. */
+  timeline(query) {
+    return queryTimeline(this.paths.episodes, query);
+  }
+  /** Rule-based extraction of engram candidates from content. */
+  ingest(content, options) {
+    const candidates = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const { re, type } of INGEST_PATTERNS) {
+      re.lastIndex = 0;
+      let match;
+      while ((match = re.exec(content)) !== null) {
+        const captured = match.slice(1).filter(Boolean).join(" ").trim();
+        if (!captured || captured.length < 5) continue;
+        if (seen.has(captured.toLowerCase())) continue;
+        seen.add(captured.toLowerCase());
+        candidates.push({
+          statement: captured,
+          type,
+          source: options?.source
+        });
+      }
+    }
+    if (!options?.extract_only && candidates.length > 0) {
+      for (const candidate of candidates) {
+        this.learn(candidate.statement, {
+          type: candidate.type,
+          scope: options?.scope ?? "global",
+          domain: options?.domain,
+          source: candidate.source
+        });
+      }
+    }
+    return candidates;
+  }
+  /** Install a pack from a source path. */
+  installPack(source) {
+    return installPack(this.paths.packs, source);
+  }
+  /** Export engrams as a shareable pack. */
+  exportPack(engrams, outputDir, manifest) {
+    return exportPack(engrams, outputDir, manifest);
+  }
+  /** List all installed packs. */
+  listPacks() {
+    return listPacks(this.paths.packs);
+  }
+  /** Return system health info. */
+  status() {
+    const engrams = loadEngrams(this.paths.engrams);
+    const episodes = queryTimeline(this.paths.episodes);
+    const packs = listPacks(this.paths.packs);
+    return {
+      engram_count: engrams.filter((e) => e.status !== "retired").length,
+      episode_count: episodes.length,
+      pack_count: packs.length,
+      storage_root: this.paths.root,
+      config: this.config
+    };
+  }
+};
+export {
+  Plur
+};