prism-mcp-server 6.5.2 → 7.0.0

package/dist/tools/graphHandlers.js

@@ -50,7 +50,9 @@ const activeCompactions = new Set();
  *
  * After saving, generates an embedding vector for the entry via fire-and-forget.
  */
-import { computeEffectiveImportance, updateLastAccessed } from "../utils/cognitiveMemory.js";
+import { computeEffectiveImportance, recordMemoryAccess } from "../utils/cognitiveMemory.js";
+import { baseLevelActivation, candidateScopedSpreadingActivation, compositeRetrievalScore, } from "../utils/actrActivation.js";
+import { PRISM_ACTR_ENABLED, PRISM_ACTR_DECAY, PRISM_ACTR_WEIGHT_SIMILARITY, PRISM_ACTR_WEIGHT_ACTIVATION, PRISM_ACTR_SIGMOID_MIDPOINT, PRISM_ACTR_SIGMOID_STEEPNESS, PRISM_ACTR_MAX_ACCESSES_PER_ENTRY, } from "../config.js";
 import { HdcStateMachine } from "../sdm/stateMachine.js";
 import { ConceptDictionary } from "../sdm/conceptDictionary.js";
 import { PolicyGateway } from "../sdm/policyGateway.js";
@@ -114,7 +116,7 @@ export async function knowledgeSearchHandler(args) {
     if (data.results && Array.isArray(data.results)) {
         const resultIds = data.results.map((r) => r.id).filter(Boolean);
         if (resultIds.length > 0) {
-            updateLastAccessed(resultIds);
+            recordMemoryAccess(resultIds);
         }
         // Mutate results to surface effective importance
         for (const r of data.results) {
@@ -359,10 +361,17 @@ export async function sessionSearchMemoryHandler(args) {
         // For Supabase: this measures the pgvector cosine distance RPC call.
         // For SQLite: this measures the local sqlite-vec similarity search.
         const storageStart = performance.now();
+        // v7.0: Over-fetch candidates to give ACT-R re-ranker a meaningful pool.
+        // If we only fetch `limit` rows, the re-ranker can only shuffle those exact
+        // results — a memory at rank #(limit+1) by similarity but accessed 500 times
+        // would never surface. Fetch 4× or minimum 20, then slice after re-ranking.
+        const candidateLimit = PRISM_ACTR_ENABLED
+            ? Math.min(Math.max(limit * 4, 20), 50)
+            : Math.min(limit, 20);
         const results = await storage.searchMemory({
             queryEmbedding: JSON.stringify(queryEmbedding),
             project: project || null,
-            limit: Math.min(limit, 20),
+            limit: candidateLimit,
             similarityThreshold: similarity_threshold,
             userId: PRISM_USER_ID,
         });
@@ -399,28 +408,98 @@ export async function sessionSearchMemoryHandler(args) {
             }
             return { content: contentBlocks, isError: false };
         }
-        // ── v5.2: Dynamic Importance Decay (Ebbinghaus Curve) ──────
-        // Compute effective_importance at retrieval time
+        // ── v7.0: ACT-R Re-Ranking Pipeline ──────────────────────────
         const resultIds = results.map((r) => r.id).filter(Boolean);
-        // Fire-and-forget: update last_accessed_at for all returned results
-        if (resultIds.length > 0) {
-            updateLastAccessed(resultIds);
+        const now = new Date();
+        // Accumulate ACT-R metrics for trace output
+        let actrMetrics = null;
+        if (PRISM_ACTR_ENABLED && resultIds.length > 0) {
+            try {
+                // Step A: Bulk-fetch access logs for all candidate IDs
+                const accessLogMap = await storage.getAccessLog(resultIds, PRISM_ACTR_MAX_ACCESSES_PER_ENTRY);
+                // Step B: Fetch outbound links for spreading activation
+                const candidateIdSet = new Set(resultIds);
+                const linksMap = new Map();
+                for (const id of resultIds) {
+                    try {
+                        const links = await storage.getLinksFrom(id, PRISM_USER_ID, 0.0, 20);
+                        linksMap.set(id, links.map((l) => ({
+                            target_id: l.target_id,
+                            strength: l.strength ?? 1.0,
+                        })));
+                    }
+                    catch {
+                        linksMap.set(id, []);
+                    }
+                }
+                // Step C: Compute activation for each result and re-rank
+                actrMetrics = { baseLevels: [], spreadings: [], sigmoids: [], composites: [] };
+                for (const r of results) {
+                    const id = r.id;
+                    if (!id)
+                        continue;
+                    // B_i: Base-level activation from access log
+                    const accessTimestamps = accessLogMap.get(id) || [];
+                    // If no access log entries, use created_at as single proxy
+                    const timestamps = accessTimestamps.length > 0
+                        ? accessTimestamps
+                        : [new Date(r.created_at || now)];
+                    const Bi = baseLevelActivation(timestamps, now, PRISM_ACTR_DECAY);
+                    // S_i: Candidate-scoped spreading activation
+                    const outboundLinks = linksMap.get(id) || [];
+                    const Si = candidateScopedSpreadingActivation(outboundLinks, candidateIdSet);
+                    // Composite retrieval score
+                    const composite = compositeRetrievalScore(typeof r.similarity === "number" ? r.similarity : 0, Bi + Si, PRISM_ACTR_WEIGHT_SIMILARITY, PRISM_ACTR_WEIGHT_ACTIVATION, PRISM_ACTR_SIGMOID_MIDPOINT, PRISM_ACTR_SIGMOID_STEEPNESS);
+                    // Attach to result for re-sorting and display
+                    r._actr_Bi = Bi;
+                    r._actr_Si = Si;
+                    r._actr_composite = composite;
+                    actrMetrics.baseLevels.push(Bi);
+                    actrMetrics.spreadings.push(Si);
+                    actrMetrics.composites.push(composite);
+                }
+                // Re-sort by composite score (descending)
+                results.sort((a, b) => (b._actr_composite ?? 0) - (a._actr_composite ?? 0));
+                debugLog(`[session_search_memory] ACT-R re-ranking applied to ${results.length} candidates (returning top ${limit}): ` +
+                    `mean B_i=${(actrMetrics.baseLevels.reduce((a, b) => a + b, 0) / actrMetrics.baseLevels.length).toFixed(3)}, ` +
+                    `mean composite=${(actrMetrics.composites.reduce((a, b) => a + b, 0) / actrMetrics.composites.length).toFixed(3)}`);
+            }
+            catch (actrErr) {
+                // ACT-R failures are non-fatal — degrade to similarity-only ordering
+                debugLog(`[session_search_memory] ACT-R re-ranking failed (non-fatal): ${actrErr instanceof Error ? actrErr.message : String(actrErr)}`);
+            }
         }
-        // Format results with similarity scores + effective importance
+        // v7.0: Slice the re-ranked candidate pool back to the requested limit.
+        // This MUST happen after re-ranking but BEFORE recording access events,
+        // so we only log access for results actually delivered to the LLM.
+        results.splice(limit);
+        // Fire-and-forget: record access events for the final delivered results
+        // v7.0: Writes to both access_log buffer AND legacy last_accessed_at
+        const finalIds = results.map((r) => r.id).filter(Boolean);
+        if (finalIds.length > 0) {
+            const queryHash = query.substring(0, 64);
+            recordMemoryAccess(finalIds, queryHash);
+        }
+        // Format results with similarity scores + effective importance + ACT-R
         const formatted = results.map((r, i) => {
-            const score = typeof r.similarity === "number"
+            const simScore = typeof r.similarity === "number"
                 ? `${(r.similarity * 100).toFixed(1)}%`
                 : "N/A";
-            // Dynamic importance decay
+            // Dynamic importance decay (uses ACT-R internally when enabled)
             const baseImportance = r.importance ?? 0;
             const effectiveImportance = computeEffectiveImportance(baseImportance, r.last_accessed_at, r.created_at);
             const importanceStr = baseImportance > 0
                 ? `  Importance: ${effectiveImportance}${effectiveImportance !== baseImportance ? ` (base: ${baseImportance}, decayed)` : ""}\n`
                 : "";
-            return `[${i + 1}] ${score} similar — ${r.session_date || "unknown date"}\n` +
+            // v7.0: Append ACT-R composite score when available
+            const actrStr = r._actr_composite !== undefined
+                ? `  ACT-R: composite=${r._actr_composite.toFixed(3)} (B=${r._actr_Bi?.toFixed(2)}, S=${r._actr_Si?.toFixed(3)})\n`
+                : "";
+            return `[${i + 1}] ${simScore} similar — ${r.session_date || "unknown date"}\n` +
                 `  Project: ${r.project}\n` +
                 `  Summary: ${r.summary}\n` +
                 importanceStr +
+                actrStr +
                 (r.decisions?.length ? `  Decisions: ${r.decisions.join("; ")}\n` : "") +
                 (r.files_changed?.length ? `  Files: ${r.files_changed.join(", ")}\n` : "");
         }).join("\n");
@@ -437,6 +516,8 @@ export async function sessionSearchMemoryHandler(args) {
             const topScore = results.length > 0 && typeof results[0].similarity === "number"
                 ? results[0].similarity
                 : null;
+            // v7.0: Compute ACT-R trace metrics (means)
+            const mean = (arr) => arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : undefined;
             const trace = createMemoryTrace({
                 strategy: "semantic",
                 query,
@@ -447,6 +528,11 @@ export async function sessionSearchMemoryHandler(args) {
                 storageMs,
                 totalMs,
                 project: project || null,
+                // v7.0: ACT-R observability
+                actrEnabled: PRISM_ACTR_ENABLED,
+                actrBaseLevelMean: actrMetrics ? mean(actrMetrics.baseLevels) : undefined,
+                actrSpreadingMean: actrMetrics ? mean(actrMetrics.spreadings) : undefined,
+                actrCompositeMean: actrMetrics ? mean(actrMetrics.composites) : undefined,
             });
             contentBlocks.push(traceToContentBlock(trace));
         }

package/dist/tools/ledgerHandlers.js

@@ -54,7 +54,7 @@ import { notifyResourceUpdate } from "../server.js";
  *
  * After saving, generates an embedding vector for the entry via fire-and-forget.
  */
-import { computeEffectiveImportance, updateLastAccessed } from "../utils/cognitiveMemory.js";
+import { computeEffectiveImportance, recordMemoryAccess } from "../utils/cognitiveMemory.js";
 export async function sessionSaveLedgerHandler(args) {
     if (!isSessionSaveLedgerArgs(args)) {
         throw new Error("Invalid arguments for session_save_ledger");
@@ -644,7 +644,7 @@ export async function sessionLoadContextHandler(args) {
     if (d.recent_sessions?.length) {
         const resultIds = d.recent_sessions.map((r) => r.id).filter(Boolean);
         if (resultIds.length > 0)
-            updateLastAccessed(resultIds);
+            recordMemoryAccess(resultIds);
         formattedContext += `\n⏳ Recent Sessions:\n` + d.recent_sessions.map((s) => {
             let impStr = "";
             if (typeof s.importance === 'number' && s.importance > 0) {

package/dist/utils/accessLogBuffer.js

@@ -0,0 +1,159 @@
+/**
+ * AccessLogBuffer — Write Contention Prevention for memory_access_log
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PURPOSE:
+ *   Prevents SQLite SQLITE_BUSY errors by batching access log writes.
+ *
+ * PROBLEM (Rule #1):
+ *   Every memory search fires logAccess() writes. If an LLM agent fires
+ *   5 parallel tool calls to search memory, you get 5 concurrent SQLite
+ *   write attempts. SQLite's WAL mode helps for reads but writes still
+ *   acquire an exclusive lock — concurrent writes throw SQLITE_BUSY.
+ *
+ * SOLUTION:
+ *   Buffer access events in memory, flush as a single INSERT transaction
+ *   every flushIntervalMs (default 5000ms). This reduces write operations
+ *   from O(searches) to O(1 per interval).
+ *
+ * PROPERTIES:
+ *   - push() is synchronous (zero latency for callers)
+ *   - flush() uses a single multi-value INSERT (1 write lock, not N)
+ *   - splice(0) drain is atomic — no data loss during concurrent access
+ *   - dispose() flushes remaining buffer on shutdown
+ *   - Deduplication: collapses duplicate entryIds within the same
+ *     flush window (prevents bloat from rapid agent loops, Rule #3B)
+ *
+ * LIFECYCLE:
+ *   Instantiated once in SqliteStorage.initialize().
+ *   Disposed in SqliteStorage.close().
+ *
+ * FILES THAT IMPORT THIS:
+ *   - src/storage/sqlite.ts (construction + delegation)
+ * ═══════════════════════════════════════════════════════════════════
+ */
+import { debugLog } from "./logger.js";
+export class AccessLogBuffer {
+    buffer = [];
+    flushTimer = null;
+    db;
+    disposed = false;
+    /**
+     * @param db - Database connection for flushing (injected for testability)
+     * @param flushIntervalMs - How often to flush (default: 5000ms)
+     */
+    constructor(db, flushIntervalMs = 5000) {
+        this.db = db;
+        // Only start the timer if a positive interval is given.
+        // Tests may pass 0 to disable auto-flush and control it manually.
+        if (flushIntervalMs > 0) {
+            this.flushTimer = setInterval(() => {
+                this.flush().catch(err => {
+                    debugLog(`[AccessLogBuffer] Auto-flush failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }, flushIntervalMs);
+            // Prevent the timer from keeping the Node.js process alive
+            // when all other handles have been closed (graceful shutdown).
+            if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) {
+                this.flushTimer.unref();
+            }
+        }
+    }
+    /**
+     * Record an access event. This is intentionally SYNCHRONOUS —
+     * callers pay zero async overhead. The event is buffered in memory
+     * and will be flushed to SQLite on the next flush cycle.
+     *
+     * @param entryId - The session_ledger entry that was accessed
+     * @param contextHash - Optional hash of the search query context
+     */
+    push(entryId, contextHash) {
+        if (this.disposed)
+            return;
+        this.buffer.push({
+            entryId,
+            contextHash: contextHash || null,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Flush the buffer to SQLite as a single batch INSERT.
+     *
+     * DEDUPLICATION (Rule #3B — Buffer Debouncing):
+     *   Before building the INSERT, collapses duplicate entryIds within
+     *   the same flush window. If an agent retrieves the same memory 5
+     *   times in 2 seconds, only 1 access log row is written.
+     *   This preserves frequency semantics (1 access per 5s is plenty
+     *   for ACT-R math) without database bloat.
+     *
+     * @returns Number of unique rows inserted
+     */
+    async flush() {
+        // Atomic drain: splice(0) removes all elements and returns them.
+        // Even if push() is called during this async operation, those new
+        // events won't be lost — they go into the fresh empty array.
+        const batch = this.buffer.splice(0);
+        if (batch.length === 0)
+            return 0;
+        // ── Deduplication: keep only the LATEST access per entryId ──
+        // Map from entryId → BufferedAccess, last-write-wins within window
+        const deduped = new Map();
+        for (const event of batch) {
+            deduped.set(event.entryId, event);
+        }
+        const uniqueEvents = Array.from(deduped.values());
+        if (uniqueEvents.length === 0)
+            return 0;
+        // ── Chunked INSERT to stay within SQLITE_MAX_VARIABLE_NUMBER ──
+        // Older SQLite builds cap bound variables at 999; modern ones at 32766.
+        // 500 entries × 3 vars = 1500, safe on all versions.
+        const CHUNK_SIZE = 500;
+        let totalInserted = 0;
+        try {
+            for (let i = 0; i < uniqueEvents.length; i += CHUNK_SIZE) {
+                const chunk = uniqueEvents.slice(i, i + CHUNK_SIZE);
+                const placeholders = chunk.map(() => "(?, ?, ?)").join(", ");
+                const args = [];
+                for (const event of chunk) {
+                    args.push(event.entryId, event.timestamp, event.contextHash);
+                }
+                await this.db.execute({
+                    sql: `INSERT INTO memory_access_log (entry_id, accessed_at, context_hash) VALUES ${placeholders}`,
+                    args,
+                });
+                totalInserted += chunk.length;
+            }
+            debugLog(`[AccessLogBuffer] Flushed ${totalInserted} access events (from ${batch.length} raw)`);
+            return totalInserted;
+        }
+        catch (err) {
+            // On failure, DO NOT re-queue — access logs are telemetry,
+            // not critical data. Losing a flush window is acceptable.
+            debugLog(`[AccessLogBuffer] Flush failed (partial loss): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            return totalInserted;
+        }
+    }
+    /**
+     * Graceful shutdown: clear the timer and flush any remaining events.
+     * Called from SqliteStorage.close().
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Final flush to drain any remaining events
+        await this.flush();
+        debugLog("[AccessLogBuffer] Disposed");
+    }
+    /**
+     * Returns the number of events currently buffered (for observability).
+     */
+    get pendingCount() {
+        return this.buffer.length;
+    }
+}

package/dist/utils/actrActivation.js

@@ -0,0 +1,197 @@
+/**
+ * ACT-R Activation Engine — v7.0 Cognitive Memory
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PURPOSE:
+ *   Implements the ACT-R (Adaptive Control of Thought—Rational) memory
+ *   activation model for production-grade retrieval ranking.
+ *
+ * PAPER BASIS:
+ *   "Human-Like Remembering and Forgetting in LLM Agents:
+ *    An ACT-R Integration" (ACM, 2025)
+ *
+ * KEY EQUATIONS:
+ *   Base-Level Activation:  B_i = ln(Σ t_j^(-d))
+ *   Spreading Activation:   S_i = Σ(W × link.strength) for links ∈ candidateSet
+ *   Composite Score:         Score = w_sim × sim + w_act × σ(B_i + S_i)
+ *
+ * PRODUCTION HARDENING:
+ *   - Rule #3: Creation = Access (zero-access memories handled gracefully)
+ *   - Rule #4: Time clamp t ≥ 1.0s prevents Infinity/NaN
+ *   - Rule #5: Candidate-scoped spreading prevents God node centrality
+ *   - Parameterized sigmoid for proper activation discrimination
+ *
+ * DESIGN:
+ *   All functions are PURE — zero side effects, zero I/O, zero imports
+ *   from storage. State (timestamps, links) is passed in as arguments.
+ *   This makes the module fully testable with no mocking.
+ *
+ * FILES THAT IMPORT THIS:
+ *   - src/utils/cognitiveMemory.ts (computeEffectiveImportance)
+ *   - src/tools/graphHandlers.ts (search re-ranking pipeline)
+ * ═══════════════════════════════════════════════════════════════════
+ */
+// ─── Constants ────────────────────────────────────────────────
+/** ACT-R standard decay parameter. Higher = faster forgetting. */
+export const ACT_R_DEFAULT_DECAY = 0.5;
+/** Hard floor for activation when no access history exists. */
+export const ACTIVATION_FLOOR = -10.0;
+/**
+ * Minimum time delta in seconds. Prevents division by zero
+ * when a memory was accessed in the same second (or subsecond).
+ * Rule #4: Hard clamp t_j ≥ 1.0s.
+ */
+export const MIN_TIME_DELTA_SECONDS = 1.0;
+/** Default parameterized sigmoid midpoint. */
+export const DEFAULT_SIGMOID_MIDPOINT = -2.0;
+/** Default parameterized sigmoid steepness. */
+export const DEFAULT_SIGMOID_STEEPNESS = 1.0;
+/** Default similarity weight in composite score. */
+export const DEFAULT_WEIGHT_SIMILARITY = 0.7;
+/** Default activation weight in composite score. */
+export const DEFAULT_WEIGHT_ACTIVATION = 0.3;
+// ─── Base-Level Activation ────────────────────────────────────
+/**
+ * Computes ACT-R base-level activation for a memory item.
+ *
+ * B_i = ln(Σ t_j^(-d))
+ *
+ * Where:
+ *   t_j = max(1.0, seconds since j-th access)  ← CLAMPED (Rule #4)
+ *   d   = decay parameter (0.5 per ACT-R standard)
+ *
+ * Interpretation:
+ *   - More recent accesses → larger t^(-d) → higher B_i
+ *   - More total accesses  → more terms in sum → higher B_i
+ *   - Very old accesses    → t^(-d) ≈ 0 → negligible contribution
+ *
+ * Edge cases:
+ *   - Zero accesses → ACTIVATION_FLOOR (-10.0)
+ *   - Single access just now → ln(1^-0.5) = ln(1) = 0.0 (neutral)
+ *   - Sub-second timestamps → clamped to 1.0s (prevents Infinity)
+ *   - Negative time delta (clock skew) → clamped to 1.0s
+ *
+ * @param accessTimestamps - Array of Date objects, one per access event
+ * @param now - Current time reference (injected for testability)
+ * @param decayRate - ACT-R decay parameter d (default: 0.5)
+ * @returns Base-level activation value (typically -10 to +5 range)
+ */
+export function baseLevelActivation(accessTimestamps, now, decayRate = ACT_R_DEFAULT_DECAY) {
+    if (accessTimestamps.length === 0) {
+        return ACTIVATION_FLOOR;
+    }
+    const nowMs = now.getTime();
+    let sum = 0;
+    for (const ts of accessTimestamps) {
+        // Seconds since this access occurred
+        const deltaMs = nowMs - ts.getTime();
+        const deltaSec = Math.max(MIN_TIME_DELTA_SECONDS, deltaMs / 1000);
+        // t_j^(-d)  — each access contributes to the sum
+        sum += Math.pow(deltaSec, -decayRate);
+    }
+    // Guard against sum=0 (shouldn't happen with clamped t, but be safe)
+    if (sum <= 0) {
+        return ACTIVATION_FLOOR;
+    }
+    return Math.log(sum);
+}
+// ─── Candidate-Scoped Spreading Activation ────────────────────
+/**
+ * Computes spreading activation scoped to the current search result set.
+ *
+ * S_i = Σ(W × link.strength) for links where target_id ∈ candidateIds
+ *
+ * CRITICAL DESIGN (Rule #5: No God Nodes):
+ *   Only counts links pointing to OTHER entries in the current search
+ *   result set. A memory connected to 1000 random entries but only
+ *   2 search results gets S_i based on those 2 only.
+ *
+ *   This prevents "hub" memories from dominating rankings just
+ *   because they have high degree centrality.
+ *
+ * W = 1 / |candidateIds| (uniform attention weight across candidates)
+ *
+ * @param outboundLinks - All outbound links from this memory entry
+ * @param candidateIds - Set of entry IDs in the current search result set
+ * @returns Spreading activation value (0 to ~1.0 range)
+ */
+export function candidateScopedSpreadingActivation(outboundLinks, candidateIds) {
+    if (candidateIds.size === 0 || outboundLinks.length === 0) {
+        return 0;
+    }
+    // Filter to only links pointing to other search results
+    const relevantLinks = outboundLinks.filter(l => candidateIds.has(l.target_id));
+    if (relevantLinks.length === 0) {
+        return 0;
+    }
+    // Uniform attention weight across all candidates
+    const W = 1 / candidateIds.size;
+    return relevantLinks.reduce((sum, link) => sum + W * link.strength, 0);
+}
+// ─── Parameterized Sigmoid ────────────────────────────────────
+/**
+ * Parameterized sigmoid normalization.
+ *
+ * σ(x) = 1 / (1 + e^(-k(x - x₀)))
+ *
+ * WHY NOT STANDARD SIGMOID?
+ *   Standard sigmoid σ(x) = 1/(1+e^(-x)) is centered at 0. But ACT-R
+ *   base-level activations naturally cluster in the -7 to +3 range.
+ *   A naive sigmoid would compress most values near 0.01-0.11, making
+ *   the activation weight irrelevant.
+ *
+ * CALIBRATED DEFAULTS (from ACT-R activation distribution):
+ *   x₀ = -2.0 (midpoint: activation of -2 maps to 0.5)
+ *   k  = 1.0  (steepness)
+ *
+ * Resulting discrimination:
+ *   B = -10 → σ ≈ 0.0003 (dead memory, near-zero boost)
+ *   B = -5  → σ ≈ 0.047  (cold memory, minimal boost)
+ *   B = -2  → σ = 0.50   (moderate, midpoint)
+ *   B =  0  → σ ≈ 0.88   (fresh memory, strong boost)
+ *   B = +3  → σ ≈ 0.99   (hot memory, maximum boost)
+ *
+ * @param x - Raw activation value (B_i + S_i)
+ * @param midpoint - Activation value that maps to 0.5 (default: -2.0)
+ * @param steepness - How sharply the curve rises (default: 1.0)
+ * @returns Normalized activation in (0, 1)
+ */
+export function parameterizedSigmoid(x, midpoint = DEFAULT_SIGMOID_MIDPOINT, steepness = DEFAULT_SIGMOID_STEEPNESS) {
+    // Guard against NaN/Infinity inputs
+    if (!Number.isFinite(x)) {
+        return x > 0 ? 1.0 : 0.0;
+    }
+    const exponent = -steepness * (x - midpoint);
+    // Prevent overflow: if exponent is very large, sigmoid ≈ 0
+    // If exponent is very negative, sigmoid ≈ 1
+    if (exponent > 500)
+        return 0;
+    if (exponent < -500)
+        return 1;
+    return 1 / (1 + Math.exp(exponent));
+}
+// ─── Composite Retrieval Score ────────────────────────────────
+/**
+ * Computes the final retrieval ranking score combining similarity
+ * and ACT-R activation.
+ *
+ * Score = w_sim × similarity + w_act × σ(activation)
+ *
+ * The parameterized sigmoid normalizes activation from (-∞, +∞)
+ * to (0, 1) so the two components are on comparable scales.
+ *
+ * Default weights: w_sim = 0.7, w_act = 0.3
+ * (Similarity dominates — activation is a re-ranking boost, not a replacement)
+ *
+ * @param similarity - Cosine similarity score from vector search (0 to 1)
+ * @param activation - Raw ACT-R activation (B_i + S_i, pre-sigmoid)
+ * @param weightSimilarity - Weight for similarity component (default: 0.7)
+ * @param weightActivation - Weight for activation component (default: 0.3)
+ * @param sigmoidMidpoint - Sigmoid midpoint (default: -2.0)
+ * @param sigmoidSteepness - Sigmoid steepness (default: 1.0)
+ * @returns Composite score (higher = better retrieval candidate)
+ */
+export function compositeRetrievalScore(similarity, activation, weightSimilarity = DEFAULT_WEIGHT_SIMILARITY, weightActivation = DEFAULT_WEIGHT_ACTIVATION, sigmoidMidpoint = DEFAULT_SIGMOID_MIDPOINT, sigmoidSteepness = DEFAULT_SIGMOID_STEEPNESS) {
+    const normalizedActivation = parameterizedSigmoid(activation, sigmoidMidpoint, sigmoidSteepness);
+    return weightSimilarity * similarity + weightActivation * normalizedActivation;
+}