feat(memory): classifyMemoryTopic helper + recordMemoryWithAutoTopic wrapper

Wires the TarotScript memory-topic-classify spread into aegis-oss as an
opt-in auto-topic inference path for recordMemory. Callers that want
automatic topic classification switch from recordMemory() (explicit
topic) to recordMemoryWithAutoTopic() (classifier-inferred topic)
and pass the tarotscript service binding alongside the memory binding.

Existing call sites are unchanged — this is additive, not a replacement.
The migration rollout plan (see artifacts/tarotscript-classifier-migration.md
in aegis-daemon) calls for observation-mode first: flip on for one
caller, watch divergence between classifier output and operator-provided
topics for a week, then expand.

New module: web/src/kernel/classify-memory-topic.ts

Exports:
- CANONICAL_MEMORY_TOPICS — the 15-topic set the classifier can emit.
  Kept in sync with decks/memory-topics.deck in the tarotscript repo
  via a test assertion. Deck drift fails loudly.
- runMemoryTopicClassification(fetcher, fact) — raw classification
  call, returns facts object or null on failure. No fallback logic.
- classifyMemoryTopic(fetcher, fact) — high-level wrapper with
  fallback semantics. Falls through to { topic: 'general',
  source: 'fallback' } when:
    * fetcher call fails (network, auth, binding unavailable)
    * classifier returns low confidence
    * classifier returns an unknown canonical topic (deck drift guard)

Fallback rationale: classification is best-effort metadata, never
block the memory write. The 'general' card exists in the deck as the
stable fallback bucket precisely for this. Callers distinguish
classifier vs fallback via result.source.

New wrapper in memory-adapter.ts:
- recordMemoryWithAutoTopic(mem, tarotscriptFetcher, fact, confidence, source)
  composes classifyMemoryTopic + recordMemory. Returns both the record
  result AND the classification metadata so callers can observe
  divergence during rollout.

Tests (13 cases in web/tests/classify-memory-topic.test.ts):
- Worker response parsing (facts extraction, receipt hash)
- Non-OK response returns null (never throws)
- Network error returns null
- Correct request shape sent to worker (spreadType, querent, seed, inscribe)
- Happy path: moderate confidence → returns classifier topic
- Low confidence → falls through to 'general', marked fallback
- Unreachable worker → falls through to 'general'
- Unknown topic (deck drift) → falls through to 'general', confidence preserved
- Seed passed through
- CANONICAL_MEMORY_TOPICS drift guard (enumerates all 15 topics)
- recordMemoryWithAutoTopic happy path (infers operator, writes with topic)
- recordMemoryWithAutoTopic on classifier failure (writes with 'general')
- Critical invariant: classifier failure must not block the memory write

Full web suite: 66 files, 1473 pass, 1 skipped. Typecheck clean in
aegis-oss/web and aegis-daemon/web.

Not yet wired into any existing call site — operators flip on auto-topic
at the call site by switching to recordMemoryWithAutoTopic as observation
begins. First target is memory topic routing from dreaming cycle and
inbox-processor (both async, low-latency-tolerance).

Related:
- Stackbilt-dev/tarotscript@7f6854c — memory-topics deck + spread
- Stackbilt-dev/tarotscript@ae0c517 — worker bundle regeneration
- artifacts/tarotscript-classifier-migration.md in aegis-daemon

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

web/src/kernel/classify-memory-topic.ts

@@ -0,0 +1,166 @@
+// Memory topic classification via TarotScript memory-topic-classify spread.
+//
+// The spread lives at Stackbilt-dev/tarotscript:spreads/memory-topic-classify.tarot
+// and draws from decks/memory-topics (15 canonical topics for AEGIS semantic
+// memory). See artifacts/tarotscript-classifier-migration.md in aegis-daemon
+// for the broader design and rollout plan.
+//
+// Contract:
+//   classifyMemoryTopic(fetcher, fact) → {
+//     topic: canonical topic string,
+//     confidence: 'high' | 'moderate' | 'low',
+//     source: 'classifier' | 'fallback',
+//     element?: element of drawn card (debugging aid),
+//   }
+//
+// When the classifier returns confidence='low', OR when the classification
+// lands on the 'general' fallback card, OR when the fetcher call fails for
+// any reason, the helper falls through to { topic: 'general', source: 'fallback' }.
+// Callers who want the raw classifier output can use runMemoryTopicClassification
+// directly instead.
+//
+// Telemetry: the helper does not log or persist anything itself. Callers are
+// responsible for recording divergence between operator-provided topics and
+// classifier-inferred topics during the observation rollout.
+
+// The set of canonical topics the classifier is trained to emit. Kept in sync
+// with decks/memory-topics.deck in the tarotscript repo. If the deck adds a
+// new card, also update this list so typecheck catches stale consumers.
+export type CanonicalMemoryTopic =
+  | 'operator'
+  | 'feedback'
+  | 'business_ops'
+  | 'compliance'
+  | 'execution'
+  | 'content'
+  | 'research'
+  | 'reflection'
+  | 'cross_repo_intelligence'
+  | 'feed_intel'
+  | 'aegis'
+  | 'tarotscript'
+  | 'infrastructure'
+  | 'portfolio_project'
+  | 'general';
+
+export const CANONICAL_MEMORY_TOPICS: readonly CanonicalMemoryTopic[] = [
+  'operator', 'feedback', 'business_ops', 'compliance', 'execution',
+  'content', 'research', 'reflection', 'cross_repo_intelligence',
+  'feed_intel', 'aegis', 'tarotscript', 'infrastructure',
+  'portfolio_project', 'general',
+] as const;
+
+export type ClassificationConfidence = 'high' | 'moderate' | 'low';
+
+export interface MemoryTopicClassification {
+  topic: CanonicalMemoryTopic;
+  confidence: ClassificationConfidence;
+  source: 'classifier' | 'fallback';
+  element?: string;
+  receipt_hash?: string;
+}
+
+/**
+ * Raw classification call. Invokes the memory-topic-classify spread on the
+ * tarotscript worker and returns the parsed facts object, or null if the
+ * call fails for any reason (network, auth, worker down, spread error).
+ * The helper wrapper `classifyMemoryTopic` applies fallback semantics on
+ * top of this; most callers should use the wrapper instead.
+ */
+export async function runMemoryTopicClassification(
+  fetcher: Fetcher,
+  fact: string,
+  opts: { seed?: number } = {},
+): Promise<{
+  classification?: string;
+  classification_confidence?: string;
+  classification_element?: string;
+  receipt_hash?: string;
+} | null> {
+  try {
+    const response = await fetcher.fetch('https://internal/run', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        spreadType: 'memory-topic-classify',
+        querent: {
+          id: 'aegis',
+          intention: fact,
+        },
+        seed: opts.seed,
+        inscribe: false, // classification is metadata, not a consultation
+      }),
+    });
+
+    if (!response.ok) {
+      console.warn(`[classify-memory-topic] worker returned ${response.status}`);
+      return null;
+    }
+
+    const body = await response.json() as {
+      facts?: Record<string, string>;
+      receipt?: { hash?: string };
+    };
+
+    return {
+      classification: body.facts?.classification,
+      classification_confidence: body.facts?.classification_confidence,
+      classification_element: body.facts?.classification_element,
+      receipt_hash: body.receipt?.hash,
+    };
+  } catch (err) {
+    console.warn(
+      `[classify-memory-topic] fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}
+
+function isCanonicalTopic(value: string | undefined): value is CanonicalMemoryTopic {
+  return typeof value === 'string'
+    && (CANONICAL_MEMORY_TOPICS as readonly string[]).includes(value);
+}
+
+/**
+ * High-level classifier with fallback. Calls the memory-topic-classify spread,
+ * validates the output, and returns 'general' as a stable fallback when:
+ *   - the fetcher call fails (network, auth, worker down)
+ *   - the spread returns an unknown topic (deck drift — log + fall through)
+ *   - the classification confidence is 'low' (deck scoring was ambiguous)
+ *
+ * The fallback is 'general' on purpose — that card exists in the deck for
+ * exactly this reason and callers can filter on `source === 'fallback'` to
+ * distinguish model output from fall-through behavior.
+ */
+export async function classifyMemoryTopic(
+  fetcher: Fetcher,
+  fact: string,
+  opts: { seed?: number } = {},
+): Promise<MemoryTopicClassification> {
+  const raw = await runMemoryTopicClassification(fetcher, fact, opts);
+
+  if (!raw) {
+    return { topic: 'general', confidence: 'low', source: 'fallback' };
+  }
+
+  const confidence = (raw.classification_confidence ?? 'low') as ClassificationConfidence;
+
+  if (confidence === 'low') {
+    return { topic: 'general', confidence: 'low', source: 'fallback' };
+  }
+
+  if (!isCanonicalTopic(raw.classification)) {
+    console.warn(
+      `[classify-memory-topic] unknown canonical topic from classifier: "${raw.classification}" — falling through to 'general'`,
+    );
+    return { topic: 'general', confidence, source: 'fallback' };
+  }
+
+  return {
+    topic: raw.classification,
+    confidence,
+    source: 'classifier',
+    element: raw.classification_element,
+    receipt_hash: raw.receipt_hash,
+  };
+}

web/src/kernel/memory-adapter.ts

@@ -7,6 +7,7 @@
 
 import type { MemoryServiceBinding, MemoryFragmentResult, MemoryStatsResult, MemoryStoreRequest } from '../types.js';
 import { estimateTokens } from './memory/episodic.js';
+import { classifyMemoryTopic, type MemoryTopicClassification } from './classify-memory-topic.js';
 
 const TENANT = 'aegis';
 const MEMORY_CONTEXT_LIMIT = 50;
@@ -115,6 +116,39 @@ export async function recordMemory(
   }
 }
 
+// ─── recordMemoryWithAutoTopic ──────────────────────────────
+// Opt-in convenience wrapper: classify the fact via TarotScript's
+// memory-topic-classify spread, then write with the inferred topic.
+//
+// Callers pass the tarotscript service binding alongside the memory binding.
+// If the classifier returns 'general' via the fallback path (classifier
+// down, low confidence, unknown topic), the wrapper still writes the fact
+// but with the 'general' topic — the caller can filter on the returned
+// `classification.source === 'fallback'` to decide whether to re-tag later.
+//
+// Rollout note: this is additive, not a replacement for recordMemory. Existing
+// call sites that pass an explicit topic continue to work unchanged. Callers
+// wanting auto-topic opt in explicitly by switching to this wrapper. The
+// feature flag lives at the call site (not in this helper) so each caller
+// can independently decide when to flip on auto-topic inference.
+
+export interface RecordMemoryWithTopicResult extends RecordMemoryResult {
+  classification: MemoryTopicClassification;
+}
+
+export async function recordMemoryWithAutoTopic(
+  mem: MB,
+  tarotscriptFetcher: Fetcher,
+  fact: string,
+  confidence: number,
+  source: string,
+  opts: { seed?: number } = {},
+): Promise<RecordMemoryWithTopicResult> {
+  const classification = await classifyMemoryTopic(tarotscriptFetcher, fact, opts);
+  const record = await recordMemory(mem, classification.topic, fact, confidence, source);
+  return { ...record, classification };
+}
+
 // ─── getMemoryEntries ───────────────────────────────────────
 export async function getMemoryEntries(
   mem: MB, topic?: string, limit = 50,