---
path: /studio/hathor/npc-memory-system
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/npc-memory-system/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# 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`](../../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`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-hathor-llm-npc.md`](./studio-hathor-llm-npc.md)
  (aggregator that embeds this workspace),
  [`./studio-hathor-npc-emotional-state.md`](./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.