Studio Hathor · NPC Memory System

Purpose#

Admin lane console for the real NPC memory-relevance ranker. Supply a set of NPC memories and a recall query, and read back the top-K recalled memories ranked by importance + access frequency + a 20-hour recency window + emotional salience + content match, scaled by the memory decay penalty. Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/npc-emotional-state (this page links out to npc-emotional-state)
• Aggregator embed: StudioHathorLlmNpcWorkspace mounts this workspace inline as its "NPC Memory System Lane"
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace <section data-hathor-npc-memory-system-workspace>:
  • <h1> (WorkspaceHeading) "Hathor NPC Memory System Workspace"
  • Summary <p data-hathor-npc-memory-system-summary>
  • Memory Recall Lane (<h2 data-hathor-nms-lane-heading>) — the engine summary (data-hathor-nms-engine-summary, from the catalog) and the recall form data-hathor-nms-form
• Route Map panel (data-hathor-npc-memory-system-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_NPC_MEMORY_SYSTEM_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — NPC Emotional State, Back to Studio workspace index

States#

• Loading — <p data-hathor-nms-loading>
• Unauthorized — data-hathor-nms-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-nms-error on non-OK GET / malformed catalog
• Ready (form) — engine summary + data-hathor-nms-form once the catalog loads
• Result — data-hathor-nms-result after a 200 recall; data-hathor-nms-recall-error for invalid JSON / non-200

Interactions#

Memory Recall Lane#

• NPC memories (JSON array) — <textarea data-hathor-nms-memories> (aria-label "npc memories json")
• Recall query — <input data-hathor-nms-query> (aria-label "recall query")
• Now (epoch ms) — <input data-hathor-nms-now> (aria-label "now ms")
• Top K — <input data-hathor-nms-topk> (aria-label "top k")
• Recall memories — <button data-hathor-nms-submit type="submit"> → POST /v1/admin/hathor/npc-memory-system/recall
• Result — data-hathor-nms-headline, data-hathor-nms-bounds, data-hathor-nms-now, and a data-hathor-nms-memories-list of data-hathor-nms-memory-row rows

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_NPC_MEMORY_SYSTEM_ROUTE_MAP

Quick-action lane#

• "Open Hathor NPC Emotional State workspace" (→ /studio/hathor/npc-emotional-state)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/npc-memory-system (engine summary catalog) on mount
• Writes: POST /v1/admin/hathor/npc-memory-system/recall
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-llm-npc.md (aggregator that embeds this workspace), ./studio-hathor-npc-emotional-state.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorNpcMemorySystemWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorNpcMemorySystemRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The recency half-life is fixed at a 20-hour window in the ranker; confirm whether decay/half-life is meant to be operator-tunable from this lane.
• Route Map advertises profiles/, memories/, timelines/, and governance/ sub-routes with no page.tsx yet.