prism-mcp-server 6.5.2 → 7.0.0

package/README.md

@@ -24,6 +24,7 @@ Works with **Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gem
 - [Quick Start](#-quick-start)
 - [The Magic Moment](#-the-magic-moment)
 - [Setup Guides](#-setup-guides)
+- [Universal Import](#-universal-import-bring-your-history)
 - [What Makes Prism Different](#-what-makes-prism-different)
 - [Use Cases](#-use-cases)
 - [What's New](#-whats-new)
@@ -43,6 +44,10 @@ Every time you start a new conversation with an AI coding assistant, it starts f
 
 **Prism gives your agent a brain that persists.** Save what matters at the end of each session. Load it back instantly on the next one. Your agent remembers what it did, what it learned, and what's left to do.
 
+> 📌 **Terminology:** Throughout this doc, **"Prism"** refers to the MCP server and storage engine. **"Mind Palace"** refers to the visual dashboard UI at `localhost:3000` — your window into the agent's brain. They work together; the dashboard is optional.
+
+**Starting in v7.0**, Prism doesn't just *store* memories — it **ranks them like a human brain.** The ACT-R activation model (from cognitive science) means memories that were accessed recently and frequently surface first, while stale context fades naturally. Combine that with candidate-scoped spreading activation and you get retrieval quality that no flat vector search can match.
+
 ---
 
 ## 🚀 Quick Start
@@ -63,7 +68,28 @@ Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`,
 
 > **Note on Windows/Restricted Shells:** If your MCP client complains that `npx` is not found, use the absolute path to your node binary (e.g. `C:\Program Files\nodejs\npx.cmd`) or install globally with caution.
 
-**That's it.** Restart your client. All tools are available. Dashboard at `http://localhost:3000`. *(Note: The MCP server automatically starts this UI on port 3000 when connected. If you have a Next.js/React app running, port 3000 might already be in use.)*
+**That's it.** Restart your client. All tools are available. The **Mind Palace Dashboard** (the visual UI for your agent's brain) starts automatically at `http://localhost:3000`. You don't need to keep a tab open — the dashboard runs in the background and the MCP tools work with or without it.
+
+<details>
+<summary>Port 3000 already in use? (Next.js / Vite / etc.)</summary>
+
+Add `PRISM_DASHBOARD_PORT` to your MCP config env block:
+
+```json
+{
+  "mcpServers": {
+    "prism-mcp": {
+      "command": "npx",
+      "args": ["-y", "prism-mcp-server"],
+      "env": { "PRISM_DASHBOARD_PORT": "3001" }
+    }
+  }
+}
+```
+
+Then open `http://localhost:3001` instead.
+</details>
+
 
 ### Capability Matrix
 
@@ -77,7 +103,7 @@ Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`,
 | Semantic vector search | ❌ | ✅ `GOOGLE_API_KEY` |
 | Morning Briefings | ❌ | ✅ `GOOGLE_API_KEY` |
 | Auto-compaction | ❌ | ✅ `GOOGLE_API_KEY` |
-| Web Scholar research | ❌ | ✅ `BRAVE_API_KEY` + `FIRECRAWL_API_KEY` (or `TAVILY_API_KEY`) |
+| Web Scholar research | ❌ | ✅ [`BRAVE_API_KEY`](#environment-variables) + [`FIRECRAWL_API_KEY`](#environment-variables) (or `TAVILY_API_KEY`) |
 | VLM image captioning | ❌ | ✅ Provider key |
 
 > 🔑 The core Mind Palace works **100% offline** with zero API keys. Cloud keys unlock intelligence features. See [Environment Variables](#environment-variables).
@@ -183,39 +209,6 @@ Add to your Continue `config.json` or Cline MCP settings:
 
 </details>
 
-### Migration
-
-<details>
-<summary><strong>Migrating Existing History (Claude, Gemini, OpenAI)</strong></summary>
-
-Prism can ingest months of historical sessions from other tools to give your Mind Palace a massive head start. Import via the **CLI** or directly from the [Mind Palace Dashboard](#-mind-palace-dashboard) Import tab (file picker + manual path + dry-run toggle).
-
-#### Supported Formats
-* **Claude Code** (`.jsonl` logs) — Automatically handles streaming chunk deduplication and `requestId` normalization.
-* **Gemini** (JSON history arrays) — Supports large-file streaming for 100MB+ exports.
-* **OpenAI** (JSON chat completion history) — Normalizes disparate tool-call structures into the unified Ledger schema.
-
-#### How to Run
-
-**Option 1 — CLI:**
-
-```bash
-# Ingest Claude Code history
-npx -y prism-mcp-server universal-import --format claude --path ~/path/to/claude_log.jsonl --project my-project
-
-# Dry run (verify mapping without saving)
-npx -y prism-mcp-server universal-import --format gemini --path ./gemini_history.json --dry-run
-```
-
-**Option 2 — Dashboard:** Open `localhost:3000`, navigate to the **Import** tab, select the format and file, and click Import. Supports dry-run preview. See the [dashboard screenshot](#-mind-palace-dashboard) above.
-
-#### Key Features
-* **OOM-Safe Streaming:** Processes massive log files line-by-line using `stream-json`.
-* **Idempotent Dedup:** Content-hash prevents duplicate imports on re-run (`skipCount` reported).
-* **Chronological Integrity:** Uses timestamp fallbacks and `requestId` sorting to ensure your memory timeline is accurate.
-* **Smart Context Mapping:** Extracts `cwd`, `gitBranch`, and tool usage patterns into searchable metadata.
-
-</details>
 
 <details>
 <summary><strong>Claude Code — Lifecycle Autoload (.clauderules)</strong></summary>
@@ -329,6 +322,39 @@ Then add to your MCP config:
 
 ---
 
+## 📥 Universal Import — Bring Your History
+
+Switching to Prism? Don't leave months of AI session history behind. Prism can **ingest historical sessions from Claude Code, Gemini, and OpenAI** and give your Mind Palace an instant head start — no manual re-entry required.
+
+Import via the **CLI** or directly from the Mind Palace Dashboard (**Import** tab → file picker + dry-run toggle).
+
+### Supported Formats
+* **Claude Code** (`.jsonl` logs) — Automatically handles streaming chunk deduplication and `requestId` normalization.
+* **Gemini** (JSON history arrays) — Supports large-file streaming for 100MB+ exports.
+* **OpenAI** (JSON chat completion history) — Normalizes disparate tool-call structures into the unified Ledger schema.
+
+### How to Import
+
+**Option 1 — CLI:**
+
+```bash
+# Ingest Claude Code history
+npx -y prism-mcp-server universal-import --format claude --path ~/path/to/claude_log.jsonl --project my-project
+
+# Dry run (verify mapping without saving)
+npx -y prism-mcp-server universal-import --format gemini --path ./gemini_history.json --dry-run
+```
+
+**Option 2 — Dashboard:** Open `localhost:3000`, navigate to the **Import** tab, select the format and file, and click Import. Supports dry-run preview.
+
+### Why It's Safe to Re-Run
+* **OOM-Safe Streaming:** Processes massive log files line-by-line using `stream-json`.
+* **Idempotent Dedup:** Content-hash prevents duplicate imports on re-run (`skipCount` reported).
+* **Chronological Integrity:** Uses timestamp fallbacks and `requestId` sorting to preserve your memory timeline.
+* **Smart Context Mapping:** Extracts `cwd`, `gitBranch`, and tool usage patterns into searchable metadata.
+
+---
+
 ## ✨ What Makes Prism Different
 
 
@@ -357,7 +383,7 @@ A gorgeous glassmorphism UI at `localhost:3000` that lets you see exactly what y
 Powered by a pure TypeScript port of Google's TurboQuant (inspired by Google's ICLR research), Prism compresses 768-dim embeddings from **3,072 bytes → ~400 bytes** — enabling decades of session history on a standard laptop. No native modules. No vector database required.
 
 ### 🐝 Multi-Agent Hivemind
-Multiple agents (dev, QA, PM) can work on the same project with **role-isolated memory**. Agents discover each other automatically, share context in real-time via Telepathy sync, and see a team roster during context loading.
+Multiple agents (dev, QA, PM) can work on the same project with **role-isolated memory**. Agents discover each other automatically, share context in real-time via Telepathy sync, and see a team roster during context loading. → [Multi-agent setup example](examples/multi-agent-hivemind/)
 
 ### 🖼️ Visual Memory
 Save UI screenshots, architecture diagrams, and bug states to a searchable vault. Images are auto-captioned by a VLM (Claude Vision / GPT-4V / Gemini) and become semantically searchable across sessions.
@@ -391,16 +417,78 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 
 **Morning Briefings** — After 4+ hours away, Prism auto-synthesizes a 3-bullet action plan from your last sessions.
 
+### Claude Code: Parallel Explore Agent Workflows
+
+When you need to quickly map a large auth system, launch multiple `Explore` subagents in parallel and merge their findings:
+
+```text
+Run 3 Explore agents in parallel.
+1) Map auth architecture
+2) List auth API endpoints
+3) Find auth test coverage gaps
+Research only, no code changes.
+Return a merged summary.
+```
+
+Then continue a specific thread with a follow-up message to the selected agent, such as deeper refresh-token edge-case analysis.
+
 ---
 
 ## 🆕 What's New
 
+### v7.0.0 — ACT-R Activation Memory ✅
+> **Current stable release.** Memory retrieval now uses a scientifically-grounded cognitive model.
+
+- 🧠 **ACT-R Base-Level Activation** — `B_i = ln(Σ t_j^(-d))` computes recency × frequency activation per memory. Recent, frequently-accessed memories surface first; cold memories fade to near-zero. Based on Anderson's *Adaptive Control of Thought—Rational* (ACM, 2025).
+- 🔗 **Candidate-Scoped Spreading Activation** — `S_i = Σ(W × strength)` for links within the current search result set only. Prevents "God node" centrality from dominating rankings (Rule #5).
+- 📐 **Parameterized Sigmoid Normalization** — Calibrated `σ(x) = 1/(1 + e^(-k(x - x₀)))` with midpoint at -2.0 maps the natural ACT-R activation range (-10 to +5) into discriminating (0, 1) scores.
+- 🏗️ **Composite Retrieval Scoring** — `Score = 0.7 × similarity + 0.3 × σ(activation)` — similarity dominates, activation re-ranks. Fully configurable weights via `PRISM_ACTR_WEIGHT_*` env vars.
+- ⚡ **AccessLogBuffer** — In-memory write buffer with 5-second batch flush prevents SQLite `SQLITE_BUSY` contention under parallel agent tool calls. Deduplicates within flush windows.
+- 🗂️ **Access Log Infrastructure** — New `memory_access_log` table with `logAccess()`, `getAccessLog()`, `pruneAccessLog()` across both SQLite and Supabase backends. Creation seeds initial access (zero cold-start penalty).
+- 🧹 **Background Access Log Pruning** — Scheduler automatically prunes access logs exceeding retention window (default: 90 days). Configurable via `PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS`.
+- 🧪 **49-Test ACT-R Suite** — Pure-function unit tests covering base-level activation, spreading activation, sigmoid normalization, composite scoring, AccessLogBuffer lifecycle, deduplication, chunking, and edge cases.
+- 📊 **705 Tests** — 32 suites, all passing, zero regressions.
+
+<details>
+<summary><strong>🔬 Live Example: v6.5 vs v7.0 Retrieval Behavior</strong></summary>
+
+Consider an agent searching for "OAuth migration" with 3 memories in the result set:
+
+| Memory | Cosine Similarity | Last Accessed | Access Count (30d) |
+|--------|:-:|:-:|:-:|
+| A: "PKCE flow decision" | 0.82 | 2 hours ago | 12× |
+| B: "OAuth library comparison" | 0.85 | 14 days ago | 2× |
+| C: "Auth middleware refactor" | 0.81 | 30 minutes ago | 8× |
+
+**v6.5 (pure similarity):** B > A > C — the stale library comparison wins because it has the highest cosine score, even though the agent hasn't looked at it in two weeks.
+
+**v7.0 (ACT-R re-ranking):**
+
+| Memory | Similarity (0.7×) | ACT-R σ(B+S) (0.3×) | **Composite** |
+|--------|:-:|:-:|:-:|
+| A | 0.574 | 0.3 × 0.94 = 0.282 | **0.856** |
+| C | 0.567 | 0.3 × 0.91 = 0.273 | **0.840** |
+| B | 0.595 | 0.3 × 0.12 = 0.036 | **0.631** |
+
+**Result:** The actively-used PKCE decision (A) and the just-touched middleware (C) surface above the stale comparison (B). The agent gets the context it's *actually working with*, not just the closest embedding.
+
+</details>
+
+### v6.5.3 — Auth Hardening ✅
+- 🔒 **Rate Limiting** — Login endpoint (`POST /api/auth/login`) protected by sliding-window rate limiter (5 attempts per 60s per IP). Resets on success.
+- 🔒 **CORS Hardening** — Dynamic `Origin` echo with `Allow-Credentials` when auth enabled (replaces wildcard `*`).
+- 🚪 **Logout Endpoint** — `POST /api/auth/logout` invalidates session server-side and clears client cookie.
+- 🧪 **42-Test Auth Suite** — Unit + HTTP integration tests covering `safeCompare`, `generateToken`, `isAuthenticated`, `createRateLimiter`, login/logout lifecycle, rate limiting, and CORS.
+- 🏗️ **Auth Module Extraction** — Decoupled auth logic from `server.ts` closures into testable `authUtils.ts`.
+
+### v6.5.2 — SDM/HDC Test Hardening ✅
+- 🧪 **37 New Edge-Case Tests** — Hardened the cognitive routing pipeline (HDC engine, PolicyGateway, StateMachine, SDM engine) with boundary condition tests. 571 → 608 total tests.
+
 ### v6.5.1 — Dashboard Project-Load Hotfix ✅
 - 🩹 **Project Selector Recovery** — Fixed a startup path where the dashboard selector could stay stuck on "Loading projects..." when Supabase env vars were unresolved placeholders.
 - 🔄 **Safe Backend Fallback** — If Supabase is requested but env is invalid/unresolved, Prism now auto-falls back to local SQLite so `/api/projects` and dashboard boot remain operational.
 
 ### v6.5 — HDC Cognitive Routing ✅
-> **Current stable release.** The Mind Palace gains a brain-inspired routing engine.
 
 - 🧠 **Hyperdimensional Cognitive Routing** — New `session_cognitive_route` tool composes the agent's current state, role, and action into a single 768-dim binary hypervector via XOR binding, then resolves it to a semantic concept via Hamming distance. Three-outcome policy gateway: `direct` / `clarify` / `fallback`.
 - 🎛️ **Per-Project Threshold Overrides** — Fallback and clarify thresholds are configurable per-project and persisted via the existing `getSetting`/`setSetting` contract (no new migrations).
@@ -472,7 +560,7 @@ Standard memory servers (like Mem0, Zep, or the baseline Anthropic MCP) act as p
 | **Primary Interface** | **Native MCP** (Tools, Prompts, Resources) | REST API & Python/TS SDKs | REST API & Python/TS SDKs | Native MCP (Tools only) |
 | **Storage Engine** | **BYO SQLite or Supabase** | Managed Cloud / VectorDBs | Managed Cloud / Postgres | Local SQLite only |
 | **Context Assembly** | **Progressive (Quick/Std/Deep)** | Top-K Semantic Search | Top-K + Temporal Summaries | Basic Entity Search |
-| **Memory Mechanics** | **Ebbinghaus Decay, SDM, HDC** | Basic Vector + Entity | Fading Temporal Graph | None (Infinite growth) |
+| **Memory Mechanics** | **ACT-R Activation (recency×freq), SDM, HDC** | Basic Vector + Entity | Fading Temporal Graph | None (Infinite growth) |
 | **Multi-Agent Sync** | **CRDT (Add-Wins / LWW)** | Cloud locks | Postgres locks | ❌ None (Data races) |
 | **Data Compression** | **TurboQuant (7x smaller vectors)** | ❌ Standard F32 Vectors | ❌ Standard Vectors | ❌ No Vectors |
 | **Observability** | **OTel Traces + Built-in PWA UI** | Cloud Dashboard | Cloud Dashboard | ❌ None |
@@ -486,7 +574,7 @@ Standard memory servers (like Mem0, Zep, or the baseline Anthropic MCP) act as p
 Mem0 and Zep are APIs that *can* be wrapped into an MCP server. Prism was built *for* MCP from day one. Instead of wasting tokens on "search" tool calls, Prism uses **MCP Prompts** (`/resume_session`) to inject context *before* the LLM thinks, and **MCP Resources** (`memory://project/handoff`) to attach live, subscribing context.
 
 #### 2. Academic-Grade Cognitive Computer Science
-The giants use standard RAG (Retrieval-Augmented Generation). Prism uses biological and academic models of memory: **TurboQuant** for extreme vector compression, **Ebbinghaus curves** for importance decay, and **Sparse Distributed Memory (SDM)**. This makes Prism vastly more efficient on a local machine than running a giant Postgres/pgvector instance.
+The giants use standard RAG (Retrieval-Augmented Generation). Prism uses biological and academic models of memory: **ACT-R base-level activation** (`B_i = ln(Σ t_j^(-d))`) for recency–frequency re-ranking, **TurboQuant** for extreme vector compression, **Ebbinghaus curves** for importance decay, and **Sparse Distributed Memory (SDM)**. The result is retrieval quality that follows how human memory actually works — not just nearest-neighbor cosine distance. And all of it runs on a laptop without a Postgres/pgvector instance.
 
 #### 3. True Multi-Agent Coordination (CRDTs)
 If Cursor (Agent A) and Claude Desktop (Agent B) try to update a Mem0 or standard SQLite database at the exact same time, you get a race condition and data loss. Prism uses **Optimistic Concurrency Control (OCC) with CRDT OR-Maps** — mathematically guaranteeing that simultaneous agent edits merge safely. Enterprise-grade distributed systems on a local machine.
@@ -609,6 +697,14 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 
 ## Environment Variables
 
+> **🚦 TL;DR — Just want the best experience fast?** Set these three keys and you're done:
+> ```
+> GOOGLE_API_KEY=...      # Unlocks: semantic search, Morning Briefings, auto-compaction
+> BRAVE_API_KEY=...       # Unlocks: Web Scholar research + Brave Answers
+> FIRECRAWL_API_KEY=...   # Unlocks: Web Scholar deep scraping (or use TAVILY_API_KEY instead)
+> ```
+> **Zero keys = zero problem.** Core session memory, keyword search, time travel, and the full dashboard work 100% offline. Cloud keys are optional power-ups.
+
 <details>
 <summary><strong>Full variable reference</strong></summary>
 
@@ -637,6 +733,11 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN` | No | Max articles per Scholar run (default: `3`) |
 | `PRISM_HDC_ENABLED` | No | `"true"` (default) to enable HDC cognitive routing pipeline |
 | `PRISM_HDC_EXPLAINABILITY_ENABLED` | No | `"true"` (default) to include convergence/distance/ambiguity in cognitive route responses |
+| `PRISM_ACTR_ENABLED` | No | `"true"` (default) to enable ACT-R activation re-ranking on semantic search |
+| `PRISM_ACTR_DECAY` | No | ACT-R decay parameter `d` (default: `0.5`). Higher values = faster recency drop-off |
+| `PRISM_ACTR_WEIGHT_SIMILARITY` | No | Composite score similarity weight (default: `0.7`) |
+| `PRISM_ACTR_WEIGHT_ACTIVATION` | No | Composite score ACT-R activation weight (default: `0.3`) |
+| `PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS` | No | Days before access logs are pruned by background scheduler (default: `90`) |
 
 </details>
 
@@ -726,6 +827,10 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 | **v6.1** | Prism-Port Vault Export — Obsidian/Logseq `.zip` with YAML frontmatter & `[[Wikilinks]]` | Data sovereignty, PKM interop | ✅ Shipped |
 | **v6.1** | Cognitive Load & Semantic Search — dynamic graph thinning, search highlights | Contextual working memory | ✅ Shipped |
 | **v6.2** | Synthesize & Prune — automated edge synthesis, graph pruning, SLO observability | Implicit associative memory | ✅ Shipped |
+| **v7.0** | ACT-R Base-Level Activation — `B_i = ln(Σ t_j^(-d))` recency×frequency re-ranking over similarity candidates | Anderson's ACT-R (Adaptive Control of Thought—Rational, ACM 2025) | ✅ Shipped |
+| **v7.0** | Candidate-Scoped Spreading Activation — `S_i = Σ(W × strength)` bounded to search result set; prevents God-node dominance | Spreading activation networks (Collins & Loftus, 1975) | ✅ Shipped |
+| **v7.0** | Composite Retrieval Scoring — `0.7 × similarity + 0.3 × σ(activation)`; configurable via `PRISM_ACTR_WEIGHT_*` | Hybrid cognitive-neural retrieval models | ✅ Shipped |
+| **v7.0** | AccessLogBuffer — in-memory batch-write buffer with 5s flush; prevents SQLite `SQLITE_BUSY` under parallel agents | Production reliability engineering | ✅ Shipped |
 | **v7.x** | Affect-Tagged Memory — sentiment shapes what gets recalled | Affect-modulated retrieval (neuroscience) | 🔭 Horizon |
 | **v8+** | Zero-Search Retrieval — no index, no ANN, just ask the vector | Holographic Reduced Representations | 🔭 Horizon |
 
@@ -740,10 +845,13 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 ### v6.2: The "Synthesize & Prune" Phase ✅
 Shipped in v6.2.0. Edge synthesis, graph pruning with SLO observability, temporal decay heatmaps, active recall prompt generation, and full dashboard metrics integration.
 
-### v6.5: Cognitive Architecture (Primary)
-Full Superposed Memory (SDM) + Hyperdimensional Computing (HDC/VSA) becomes the next major implementation phase, targeting compositional memory states and faster associative retrieval at scale.
+### v6.5: Cognitive Architecture ✅
+Shipped. Full Superposed Memory (SDM) + Hyperdimensional Computing (HDC/VSA) cognitive routing pipeline. Compositional memory states via XOR binding, Hamming resolution, and policy-gated routing (direct / clarify / fallback). 705 tests passing.
+
+### v7.0: ACT-R Activation Memory ✅
+Shipped. Scientifically-grounded retrieval re-ranking via ACT-R base-level activation (`B_i = ln(Σ t_j^(-d))`), candidate-scoped spreading activation, parameterized sigmoid normalization, composite scoring, and zero-cold-start access log infrastructure. 49 dedicated unit tests, 705 total passing.
 
-### After v6.5: Future Tracks
+### Future Tracks
 - **v7.x: Affect-Tagged Memory** — Recall prioritization improves by weighting memories with affective/contextual valence, making surfaced context more behaviorally useful.
 - **v8+: Zero-Search Retrieval** — Direct vector-addressed recall (“just ask the vector”) reduces retrieval indirection and moves Prism toward truly native associative memory.
 

package/dist/backgroundScheduler.js

@@ -17,7 +17,7 @@
  * storage backends during maintenance windows.
  */
 import { getStorage } from "./storage/index.js";
-import { PRISM_USER_ID, PRISM_SCHOLAR_ENABLED, PRISM_SCHOLAR_INTERVAL_MS, PRISM_GRAPH_PRUNING_ENABLED, PRISM_GRAPH_PRUNE_MIN_STRENGTH, PRISM_GRAPH_PRUNE_PROJECT_COOLDOWN_MS, PRISM_GRAPH_PRUNE_SWEEP_BUDGET_MS, PRISM_GRAPH_PRUNE_MAX_PROJECTS_PER_SWEEP, } from "./config.js";
+import { PRISM_USER_ID, PRISM_SCHOLAR_ENABLED, PRISM_SCHOLAR_INTERVAL_MS, PRISM_GRAPH_PRUNING_ENABLED, PRISM_GRAPH_PRUNE_MIN_STRENGTH, PRISM_GRAPH_PRUNE_PROJECT_COOLDOWN_MS, PRISM_GRAPH_PRUNE_SWEEP_BUDGET_MS, PRISM_GRAPH_PRUNE_MAX_PROJECTS_PER_SWEEP, PRISM_ACTR_ENABLED, PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS, } from "./config.js";
 import { debugLog } from "./utils/logger.js";
 import { runWebScholar } from "./scholar/webScholar.js";
 import { getAllActiveSdmProjects, getSdmEngine } from "./sdm/sdmEngine.js";
@@ -100,6 +100,8 @@ export const DEFAULT_SCHEDULER_CONFIG = {
     graphPruneProjectCooldownMs: PRISM_GRAPH_PRUNE_PROJECT_COOLDOWN_MS,
     graphPruneSweepBudgetMs: PRISM_GRAPH_PRUNE_SWEEP_BUDGET_MS,
     graphPruneMaxProjectsPerSweep: PRISM_GRAPH_PRUNE_MAX_PROJECTS_PER_SWEEP,
+    enableAccessLogPrune: PRISM_ACTR_ENABLED,
+    accessLogRetentionDays: PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS,
 };
 // ─── Scheduler State ─────────────────────────────────────────
 let schedulerInterval = null;
@@ -147,6 +149,7 @@ export function startScheduler(config) {
         cfg.enableSdmFlush && "SdmFlush",
         cfg.enableEdgeSynthesis && "EdgeSynthesis",
         cfg.enableGraphPruning && "GraphPruning",
+        cfg.enableAccessLogPrune && "AccessLogPrune",
     ].filter(Boolean).join(", ");
     console.error(`[Scheduler] ⏰ Started (interval=${formatDuration(cfg.intervalMs)}, tasks=[${enabledTasks}])`);
     return () => {
@@ -249,6 +252,7 @@ export async function runSchedulerSweep(cfg = DEFAULT_SCHEDULER_CONFIG) {
                 durationMs: 0,
                 minStrength: cfg.graphPruneMinStrength,
             },
+            accessLogPrune: { ran: false, deleted: 0 },
         },
     };
     debugLog("[Scheduler] 🔄 Sweep starting...");
@@ -612,6 +616,24 @@ export async function runSchedulerSweep(cfg = DEFAULT_SCHEDULER_CONFIG) {
                 // Non-critical — don't let metrics failure break the scheduler
             }
         }
+        // ── Task 9: ACT-R Access Log Prune (v7.0) ──────────────────
+        // Removes stale rows from memory_access_log older than the
+        // configured retention window (default: 90 days). Prevents
+        // unbounded table growth from the ACT-R frequency tracking.
+        if (cfg.enableAccessLogPrune) {
+            try {
+                result.tasks.accessLogPrune.ran = true;
+                const deleted = await storage.pruneAccessLog(cfg.accessLogRetentionDays);
+                result.tasks.accessLogPrune.deleted = deleted;
+                if (deleted > 0) {
+                    debugLog(`[Scheduler] Access log prune: deleted ${deleted} stale entries (>${cfg.accessLogRetentionDays}d)`);
+                }
+            }
+            catch (err) {
+                result.tasks.accessLogPrune.error = err instanceof Error ? err.message : String(err);
+                debugLog(`[Scheduler] Access log prune error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
     }
     finally {
         clearInterval(heartbeatInterval);
@@ -657,6 +679,9 @@ export async function runSchedulerSweep(cfg = DEFAULT_SCHEDULER_CONFIG) {
     if (result.tasks.edgeSynthesis.ran && result.tasks.edgeSynthesis.projectsSynthesized > 0) {
         parts.push(`Synthesis:${result.tasks.edgeSynthesis.newLinks} links in ${result.tasks.edgeSynthesis.projectsSynthesized} projects`);
     }
+    if (result.tasks.accessLogPrune.ran && result.tasks.accessLogPrune.deleted > 0) {
+        parts.push(`AccessLog:${result.tasks.accessLogPrune.deleted} stale entries pruned`);
+    }
     const summaryLine = parts.length > 0
         ? parts.join(" | ")
         : "no maintenance actions needed";

package/dist/config.js

@@ -209,3 +209,25 @@ export const PRISM_GRAPH_PRUNE_MIN_STRENGTH = parseFloat(process.env.PRISM_GRAPH
 export const PRISM_GRAPH_PRUNE_PROJECT_COOLDOWN_MS = parseInt(process.env.PRISM_GRAPH_PRUNE_PROJECT_COOLDOWN_MS || "600000", 10);
 export const PRISM_GRAPH_PRUNE_SWEEP_BUDGET_MS = parseInt(process.env.PRISM_GRAPH_PRUNE_SWEEP_BUDGET_MS || "30000", 10);
 export const PRISM_GRAPH_PRUNE_MAX_PROJECTS_PER_SWEEP = parseInt(process.env.PRISM_GRAPH_PRUNE_MAX_PROJECTS_PER_SWEEP || "25", 10);
+// ─── v7.0: ACT-R Cognitive Memory Activation ────────────────
+// Scientifically-grounded retrieval re-ranking based on the ACT-R
+// cognitive architecture. Replaces simple Ebbinghaus decay with
+// a composite similarity + activation model.
+/** Master switch for ACT-R activation-based re-ranking. */
+export const PRISM_ACTR_ENABLED = process.env.PRISM_ACTR_ENABLED === "true";
+/** ACT-R decay parameter d in t^(-d). Higher = faster forgetting. (Paper default: 0.5) */
+export const PRISM_ACTR_DECAY = parseFloat(process.env.PRISM_ACTR_DECAY || "0.5");
+/** Weight of cosine similarity in composite score. (Default: 0.7 — similarity dominates) */
+export const PRISM_ACTR_WEIGHT_SIMILARITY = parseFloat(process.env.PRISM_ACTR_WEIGHT_SIMILARITY || "0.7");
+/** Weight of activation boost in composite score. (Default: 0.3 — activation re-ranks) */
+export const PRISM_ACTR_WEIGHT_ACTIVATION = parseFloat(process.env.PRISM_ACTR_WEIGHT_ACTIVATION || "0.3");
+/** Sigmoid midpoint: activation value that maps to 0.5 boost. (Default: -2.0) */
+export const PRISM_ACTR_SIGMOID_MIDPOINT = parseFloat(process.env.PRISM_ACTR_SIGMOID_MIDPOINT || "-2.0");
+/** Sigmoid steepness k. Higher = sharper discrimination. (Default: 1.0) */
+export const PRISM_ACTR_SIGMOID_STEEPNESS = parseFloat(process.env.PRISM_ACTR_SIGMOID_STEEPNESS || "1.0");
+/** Max access log entries per entry for base-level activation. (Default: 50) */
+export const PRISM_ACTR_MAX_ACCESSES_PER_ENTRY = parseInt(process.env.PRISM_ACTR_MAX_ACCESSES_PER_ENTRY || "50", 10);
+/** AccessLogBuffer flush interval in milliseconds. (Default: 5000ms) */
+export const PRISM_ACTR_BUFFER_FLUSH_MS = parseInt(process.env.PRISM_ACTR_BUFFER_FLUSH_MS || "5000", 10);
+/** Days to retain access log entries before pruning. (Default: 90) */
+export const PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS = parseInt(process.env.PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS || "90", 10);

package/dist/dashboard/authUtils.js

@@ -0,0 +1,150 @@
+/**
+ * Dashboard authentication helpers extracted from server.ts for direct unit testing.
+ */
+import { randomBytes } from "crypto";
+// ─────────────────────────────────────────────────────────────────
+// TIMING-SAFE COMPARISON
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Timing-safe string comparison to prevent timing attacks.
+ *
+ * Returns false immediately for different lengths (this leaks length
+ * information, but credential length is not considered secret in
+ * HTTP Basic Auth where the header is visible).
+ *
+ * For equal-length strings, iterates ALL characters regardless of
+ * where mismatches occur, accumulating XOR differences.
+ */
+export function safeCompare(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+// ─────────────────────────────────────────────────────────────────
+// TOKEN GENERATION
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Generate a random 64-character hex session token.
+ */
+export function generateToken() {
+    return randomBytes(32).toString("hex");
+}
+// ─────────────────────────────────────────────────────────────────
+// AUTHENTICATION CHECK
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Check if a request is authenticated against the provided config.
+ *
+ * Returns true if:
+ *   1. Auth is disabled (authEnabled === false) → pass-through
+ *   2. Request has a valid, non-expired session cookie
+ *   3. Request has valid Basic Auth credentials
+ *
+ * Side effect: expired session tokens are lazily cleaned up when
+ * encountered, preventing unbounded memory growth.
+ */
+export function isAuthenticated(req, config) {
+    if (!config.authEnabled)
+        return true;
+    // Check session cookie first
+    const cookies = req.headers.cookie || "";
+    const match = cookies.match(/prism_session=([a-f0-9]{64})/);
+    if (match) {
+        const token = match[1];
+        const expiry = config.activeSessions.get(token);
+        if (expiry && expiry > Date.now())
+            return true;
+        // Expired or unknown — lazy cleanup
+        if (expiry)
+            config.activeSessions.delete(token);
+    }
+    // Check Basic Auth header
+    const authHeader = req.headers.authorization || "";
+    if (authHeader.startsWith("Basic ")) {
+        try {
+            const decoded = Buffer.from(authHeader.slice(6), "base64").toString("utf-8");
+            const colonIndex = decoded.indexOf(":");
+            if (colonIndex === -1)
+                return false;
+            const user = decoded.slice(0, colonIndex);
+            const pass = decoded.slice(colonIndex + 1);
+            return safeCompare(user, config.authUser) && safeCompare(pass, config.authPass);
+        }
+        catch {
+            // Malformed Base64 — reject
+            return false;
+        }
+    }
+    return false;
+}
+// ─────────────────────────────────────────────────────────────────
+// RATE LIMITER
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Creates a sliding-window rate limiter.
+ *
+ * Returns an object with:
+ *   - isAllowed(key): boolean — check and record an attempt
+ *   - reset(key): void — clear attempts for a key
+ *   - clear(): void — clear all state (for testing)
+ *
+ * The limiter automatically prunes stale entries on each check
+ * to prevent unbounded memory growth from unique IPs.
+ */
+export function createRateLimiter(opts) {
+    const store = new Map();
+    let lastPrune = Date.now();
+    // Prune stale entries every 5 minutes to prevent memory leaks
+    const PRUNE_INTERVAL_MS = 5 * 60 * 1000;
+    function pruneStale(now) {
+        if (now - lastPrune < PRUNE_INTERVAL_MS)
+            return;
+        lastPrune = now;
+        for (const [key, entry] of store) {
+            // Keep only timestamps within the window
+            entry.timestamps = entry.timestamps.filter(t => now - t < opts.windowMs);
+            if (entry.timestamps.length === 0) {
+                store.delete(key);
+            }
+        }
+    }
+    return {
+        /**
+         * Check if an attempt from the given key is allowed.
+         * Records the attempt and returns false if rate limit exceeded.
+         */
+        isAllowed(key) {
+            const now = Date.now();
+            pruneStale(now);
+            let entry = store.get(key);
+            if (!entry) {
+                entry = { timestamps: [] };
+                store.set(key, entry);
+            }
+            // Filter to only timestamps within the window
+            entry.timestamps = entry.timestamps.filter(t => now - t < opts.windowMs);
+            if (entry.timestamps.length >= opts.maxAttempts) {
+                return false; // Rate limited
+            }
+            entry.timestamps.push(now);
+            return true;
+        },
+        /** Reset attempts for a specific key */
+        reset(key) {
+            store.delete(key);
+        },
+        /** Clear all state — useful for testing */
+        clear() {
+            store.clear();
+            lastPrune = Date.now();
+        },
+        /** Get current store size — for testing */
+        get size() {
+            return store.size;
+        },
+    };
+}