talon-agent 4.6.1 → 5.0.0

package/src/storage/metrics.ts

@@ -15,6 +15,7 @@ import { emptyPhases, TURN_PHASES, type TurnPhase } from "./session-record.js";
 const PHASE_HISTOGRAM: Record<TurnPhase, string> = {
   queueWait: "turn.queue_wait_ms",
   warpResolve: "turn.warp_resolve_ms",
+  memory: "turn.memory_ms",
   firstToken: "turn.first_token_ms",
   stream: "turn.stream_ms",
   delivery: "turn.delivery_ms",
@@ -30,6 +31,42 @@ const legacyCounters = new Map<string, number>();
  */
 const processHistograms = new Map<string, MetricsLatencyAgg>();
 
+/**
+ * A chat's last cross-turn cache verdict — did the turn's FIRST request
+ * read the previous turn's prefix (`hit`), pay to re-write it (`miss`), or
+ * was nothing cacheable at all (`none`)? Mirrors `CrossTurnVerdict` in
+ * backend/runtime/cache/cache-telemetry.ts, which owns the classification; the
+ * union is restated here because `/status` renders it and frontends may
+ * not import backend/ (.dependency-cruiser.cjs: frontend-not-to-backend).
+ */
+export type CacheVerdict = "hit" | "miss" | "none";
+
+/**
+ * Per-chat last verdict. Process-local and deliberately unpersisted: it
+ * describes the live prefix, which dies with the process anyway, and
+ * `/status` is the only reader. Bounded like the per-chat maps in
+ * cache-telemetry.ts, insertion-ordered eviction.
+ */
+const MAX_TRACKED_CHATS = 256;
+const lastCacheVerdicts = new Map<string, CacheVerdict>();
+
+/** Record the chat's newest cross-turn cache verdict. */
+export function noteCacheVerdict(chatId: string, verdict: CacheVerdict): void {
+  if (
+    lastCacheVerdicts.size >= MAX_TRACKED_CHATS &&
+    !lastCacheVerdicts.has(chatId)
+  ) {
+    const oldest = lastCacheVerdicts.keys().next().value;
+    if (oldest !== undefined) lastCacheVerdicts.delete(oldest);
+  }
+  lastCacheVerdicts.set(chatId, verdict);
+}
+
+/** The chat's last cross-turn verdict, or undefined if none was recorded. */
+export function getCacheVerdict(chatId: string): CacheVerdict | undefined {
+  return lastCacheVerdicts.get(chatId);
+}
+
 export type MetricsSnapshot = {
   counters: Record<string, number>;
   histograms: Record<
@@ -202,5 +239,6 @@ export function getTodayMetrics(): MetricsSnapshot {
 export function resetMetrics(): void {
   legacyCounters.clear();
   processHistograms.clear();
+  lastCacheVerdicts.clear();
   resetAllSessionMetrics();
 }

package/src/storage/repositories/sessions-repo.ts

@@ -42,6 +42,7 @@ type Row = {
   total_response_ms: number;
   last_response_ms: number;
   fastest_response_ms: number | null;
+  last_turn_ended_at: number | null;
   metrics: string | null;
 };
 
@@ -81,6 +82,7 @@ function rowToSession(row: Row): SessionState {
     lastBotMessageId: row.last_bot_message_id ?? undefined,
     sessionName: row.session_name ?? undefined,
     lastModel: row.last_model ?? undefined,
+    lastTurnEndedAt: row.last_turn_ended_at ?? undefined,
   };
 }
 
@@ -120,6 +122,10 @@ export function upsert(chatId: string, session: SessionState): void {
       num(usage?.totalResponseMs),
       num(usage?.lastResponseMs),
       typeof fastest === "number" && Number.isFinite(fastest) ? fastest : null,
+      typeof session.lastTurnEndedAt === "number" &&
+        Number.isFinite(session.lastTurnEndedAt)
+        ? session.lastTurnEndedAt
+        : null,
       JSON.stringify(session.metrics ?? emptyMetrics()),
     );
 }

package/src/storage/session-record.ts

@@ -56,12 +56,14 @@ export type MetricsLatencyAgg = {
 
 /**
  * Where a turn's wall-clock went, as seen from the Weaver: waiting in the
- * chat's FIFO, resolving the warp, until the backend's first event, the
- * whole stream, and the slice of it spent inside frontend delivery.
+ * chat's FIFO, resolving the warp, retrieving this turn's memory, until
+ * the backend's first event, the whole stream, and the slice of it spent
+ * inside frontend delivery.
  */
 export const TURN_PHASES = [
   "queueWait",
   "warpResolve",
+  "memory",
   "firstToken",
   "stream",
   "delivery",
@@ -104,6 +106,14 @@ export type SessionState = {
   sessionName?: string;
   /** Model used for this session's cost tracking. */
   lastModel?: string;
+  /**
+   * When the last turn of this chat finished (ms epoch), or undefined when
+   * no turn has completed yet. Distinct from `lastActive`, which any
+   * session write moves: this one only ever means "the transcript stopped
+   * growing here", which is what the prompt cache's TTL runs against —
+   * warm iff `now - lastTurnEndedAt < ttl` (docs/cache-economics.md).
+   */
+  lastTurnEndedAt?: number;
 };
 
 export const emptyUsage = (): SessionUsage => ({
@@ -146,6 +156,7 @@ export const emptyLatency = (): MetricsLatencyAgg => ({
 export const emptyPhases = (): MetricsPhaseAggs => ({
   queueWait: emptyLatency(),
   warpResolve: emptyLatency(),
+  memory: emptyLatency(),
   firstToken: emptyLatency(),
   stream: emptyLatency(),
   delivery: emptyLatency(),

package/src/storage/sessions.ts

@@ -480,6 +480,10 @@ export function recordUsage(
     session.usage.estimatedCostUsd += turn.costUsd;
   }
   if (turn.model) session.lastModel = turn.model;
+  // A turn just ended — this is the timestamp the prompt cache ages
+  // against (docs/cache-economics.md). Set on the one seam every backend
+  // funnels a finished turn through, failed-but-billed turns included.
+  session.lastTurnEndedAt = Date.now();
   if (turn.durationMs && turn.durationMs > 0) {
     session.usage.totalResponseMs =
       (session.usage.totalResponseMs || 0) + turn.durationMs;
@@ -580,6 +584,12 @@ export type SessionInfo = {
   lastModel?: string;
   /** True when a turn is currently streaming and `usage` includes its live so-far counts. */
   turnInProgress?: boolean;
+  /**
+   * When this chat's last turn finished (ms epoch), or undefined when none
+   * has. `/status` reports the idle gap from it; `lastActive` can't stand in
+   * because any session write moves that.
+   */
+  lastTurnEndedAt?: number;
 };
 
 export function getSessionInfo(chatId: string): SessionInfo {
@@ -594,6 +604,7 @@ export function getSessionInfo(chatId: string): SessionInfo {
     sessionName: session?.sessionName,
     lastModel: session?.lastModel,
     turnInProgress: liveTurns.has(chatId),
+    lastTurnEndedAt: session?.lastTurnEndedAt,
   };
 }
 
@@ -615,6 +626,7 @@ export function getAllSessions(): Array<{ chatId: string; info: SessionInfo }> {
       sessionName: session.sessionName,
       lastModel: session.lastModel,
       turnInProgress: liveTurns.has(chatId),
+      lastTurnEndedAt: session.lastTurnEndedAt,
     },
   }));
 }

package/src/storage/sql/db.sql

@@ -25,3 +25,8 @@ ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"cou
 -- carry more than one attachment. Fresh databases get the column via
 -- schema.sql.
 ALTER TABLE history_messages ADD COLUMN attachments TEXT
+
+-- name: addSessionsLastTurnEndedAtColumn
+-- Column reconciliation for databases that shipped before the cache-age
+-- signal existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN last_turn_ended_at INTEGER

package/src/storage/sql/schema.sql

@@ -161,6 +161,10 @@ CREATE TABLE IF NOT EXISTS sessions (
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
   fastest_response_ms REAL,
+  -- When the chat's last turn finished; NULL until one has. Read as the
+  -- prompt cache's age signal (docs/cache-economics.md), which is why it
+  -- is separate from last_active (moved by any session write).
+  last_turn_ended_at  INTEGER,
   metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 

package/src/storage/sql/sessions.sql

@@ -7,15 +7,15 @@ INSERT OR REPLACE INTO sessions
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms, metrics)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+   last_response_ms, fastest_response_ms, last_turn_ended_at, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 
 -- name: all
 SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms, metrics
+       last_response_ms, fastest_response_ms, last_turn_ended_at, metrics
 FROM sessions
 
 -- name: remove

package/src/storage/sql/statements.generated.ts

@@ -166,6 +166,10 @@ CREATE TABLE IF NOT EXISTS sessions (
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
   fastest_response_ms REAL,
+  -- When the chat's last turn finished; NULL until one has. Read as the
+  -- prompt cache's age signal (docs/cache-economics.md), which is why it
+  -- is separate from last_active (moved by any session write).
+  last_turn_ended_at  INTEGER,
   metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 
@@ -414,6 +418,9 @@ ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"cou
 -- carry more than one attachment. Fresh databases get the column via
 -- schema.sql.
 ALTER TABLE history_messages ADD COLUMN attachments TEXT`,
+  addSessionsLastTurnEndedAtColumn: `-- Column reconciliation for databases that shipped before the cache-age
+-- signal existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN last_turn_ended_at INTEGER`,
 } as const;
 
 export const goalsSql = {
@@ -657,13 +664,13 @@ export const sessionsSql = {
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms, metrics)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+   last_response_ms, fastest_response_ms, last_turn_ended_at, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   all: `SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms, metrics
+       last_response_ms, fastest_response_ms, last_turn_ended_at, metrics
 FROM sessions`,
   remove: `DELETE FROM sessions WHERE chat_id = ?`,
 } as const;

package/src/storage/sql/turn-meta.sql

@@ -1,4 +1,4 @@
--- Statements for the turn_meta table (see frontend/native/turn-meta.ts).
+-- Statements for the turn_meta table (see frontend/native/turn/turn-meta.ts).
 
 -- name: get
 SELECT meta FROM turn_meta WHERE chat_id = ? AND msg_id = ?

package/src/util/boot-timer.ts

@@ -4,7 +4,9 @@
  * has an answer in the log instead of a profiler session.
  */
 
-const phases: { label: string; ms: number }[] = [];
+export type BootPhaseSample = { label: string; ms: number };
+
+const phases: BootPhaseSample[] = [];
 
 /** Run one startup phase and remember how long it took. */
 export async function bootPhase<T>(
@@ -25,6 +27,18 @@ export function bootReport(now = Math.round(process.uptime() * 1000)): string {
   return parts.length ? `${now}ms (${parts.join(", ")})` : `${now}ms`;
 }
 
+/**
+ * The recorded phases, in the order they completed.
+ *
+ * `util/` is a leaf (.dependency-cruiser.cjs: util-is-a-leaf), so this
+ * module cannot write to the metrics store itself. It hands the samples
+ * out instead and `core/daemon/resource-sampler.ts` turns them into
+ * `boot.<phase>_ms` histograms.
+ */
+export function bootPhases(): readonly BootPhaseSample[] {
+  return phases;
+}
+
 /** Test seam. */
 export function resetBootPhases(): void {
   phases.length = 0;

package/src/util/chat-id.ts

@@ -67,3 +67,33 @@ export function isWhatsAppChatId(chatId: string): boolean {
 export function isDiscordChatId(chatId: string): boolean {
   return chatId.startsWith("discord_");
 }
+
+/**
+ * Classify a canonical chat ID as a one-to-one chat, a multi-party one,
+ * or something this grammar cannot tell apart.
+ *
+ * The ID is the only signal engine-side code has: a frontend's own
+ * `isGroup` flag rides on the inbound message, while stores, jobs and
+ * gateway actions are keyed by the string ID alone. Per frontend:
+ *
+ *   - `discord_guild_…` / `discord_dm_…` and `wa_group_…` / `wa_dm_…`
+ *     say which they are outright;
+ *   - a Telegram ID is bare digits — negative for a group, supergroup or
+ *     channel, positive for the user's own ID (a DM);
+ *   - terminal (`t_…`, `"1"`) and native (`d_…`) chats are local,
+ *     single-operator surfaces, so they are DMs;
+ *   - `teams_chat_…` covers 1:1 *and* group Teams chats alike, so it is
+ *     `"unknown"` — as is anything a future frontend invents.
+ *
+ * Callers decide what `"unknown"` means for them; anything trust- or
+ * privacy-sensitive should treat it as a group and fail closed.
+ */
+export function chatScope(chatId: string): "dm" | "group" | "unknown" {
+  if (chatId.startsWith("discord_guild_")) return "group";
+  if (chatId.startsWith("discord_dm_")) return "dm";
+  if (chatId.startsWith("wa_group_")) return "group";
+  if (chatId.startsWith("wa_dm_")) return "dm";
+  if (isTelegramChatId(chatId)) return chatId.startsWith("-") ? "group" : "dm";
+  if (isTerminalChatId(chatId) || isNativeChatId(chatId)) return "dm";
+  return "unknown";
+}

package/src/util/log.ts

@@ -62,7 +62,7 @@ export type LogComponent =
   | "mempalace"
   | "mem0"
   | "playwright"
-  | "soul"
+  | "memory"
   | "stickers"
   | "backend-controller";
 

package/src/util/paths.ts

@@ -116,8 +116,6 @@ export const files = {
   triggers: resolve(TALON_ROOT, "data", "triggers.json"),
   /** Legacy JSON native turn meta (imported into talon.db on first boot) */
   nativeTurnMeta: resolve(TALON_ROOT, "data", "native-turn-meta.json"),
-  /** Soul kernel state: ~/.talon/data/soul.json (overridable via config.soul.path) */
-  soul: resolve(TALON_ROOT, "data", "soul.json"),
   /** Legacy JSON media index (imported into talon.db on first boot) */
   mediaIndex: resolve(TALON_ROOT, "data", "media-index.json"),
   /** Persistent memory: ~/.talon/workspace/memory/memory.md */

package/src/core/soul/README.md

@@ -1,110 +0,0 @@
-# Soul Kernel
-
-Talon's compiled identity. Not a markdown prompt, not a JSON blob — a
-**content-addressed Merkle DAG** of typed identity nodes, learned **mechanically**
-from behavioral telemetry and projected into the system prompt by **selection**.
-
-> The model is the brain. Talon is the body. The Soul is the persistent identity
-> artifact that tells the brain how to be Talon.
-
-## The thesis: the model never writes its own soul
-
-There are two jobs — _being the self_ (the reasoning model reads the soul and
-acts) and _writing the self_ (turning experience into identity). If the reasoning
-model does the second, it can rationalize, flatter itself, and confabulate a
-coherent self-story that isn't true. So **writing the self is strictly
-model-free**: continuous, deterministic, evidence-grounded. The reasoning model is
-a _reader_ of the soul, never its author. That is the safety property, not just a
-cost saving.
-
-The only neural component anywhere is an optional **local embedder** (for
-clustering/dedup/contradiction-distance) — a frozen fixed function, not an agent.
-Everything else is counters, exponential decay, dot products, and selection.
-
-## The substrate
-
-A node's identity is the sha-256 of its canonical content. The single most
-important decision is the split between:
-
-- **Content** (hashed, immutable) — a node's semantic identity: kind + verbatim
-  payload + referenced child hashes. A change of content is a new node.
-- **State** (mutable, keyed by hash) — salience, evidence weight, activation
-  counts. Churns every tick; lives _outside_ the Merkle structure.
-
-So reinforcing a value a thousand times never churns a single content hash.
-Versioning, provenance, dedup, and partial recompilation fall out structurally;
-learning and decay live in the state layer.
-
-## The five structures
-
-| Structure | Node kind       | What it is                                                                                  |
-| --------- | --------------- | ------------------------------------------------------------------------------------------- |
-| Spine     | `spine`         | append-only causal narrative — _why_ Talon became Talon                                     |
-| Lattice   | `value` + edges | values as evidence clusters; tension/affinity edges self-organize via Hebbian co-activation |
-| Reflexes  | `reflex`        | `trigger → guard → action` rules the harness _enforces_                                     |
-| Holograph | `lens`          | identity refracted per interlocutor (selection + reweighting)                               |
-| Critic    | (classifiers)   | frozen feature-based gates over failure modes                                               |
-
-The atoms under all of it are `evidence` nodes — verbatim ground truth. The kernel
-never paraphrases; it only ever quotes.
-
-## The model-free pipeline
-
-```
-telemetry ──▶ signals ──▶ compiler ──▶ DAG (+ salience/Hebbian) ──▶ projector ──▶ runtime.md
-  (harness)   (structured)  (arithmetic)   (content + state)        (selection)   (injected)
-```
-
-- **Signals** (`signals.ts`) — structured harness events (reaction, engagement,
-  correction, reflex-fire). Interpretation already happened; no transcript reading.
-- **Compiler** (`compiler.ts`) — routes each signal to pure update rules. Outcome
-  signals reinforce/penalize the values that were live in that turn's projection
-  and Hebbian-coactivate them; corrections store verbatim evidence + a Spine event.
-- **Salience** (`salience.ts`) — lazy exponential decay, reinforcement, Hebbian
-  edges, predictive-coding delta rule. The whole "learning" is here, all arithmetic.
-- **Projector** (`projector.ts`) — selects verbatim evidence, salience-ordered
-  under a token budget. Reflexes are never budgeted away. The soul cannot
-  hallucinate itself.
-- **Critic** (`critic.ts`) — frozen classifiers for wall-of-text, sycophancy,
-  emoji-overload.
-- **Kernel** (`kernel.ts`) — orchestrator: genesis → ingest → commit → project,
-  with a git-like commit chain and JSON persistence.
-
-## File map
-
-```
-types.ts       node payloads, edges, activation state, commits, config
-hash.ts        canonical serialization + content addressing + Merkle root
-dag.ts         the DAG store: integrity, dirty propagation, snapshot/restore
-salience.ts    decay / reinforce / coactivate / prediction-error  (the math)
-reflex.ts      predicate registry + enforcer + the three seed reflexes
-signals.ts     structured telemetry types + emoji→valence
-compiler.ts    signal → arithmetic update routing  (writing the self)
-projector.ts   DAG → runtime surface by selection  (reading the self)
-critic.ts      frozen failure-mode classifiers
-kernel.ts      orchestrator: lifecycle, commits, persistence
-index.ts       public surface
-```
-
-## Status
-
-Implemented and tested (150+ tests, model-free end to end):
-
-- **Substrate** — content-addressed Merkle DAG, dirty-tracking, commits, persistence.
-- **Learning** — salience decay/reinforce, Hebbian edges, predictive-coding updates.
-- **Emergence** — value clustering (`crystallize`), self-reorganizing `consolidate`
-  ("dream") with adaptive thresholds + state migration, reflection into `theme`s.
-- **Embedding** — our own `TalonEmbedder` (model-free) behind a pluggable seam.
-- **Adaptation** — learned valence (meaning from outcomes), FSRS/DSR forgetting,
-  ADWIN drift → Spine epochs, emergent failure modes.
-- **Recall** — Generative-Agents context retrieval, PageRank centrality, modern
-  Hopfield associative recall, VSA/HDC compositional episodic memory.
-- **Refraction** — relational holograph lens compilation.
-- **Surfaces** — projector (selection), delta stream, mechanical Critic.
-- **Governance** — protected-node approval queue; runtime gate (off by default).
-
-See `RESEARCH.md` for the literature behind each mechanism.
-
-Remaining: **harness wiring** — telemetry taps (reactions/engagement/corrections →
-signals), prompt injection of the projected surface, and live reflex enforcement.
-This touches the live Talon runtime and is gated behind `TALON_SOUL_ENABLED`.

package/src/core/soul/RESEARCH.md

@@ -1,98 +0,0 @@
-# Soul Kernel — research grounding
-
-Every mechanism in the kernel is model-free, but few are invented. This maps the
-load-bearing ideas to the literature they come from, and notes where each lives.
-
-## Implemented
-
-### Content-addressed Merkle DAG — `hash.ts`, `dag.ts`
-
-- Merkle, "A Digital Signature Based on a Conventional Encryption Function" (1987);
-  the git object model (Torvalds/Hamano, 2005).
-- Why: content addressing makes dedup, provenance, versioning, and partial
-  recompilation structural rather than bolted on.
-
-### Hebbian association — `salience.coactivate`, `lattice.ts`
-
-- Hebb, _The Organization of Behavior_ (1949): "cells that fire together wire
-  together."
-- Why: the value lattice's affinity/tension edges self-organize from
-  co-activation counts; no model decides what relates.
-
-### Predictive-coding / free-energy updates — `salience.applyPredictionError`
-
-- Rao & Ballard (1999); Friston, free-energy principle (2010).
-- Why: the soul is a predictive model of its own behavior; a correction is a
-  large prediction error and updates salience proportionally.
-
-### Complementary Learning Systems / systems consolidation — `consolidate.ts`
-
-- McClelland, McNaughton & O'Reilly (1995); memory replay during sleep
-  (Wilson & McNaughton, 1994).
-- Why: fast intake (crystallize) vs. slow reorganization (the "dream" pass that
-  merges drifted-together values and migrates learned state) mirrors the
-  fast-hippocampal / slow-neocortical split.
-
-### Feature hashing embedder — `talon-embedder.ts`
-
-- Weinberger et al., "Feature Hashing for Large Scale Multitask Learning" (2009);
-  signed hashing to debias collisions.
-- Why: a deterministic, dependency-free, model-free encoder we own — robust to
-  typos via shared character n-grams; a real sentence encoder drops in behind the
-  same interface.
-
-### Generative-Agents retrieval — `retrieve.ts`
-
-- Park et al., "Generative Agents: Interactive Simulacra of Human Behavior" (2023).
-- Score = normalized(recency) + normalized(importance) + normalized(relevance),
-  each min-max'd to [0,1] before summation, exactly as in the paper. Makes the
-  projected soul _relevant to the current moment_, not just globally salient.
-
-### FSRS / DSR adaptive forgetting — `forgetting.ts`
-
-- Wozniak's DSR model; FSRS (open-spaced-repetition); power-law forgetting
-  (Wickelgren, 1974) which fits human retention better than an exponential.
-- Retrievability R(t) = (1 + FACTOR·t/S)^DECAY with R(S) ≈ 0.9; stability S grows
-  on spaced successful recall and shrinks on a lapse. Core traits become durable,
-  fads evaporate — emergently.
-
-### Modern Hopfield associative recall — `associative.ts`
-
-- Ramsauer et al., "Hopfield Networks is All You Need" (2020); Krotov & Hopfield
-  (2016, 2020). Continuous Hopfield retrieval is one softmax step — the same
-  operation as attention.
-- Recall from a cue = softmax over Hebbian edge weights, p ∝ exp(β·w); `prime`
-  applies the update to the lattice so the soul recalls in constellations.
-
-### Reflection — `reflect.ts`
-
-- Park et al. (2023): synthesize higher-level inferences over time. Done
-  structurally — themes form over values that are coherent AND co-active. The one
-  optional, gated model pass (a label-only `synthesize` hook) lives here and can
-  never change which values group.
-
-### Concept-drift detection — `drift.ts`
-
-- Bifet & Gavaldà, "Learning from Time-Changing Data with Adaptive Windowing"
-  (ADWIN, 2007). Detects shifts in interaction-outcome distribution and opens a
-  developmental epoch in the Spine.
-
-### Personalized PageRank centrality — `centrality.ts`
-
-- Page, Brin, Motwani & Winograd (1999). Structural importance over the
-  co-activation graph; personalizable to a context.
-
-### Hyperdimensional / Vector-Symbolic memory — `hdc.ts`
-
-- Kanerva, "Hyperdimensional Computing" (2009). bind/bundle/permute/cleanup over
-  high-dim bipolar vectors give a compositional, model-free episodic memory:
-  context⊗value bound and bundled, recalled by unbinding — "in a situation like
-  this, what do I do?"
-
-## Future directions (researched, not yet built)
-
-- **Holographic Reduced Representations** (Plate, 1995) as a circular-convolution
-  alternative to elementwise binding, for graceful capacity scaling.
-- **Sparse distributed memory** (Kanerva, 1988) as an alternative episodic store.
-- **Active-inference planning** (Friston et al.) atop the existing predictive-
-  coding updates, to _select_ behavior, not just learn from it.

package/src/core/soul/associative.ts

@@ -1,98 +0,0 @@
-/**
- * Soul Kernel — associative recall (modern Hopfield / attention).
- *
- * Grounded in Ramsauer et al., "Hopfield Networks is All You Need" (2020), which
- * showed that a continuous modern Hopfield network retrieves a stored pattern in
- * ONE update via a softmax over similarities — the very operation at the heart of
- * attention. We apply the same rule to the lattice: the Hebbian coactivation
- * edges are the stored associations, and recalling from a cue is a one-step
- * softmax over the edge weights.
- *
- *   p(neighbor) ∝ exp(β · w(cue → neighbor))
- *
- * `prime` then performs the Hopfield update against the lattice itself: it nudges
- * the salience of the associatively-bound partners. The behavioral effect is what
- * you would want from a self — thinking of one value brings its companions to
- * mind ("push back" primes "be direct"), so the soul recalls in coherent
- * constellations rather than isolated points. Still model-free: a softmax over
- * counts.
- */
-
-import type { SoulDag } from "./dag.js";
-import type { Hash } from "./types.js";
-
-export interface RecallResult {
-  readonly node: Hash;
-  /** Softmax weight in (0, 1]; the constellation sums to 1. */
-  readonly weight: number;
-}
-
-export interface RecallOptions {
-  /** Inverse temperature; higher β sharpens recall toward the strongest bond. */
-  readonly beta?: number;
-  /** Keep only the top-K partners (default: all). */
-  readonly topK?: number;
-}
-
-/**
- * One-step associative retrieval from one or more cue nodes. Aggregates
- * coactivation edge weights to each neighbor, then softmaxes. Cues are excluded
- * from their own recall.
- */
-export function associativeRecall(
-  dag: SoulDag,
-  cues: readonly Hash[],
-  opts: RecallOptions = {},
-): RecallResult[] {
-  const beta = opts.beta ?? 1;
-  const cueSet = new Set(cues);
-  const score = new Map<Hash, number>();
-  for (const cue of cues) {
-    for (const e of dag.edgesFrom(cue, "coactivation")) {
-      if (cueSet.has(e.to)) continue;
-      score.set(e.to, (score.get(e.to) ?? 0) + e.weight);
-    }
-  }
-  if (score.size === 0) return [];
-
-  // Numerically-stable softmax over β·score.
-  const entries = [...score.entries()];
-  const max = Math.max(...entries.map(([, w]) => w));
-  const exps = entries.map(
-    ([h, w]) => [h, Math.exp(beta * (w - max))] as const,
-  );
-  const z = exps.reduce((s, [, e]) => s + e, 0);
-
-  const out = exps
-    .map(([node, e]) => ({ node, weight: e / z }))
-    .sort((a, b) => b.weight - a.weight || a.node.localeCompare(b.node));
-  return opts.topK ? out.slice(0, opts.topK) : out;
-}
-
-export interface PrimeOptions extends RecallOptions {
-  readonly now: number;
-  /** Salience injected, distributed across the recalled constellation. */
-  readonly gain: number;
-}
-
-/**
- * The Hopfield update applied to the lattice: recall from the cues and add
- * salience to the bound partners in proportion to their recall weight. Returns
- * the primed nodes. Caller commits.
- */
-export function prime(
-  dag: SoulDag,
-  cues: readonly Hash[],
-  opts: PrimeOptions,
-): Hash[] {
-  const recalled = associativeRecall(dag, cues, opts);
-  const primed: Hash[] = [];
-  for (const { node, weight } of recalled) {
-    const s = dag.stateOf(node);
-    s.salience += opts.gain * weight;
-    s.lastActivatedAt = opts.now;
-    dag.touch(node);
-    primed.push(node);
-  }
-  return primed;
-}