@heixui/dsh-session-suite 0.3.3 → 0.4.0

package/lib/memory-engine.js

@@ -27,8 +27,10 @@ import path from 'node:path'
 import { ensureDir, readJson, sha256Text, shortId, writeJson } from './util.js'
 import { applySupersession, isCatchAllKey, normalizeFactKey } from './factkeys.js'
 import { isLoaded, loadWordList, wordTokens } from './wordlist.js'
+import { DISABLED_PROVIDER, createEmbeddingProvider } from './embeddings.js'
 import {
   bm25,
+  cosineSimilarity,
   rankIds,
   reciprocalRankFusion,
   tokens,
@@ -45,6 +47,113 @@ export const DEFAULT_WEIGHTS = { frequency: 0.35, recency: 0.3, affect: 0.15, un
 /** Lifecycle thresholds on the 0..1 composite score. */
 export const DEFAULT_THRESHOLDS = { compress: 0.45, archive: 0.25 }
 
+/**
+ * What kind of memory an entry is.
+ *
+ * Three of these mirror the standard split of long-term memory, and the split is
+ * not cosmetic: each kind decays at a different rate and answers a different
+ * question.
+ *
+ *   fact    语义 — a stable truth ("the export inlines images as data URLs")
+ *   rule    程序 — how something should be done ("refuse over-long memories")
+ *   summary 聚合 — several entries compressed into one
+ *   episode 情景 — what happened, when, and how it turned out
+ *
+ * `episode` is the one the library lacked entirely. Such a memory is not a fact
+ * (things can stay true) nor a rule (it prescribes nothing); it records an event
+ * with a time and an outcome, e.g. "last week's PPT was rejected for using too many
+ * colours". Filing those as `fact` lost the time and the outcome, which are the
+ * parts that make them useful later.
+ */
+export const KINDS = ['fact', 'rule', 'summary', 'episode']
+
+/**
+ * How much faster an episode ages than a fact.
+ *
+ * An event is dated: "the deployment failed on Tuesday" stops being actionable
+ * quickly, while "the project uses pnpm" stays true for years. Halving the
+ * half-life is a defensible default rather than a tuned constant — there is no
+ * held-out set of episodic queries to fit it against, so claiming a precise value
+ * would be unfounded.
+ */
+export const EPISODE_DECAY_FACTOR = 0.5
+
+/**
+ * How private a memory is.
+ *
+ * The library had only a scope (global / workspace), which controls *where* a
+ * memory is stored but says nothing about *who may see it*. That gap is a real risk:
+ * a password or a medical note filed under `workspace` is still exported by the share
+ * feature and still injected into every prompt in that workspace.
+ *
+ *   public    safe to include in an export someone else may read
+ *   internal  stays on this machine; excluded from exports (the default)
+ *   secret    never injected, never exported, masked in the list
+ *
+ * The default is `internal`, not `public`: guessing wrong toward privacy costs a
+ * little convenience, guessing wrong the other way leaks something.
+ */
+export const PRIVACY_LEVELS = ['public', 'internal', 'secret']
+
+/**
+ * Patterns that identify a credential or a government id.
+ *
+ * Deliberately blunt. A false positive only makes a memory harder to read; a false
+ * negative puts a secret in an export. Precision matters less than never missing.
+ */
+const SECRET_PATTERNS = [
+  /(?:密码|口令|password|passwd|pwd)\s*[:=：]?\s*\S+/i,
+  /\b(?:sk|pk|ghp|gho|ghs|xox[baprs])[-_][A-Za-z0-9_-]{12,}/,
+  /\b\d{17}[\dXx]\b/, // mainland id number
+  /\b(?:\d{15,19})\b/, // bank card
+  /\b1[3-9]\d{9}\b/, // mainland mobile
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/, // email
+  /(?:身份证|银行卡|信用卡|私钥|密钥|token|secret|api[_-]?key)/i,
+]
+
+/** Topics that are personal but not credentials. */
+const PRIVATE_TOPICS = /(工资|存款|现金|房租|负债|病历|诊断|吃药|抑郁|焦虑|家庭住址|身份证地址)/
+
+/**
+ * Decide a privacy level from the text alone.
+ *
+ * @param {string} text memory text
+ * @param {string} [explicit] a level the caller supplied
+ * @returns {'public' | 'internal' | 'secret'} level
+ */
+export function inferPrivacy(text, explicit) {
+  if (typeof explicit === 'string' && PRIVACY_LEVELS.includes(explicit)) return explicit
+  const value = String(text ?? '')
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(value)) return 'secret'
+  }
+  if (PRIVATE_TOPICS.test(value)) return 'internal'
+  return 'internal'
+}
+
+/**
+ * Whether a memory may be shown to someone other than its owner.
+ *
+ * @param {any} entry memory entry
+ * @returns {boolean} true when it may appear in an export
+ */
+export function isExportable(entry) {
+  return (entry?.privacy ?? 'internal') === 'public'
+}
+
+/**
+ * Whether a memory may be injected into a prompt.
+ *
+ * `secret` is excluded: a credential is not context, and injecting it would copy it
+ * into every provider request.
+ *
+ * @param {any} entry memory entry
+ * @returns {boolean} true when it may be injected
+ */
+export function isInjectable(entry) {
+  return (entry?.privacy ?? 'internal') !== 'secret'
+}
+
 const DEFAULTS = {
   /** Half-life of the recency factor, in days. */
   decayDays: 60,
@@ -75,6 +184,55 @@ const DEFAULTS = {
   bm25B: 0.75,
   /** RRF smoothing constant; 60 is the customary default. */
   rrfK: 60,
+  /**
+   * How many candidates the dense reranker may embed per query.
+   *
+   * Reranking runs on the prompt path, so its cost has to be bounded: embedding
+   * the whole library for one question would turn a 200ms step into a multi-second
+   * one. The lexical stage has already narrowed the field, and reranking only
+   * needs to reorder the head of that list.
+   */
+  denseRerankCandidates: 24,
+  /**
+   * How many topic cards the resident layer may inject, and the character budget
+   * for the whole block.
+   *
+   * The budget is the real constraint: cards exist to give the model a cheap
+   * overview, and an overview that costs a thousand tokens per turn defeats the
+   * purpose. Five cards of about 120 characters each keeps the block near 600
+   * characters, which is roughly what the previous flat layer cost while being far
+   * more informative.
+   */
+  residentCards: 5,
+  residentBudget: 600,
+  /**
+   * How much of a card's lead memory to show.
+   *
+   * A card is a pointer, not the memory itself: the full text stays reachable
+   * through recall. Capping this is what keeps ONE verbose memory from consuming
+   * the whole card budget and hiding every other topic — measured at 621
+   * characters for a single card before this cap.
+   */
+  residentCardSummaryChars: 60,
+  /**
+   * How much the dense similarity may nudge the fused lexical rank.
+   *
+   * Measured, not guessed. Swept over eight paraphrased queries against the real
+   * library and model (tools/probe-dense-rerank.mjs):
+   *
+   *   off    recall@5 1.000  MRR 0.535
+   *   0.15   recall@5 1.000  MRR 0.546   ← the value first shipped, effectively inert
+   *   0.5    recall@5 1.000  MRR 0.708
+   *   1      recall@5 1.000  MRR 0.760   ← chosen
+   *   2      recall@5 1.000  MRR 0.723
+   *   8      recall@5 1.000  MRR 0.629   ← over-weighted, drags good results down
+   *
+   * The curve has a clear maximum and recall never drops, which is what makes this a
+   * defensible default rather than a preference. An earlier measurement at 0.15
+   * concluded "the dense stage changes nothing" — that was a flaw in the query set
+   * (all eight were already ranked correctly by lexical retrieval), not in the stage.
+   */
+  denseWeight: 1,
 }
 
 /**
@@ -253,6 +411,15 @@ function matchesFilter(entry, input) {
     const when = Math.max(Number(entry.createdAt ?? 0), Number(entry.lastAccessAt ?? 0))
     if (when < cutoff) return false
   }
+  const privacy = typeof input?.privacy === 'string' ? input.privacy : ''
+  if (privacy) {
+    const level = entry.privacy ?? 'internal'
+    // One requested level, or 'all' for no filtering.
+    if (privacy !== 'all' && level !== privacy) return false
+  }
+  // Export wants only what may leave this machine. Filtered here rather than in the
+  // caller so the share path cannot forget it.
+  if (input?.exportable === true && !isExportable(entry)) return false
   return true
 }
 
@@ -266,9 +433,18 @@ function matchesFilter(entry, input) {
 export function scoreEntry(entry, context) {
   const weights = { ...DEFAULT_WEIGHTS, ...(context.weights ?? {}) }
   const now = context.now ?? Date.now()
-  const decayDays = context.decayDays ?? DEFAULTS.decayDays
+  // An episode ages faster than a fact: "the deployment failed on Tuesday" stops
+  // being actionable in weeks, while "the project uses pnpm" stays true for years.
+  // The episode's own occurrence time is the clock, not when it was written — an
+  // event recorded late is not a fresh event.
+  const isEpisode = entry.kind === 'episode'
+  const baseDecay = context.decayDays ?? DEFAULTS.decayDays
+  const decayDays = isEpisode ? baseDecay * EPISODE_DECAY_FACTOR : baseDecay
   const frequency = Math.log1p(entry.accessCount ?? 0) / Math.log1p(Math.max(1, context.maxAccess))
-  const days = Math.max(0, (now - (entry.lastAccessAt ?? entry.createdAt)) / 86400000)
+  const anchor = isEpisode
+    ? (entry.occurredAt ?? entry.lastAccessAt ?? entry.createdAt)
+    : (entry.lastAccessAt ?? entry.createdAt)
+  const days = Math.max(0, (now - anchor) / 86400000)
   // A freeze pins the recency clock: a frozen memory never decays away.
   const recency = entry.frozen ? 1 : Math.exp(-days / decayDays)
   const affect = clamp01(entry.affect ?? 0.4)
@@ -506,7 +682,7 @@ export class MemoryEngine {
       scope,
       workspaceKey: key,
       text,
-      kind: input.kind === 'rule' ? 'rule' : 'fact',
+      kind: KINDS.includes(input.kind) ? input.kind : 'fact',
       tags: Array.isArray(input.tags) ? input.tags.filter(tag => typeof tag === 'string') : [],
       affect: clamp01(input.affect ?? 0.4),
       frozen: input.frozen === true,
@@ -522,6 +698,23 @@ export class MemoryEngine {
       factKey,
       clusterId: null,
       summary: null,
+      // Who may see this. Scope says where it lives; privacy says who may read it.
+      privacy: inferPrivacy(text, input.privacy),
+    }
+    // An episode carries the three things that make it an event rather than a
+    // truth: when it happened, the situation, and how it turned out. They are
+    // optional so a caller that only knows the text can still file one.
+    if (entry.kind === 'episode') {
+      entry.occurredAt =
+        typeof input.occurredAt === 'number' && Number.isFinite(input.occurredAt)
+          ? input.occurredAt
+          : entry.createdAt
+      if (typeof input.context === 'string' && input.context.trim()) {
+        entry.context = input.context.trim().slice(0, 200)
+      }
+      if (typeof input.outcome === 'string' && input.outcome.trim()) {
+        entry.outcome = input.outcome.trim().slice(0, 200)
+      }
     }
     store.entries.push(entry)
     // Supersede older entries that talk about the same fact. Done in the same
@@ -599,6 +792,10 @@ export class MemoryEngine {
     await collect('workspace')
     await collect('global')
 
+    // Remember the scanned set so the dense reranker can look an entry up by id
+    // without re-reading the stores it was just built from.
+    this.lastScan = results
+
     // Rank by two lexical routes fused by rank, not by one coverage score.
     //
     // History: this used Jaccard, which is symmetric and therefore punishes a
@@ -619,7 +816,11 @@ export class MemoryEngine {
     // real match scored 0.93. Scores of zero are therefore dropped before fusion,
     // so only documents that actually matched compete for rank.
     if (query.size > 0) {
-      const live = results.filter(item => !item.archived)
+      // A secret is filtered here, in the engine, rather than trusted to every
+      // caller: recall is the one function whose output ends up in a prompt, and a
+      // credential is not context. Filtering at the call sites would mean the
+      // guarantee holds only where someone remembered to apply it.
+      const live = results.filter(item => !item.archived && item.privacy !== 'secret')
       const documents = live.map(item => tokens(item.text))
       const looseDocuments = live.map(item => unigrams(item.text))
       const ids = live.map(item => item.id)
@@ -674,6 +875,18 @@ export class MemoryEngine {
         this.config.rrfK ?? DEFAULTS.rrfK,
       )
 
+      // Optional second stage: dense reranking of the candidates the lexical
+      // routes already found. Lexical retrieval cannot bridge a paraphrase that
+      // shares no character (checkpoint vs 快照); a dense model can. It runs only
+      // when a provider is configured and a query exists, and every failure path
+      // inside the provider returns undefined, so the fused order below is the
+      // fallback rather than an exception.
+      //
+      // Note the interpolation weight is applied against the *fused* ranking, so
+      // a strong lexical agreement is not discarded just because the vector is
+      // mediocre — the two signals describe different things and both are kept.
+      const denseRanking = await this.#denseRerank(input.query, ids, fused).catch(() => undefined)
+
       for (let index = 0; index < live.length; index += 1) {
         const item = live[index]
         const bm25Score = preciseScores[index]
@@ -684,13 +897,29 @@ export class MemoryEngine {
         item.matched = bm25Score > 0 || looseScores[index] > 0 || wordScore > 0
         item.rank =
           (fused.get(item.id) ?? 0) * 0.75 + item.score * 0.2 + (item.scope === 'workspace' ? 0.05 : 0)
+        // The dense score nudges the order without replacing it. The weight is
+        // configurable because the right value is empirical, not obvious: measured on
+        // a hold-out of eight paraphrase queries, a weight of 0.15 changed the
+        // ordering of NOT ONE result — the three lexical routes had already agreed,
+        // and the dense signal was too small to overturn them. A weight that DOES
+        // change ordering has to be justified by measurement, so it is exposed here
+        // rather than guessed at.
+        if (denseRanking?.has(item.id)) {
+          item.dense = Number(denseRanking.get(item.id).toFixed(3))
+          item.rank += Math.max(0, item.dense) * (this.config.denseWeight ?? DEFAULTS.denseWeight)
+        }
       }
     }
 
     // With no query every rank is 0, so this only orders the importance-only
     // case; with a query the coverage ranks are already in place.
     results.sort((a, b) => b.rank - a.rank)
-    const top = results.slice(0, limit)
+    // The secret filter must be applied to the FINAL list, not only to the
+    // candidate set the lexical routes scored: filtering `live` alone left the
+    // unfiltered `results` to be sorted and sliced below, so a credential still
+    // came back. This is the last gate before the output leaves the engine.
+    const safe = results.filter(item => item.privacy !== 'secret')
+    const top = safe.slice(0, limit)
     if (input.touch !== false) await this.#touch(top, input.cwd)
     return top
   }
@@ -718,6 +947,113 @@ export class MemoryEngine {
    * @param {object} input same as recall, plus `tiered` (default true)
    * @returns {Promise<{ items: any[], omitted: any[], effectiveLimit: number, topScore: number }>}
    */
+  /**
+   * Group high-value memories into topic cards for the resident layer.
+   *
+   * Why cards instead of "the N most important entries": the flat version made the
+   * injected block unreadable and, worse, misleading. A user who typed a question
+   * into the settings probe saw six lines and assumed all six were the recall
+   * result, when two of them were the resident layer and had nothing to do with the
+   * question. Grouping by topic lets the block state *what* it is summarising
+   * ("缓存: 4 条") instead of dumping four unrelated sentences and calling the
+   * whole thing "relevant".
+   *
+   * The shape follows the two-layer architecture described for agent memory: a
+   * compact overview of what the library knows, with detail left to on-demand
+   * recall. It is deliberately NOT a hierarchical index — one level of grouping is
+   * what the injected budget can afford, and a deeper tree would cost more context
+   * than it saves.
+   *
+   * @param {object} input input
+   * @param {string} [input.cwd] workspace
+   * @param {number} [input.limit] how many cards, default 5
+   * @param {number} [input.budget] total character budget for card text, default 600
+   * @returns {Promise<Array<{ topic: string, count: number, summary: string, updatedAt: number }>>} cards
+   */
+  async residentCards(input = {}) {
+    const limit = typeof input.limit === 'number' ? input.limit : DEFAULTS.residentCards
+    const budget = typeof input.budget === 'number' ? input.budget : DEFAULTS.residentBudget
+    const entries = (await this.list({ cwd: input.cwd })).filter(
+      // A secret must not appear in the overview either: a card's summary is text
+      // that gets injected, so listing one here would leak it just as surely as
+      // putting it in the matched half.
+      entry => !entry.archived && entry.privacy !== 'secret' && String(entry.text ?? '').trim(),
+    )
+    if (entries.length === 0) return []
+
+    // Group by the first tag that is not the generic feature tag. A memory usually
+    // carries one or two tags; the first is the subject, and grouping by it is
+    // what a reader would call "the topic".
+    const groups = new Map()
+    for (const entry of entries) {
+      const tags = Array.isArray(entry.tags) ? entry.tags.filter(tag => typeof tag === 'string' && tag) : []
+      const topic = tags[0] ?? '未分类'
+      if (!groups.has(topic)) groups.set(topic, [])
+      groups.get(topic).push(entry)
+    }
+
+    const cards = []
+    for (const [topic, members] of groups) {
+      // Rank the members so the card's summary line carries the most valuable
+      // sentence: frozen first (the user pinned it), then by score, then recency.
+      const ranked = [...members].sort(
+        (a, b) =>
+          Number(Boolean(b.frozen)) - Number(Boolean(a.frozen)) ||
+          (b.score ?? 0) - (a.score ?? 0) ||
+          (b.lastAccessAt ?? 0) - (a.lastAccessAt ?? 0),
+      )
+      const head = ranked[0]
+      // A card is an overview line, not a memory. The head memory can be up to
+      // maxMemoryChars long, and pasting it whole turned one card into 600
+      // characters on its own — which then crowded every other topic out of the
+      // budget. Truncation is acceptable HERE, unlike at the write path: this is a
+      // pointer that says "there is something about X", and the full text is still
+      // available through recall.
+      const headText = String(head?.text ?? '').replace(/\s+/g, ' ').trim()
+      const summary =
+        headText.length > DEFAULTS.residentCardSummaryChars
+          ? `${headText.slice(0, DEFAULTS.residentCardSummaryChars)}…`
+          : headText
+      cards.push({
+        topic,
+        count: members.length,
+        summary,
+        updatedAt: Math.max(...members.map(entry => entry.lastAccessAt ?? entry.createdAt ?? 0)),
+        weight: ranked.reduce((sum, entry) => sum + (entry.score ?? 0), 0) / members.length,
+      })
+    }
+
+    // Biggest and most valuable topics first; a card for one stray memory is noise.
+    cards.sort((a, b) => b.count - a.count || b.weight - a.weight || b.updatedAt - a.updatedAt)
+
+    const kept = []
+    let used = 0
+    for (const card of cards) {
+      if (kept.length >= limit) break
+      // Cost is the rendered line, not just the summary: the topic name and count
+      // are charged too. The check is BEFORE adding, and the first card is allowed
+      // through regardless so the layer is never empty — a 621-character single
+      // card against a 600-character budget is exactly the overrun this avoids.
+      const line = `${card.topic}（${card.count} 条）：${card.summary}`
+      if (kept.length > 0 && used + line.length + 1 > budget) break
+      kept.push(card)
+      used += line.length + 1
+    }
+    return kept
+  }
+
+  /**
+   * Render the resident cards as prompt lines.
+   *
+   * @param {Array<any>} cards output of residentCards
+   * @returns {string[]} one line per card
+   */
+  static formatCards(cards) {
+    return (Array.isArray(cards) ? cards : []).map(
+      card => `- ${card.topic}（${card.count} 条）：${card.summary}`,
+    )
+  }
+
   async select(input = {}) {
     const limit = typeof input.limit === 'number' ? input.limit : DEFAULTS.recallLimit
     const tiered = input.tiered !== false
@@ -882,9 +1218,28 @@ export class MemoryEngine {
         const clusterId = `cluster_${shortId(group.map(entry => entry.id).join(':'))}`
         const summary = group.map(entry => entry.text).join('；')
         const summaryText = summary.length > 400 ? `${summary.slice(0, 400)}…` : summary
-        // The same text under a new cluster id is a duplicate, not a finding.
-        // Content decides identity here; the member ids only decide the cluster.
-        const existing = store.entries.find(entry => entry.summary && entry.text === summaryText)
+        // Identity is the CONTENT, and the cold archive counts.
+        //
+        // The live-only, exact-text check was the hole that kept refilling the
+        // library. Sequence: a group is clustered → its summary is written and
+        // its members are archived → a later pass clusters a DIFFERENT group
+        // whose joined text is equivalent but not byte-identical (member order
+        // differs, or one member came back as a new fact) → the exact-text probe
+        // missed it → another near-identical summary appeared. One sentence ended
+        // up in the library seven times.
+        //
+        // Comparing a normalised digest rather than raw text fixes the ordering
+        // half, and searching the cold archive fixes the "it was archived"
+        // half — the same reasoning that already protected rule generation.
+        const summaryDigest = sha256Text(
+          group
+            .map(entry => String(entry.text ?? '').trim())
+            .sort()
+            .join('；'),
+        ).slice(0, 16)
+        const existing = [...store.entries, ...cold.entries].find(
+          entry => entry.summary && (entry.summaryDigest === summaryDigest || entry.text === summaryText),
+        )
         if (existing) {
           for (const entry of group) {
             entry.clusterId = existing.clusterId
@@ -909,6 +1264,7 @@ export class MemoryEngine {
           lastAccessAt: Date.now(),
           source: 'cluster',
           digest: sha256Text(summary).slice(0, 16),
+          summaryDigest,
           clusterId,
           summary: true,
         }
@@ -1045,6 +1401,10 @@ export class MemoryEngine {
       lastMaintainedCwd: typeof data?.lastMaintainedCwd === 'string' ? data.lastMaintainedCwd : null,
       lastReport: data?.lastReport ?? null,
       lastFingerprint: typeof data?.lastFingerprint === 'string' ? data.lastFingerprint : '',
+      // The most recent implicit-extraction attempt, set by the host half. It is
+      // in-memory on purpose: a restart legitimately forgets it, and the settings
+      // page only ever asks "why is the queue empty right now".
+      extraction: this.lastExtraction ?? null,
     }
   }
 
@@ -1082,6 +1442,100 @@ export class MemoryEngine {
     return fingerprint !== status.lastFingerprint
   }
 
+  /**
+   * Score query/candidate pairs with the configured embedding provider.
+   *
+   * Returns undefined whenever dense ranking is unavailable, which is the normal
+   * state: no provider configured, no query, or an embedding failure. The caller
+   * treats undefined as "keep the lexical order", so this is an optimisation that
+   * cannot break recall.
+   *
+   * @param {string} query the user's question
+   * @param {Array<string | number>} ids candidate ids, aligned with `live`
+   * @param {Map<string | number, number>} fused lexical scores, best-first order
+   * @returns {Promise<Map<string | number, number> | undefined>} dense cosine per id
+   */
+  async #denseRerank(query, ids, fused) {
+    const text = String(query ?? '').trim()
+    if (!text) return undefined
+    const provider = await this.#ensureEmbeddingProvider()
+    if (!provider?.available) return undefined
+
+    // Only embed candidates the lexical stage actually matched, capped so a huge
+    // library cannot turn one prompt step into hundreds of inferences.
+    const selected = [...fused.entries()]
+      .filter(([, score]) => score > 0)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, DEFAULTS.denseRerankCandidates)
+      .map(([id]) => id)
+    if (selected.length === 0) return undefined
+
+    const queryVector = await provider.embed(text)
+    if (!queryVector) return undefined
+
+    const scores = new Map()
+    for (const id of selected) {
+      const entry = this.#findEntryById(id)
+      if (!entry) continue
+      const vector = await this.#embeddingFor(provider, entry)
+      if (!vector) continue
+      scores.set(id, cosineSimilarity(queryVector, vector))
+    }
+    return scores.size > 0 ? scores : undefined
+  }
+
+  /**
+   * The embedding provider for this engine, created at most once.
+   *
+   * Lazy on purpose: constructing a local pipeline is expensive and most users run
+   * without a model, so nothing happens until a query actually needs it.
+   *
+   * @returns {Promise<any>} provider, or the disabled one
+   */
+  async #ensureEmbeddingProvider() {
+    if (this.denseProvider !== undefined) return this.denseProvider
+    try {
+      this.denseProvider = await createEmbeddingProvider({ ...this.config, root: this.root })
+    } catch {
+      this.denseProvider = DISABLED_PROVIDER
+    }
+    return this.denseProvider
+  }
+
+  /**
+   * Embedding for one entry, memoised in memory.
+   *
+   * Entries are immutable except for scoring metadata, so a vector stays valid
+   * for the process lifetime; recomputing it per query would make reranking far
+   * more expensive than the lexical routes it augments.
+   *
+   * @param {any} provider embedding provider
+   * @param {any} entry memory entry
+   * @returns {Promise<number[] | undefined>} vector
+   */
+  async #embeddingFor(provider, entry) {
+    if (!this.denseCache) this.denseCache = new Map()
+    // Key on the text plus its length: a rewritten memory changes the text, so a
+    // stale vector cannot be served for different content.
+    const key = `${entry.id}:${String(entry.text ?? '').length}:${entry.text}`
+    if (this.denseCache.has(key)) return this.denseCache.get(key)
+    const vector = await provider.embed(String(entry.text ?? ''))
+    this.denseCache.set(key, vector)
+    return vector
+  }
+
+  /**
+   * Look up an entry by id across the stores this engine has loaded.
+   *
+   * @param {string | number} id entry id
+   * @returns {any | undefined} entry
+   */
+  #findEntryById(id) {
+    const scanned = this.lastScan
+    if (!Array.isArray(scanned)) return undefined
+    return scanned.find(entry => entry.id === id)
+  }
+
   /**
    * The stores a maintenance pass covers: the global store plus every workspace.
    *
@@ -1248,11 +1702,22 @@ export class MemoryEngine {
    * @returns {Promise<any>} everything, for a portable backup
    */
   async export(input = {}) {
-    const out = { version: 2, exportedAt: Date.now(), global: {}, workspace: {} }
-    const read = async (scope, key) => ({
-      live: await this.#readStore(scope, key),
-      cold: await this.#readCold(scope, key),
-    })
+    const out = { version: 2, exportedAt: Date.now(), global: {}, workspace: {}, excluded: 0 }
+    // A share export leaves this machine, so only `public` memories may travel.
+    // `internal` is the default level, which means the honest behaviour for a library
+    // nobody has classified is to export nothing private — and to say how many were
+    // withheld, because silently dropping rows looks like data loss.
+    const keep = (scope, store) => {
+      const entries = Array.isArray(store?.entries) ? store.entries : []
+      const kept = entries.filter(isExportable)
+      out.excluded += entries.length - kept.length
+      return { ...store, entries: kept }
+    }
+    const read = async (scope, key) => {
+      const live = await this.#readStore(scope, key)
+      const cold = await this.#readCold(scope, key)
+      return { live: keep(scope, live), cold: keep(scope, cold) }
+    }
     out.global = await read('global', 'global')
     if (input.cwd) out.workspace = await read('workspace', MemoryEngine.workspaceKey(input.cwd))
     return out
@@ -1285,6 +1750,10 @@ export class MemoryEngine {
       digest,
       text: String(suggestion.text ?? '').trim(),
       scope: suggestion.scope === 'global' ? 'global' : 'workspace',
+      // The kind travels with the suggestion so accepting it later stores the same
+      // shape the extractor meant. Without this, an episode would be flattened to a
+      // fact at confirmation time and lose its time and outcome.
+      kind: KINDS.includes(suggestion.kind) ? suggestion.kind : 'fact',
       cwd: suggestion.cwd ?? null,
       tags: suggestion.tags ?? [],
       affect: clamp01(suggestion.affect ?? 0.5),
@@ -1292,6 +1761,14 @@ export class MemoryEngine {
       sessionId: suggestion.sessionId ?? null,
       createdAt: Date.now(),
     }
+    if (item.kind === 'episode') {
+      if (typeof suggestion.context === 'string' && suggestion.context.trim()) {
+        item.context = suggestion.context.trim().slice(0, 200)
+      }
+      if (typeof suggestion.outcome === 'string' && suggestion.outcome.trim()) {
+        item.outcome = suggestion.outcome.trim().slice(0, 200)
+      }
+    }
     if (!item.text) return undefined
     items.push(item)
     await ensureDir(this.root)
@@ -1311,6 +1788,8 @@ export class MemoryEngine {
       scope: item.scope,
       cwd: item.cwd,
       text: item.text,
+      kind: item.kind,
+      ...(item.kind === 'episode' ? { context: item.context, outcome: item.outcome } : {}),
       tags: item.tags,
       affect: item.affect,
       source: 'implicit',