# Prism v14.0.0 — Prism as Foundation

**Released:** 2026-05-07
**Theme:** Prism's algorithms now power external systems beyond MCP-aware agents.

---

## TL;DR

For two years Prism was something AI agents talked to. With v14.0.0 we're documenting the inversion: **Prism's algorithms are themselves a foundation library**. Other systems can lift `actrActivation.ts`, `spreadingActivation.ts`, `routerExperience.ts`, `compactionHandler.ts`, and the constants in `config.ts` and reuse them with citations — the same way scientific code reuses textbook formulas.

The first canonical consumer is the **audit hooks framework** at `~/.agent/skills/hooks/` (a separate skill, not part of this repo). Every threshold in that framework — every decay rate, every prune cutoff, every score blend — carries a comment pointing back to the exact line in Prism's source. We've now formalised that pattern so others can do the same.

This is a major version bump because we're committing to algorithm-stability as a public contract. Behavior of `baseLevelActivation`, `parameterizedSigmoid`, `applySpreadingActivation`, `getExperienceBias`, and the `PRISM_*` constants in `config.ts` is now part of Prism's API surface. Breaking changes go through deprecation cycles.

---

## What's new

### Algorithm-stability contract

The following module exports are now considered **stable public API** under SemVer:

| Module | Exported surface | Stable since |
|---|---|---|
| `src/utils/actrActivation.ts` | `baseLevelActivation`, `parameterizedSigmoid`, `compositeRetrievalScore`, `ACT_R_DEFAULT_DECAY`, `ACTIVATION_FLOOR`, `MIN_TIME_DELTA_SECONDS`, `DEFAULT_SIGMOID_*`, `DEFAULT_WEIGHT_*` | v14.0.0 |
| `src/memory/spreadingActivation.ts` | `applySpreadingActivation`, the hybrid score blend (0.7 sim + 0.3 activation), `finalM` semantic | v14.0.0 |
| `src/tools/routerExperience.ts` | `getExperienceBias`, `MAX_BIAS_CAP`, `MIN_SAMPLES`, the bias-scale formula | v14.0.0 |
| `src/tools/compactionHandler.ts` | the default `threshold=50`, `keep_recent=10`, `MAX_ENTRIES_CHARS=25000`, prompt-budget semantics | v14.0.0 |
| `src/observability/graphMetrics.ts` | warning-flag thresholds: `synthesis_failure_warning > 0.20`, `cognitive_fallback_rate_warning > 0.30`, `cognitive_ambiguity_rate_warning > 0.40` | v14.0.0 |
| `src/config.ts` | `PRISM_ACTR_DECAY`, `PRISM_GRAPH_PRUNE_MIN_STRENGTH`, `PRISM_GRAPH_PRUNE_*` family | v14.0.0 |

If you reuse any of these, you can pin a Prism version and rely on the values not silently shifting under you. Changes will be flagged in CHANGELOG with deprecation cycles.

### `docs/WOW_FEATURES.md` — algorithm catalogue

New document showcasing what each Prism algorithm DOES and how external consumers can reuse it. Not a tutorial — a citation-grade reference for systems that want to ground their thresholds in Prism rather than guessing.

Covers:
- ACT-R decay (`B_i = ln(Σ t_j^(-d))`) — when to use raw d=0.5 vs. rollup d=0.25
- Spreading activation hybrid score (0.7 similarity + 0.3 activation) — as a general blend formula for "user signal × graph context"
- Experience bias (`(winRate − 0.5) × 0.30`, capped ±0.15) — for "warm corpus" decisions on top of `MIN_SAMPLES = 5`
- graphMetrics warning ratios — for tier-escalation in any sequence-of-events monitor
- Compaction's prompt-budget cap (25KB) — as a generic LLM-output size discipline

### Reference implementation: audit hooks framework

The first system built end-to-end on Prism algorithm citations is **not in this repo**. It's at `~/.agent/skills/hooks/` (separate skill, separate distribution). What it demonstrates:

| Component | Lines | Cited from Prism |
|---|---|---|
| ACT-R decay engine | `core/decay.py`, ~145 | direct port of `actrActivation.ts:90-210` |
| Pre-execution clarification gate | `prompt_audit/gate.py`, ~300 | uses `MIN_SAMPLES=5` + experience-bias formula + lesson decay rate |
| Tier escalation | `prompt_audit/scorer.py`, ~335 | uses `synthesis_failure_warning` / `cognitive_fallback_rate_warning` / `cognitive_ambiguity_rate_warning` ratios |
| Output budget | `core/budget.py`, ~91 | uses `MAX_ENTRIES_CHARS = 25_000` from compactionHandler |
| Postflight harvester | `prompt_audit/postflight.py`, ~276 | persists experiences in the same `level / fingerprint / gotchas` shape Prism uses for ledger entries |

327 tests in that framework — 184 of them parameterized over Prism-derived constants. **If a constant changes in this repo, the framework's tests break.** That's the point.

### What's NOT included in this release

- **No new MCP tools.** This release is about formalizing the algorithm surface; no new tool definitions in `src/tools/`.
- **No model changes.** `prism-coder:7b` and `prism-coder:14b` are unchanged from v13.1.x.
- **No schema changes.** Storage backend stays at the v13 schema.
- **No npm package version bump for `prism-mcp-server`** — the binary distribution is unchanged. v14.0.0 is the cognitive architecture / source-tree version.

---

## Why now

External consumers were already shipping with hand-derived "approximation of Prism's behavior". Two outcomes when that happens:

1. The consumer's thresholds drift from Prism's over time. A bug in the consumer's reimplementation surfaces months later as "the agent stopped catching X."
2. Or the consumer copy-pastes the constant once and forgets the citation. Six months later nobody remembers why `0.15` was chosen.

Formalizing the contract fixes both. The hooks framework's pattern — every constant carries a `# config.ts:317` comment — is now the recommended template.

---

## Migration

If you're a Prism user (MCP client, npm package consumer, agent author): **nothing changes**. Same binary, same schema, same tools.

If you've been re-implementing Prism algorithms in your own code:

1. Audit your hand-tuned constants against the citations in [`docs/WOW_FEATURES.md`](../WOW_FEATURES.md). If you have an "approximation," replace it with a port and a citation.
2. Pin to `prism-mcp-server@14.x` (the npm package will follow on next minor bump).
3. Watch CHANGELOG for any deprecation entries before changing your reimplementation's behavior.

---

## Acknowledgments

Algorithm-stability contract designed during the May 2026 audit hooks framework build. Every constant table in this release is a direct port of the citation tables in that framework's research doc.
