refactor(memory,gui): Streamline memory archtiecture and terminology

- Short term memory/ recent events are collectively now Cognitive Buffer (Tier 1)

- Long term memory/ memory ledgers are just Memory Ledger (Tier 2)

- Dossiers stay Dossiers (Tier 3)

README.md

@@ -91,7 +91,7 @@ Access the application locally at `http://localhost:3000`.
 
 ### The Actor Agent
 
-Each entity takes turns through an **Actor Agent** that receives a strictly epistemically bounded prompt: its own attributes (public, plus private ones explicitly granted to itself), its subjective memory buffer, the entities co-present at its location, and the current moment. Nothing else. The actor responds with free narrative prose.
+Each entity takes turns through an **Actor Agent** that receives a strictly epistemically bounded prompt: its own attributes (public, plus private ones explicitly granted to itself), its **Cognitive Buffer**, the entities co-present at its location, and the current moment. Nothing else. The actor responds with free narrative prose.
 
 Prose is decoded into typed intents:
 
@@ -121,8 +121,8 @@ Space is a graph: `world → region → location → point of interest`, connect
 
 ### Memory Tiers
 
-- **Verbatim Buffer (implemented):** Per-character subjective event log. Every entry is stored from the owner's perspective actors resolved through the owner's alias map, outcomes attached — and recalled with naturalized time phrasing.
-- **Vector Archive (implemented):** Summarized, embedded memory entries for semantic retrieval, keeping verbatim quotes only for high-salience lines.
+- **Cognitive Buffer (implemented):** Per-character subjective event log. Every entry is stored from the owner's perspective actors resolved through the owner's alias map, outcomes attached — and recalled with naturalized time phrasing.
+- **Memory Ledger (implemented):** Summarized, embedded memory entries for semantic retrieval, keeping verbatim quotes only for high-salience lines.
 - **Dossier (planned):** Each observer's subjective beliefs about another character.
 
 Memory is per-character on purpose: recall is testimony from a vantage point, which is what makes interrogating two witnesses interesting.
@@ -156,14 +156,14 @@ The finish line for the first milestone is small on purpose. `v0` is almost on t
 - [x] Typed intent pipeline: `dialogue` / `action` / `monologue`, decoded from free prose.
 - [x] World Architect: LLM validation plus time-delta generation, end-to-end for single actions.
 - [x] Actor Agent with epistemically-bounded prompts (self, memory, co-located entities, subjective time).
-- [x] Verbatim memory buffer with per-observer subjective serialization and alias resolution.
+- [x] Verbatim Cognitive Buffer with per-observer subjective serialization and alias resolution.
 - [x] Spatial location graph (data model; perception is co-location only).
 - [x] Scenario loader (JSON → SQLite) and a playable CLI loop with human or LLM actors.
 
 **[The `v0` Milestone:](https://github.com/sortedcord/omnia-consolidated/milestone/1)**
 
 - [x] Two hand-authored NPCs live in one location, playable via CLI.
-- [x] Each has buffer and vector-archive memory and recalls something said a few turns earlier.
+- [x] Each has Cognitive Buffer and Memory Ledger memory and recalls something said a few turns earlier.
 - [x] One NPC knows a fact the other does not and, provably by testing, will not leak it.
 - [x] The Architect processes at least one non-trivial action per exchange with a visible state change.
 - [x] The whole thing persists to a SQLite file and reloads identically.

apps/gui/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/gui/src/app/actions.ts

@@ -38,6 +38,7 @@ export async function startSimulation(input: {
   scenario?: string;
   playEntity?: string;
   providerInstanceId?: string;
+  customName?: string;
 }): Promise<ActionResult> {
   try {
     const scenarioFile =
@@ -52,6 +53,7 @@ export async function startSimulation(input: {
       resolved,
       input.playEntity || undefined,
       input.providerInstanceId,
+      input.customName,
     );
 
     if (snapshot.status === "error") {
@@ -348,3 +350,21 @@ export async function fetchAvailableModelsForInstance(
     inst.endpointUrl,
   );
 }
+
+export async function renameSimulation(
+  simId: string,
+  newName: string,
+): Promise<{ ok: true; snapshot: SimSnapshot } | { ok: false; error: string }> {
+  try {
+    const snapshot = await simulationManager.rename(simId, newName);
+    if (!snapshot) {
+      return { ok: false, error: "Simulation session not found" };
+    }
+    return { ok: true, snapshot };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : "Failed to rename simulation",
+    };
+  }
+}

apps/gui/src/components/config/ConfigView.tsx

@@ -103,7 +103,7 @@ export function ConfigView() {
 
   return (
     <div className="flex-1 overflow-y-auto w-full relative">
-      <div className="relative z-10 mx-auto max-w-[800px] px-10 py-12">
+      <div className="relative z-10 mx-auto max-w-[1024px] px-10 py-12">
         <h1 className="mb-6 text-headline-lg text-primary animate-fade-in">
           Configuration
         </h1>
@@ -177,13 +177,13 @@ export function ConfigView() {
                   {
                     key: "handoff",
                     label: "Memory Handoff Engine",
-                    desc: "Promotes entities' working memories to the long-term Ledger via LLM summarization and pruning.",
+                    desc: "Promotes entities' Cognitive Buffer entries to the Memory Ledger via LLM summarization and pruning.",
                     type: "generative",
                   },
                   {
                     key: "embeddings",
                     label: "Text Embeddings Generator",
-                    desc: "Generates vector embeddings for long-term memory retrieval.",
+                    desc: "Generates vector embeddings for Memory Ledger retrieval.",
                     type: "embedding",
                   },
                 ].map((task) => (

apps/gui/src/components/config/ProviderInstancesConfig.tsx

@@ -54,6 +54,16 @@ import { Empty, EmptyTitle, EmptyDescription } from "@/components/ui/empty";
 import { cn } from "@/lib/utils";
 import { RefreshCwIcon } from "lucide-react";
 
+const providerLogoMap: Record<string, string> = {
+  anthropic: "/claude_logo.webp",
+  "google-genai": "/gemini_logo.webp",
+  openrouter: "/openrouter_logo.webp",
+  ollama: "/ollama_logo.webp",
+  deepseek: "/deepseek_logo.webp",
+  openai: "/openai_logo.webp",
+  groq: "/groq_logo.webp",
+};
+
 interface ProviderInstancesConfigProps {
   instances: ModelProviderInstance[];
   availableProviders: ModelProviderMeta[];
@@ -337,7 +347,7 @@ export function ProviderInstancesConfig({
   };
 
   return (
-    <section className="mb-8">
+    <section className="mb-8 flex min-h-[600px] flex-col">
       {error && (
         <div className="mb-4 rounded border-2 border-red-500 bg-red-50 px-3 py-2 text-sm text-red-700">
           {error}
@@ -345,7 +355,7 @@ export function ProviderInstancesConfig({
       )}
       <div
         className={cn(
-          "mt-4 grid min-h-[400px] grid-cols-1 gap-4 md:grid-cols-[30%_70%]",
+          "mt-4 grid flex-1 grid-cols-1 gap-4 md:grid-cols-[30%_70%]",
           loading && "pointer-events-none opacity-60",
           "transition-opacity duration-200",
         )}
@@ -379,14 +389,22 @@ export function ProviderInstancesConfig({
                     )}
                     onClick={() => setSelectedInstanceId(inst.id)}
                   >
-                    <ItemContent>
-                      <ItemTitle>{inst.name}</ItemTitle>
-                      <ItemDescription>{inst.providerName}</ItemDescription>
-                      <div className="flex flex-row gap-1.5">
-                        {inst.isActive && <Badge>Active</Badge>}
-                        <Badge variant="outline">
-                          {inst.type === "generative" ? "gen" : "embed"}
-                        </Badge>
+                    <ItemContent className="flex-row items-center gap-3">
+                      {providerLogoMap[inst.providerName] && (
+                        <img
+                          src={providerLogoMap[inst.providerName]}
+                          alt={inst.providerName}
+                          className="max-h-[38px] max-w-[38px] shrink-0 rounded-sm object-contain"
+                        />
+                      )}
+                      <div className="flex flex-col gap-1">
+                        <ItemTitle>{inst.name}</ItemTitle>
+                        <div className="flex flex-row gap-1.5">
+                          {inst.isActive && <Badge>Active</Badge>}
+                          <Badge variant="outline">
+                            {inst.type === "generative" ? "gen" : "embed"}
+                          </Badge>
+                        </div>
                       </div>
                     </ItemContent>
                   </Item>
@@ -431,6 +449,7 @@ export function ProviderInstancesConfig({
                 <div className="grid grid-cols-[2fr_3fr] gap-4">
                   <div className="flex flex-col gap-1.5">
                     <Label>Instance Type</Label>
+                    {/* TODO: Change this to choice card */}
                     <Select
                       value={editType}
                       onValueChange={(v) =>

apps/gui/src/components/home/HomeView.tsx

@@ -33,6 +33,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Input } from "@/components/ui/input";
 
 export function HomeView() {
   const router = useRouter();
@@ -59,6 +60,7 @@ export function HomeView() {
   const [loadingEntities, setLoadingEntities] = useState(false);
   const [selectedEntityForModal, setSelectedEntityForModal] =
     useState<string>("");
+  const [customName, setCustomName] = useState<string>("");
 
   const loadSavedSessions = useCallback(async () => {
     try {
@@ -144,6 +146,7 @@ export function HomeView() {
     setScenarioForModal(scenario);
     setLoadingEntities(true);
     setSelectedEntityForModal(""); // Reset selection to Spectator
+    setCustomName(scenario.name); // Set custom simulation name default
     try {
       const res = await getScenarioEntities(scenario.path);
       if (res.ok) {
@@ -168,6 +171,7 @@ export function HomeView() {
       const result = await startSimulation({
         scenario: targetScenario.path,
         playEntity: selectedEntityForModal || undefined,
+        customName: customName.trim() || undefined,
       });
 
       if (!result.ok) {
@@ -188,7 +192,7 @@ export function HomeView() {
 
   return (
     <div className="flex-1 overflow-y-auto w-full relative">
-      <div className="relative z-10 mx-auto max-w-[800px] px-10 py-12">
+      <div className="relative z-10 mx-auto max-w-[1024px] px-10 py-12">
         <div className="animate-fade-in">
           {/* Centered Big Logo */}
           <div className="flex flex-col items-center justify-center mb-10 pt-4">
@@ -394,6 +398,16 @@ export function HomeView() {
                   </div>
                 ) : (
                   <div className="flex flex-col gap-4 py-4">
+                    <div className="flex flex-col gap-2">
+                      <label className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono">
+                        Custom Simulation Name
+                      </label>
+                      <Input
+                        value={customName}
+                        onChange={(e) => setCustomName(e.target.value)}
+                        placeholder="Enter custom name..."
+                      />
+                    </div>
                     <div className="flex flex-col gap-2">
                       <label className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono">
                         Simulation Mode / Play as

apps/gui/src/components/play/HandoffModal.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+import { useState } from "react";
+import type { SimSnapshot } from "@/lib/simulation-types";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Badge } from "@/components/ui/badge";
+
+interface HandoffModalProps {
+  entry: SimSnapshot["log"][number];
+  onClose: () => void;
+}
+
+export function HandoffModal({ entry, onClose }: HandoffModalProps) {
+  const [activeTab, setActiveTab] = useState<"chunks" | "prompt" | "output">(
+    "chunks",
+  );
+
+  const handoffResult = entry.handoffResult;
+  const chunks = handoffResult?.chunks || [];
+
+  const getImportanceColor = (score: number) => {
+    if (score >= 8)
+      return "bg-destructive/10 text-destructive border-destructive/30";
+    if (score >= 5) return "bg-amber-500/10 text-amber-500 border-amber-500/30";
+    return "bg-emerald-500/10 text-emerald-500 border-emerald-500/30";
+  };
+
+  return (
+    <Dialog open onOpenChange={(open) => !open && onClose()}>
+      <DialogContent className="max-w-[800px] sm:max-w-[800px] h-[85vh] overflow-hidden flex flex-col p-0 gap-0 border-2">
+        <DialogHeader className="px-6 pt-5 pb-4 border-b">
+          <DialogTitle className="text-lg font-head tracking-wide text-primary flex items-center justify-between">
+            <span>Memory Handoff Details &mdash; {entry.entityName}</span>
+            {entry.usage && (
+              <span className="text-xs font-mono font-normal text-muted-foreground">
+                {entry.usage.modelName || "Handoff Model"}
+              </span>
+            )}
+          </DialogTitle>
+        </DialogHeader>
+
+        {/* Custom Tab Switcher */}
+        <div className="flex border-b bg-muted/20 px-6 py-2 gap-2">
+          <button
+            onClick={() => setActiveTab("chunks")}
+            className={`px-3 py-1.5 text-xs font-medium border transition-all duration-100 ${
+              activeTab === "chunks"
+                ? "border-primary bg-primary/10 text-primary shadow-[1px_1px_0_0_var(--primary)]"
+                : "border-transparent hover:bg-secondary text-muted-foreground"
+            }`}
+          >
+            Promoted Chunks ({chunks.length})
+          </button>
+          <button
+            onClick={() => setActiveTab("prompt")}
+            className={`px-3 py-1.5 text-xs font-medium border transition-all duration-100 ${
+              activeTab === "prompt"
+                ? "border-primary bg-primary/10 text-primary shadow-[1px_1px_0_0_var(--primary)]"
+                : "border-transparent hover:bg-secondary text-muted-foreground"
+            }`}
+          >
+            Raw LLM Prompt
+          </button>
+          <button
+            onClick={() => setActiveTab("output")}
+            className={`px-3 py-1.5 text-xs font-medium border transition-all duration-100 ${
+              activeTab === "output"
+                ? "border-primary bg-primary/10 text-primary shadow-[1px_1px_0_0_var(--primary)]"
+                : "border-transparent hover:bg-secondary text-muted-foreground"
+            }`}
+          >
+            Raw JSON Output
+          </button>
+        </div>
+
+        <div className="overflow-y-auto flex-1 p-6 space-y-4">
+          {activeTab === "chunks" && (
+            <div className="space-y-4">
+              {entry.usage && (
+                <div className="grid grid-cols-3 gap-4 border border-dotted border-border/20 p-3 bg-secondary/10 rounded text-xs font-mono">
+                  <div>
+                    <span className="text-muted-foreground block uppercase tracking-wider text-[10px]">
+                      Input Tokens
+                    </span>
+                    <strong className="text-foreground">
+                      {entry.usage.inputTokens}
+                    </strong>
+                  </div>
+                  <div>
+                    <span className="text-muted-foreground block uppercase tracking-wider text-[10px]">
+                      Output Tokens
+                    </span>
+                    <strong className="text-foreground">
+                      {entry.usage.outputTokens}
+                    </strong>
+                  </div>
+                  <div>
+                    <span className="text-muted-foreground block uppercase tracking-wider text-[10px]">
+                      Total Tokens
+                    </span>
+                    <strong className="text-foreground">
+                      {entry.usage.totalTokens}
+                    </strong>
+                  </div>
+                </div>
+              )}
+
+              {chunks.length === 0 ? (
+                <div className="border border-dotted border-border/30 p-8 text-center bg-card text-muted-foreground rounded">
+                  <p className="text-sm">
+                    No memories were promoted to the Memory Ledger during this
+                    turn.
+                  </p>
+                  <p className="text-xs mt-1">
+                    All Cognitive Buffer entries were summarized or forgotten.
+                  </p>
+                </div>
+              ) : (
+                <div className="space-y-4">
+                  <h3 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono">
+                    Memory Ledger Additions
+                  </h3>
+                  {chunks.map((chunk: any, index: number) => (
+                    <div
+                      key={index}
+                      className="border border-border/30 bg-card p-4 shadow-[2px_2px_0_0_var(--border)] relative flex flex-col gap-3"
+                    >
+                      <div className="flex justify-between items-start gap-4">
+                        <div className="flex-1 text-sm text-foreground/90 leading-relaxed font-sans">
+                          {chunk.content}
+                        </div>
+                        <Badge
+                          variant="outline"
+                          className={`font-mono text-xs ${getImportanceColor(chunk.importance)}`}
+                        >
+                          Importance: {chunk.importance}
+                        </Badge>
+                      </div>
+
+                      {chunk.quotes && chunk.quotes.length > 0 && (
+                        <div className="bg-secondary/10 border-l-2 border-primary/50 p-2.5 my-1 text-xs italic text-muted-foreground space-y-1">
+                          {chunk.quotes.map((quote: string, qIdx: number) => (
+                            <div key={qIdx}>&ldquo;{quote}&rdquo;</div>
+                          ))}
+                        </div>
+                      )}
+
+                      <div className="flex flex-wrap gap-2 text-xs pt-2 border-t border-dotted border-border/10">
+                        {chunk.retainInBuffer ? (
+                          <Badge
+                            variant="outline"
+                            className="bg-primary/5 text-primary border-primary/20 text-[10px] font-mono"
+                          >
+                            Pinned in Buffer
+                          </Badge>
+                        ) : (
+                          <Badge
+                            variant="outline"
+                            className="bg-muted text-muted-foreground border-border/20 text-[10px] font-mono"
+                          >
+                            Pruned from Buffer
+                          </Badge>
+                        )}
+
+                        {chunk.involvedEntityIds &&
+                          chunk.involvedEntityIds.length > 0 && (
+                            <div className="flex items-center gap-1.5 ml-auto text-[10px] font-mono text-muted-foreground">
+                              <span>Entities:</span>
+                              {chunk.involvedEntityIds.map((entId: string) => (
+                                <Badge
+                                  key={entId}
+                                  variant="outline"
+                                  className="text-[10px] px-1 py-0 border-border/20 font-mono"
+                                >
+                                  {entId}
+                                </Badge>
+                              ))}
+                            </div>
+                          )}
+                      </div>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+
+          {activeTab === "prompt" && entry.rawPrompt && (
+            <div className="space-y-4">
+              <div>
+                <h4 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono mb-2">
+                  System Prompt
+                </h4>
+                <pre className="p-3 bg-muted rounded text-xs font-mono whitespace-pre-wrap text-foreground border max-h-[250px] overflow-y-auto">
+                  {entry.rawPrompt.systemPrompt}
+                </pre>
+              </div>
+
+              <div>
+                <h4 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono mb-2">
+                  User Context (Candidates)
+                </h4>
+                <pre className="p-3 bg-muted rounded text-xs font-mono whitespace-pre-wrap text-foreground border max-h-[350px] overflow-y-auto font-sans leading-relaxed font-mono">
+                  {entry.rawPrompt.userContext}
+                </pre>
+              </div>
+            </div>
+          )}
+
+          {activeTab === "output" && (
+            <div className="space-y-2 h-full flex flex-col">
+              <h4 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground font-mono">
+                Raw JSON Output
+              </h4>
+              <pre className="p-3 bg-muted rounded text-xs font-mono whitespace-pre-wrap text-foreground border flex-1 overflow-y-auto max-h-[500px]">
+                {handoffResult
+                  ? JSON.stringify(handoffResult, null, 2)
+                  : "No JSON Output recorded."}
+              </pre>
+            </div>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

apps/gui/src/components/play/InteractView.tsx

@@ -0,0 +1,255 @@
+"use client";
+
+import * as React from "react";
+import { useRouter } from "next/navigation";
+import type { SimSnapshot } from "@/lib/simulation-types";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import {
+  Alert,
+  AlertAction,
+  AlertDescription,
+  AlertTitle,
+} from "@/components/ui/alert";
+
+function IntentTag({
+  intent,
+  isSelf,
+}: {
+  intent: SimSnapshot["log"][number]["intents"][number];
+  isSelf?: boolean;
+}) {
+  const labels: Record<string, string> = {
+    monologue: "thought",
+    dialogue: "dialogue",
+    action: "action",
+  };
+
+  const label = labels[intent.type] || intent.type;
+
+  let outcome = "";
+  if (intent.type === "action") {
+    outcome = intent.isValid ? " ✅" : ` ❌ (${intent.reason})`;
+  }
+
+  const textToDisplay =
+    isSelf && intent.selfDescription
+      ? intent.selfDescription
+      : intent.description;
+
+  const modifiersStr =
+    intent.modifiers && intent.modifiers.length > 0 ? (
+      <span className="italic opacity-80 text-muted-foreground ml-1">
+        ({intent.modifiers.join(", ")})
+      </span>
+    ) : null;
+
+  return (
+    <span className="text-sm text-muted-foreground">
+      [{label}] &ldquo;{textToDisplay}&rdquo;{modifiersStr}
+      {outcome}
+      {intent.minutesToAdvance ? ` [+${intent.minutesToAdvance}min]` : ""}
+    </span>
+  );
+}
+
+function formatSimTime(isoString: string) {
+  try {
+    const d = new Date(isoString);
+    if (isNaN(d.getTime())) return isoString;
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(d.getUTCDate()).padStart(2, "0");
+    const hh = String(d.getUTCHours()).padStart(2, "0");
+    const min = String(d.getUTCMinutes()).padStart(2, "0");
+    const ss = String(d.getUTCSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}:${ss} UTC`;
+  } catch {
+    return isoString;
+  }
+}
+
+function LogEntryCard({
+  entry,
+  onShowPrompt,
+  isPlayerCard,
+}: {
+  entry: SimSnapshot["log"][number];
+  onShowPrompt: (entry: SimSnapshot["log"][number]) => void;
+  isPlayerCard: boolean;
+}) {
+  const showMenu = !!(entry.rawPrompt || entry.decoderPrompt);
+
+  return (
+    <div
+      className={cn(
+        "border p-4 shadow-[2px_2px_0_0_var(--border)]",
+        isPlayerCard
+          ? "border-primary bg-surface-container-low"
+          : "border-border/30 bg-card",
+      )}
+    >
+      <div className="flex justify-between items-center mb-2 border-b border-dotted border-border/20 pb-2">
+        <div className="flex items-center gap-2">
+          <strong className="text-body-md font-bold text-foreground">
+            {entry.entityName}
+          </strong>
+          <span className="text-xs text-muted-foreground font-mono">
+            Turn {entry.turn} &middot; {formatSimTime(entry.timestamp)}
+          </span>
+        </div>
+        {showMenu && (
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => onShowPrompt(entry)}
+            title="View Raw Prompts & Token Usage"
+          >
+            ☰
+          </Button>
+        )}
+      </div>
+      <div className="text-body-md leading-relaxed mb-3 text-foreground/90 whitespace-pre-wrap">
+        {entry.narrativeProse}
+      </div>
+      <div className="flex flex-col gap-1.5 mt-2 border-t border-dotted border-border/10 pt-2">
+        {entry.intents.map((intent, i) => (
+          <IntentTag key={i} intent={intent} isSelf={isPlayerCard} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+interface InteractViewProps {
+  snapshot: SimSnapshot;
+  loading: boolean;
+  statusText: string;
+  playerInput: string;
+  setPlayerInput: (value: string) => void;
+  onSubmitAction: (e: React.FormEvent<HTMLFormElement>) => void;
+  onShowPrompt: (entry: SimSnapshot["log"][number]) => void;
+  onShowHandoff: (entry: SimSnapshot["log"][number]) => void;
+  logEndRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export function InteractView({
+  snapshot,
+  loading,
+  statusText,
+  playerInput,
+  setPlayerInput,
+  onSubmitAction,
+  onShowPrompt,
+  onShowHandoff,
+  logEndRef,
+}: InteractViewProps) {
+  const router = useRouter();
+
+  const playerEntity = snapshot.entities.find((e) => e.isPlayer);
+
+  return (
+    <>
+      {/* Scrollable Center Viewport */}
+      <main className="flex-1 overflow-y-auto px-8 py-6">
+        <div className="flex flex-col gap-4 max-w-[800px] mx-auto pb-12">
+          {snapshot.log.map((entry, i) => {
+            if (entry.isHandoff) {
+              return (
+                <Alert
+                  key={i}
+                  className="max-w-md border-dashed bg-secondary/10"
+                >
+                  <div className="flex-1">
+                    <AlertTitle>
+                      Handoff triggered for {entry.entityName}
+                    </AlertTitle>
+                    <AlertDescription>
+                      Memories were transferred from Cognitive Buffer to Memory
+                      Ledger
+                    </AlertDescription>
+                  </div>
+                  <AlertAction>
+                    <Button
+                      size="xs"
+                      variant="default"
+                      onClick={() => onShowHandoff(entry)}
+                    >
+                      View Details
+                    </Button>
+                  </AlertAction>
+                </Alert>
+              );
+            }
+            return (
+              <LogEntryCard
+                key={i}
+                entry={entry}
+                onShowPrompt={onShowPrompt}
+                isPlayerCard={entry.entityId === playerEntity?.id}
+              />
+            );
+          })}
+          {loading && (
+            <div className="flex items-center gap-2 text-sm italic text-muted-foreground p-2 font-mono">
+              <Spinner />
+              {statusText || "Processing..."}
+            </div>
+          )}
+          <div ref={logEndRef} />
+        </div>
+      </main>
+
+      {/* Sticky Chat / Interaction Input Footer */}
+      <footer className="sticky bottom-0 bg-background/95 backdrop-blur-xs border-t border-dotted border-border/20 px-8 py-4 z-10 shrink-0">
+        <div className="max-w-[800px] mx-auto">
+          {snapshot.status === "waiting_player" && snapshot.waitingEntity ? (
+            <div className="border border-border/30 bg-card p-4 shadow-[2px_2px_0_0_var(--border)]">
+              <details className="mb-3">
+                <summary className="cursor-pointer text-sm font-medium font-head text-primary select-none outline-none">
+                  <strong>Your context as {snapshot.waitingEntity.name}</strong>
+                </summary>
+                <pre className="text-xs whitespace-pre-wrap bg-input border border-border/20 p-2 max-h-[150px] overflow-y-auto mt-2 font-mono">
+                  {snapshot.waitingEntity.userContext}
+                </pre>
+              </details>
+
+              <form onSubmit={onSubmitAction} className="flex flex-col gap-2">
+                <Textarea
+                  value={playerInput}
+                  onChange={(e) => setPlayerInput(e.target.value)}
+                  placeholder="Describe what your character does, says, or thinks..."
+                  rows={3}
+                  disabled={loading}
+                />
+                <Button type="submit" disabled={loading || !playerInput.trim()}>
+                  {loading ? "Processing..." : "Submit Action"}
+                </Button>
+              </form>
+            </div>
+          ) : snapshot.status === "done" || snapshot.status === "error" ? (
+            <div className="flex justify-between items-center bg-card border border-border/30 p-4 shadow-[2px_2px_0_0_var(--border)]">
+              <span className="text-sm font-mono text-muted-foreground">
+                {snapshot.status === "error"
+                  ? "Simulation finished with an error."
+                  : "Simulation complete."}
+              </span>
+              <Button
+                onClick={() => {
+                  router.push("/");
+                }}
+                size="sm"
+              >
+                {snapshot.status === "error"
+                  ? "Back to Dashboard"
+                  : "New Simulation"}
+              </Button>
+            </div>
+          ) : null}
+        </div>
+      </footer>
+    </>
+  );
+}

apps/gui/src/components/play/ManageView.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import * as React from "react";
+import { useState } from "react";
+import type { SimSnapshot } from "@/lib/simulation-types";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { renameSimulation } from "@/app/actions";
+
+interface ManageViewProps {
+  snapshot: SimSnapshot;
+  onRename: (updated: SimSnapshot) => void;
+}
+
+export function ManageView({ snapshot, onRename }: ManageViewProps) {
+  const [isEditingName, setIsEditingName] = useState(false);
+  const [editedName, setEditedName] = useState(snapshot.scenarioName);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  React.useEffect(() => {
+    setEditedName(snapshot.scenarioName);
+  }, [snapshot.scenarioName]);
+
+  const handleSaveName = async () => {
+    if (!editedName.trim()) return;
+    setSaving(true);
+    setError("");
+    try {
+      const res = await renameSimulation(snapshot.id, editedName.trim());
+      if (res.ok) {
+        onRename(res.snapshot);
+        setIsEditingName(false);
+      } else {
+        setError(res.error);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Failed to rename simulation",
+      );
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <main className="flex-1 overflow-y-auto px-8 py-6">
+      <div className="max-w-[800px] mx-auto space-y-6 pb-12">
+        {/* Simulation Info */}
+        <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
+          <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
+            Simulation Info
+          </h3>
+          {error && (
+            <div className="mb-4 border border-destructive bg-destructive/10 px-3 py-2 text-xs text-destructive">
+              {error}
+            </div>
+          )}
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-6 text-sm font-mono">
+            <div className="flex flex-col gap-1 border-b border-border/10 pb-2 md:col-span-2">
+              <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                Simulation Name
+              </span>
+              {isEditingName ? (
+                <div className="flex items-center gap-2 mt-1">
+                  <Input
+                    value={editedName}
+                    onChange={(e) => setEditedName(e.target.value)}
+                    className="h-8 max-w-sm font-sans"
+                    disabled={saving}
+                  />
+                  <Button size="sm" onClick={handleSaveName} disabled={saving}>
+                    {saving ? "Saving..." : "Save"}
+                  </Button>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    onClick={() => setIsEditingName(false)}
+                    disabled={saving}
+                  >
+                    Cancel
+                  </Button>
+                </div>
+              ) : (
+                <div className="flex items-center gap-3">
+                  <span className="text-foreground font-bold text-base font-head">
+                    {snapshot.scenarioName}
+                  </span>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    className="h-6 text-[10px]"
+                    onClick={() => {
+                      setEditedName(snapshot.scenarioName);
+                      setIsEditingName(true);
+                    }}
+                  >
+                    Rename
+                  </Button>
+                </div>
+              )}
+            </div>
+
+            <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+              <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                Session ID
+              </span>
+              <span className="text-foreground font-bold break-all">
+                {snapshot.id}
+              </span>
+            </div>
+            <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+              <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                Max Turns
+              </span>
+              <span className="text-foreground font-bold font-mono">
+                {snapshot.maxTurns}
+              </span>
+            </div>
+            <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+              <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                Turn Count
+              </span>
+              <span className="text-foreground font-bold font-mono">
+                {snapshot.turn}
+              </span>
+            </div>
+            <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+              <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                Entities Registered
+              </span>
+              <span className="text-foreground font-bold font-mono">
+                {snapshot.entities.length}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {/* Entities Involved */}
+        <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
+          <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
+            Entities Involved
+          </h3>
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            {snapshot.entities.map((ent) => (
+              <div
+                key={ent.id}
+                className="border border-border/20 bg-secondary/20 p-4 shadow-[1px_1px_0_0_var(--border)] flex justify-between items-center"
+              >
+                <div>
+                  <strong className="text-sm text-foreground block font-head tracking-wide">
+                    {ent.name}
+                  </strong>
+                  <span className="text-xs text-muted-foreground font-mono block mt-1">
+                    ID: {ent.id}
+                  </span>
+                </div>
+                <div className="flex items-center gap-2">
+                  {ent.isPlayer ? (
+                    <span className="bg-primary/20 text-primary border border-primary/30 px-2 py-0.5 text-xs font-mono">
+                      PLAYER
+                    </span>
+                  ) : (
+                    <span className="bg-secondary/60 text-muted-foreground border border-border/20 px-2 py-0.5 text-xs font-mono">
+                      NPC
+                    </span>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}

apps/gui/src/components/play/PlayView.tsx

@@ -9,9 +9,11 @@ import {
 } from "@/app/actions";
 import type { SimSnapshot } from "@/lib/simulation-types";
 import { Button } from "@/components/ui/button";
-import { Textarea } from "@/components/ui/textarea";
 import { Spinner } from "@/components/ui/spinner";
 import { PromptModal } from "./PromptModal";
+import { HandoffModal } from "./HandoffModal";
+import { InteractView } from "./InteractView";
+import { ManageView } from "./ManageView";
 import { cn } from "@/lib/utils";
 import { ChevronLeft } from "lucide-react";
 import {
@@ -22,114 +24,6 @@ import {
   useSidebar,
 } from "@/components/ui/sidebar";
 
-function IntentTag({
-  intent,
-  isSelf,
-}: {
-  intent: SimSnapshot["log"][number]["intents"][number];
-  isSelf?: boolean;
-}) {
-  const labels: Record<string, string> = {
-    monologue: "thought",
-    dialogue: "dialogue",
-    action: "action",
-  };
-
-  const label = labels[intent.type] || intent.type;
-
-  let outcome = "";
-  if (intent.type === "action") {
-    outcome = intent.isValid ? " ✅" : ` ❌ (${intent.reason})`;
-  }
-
-  const textToDisplay =
-    isSelf && intent.selfDescription
-      ? intent.selfDescription
-      : intent.description;
-
-  const modifiersStr =
-    intent.modifiers && intent.modifiers.length > 0 ? (
-      <span className="italic opacity-80 text-muted-foreground ml-1">
-        ({intent.modifiers.join(", ")})
-      </span>
-    ) : null;
-
-  return (
-    <span className="text-sm text-muted-foreground">
-      [{label}] &ldquo;{textToDisplay}&rdquo;{modifiersStr}
-      {outcome}
-      {intent.minutesToAdvance ? ` [+${intent.minutesToAdvance}min]` : ""}
-    </span>
-  );
-}
-
-function formatSimTime(isoString: string) {
-  try {
-    const d = new Date(isoString);
-    if (isNaN(d.getTime())) return isoString;
-    const yyyy = d.getUTCFullYear();
-    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
-    const dd = String(d.getUTCDate()).padStart(2, "0");
-    const hh = String(d.getUTCHours()).padStart(2, "0");
-    const min = String(d.getUTCMinutes()).padStart(2, "0");
-    const ss = String(d.getUTCSeconds()).padStart(2, "0");
-    return `${yyyy}-${mm}-${dd} ${hh}:${min}:${ss} UTC`;
-  } catch {
-    return isoString;
-  }
-}
-
-function LogEntryCard({
-  entry,
-  onShowPrompt,
-  isPlayerCard,
-}: {
-  entry: SimSnapshot["log"][number];
-  onShowPrompt: (entry: SimSnapshot["log"][number]) => void;
-  isPlayerCard: boolean;
-}) {
-  const showMenu = !!(entry.rawPrompt || entry.decoderPrompt);
-
-  return (
-    <div
-      className={cn(
-        "border p-4 shadow-[2px_2px_0_0_var(--border)]",
-        isPlayerCard
-          ? "border-primary bg-surface-container-low"
-          : "border-border/30 bg-card",
-      )}
-    >
-      <div className="flex justify-between items-center mb-2 border-b border-dotted border-border/20 pb-2">
-        <div className="flex items-center gap-2">
-          <strong className="text-body-md font-bold text-foreground">
-            {entry.entityName}
-          </strong>
-          <span className="text-xs text-muted-foreground font-mono">
-            Turn {entry.turn} &middot; {formatSimTime(entry.timestamp)}
-          </span>
-        </div>
-        {showMenu && (
-          <Button
-            variant="ghost"
-            size="icon"
-            onClick={() => onShowPrompt(entry)}
-            title="View Raw Prompts & Token Usage"
-          >
-            ☰
-          </Button>
-        )}
-      </div>
-      <div className="text-body-md leading-relaxed mb-3 text-foreground/90 whitespace-pre-wrap">
-        {entry.narrativeProse}
-      </div>
-      <div className="flex flex-col gap-1.5 mt-2 border-t border-dotted border-border/10 pt-2">
-        {entry.intents.map((intent, i) => (
-          <IntentTag key={i} intent={intent} isSelf={isPlayerCard} />
-        ))}
-      </div>
-    </div>
-  );
-}
 function MobileSidebarClose() {
   const { isMobile, setOpenMobile } = useSidebar();
   if (!isMobile) return null;
@@ -163,6 +57,9 @@ export function PlayView() {
   const [selectedEntryForModal, setSelectedEntryForModal] = useState<
     SimSnapshot["log"][number] | null
   >(null);
+  const [selectedHandoffForModal, setSelectedHandoffForModal] = useState<
+    SimSnapshot["log"][number] | null
+  >(null);
 
   const logEndRef = useRef<HTMLDivElement>(null);
   const steppingRef = useRef(false);
@@ -482,171 +379,20 @@ export function PlayView() {
             )}
           </header>
 
-          {/* Scrollable Center Viewport */}
-          <main className="flex-1 overflow-y-auto px-8 py-6">
-            {activeTab === "interact" ? (
-              <div className="flex flex-col gap-4 max-w-[800px] mx-auto pb-12">
-                {(() => {
-                  const playerEntity = snapshot.entities.find(
-                    (e) => e.isPlayer,
-                  );
-                  return snapshot.log.map((entry, i) => (
-                    <LogEntryCard
-                      key={i}
-                      entry={entry}
-                      onShowPrompt={setSelectedEntryForModal}
-                      isPlayerCard={entry.entityId === playerEntity?.id}
-                    />
-                  ));
-                })()}
-                {loading && (
-                  <div className="flex items-center gap-2 text-sm italic text-muted-foreground p-2 font-mono">
-                    <Spinner />
-                    {statusText || "Processing..."}
-                  </div>
-                )}
-                <div ref={logEndRef} />
-              </div>
-            ) : (
-              <div className="max-w-[800px] mx-auto space-y-6 pb-12">
-                {/* Simulation Info */}
-                <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
-                  <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
-                    Simulation Info
-                  </h3>
-                  <div className="grid grid-cols-1 md:grid-cols-2 gap-6 text-sm font-mono">
-                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                        Session ID
-                      </span>
-                      <span className="text-foreground font-bold break-all">
-                        {snapshot.id}
-                      </span>
-                    </div>
-                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                        Max Turns
-                      </span>
-                      <span className="text-foreground font-bold">
-                        {snapshot.maxTurns}
-                      </span>
-                    </div>
-                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                        Turn Count
-                      </span>
-                      <span className="text-foreground font-bold">
-                        {snapshot.turn}
-                      </span>
-                    </div>
-                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                        Entities Registered
-                      </span>
-                      <span className="text-foreground font-bold">
-                        {snapshot.entities.length}
-                      </span>
-                    </div>
-                  </div>
-                </div>
-
-                {/* Entities Involved */}
-                <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
-                  <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
-                    Entities Involved
-                  </h3>
-                  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-                    {snapshot.entities.map((ent) => (
-                      <div
-                        key={ent.id}
-                        className="border border-border/20 bg-secondary/20 p-4 shadow-[1px_1px_0_0_var(--border)] flex justify-between items-center"
-                      >
-                        <div>
-                          <strong className="text-sm text-foreground block font-head tracking-wide">
-                            {ent.name}
-                          </strong>
-                          <span className="text-xs text-muted-foreground font-mono block mt-1">
-                            ID: {ent.id}
-                          </span>
-                        </div>
-                        <div className="flex items-center gap-2">
-                          {ent.isPlayer ? (
-                            <span className="bg-primary/20 text-primary border border-primary/30 px-2 py-0.5 text-xs font-mono">
-                              PLAYER
-                            </span>
-                          ) : (
-                            <span className="bg-secondary/60 text-muted-foreground border border-border/20 px-2 py-0.5 text-xs font-mono">
-                              NPC
-                            </span>
-                          )}
-                        </div>
-                      </div>
-                    ))}
-                  </div>
-                </div>
-              </div>
-            )}
-          </main>
-
-          {/* Sticky Chat / Interaction Input Footer */}
-          {activeTab === "interact" && (
-            <footer className="sticky bottom-0 bg-background/95 backdrop-blur-xs border-t border-dotted border-border/20 px-8 py-4 z-10 shrink-0">
-              <div className="max-w-[800px] mx-auto">
-                {snapshot.status === "waiting_player" &&
-                snapshot.waitingEntity ? (
-                  <div className="border border-border/30 bg-card p-4 shadow-[2px_2px_0_0_var(--border)]">
-                    <details className="mb-3">
-                      <summary className="cursor-pointer text-sm font-medium font-head text-primary select-none outline-none">
-                        <strong>
-                          Your context as {snapshot.waitingEntity.name}
-                        </strong>
-                      </summary>
-                      <pre className="text-xs whitespace-pre-wrap bg-input border border-border/20 p-2 max-h-[150px] overflow-y-auto mt-2 font-mono">
-                        {snapshot.waitingEntity.userContext}
-                      </pre>
-                    </details>
-
-                    <form
-                      onSubmit={handleSubmitAction}
-                      className="flex flex-col gap-2"
-                    >
-                      <Textarea
-                        value={playerInput}
-                        onChange={(e) => setPlayerInput(e.target.value)}
-                        placeholder="Describe what your character does, says, or thinks..."
-                        rows={3}
-                        disabled={loading}
-                      />
-                      <Button
-                        type="submit"
-                        disabled={loading || !playerInput.trim()}
-                      >
-                        {loading ? "Processing..." : "Submit Action"}
-                      </Button>
-                    </form>
-                  </div>
-                ) : snapshot.status === "done" ||
-                  snapshot.status === "error" ? (
-                  <div className="flex justify-between items-center bg-card border border-border/30 p-4 shadow-[2px_2px_0_0_var(--border)]">
-                    <span className="text-sm font-mono text-muted-foreground">
-                      {snapshot.status === "error"
-                        ? "Simulation finished with an error."
-                        : "Simulation complete."}
-                    </span>
-                    <Button
-                      onClick={() => {
-                        router.push("/");
-                      }}
-                      size="sm"
-                    >
-                      {snapshot.status === "error"
-                        ? "Back to Dashboard"
-                        : "New Simulation"}
-                    </Button>
-                  </div>
-                ) : null}
-              </div>
-            </footer>
+          {activeTab === "interact" ? (
+            <InteractView
+              snapshot={snapshot}
+              loading={loading}
+              statusText={statusText}
+              playerInput={playerInput}
+              setPlayerInput={setPlayerInput}
+              onSubmitAction={handleSubmitAction}
+              onShowPrompt={setSelectedEntryForModal}
+              onShowHandoff={setSelectedHandoffForModal}
+              logEndRef={logEndRef}
+            />
+          ) : (
+            <ManageView snapshot={snapshot} onRename={setSnapshot} />
           )}
         </div>
 
@@ -662,6 +408,13 @@ export function PlayView() {
             onClose={() => setSelectedEntryForModal(null)}
           />
         )}
+
+        {selectedHandoffForModal && (
+          <HandoffModal
+            entry={selectedHandoffForModal}
+            onClose={() => setSelectedHandoffForModal(null)}
+          />
+        )}
       </div>
     </SidebarProvider>
   );

apps/gui/src/components/play/PromptModal.tsx

@@ -30,8 +30,8 @@ export function PromptModal({ entry, onClose }: PromptModalProps) {
     userContext: string,
     inputTokens: number,
   ) => {
-    const recentHeader = "=== RECENT EVENTS ===";
-    const ledgerHeader = "=== YOUR MEMORIES ===";
+    const recentHeader = "=== COGNITIVE BUFFER ===";
+    const ledgerHeader = "=== MEMORY LEDGER ===";
 
     const recentIdx = userContext.indexOf(recentHeader);
     let worldStr = userContext;
@@ -54,14 +54,14 @@ export function PromptModal({ entry, onClose }: PromptModalProps) {
       { label: "System Prompt", type: "system", content: systemPrompt },
       { label: "World Info", type: "world", content: worldStr },
       {
-        label: "Recent Events",
+        label: "Cognitive Buffer",
         type: "events",
-        content: recentStr || "(No recent events.)",
+        content: recentStr || "(No cognitive buffer entries.)",
       },
       {
-        label: "Long-Term Memories",
+        label: "Memory Ledger",
         type: "memories",
-        content: ledgerStr || "(No long-term memories.)",
+        content: ledgerStr || "(No memory buffer entries.)",
       },
     ];
 

apps/gui/src/components/ui/alert.tsx

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    role="alert"
+    className={cn(
+      "relative w-full rounded border border-border/30 bg-card p-4 text-sm shadow-[2px_2px_0_0_var(--border)] flex flex-col md:flex-row md:items-center gap-3 justify-between",
+      className,
+    )}
+    {...props}
+  />
+));
+Alert.displayName = "Alert";
+
+const AlertTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h5
+    ref={ref}
+    className={cn(
+      "font-head font-bold leading-none tracking-tight text-foreground",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertTitle.displayName = "AlertTitle";
+
+const AlertDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "text-xs text-muted-foreground mt-1 flex-1 leading-relaxed md:mt-0",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDescription.displayName = "AlertDescription";
+
+const AlertAction = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("shrink-0 flex items-center mt-2 md:mt-0 md:ml-4", className)}
+    {...props}
+  />
+));
+AlertAction.displayName = "AlertAction";
+
+export { Alert, AlertTitle, AlertDescription, AlertAction };

apps/gui/src/components/ui/button.tsx

@@ -22,6 +22,7 @@ const buttonVariants = cva(
       size: {
         default: "h-10 px-4 py-2",
         sm: "h-9 px-3 text-xs",
+        xs: "h-7 px-2.5 text-xs",
         lg: "h-11 px-8 text-base",
         icon: "h-10 w-10",
       },

apps/gui/src/lib/simulation-types.ts

@@ -16,6 +16,8 @@ export interface LogEntry {
   narrativeProse: string;
   intents: IntentInfo[];
   timestamp: string;
+  isHandoff?: boolean;
+  handoffResult?: any;
   rawPrompt?: {
     systemPrompt: string;
     userContext: string;

apps/gui/src/lib/simulation/alias-handoff.ts

@@ -3,7 +3,7 @@ import type { SimSession } from "./types";
 
 /**
  * Runs the HandoffEngine for every agent entity that has accumulated enough
- * buffer entries to warrant a handoff (compression to long-term memory).
+ * buffer entries to warrant a handoff (compression to the Memory Ledger).
  */
 export async function runHandoffResolution(session: SimSession): Promise<void> {
   const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
@@ -33,11 +33,36 @@ export async function runHandoffResolution(session: SimSession): Promise<void> {
       maxContext,
     );
     if (trigger !== "none") {
-      await handoffEngine.runHandoff(
+      const ran = await handoffEngine.runHandoff(
         entity,
         bufferEntries,
         worldState.clock.get(),
       );
+      if (ran) {
+        const lastCall =
+          session.handoffProvider.lastCalls?.[
+            (session.handoffProvider.lastCalls?.length || 0) - 1
+          ];
+        const info = session.entities.find((e) => e.id === entity.id);
+        const entityName = info?.name || entity.id;
+        session.log.push({
+          turn: session.turn,
+          entityId: entity.id,
+          entityName,
+          narrativeProse: `Handoff triggered for ${entityName}: memories were transferred from Cognitive Buffer to Memory Ledger`,
+          intents: [],
+          timestamp: worldState.clock.get().toISOString(),
+          isHandoff: true,
+          rawPrompt: lastCall
+            ? {
+                systemPrompt: lastCall.systemPrompt,
+                userContext: lastCall.userContext,
+              }
+            : undefined,
+          usage: lastCall?.usage,
+          handoffResult: lastCall?.response,
+        });
+      }
     }
   }
 }

apps/gui/src/lib/simulation/simulation-manager.ts

@@ -36,6 +36,7 @@ export class SimulationManager {
     scenarioPath: string,
     playEntityName?: string,
     providerInstanceId?: string,
+    customName?: string,
   ): Promise<SimSnapshot> {
     // Resolve or validate the active generative provider upfront so we can
     // return a clean error snapshot before touching the filesystem.
@@ -168,7 +169,7 @@ export class SimulationManager {
       bufferRepo,
       ledgerRepo,
       worldInstanceId,
-      scenarioName: scenarioJson.name,
+      scenarioName: customName || scenarioJson.name,
       scenarioDescription: scenarioJson.description || "",
       turn: 1,
       maxTurns: 20,
@@ -291,6 +292,19 @@ export class SimulationManager {
     return session ? this.snapshot(session) : null;
   }
 
+  async rename(id: string, newName: string): Promise<SimSnapshot | null> {
+    let session = this.sessions.get(id);
+    if (!session) {
+      await this.load(id);
+      session = this.sessions.get(id);
+    }
+    if (!session) return null;
+
+    session.scenarioName = newName;
+    saveSession(session);
+    return this.snapshot(session);
+  }
+
   // ---------------------------------------------------------------------------
   // Simulation stepping
   // ---------------------------------------------------------------------------

packages/actor/src/actor-prompt-builder.ts

@@ -33,17 +33,17 @@ export type ActorResponse = z.infer<typeof ActorResponseSchema>;
  *
  * The prompt is strictly epistemically bounded: the entity only sees what
  * it is allowed to see (public attributes + private attributes explicitly
- * ACL'd to it), its own recent memory buffer, and the entities co-located
+ * ACL'd to it), its own Cognitive Buffer, and the entities co-located
  * with it. System UUIDs are surfaced as subjective aliases.
  */
 export class ActorPromptBuilder {
   /**
-   * @param bufferRepo  Used to fetch the actor's recent memory. Optional —
+   * @param bufferRepo  Used to fetch the actor's Cognitive Buffer. Optional —
    *                    if absent, the memory section is omitted.
-   * @param ledgerRepo  Used to fetch long-term memories. Optional.
-   * @param memoryLimit Maximum number of recent buffer entries to inject.
+   * @param ledgerRepo  Used to fetch Memory Ledger entries. Optional.
+   * @param memoryLimit Maximum number of recent Cognitive Buffer entries to inject.
    *                    Defaults to 20.
-   * @param ledgerLimit Maximum number of long-term memories to retrieve.
+   * @param ledgerLimit Maximum number of Memory Ledger entries to retrieve.
    *                    Defaults to 5.
    */
   constructor(
@@ -111,13 +111,13 @@ Guidelines:
       }
     }
 
-    // --- Recent memory ---
+    // --- Cognitive Buffer ---
     const memorySection = this.buildMemorySection(entity, recentEntries, now);
     if (memorySection) {
       sections.push(memorySection);
     }
 
-    // --- Recalled Long-Term memory ---
+    // --- Recalled Memory Ledger ---
     const ledgerSection = this.buildLedgerSection(
       worldState,
       entity,
@@ -139,7 +139,7 @@ Guidelines:
     if (!this.bufferRepo) return null;
 
     if (entries.length === 0) {
-      return `=== RECENT EVENTS ===\n(No recent events recorded.)`;
+      return `=== COGNITIVE BUFFER ===\n(No recent events recorded.)`;
     }
 
     const recent = entries.slice(-this.memoryLimit);
@@ -159,7 +159,7 @@ Guidelines:
       groupedLines.push(`  - ${serialized}`);
     }
 
-    return `=== RECENT EVENTS ===\n${groupedLines.join("\n")}`;
+    return `=== COGNITIVE BUFFER ===\n${groupedLines.join("\n")}`;
   }
 
   private buildLedgerSection(
@@ -263,6 +263,6 @@ Guidelines:
       }
     }
 
-    return `=== YOUR MEMORIES ===\n${groupedLines.join("\n")}`;
+    return `=== MEMORY LEDGER ===\n${groupedLines.join("\n")}`;
   }
 }

packages/actor/tests/actor-prompt-builder.test.ts

@@ -4,7 +4,7 @@ import { WorldState, Entity } from "@omnia/core";
 import { BufferRepository, LedgerRepository } from "@omnia/memory";
 import { ActorPromptBuilder } from "../src/actor-prompt-builder";
 
-describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
+describe("ActorPromptBuilder with Memory Ledger Integration", () => {
   let db: Database.Database;
   let bufferRepo: BufferRepository;
   let ledgerRepo: LedgerRepository;
@@ -31,7 +31,7 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
     db.close();
   });
 
-  it("should inject both recent memory and recalled long-term memory with subjective aliases resolved", () => {
+  it("should inject both Cognitive Buffer and recalled Memory Ledger entries with subjective aliases resolved", () => {
     const world = new WorldState(
       "world-123",
       new Date("2024-01-10T12:00:00.000Z"),
@@ -60,7 +60,7 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
       },
     });
 
-    // 2. Populate ledger repository (long-term memory)
+    // 2. Populate ledger repository (Memory Ledger)
     ledgerRepo.save({
       id: "ledger1",
       ownerId: "alice",
@@ -76,12 +76,12 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
     const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
     const { userContext } = builder.build(world, alice);
 
-    // Check recent memory exists
-    expect(userContext).toContain("=== RECENT EVENTS ===");
+    // Check Cognitive Buffer exists
+    expect(userContext).toContain("=== COGNITIVE BUFFER ===");
     expect(userContext).toContain("Alice greets Bob");
 
-    // Check long-term memory exists
-    expect(userContext).toContain("=== YOUR MEMORIES ===");
+    // Check Memory Ledger exists
+    expect(userContext).toContain("=== MEMORY LEDGER ===");
     // Bob should be resolved to Strider in the ledger content
     expect(userContext).toContain("alice met Strider at the tavern.");
     expect(userContext).toContain('Quote: "I am a ranger."');
@@ -98,7 +98,7 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
     const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
     const { userContext } = builder.build(world, alice);
 
-    expect(userContext).toContain("=== RECENT EVENTS ===");
-    expect(userContext).not.toContain("=== YOUR MEMORIES ===");
+    expect(userContext).toContain("=== COGNITIVE BUFFER ===");
+    expect(userContext).not.toContain("=== MEMORY LEDGER ===");
   });
 });

packages/llm/chat-openai.md

@@ -1,225 +0,0 @@
-> ## Documentation Index
->
-> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
-> Use this file to discover all available pages before exploring further.
-
-# OpenAI integrations
-
-> Integrate with OpenAI using LangChain JavaScript.
-
-LangChain integrates with OpenAI and Azure OpenAI through the `@langchain/openai` package.
-
-> [OpenAI](https://en.wikipedia.org/wiki/OpenAI) is American artificial intelligence (AI) research laboratory
-> consisting of the non-profit `OpenAI Incorporated`
-> and its for-profit subsidiary corporation `OpenAI Limited Partnership`.
-> OpenAI conducts AI research with the declared intention of promoting and developing a friendly AI.
-> OpenAI systems run on an `Azure`-based supercomputing platform from `Microsoft`.
-
-> The [OpenAI API](https://platform.openai.com/docs/models) is powered by a diverse set of models with different capabilities and price points.
->
-> [ChatGPT](https://chat.openai.com) is the Artificial Intelligence (AI) chatbot developed by `OpenAI`.
-
-## Installation and setup
-
-- Get an OpenAI api key and set it as an environment variable (`OPENAI_API_KEY`)
-
-## Chat model
-
-See a [usage example](/oss/javascript/integrations/chat/openai).
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { ChatOpenAI } from "@langchain/openai";
-```
-
-## LLM
-
-See a [usage example](/oss/javascript/integrations/llms/openai).
-
-<Tip>
-  See [this section for general instructions on installing LangChain packages](/oss/javascript/langchain/install).
-</Tip>
-
-```bash npm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-npm install @langchain/openai @langchain/core
-```
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { OpenAI } from "@langchain/openai";
-```
-
-## Text embedding model
-
-See a [usage example](/oss/javascript/integrations/embeddings/openai)
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { OpenAIEmbeddings } from "@langchain/openai";
-```
-
-## Chain
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { OpenAIModerationChain } from "@langchain/classic/chains";
-```
-
-## Middleware
-
-Middleware specifically designed for OpenAI models. Learn more about [middleware](/oss/javascript/langchain/middleware/overview).
-
-| Middleware                                | Description                                               |
-| ----------------------------------------- | --------------------------------------------------------- |
-| [Content moderation](#content-moderation) | Moderate agent traffic using OpenAI's moderation endpoint |
-
-### Content moderation
-
-Moderate agent traffic (user input, model output, and tool results) using OpenAI's moderation endpoint to detect and handle unsafe content. Content moderation is useful for the following:
-
-- Applications requiring content safety and compliance
-- Filtering harmful, hateful, or inappropriate content
-- Customer-facing agents that need safety guardrails
-- Meeting platform moderation requirements
-
-<Info>
-  Learn more about [OpenAI's moderation models](https://platform.openai.com/docs/guides/moderation) and categories.
-</Info>
-
-**API reference:** [`openAIModerationMiddleware`](https://reference.langchain.com/javascript/langchain/index/openAIModerationMiddleware)
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { createAgent, openAIModerationMiddleware } from "langchain";
-
-const agent = createAgent({
-  model: "openai:gpt-5.5",
-  tools: [searchTool, databaseTool],
-  middleware: [
-    openAIModerationMiddleware({
-      model: "openai:gpt-5.5",
-      moderationModel: "omni-moderation-latest",
-      checkInput: true,
-      checkOutput: true,
-      exitBehavior: "end",
-    }),
-  ],
-});
-```
-
-<Accordion title="Configuration options">
-  <ParamField body="model" type="string | BaseChatModel" required>
-    OpenAI model to use for moderation. Can be either a model name string (e.g., `"openai:gpt-5.5"`) or a `BaseChatModel` instance. The middleware will use this model's client to access the moderation endpoint.
-  </ParamField>
-
-  <ParamField body="moderationModel" type="ModerationModel" default="omni-moderation-latest">
-    OpenAI moderation model to use. Options: `'omni-moderation-latest'`, `'omni-moderation-2024-09-26'`, `'text-moderation-latest'`, `'text-moderation-stable'`
-  </ParamField>
-
-  <ParamField body="checkInput" type="boolean" default="true">
-    Whether to check user input messages before the model is called
-  </ParamField>
-
-  <ParamField body="checkOutput" type="boolean" default="true">
-    Whether to check model output messages after the model is called
-  </ParamField>
-
-  <ParamField body="checkToolResults" type="boolean" default="false">
-    Whether to check tool result messages before the model is called
-  </ParamField>
-
-  <ParamField body="exitBehavior" type="'error' | 'end' | 'replace'" default="'end'">
-    How to handle violations when content is flagged. Options:
-
-    * `'end'` - End agent execution immediately with a violation message
-    * `'error'` - Throw `OpenAIModerationError` exception
-    * `'replace'` - Replace the flagged content with the violation message and continue
-
-  </ParamField>
-
-  <ParamField body="violationMessage" type="string | undefined">
-    Custom template for violation messages. Supports template variables:
-
-    * `{categories}` - Comma-separated list of flagged categories
-    * `{category_scores}` - JSON string of category scores
-    * `{original_content}` - The original flagged content
-
-    Default: `"I'm sorry, but I can't comply with that request. It was flagged for {categories}."`
-
-  </ParamField>
-</Accordion>
-
-<Accordion title="Full example">
-  The middleware integrates OpenAI's moderation endpoint to check content at different stages:
-
-**Moderation stages:**
-
-- `checkInput` - User messages before model call
-- `checkOutput` - AI messages after model call
-- `checkToolResults` - Tool outputs before model call
-
-**Exit behaviors:**
-
-- `'end'` (default) - Stop execution with violation message
-- `'error'` - Throw exception for application handling
-- `'replace'` - Replace flagged content and continue
-
-```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-import { createAgent, openAIModerationMiddleware } from "langchain";
-
-// Basic moderation
-const agent = createAgent({
-  model: "openai:gpt-5.5",
-  tools: [searchTool, customerDataTool],
-  middleware: [
-    openAIModerationMiddleware({
-      model: "openai:gpt-5.5",
-      moderationModel: "omni-moderation-latest",
-      checkInput: true,
-      checkOutput: true,
-    }),
-  ],
-});
-
-// Strict moderation with custom message
-const agentStrict = createAgent({
-  model: "openai:gpt-5.5",
-  tools: [searchTool, customerDataTool],
-  middleware: [
-    openAIModerationMiddleware({
-      model: "openai:gpt-5.5",
-      moderationModel: "omni-moderation-latest",
-      checkInput: true,
-      checkOutput: true,
-      checkToolResults: true,
-      exitBehavior: "error",
-      violationMessage:
-        "Content policy violation detected: {categories}. " +
-        "Please rephrase your request.",
-    }),
-  ],
-});
-
-// Moderation with replacement behavior
-const agentReplace = createAgent({
-  model: "openai:gpt-5.5",
-  tools: [searchTool],
-  middleware: [
-    openAIModerationMiddleware({
-      model: "openai:gpt-5.5",
-      checkInput: true,
-      exitBehavior: "replace",
-      violationMessage: "[Content removed due to safety policies]",
-    }),
-  ],
-});
-```
-
-</Accordion>
-
----
-
-<div className="source-links">
-  <Callout icon="terminal-2">
-    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
-  </Callout>
-
-  <Callout icon="edit">
-    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/providers/openai.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
-  </Callout>
-</div>

packages/llm/src/base-provider.ts

@@ -105,6 +105,7 @@ export abstract class BaseLLMProvider implements ILLMProvider {
       systemPrompt: request.systemPrompt,
       userContext: request.userContext,
       usage,
+      response: parsed,
     });
 
     return { success: true, data: parsed, usage };

packages/llm/src/llm.ts

@@ -33,6 +33,7 @@ export interface LLMCallRecord {
     providerInstanceName?: string;
     maxContext?: number;
   };
+  response?: any;
 }
 
 export interface ILLMProvider {

packages/llm/src/providers/mock.ts

@@ -48,15 +48,21 @@ export class MockLLMProvider implements ILLMProvider {
       return { success: false, error: "Mock responses exhausted" };
     }
     const usage = { inputTokens: 100, outputTokens: 50, totalTokens: 150 };
-    this.lastCalls.push({
-      systemPrompt: request.systemPrompt,
-      userContext: request.userContext,
-      usage,
-    });
     try {
       const parsed = request.schema.parse(next);
+      this.lastCalls.push({
+        systemPrompt: request.systemPrompt,
+        userContext: request.userContext,
+        usage,
+        response: parsed,
+      });
       return { success: true, data: parsed, usage };
     } catch (e) {
+      this.lastCalls.push({
+        systemPrompt: request.systemPrompt,
+        userContext: request.userContext,
+        usage,
+      });
       return {
         success: false,
         error: e instanceof Error ? e.message : String(e),

packages/memory/src/handoff.ts

@@ -33,7 +33,7 @@ export function getMemorySectionLength(
   now: Date,
 ): number {
   if (entries.length === 0) {
-    return `=== RECENT EVENTS ===\n(No recent events recorded.)`.length;
+    return `=== COGNITIVE BUFFER ===\n(No recent events recorded.)`.length;
   }
 
   const groupedLines: string[] = [];
@@ -52,7 +52,7 @@ export function getMemorySectionLength(
     groupedLines.push(`  - ${serialized}`);
   }
 
-  return `=== RECENT EVENTS ===\n${groupedLines.join("\n")}`.length;
+  return `=== COGNITIVE BUFFER ===\n${groupedLines.join("\n")}`.length;
 }
 
 function checkSceneExit(entity: Entity, bufferEntries: BufferEntry[]): boolean {
@@ -227,15 +227,17 @@ export class HandoffEngine {
       .join("\n---\n");
 
     const systemPrompt = `
-You are the memory Handoff Engine. Your task is to process a list of recent working memory buffer entries for an entity and select which memories to promote to the long-term Ledger, and which to forget or summarize.
+You are the memory Handoff Engine. Your task is to process a list of Cognitive Buffer entries for an entity and select which memories to promote to the Memory Ledger, and which to forget or summarize.
 
 Instructions:
-1. **Cluster** related consecutive buffer entries into high-level narrative beats or events (e.g. a full back-and-forth conversation or a single physical action and its outcome). Combine them into a single summary chunk.
-2. **Write in the third-person** for the "content" of each chunk (e.g. "John asked Mary for the key, and Mary reluctantly handed it over").
+1. **Cluster** related consecutive buffer entries into high-level narrative beats or events (e.g. physical action and its outcome or trivial actions). Combine them into a single chunk.
+2. **Write in the third-person** for the events of other entities. (eg. Alan did that. Sarah did this, etc)
+2. **Write in first-person for the events that you yourself did. (eg. I did this, I did that.)
 3. **verbatim Quotes**: Extract verbatim, high-salience quotes from dialogue if relevant. Do not modify or invent quotes.
 4. **Determine Importance**: Assign an importance score from 1 (trivial, e.g. waking up) to 10 (life-altering, e.g. witnessing a crime).
+4. Discard small body movements like looking around, sighing, etc that do not contextually hold any meaning after it is done.
 5. **Involved Entities**: Identify all entity IDs involved in the memories in this chunk.
-6. **Retain in Buffer (Pinning)**: If a beat represents an unresolved high-stakes situation (e.g. a standing threat, an unanswered accusation, an ongoing chase or conflict), set "retainInBuffer" to true so it remains in the working memory buffer for immediate context. Otherwise, set it to false so it is safely pruned from the buffer.
+6. **Retain in Cognitive Buffer (Pinning)**: If a beat represents an unresolved high-stakes situation (e.g. a standing threat, an unanswered accusation, an ongoing chase or conflict), set "retainInBuffer" to true so it remains in the Cognitive Buffer for immediate context. Otherwise, set it to false so it is safely pruned from the Cognitive Buffer.
 7. **Exclude stage business**: Glances, sighs, ambient noticing, and irrelevant sensory details should be ignored and not included in any promoted chunk. They will be forgotten.
 8. **Forget by omission**: Any buffer entry ID that you do not include in any chunk's "sourceEntryIds" will be permanently deleted and forgotten.
 `.trim();

web/docs/src/content/docs/architecture/actor.md

@@ -7,7 +7,7 @@ The Actor Agent is the system component that embodies a single entity and produc
 
 ## Design Principles
 
-1. **Epistemic boundedness** — The actor only sees what its entity would perceive: public attributes of other entities, private attributes explicitly ACL'd to it, its own memory buffer, and co-located entities. It does not have system-level access to all world state.
+1. **Epistemic boundedness** — The actor only sees what its entity would perceive: public attributes of other entities, private attributes explicitly ACL'd to it, its own Cognitive Buffer, and co-located entities. It does not have system-level access to all world state.
 
 2. **Proposal, not mutation** — The actor generates a _proposal_ (narrative prose). It never mutates world state, persists to the database, or writes to memory directly. Validation, execution, and persistence are the Architect's job.
 
@@ -38,7 +38,7 @@ Epistemically bounded, with these sections:
 | ---------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- |
 | Current moment               | The subjective present time                                                                        | `worldState.clock.get().toISOString()` |
 | The world as you perceive it | Self-visible attributes, co-located entities + their visible attributes, other presences elsewhere | `serializeSubjectiveWorldState()`      |
-| Your recent memory           | Recent `BufferEntry`s, alias-substituted, with relative time phrasing                              | `serializeSubjectiveBufferEntry()`     |
+| Your cognitive buffer        | Recent `BufferEntry`s, alias-substituted, with relative time phrasing                              | `serializeSubjectiveBufferEntry()`     |
 
 No system UUIDs, no private attributes the entity lacks ACL access to, and no objective-world-state dump are present.
 

web/docs/src/content/docs/architecture/handoff.md

@@ -1,15 +1,15 @@
 ---
 title: Memory Handoff Pipeline
-description: The Tier 1 (Working Buffer) to Tier 2 (Long-Term Ledger) memory promotion architecture
+description: The Cognitive Buffer to Memory Ledger promotion architecture
 sidebar:
   order: 6
 ---
 
 :::tip[Status: Fully Implemented]
-The handoff pipeline is fully integrated into the simulation step loop. The `HandoffEngine` and `checkHandoffTrigger` components process working memory entries, promoting them to the persistent episodic Ledger, while safely pruning the subjective working memory buffer.
+The handoff pipeline is fully integrated into the simulation step loop. The `HandoffEngine` and `checkHandoffTrigger` components process Cognitive Buffer entries, promoting them to the persistent Memory Ledger, while safely pruning the Cognitive Buffer.
 :::
 
-The **Handoff** pipeline manages the promotion of subjective experiences from the short-term working memory (Tier 1 Buffer) to long-term episodic memory (Tier 2 Ledger). This process regulates context window utilization by deciding **when** promotion occurs, **how much** of the buffer is processed, and **what** details are preserved or pruned.
+The **Handoff** pipeline manages the promotion of subjective experiences from the **Cognitive Buffer** to the **Memory Ledger**. This process regulates context window utilization by deciding **when** promotion occurs, **how much** of the Cognitive Buffer is processed, and **what** details are preserved or pruned.
 
 To maintain performance and prevent context bloat, the pipeline separates the process into three decoupled stages:
 
@@ -46,7 +46,7 @@ Voluntary triggers identify natural narrative boundaries where the entity is ina
 
 Involuntary triggers enforce context constraints before building the next prompt to prevent token limit overflows:
 
-- **Buffer Ceiling**: The serialized length of the working memory section (as generated by `getMemorySectionLength`) exceeds a configured fraction (default: 60%) of the provider's context window.
+- **Buffer Ceiling**: The serialized length of the Cognitive Buffer section (as generated by `getMemorySectionLength`) exceeds a configured fraction (default: 60%) of the provider's context window.
 - **Event Velocity**: The number of buffer entries exceeds a safe threshold (default: 20), indicating an event-heavy scene generating history faster than voluntary boundaries occur.
 
 If the buffer is empty, trigger detection exits immediately with `"none"`.
@@ -55,13 +55,13 @@ If the buffer is empty, trigger detection exits immediately with `"none"`.
 
 ## 2. Watermark Partitioning
 
-To preserve short-term narrative continuity and avoid immediate memory decay, recent events are protected from handoff. The pipeline divides the active buffer into a protected **Watermark Tail** and a **Candidate Pool**.
+To preserve narrative continuity and avoid immediate memory decay, recent events are protected from handoff. The pipeline divides the active Cognitive Buffer into a protected **Watermark Tail** and a **Candidate Pool**.
 
 The watermark boundary is computed as:
 
 $$\text{Watermark} = \max(K \text{ entries}, \text{entries bucketed as fresh by } \textit{naturalizeTime})$$
 
-- **Hard Floor ($K = 8$)**: The last 8 entries in the buffer are always preserved.
+- **Hard Floor ($K = 8$)**: The last 8 entries in the Cognitive Buffer are always preserved.
 - **Temporal Freshness**: Any entries that `naturalizeTime` classifies within the immediate temporal horizon (`"just now"`, `"moments ago"`, `"a few minutes ago"`, or `"several minutes ago"`) are also protected.
 
 Entries older than the watermark boundary constitute the **Candidate Pool** and are eligible for handoff processing.
@@ -100,8 +100,8 @@ The prompt instructs the model to apply the following cognitive operations:
 
 When a chunk represents an unresolved high-stakes situation (e.g., an active conflict or standing threat), the LLM sets `retainInBuffer: true`.
 
-- The summary is committed to the long-term Ledger as normal.
-- The source buffer entries are exempted from pruning, remaining in the working memory buffer with `pinned: true` until a future handoff pass determines the thread is resolved.
+- The summary is committed to the Memory Ledger as normal.
+- The source Cognitive Buffer entries are exempted from pruning, remaining in the Cognitive Buffer with `pinned: true` until a future handoff pass determines the thread is resolved.
 
 ---
 

web/docs/src/content/docs/architecture/memory-tier2.md

@@ -1,15 +1,15 @@
 ---
-title: Tier 2 Memory (Long-Term Ledger)
+title: Memory Ledger
 description: Persistent episodic memory storage, semantic indexing, and retrieval mechanics
 ---
 
-**Tier 2 Memory (the Ledger)** represents an entity's long-term episodic memory. It archives historical summaries of past events, providing a persistent record of character experiences that can be retrieved and injected into LLM prompts as needed.
+**Memory Ledger** represents an entity's persistent episodic memory. It archives historical summaries of past events, providing a durable record of character experiences that can be retrieved and injected into LLM prompts as needed.
 
 ---
 
 ## 1. Data Model
 
-A long-term memory is represented by a `LedgerEntry`. It includes metadata for deterministic database-level filtering, structured narrative content, and vector embeddings for semantic similarity scoring.
+A Memory Ledger entry is represented by a `LedgerEntry`. It includes metadata for deterministic database-level filtering, structured narrative content, and vector embeddings for semantic similarity scoring.
 
 ```ts
 interface LedgerEntry {
@@ -30,7 +30,7 @@ interface LedgerEntry {
 
 ## 2. Storage Model
 
-To support fast, low-latency queries across large historical datasets, Tier 2 memory is stored in standard SQLite tables. Vector embeddings are stored in raw binary format as `Float32Array` BLOBs.
+To support fast, low-latency queries across large historical datasets, Memory Ledger entries are stored in standard SQLite tables. Vector embeddings are stored in raw binary format as `Float32Array` BLOBs.
 
 Standard secondary indices optimize query execution time to microseconds, eliminating the compilation and cross-platform installation overhead of native vector database extensions (such as `sqlite-vec` or `node-gyp` binaries).
 
@@ -64,7 +64,7 @@ CREATE INDEX IF NOT EXISTS idx_ledger_involved_entity ON ledger_involved_entitie
 
 ## 3. The Handoff Pipeline
 
-Working memory (Tier 1 Buffer) entries are promoted to the Ledger through the automated [Handoff Pipeline](./handoff).
+**Cognitive Buffer** entries are promoted to the Memory Ledger through the automated [Handoff Pipeline](./handoff).
 
 During handoff:
 
@@ -72,7 +72,7 @@ During handoff:
 2. Ambient stage business and redundant details are pruned.
 3. Chunks are synthesized into third-person summaries and assigned importance scores.
 4. Text embeddings are generated for the summary.
-5. The processed memories are committed to the SQLite store, and the short-term buffer is pruned.
+5. The processed memories are committed to the SQLite store, and the Cognitive Buffer is pruned.
 
 ---
 
@@ -116,13 +116,13 @@ Once the candidate pool is loaded, the ranking engine evaluates entries in appli
 
 ## 5. Active Focus & Attention Loop
 
-In crowded settings (e.g., a room with many characters), retrieving long-term memories for all co-located entities would exhaust the prompt context window. To prevent this, retrieval uses an **Active Focus** selection strategy:
+In crowded settings (e.g., a room with many characters), retrieving Memory Ledger entries for all co-located entities would exhaust the prompt context window. To prevent this, retrieval uses an **Active Focus** selection strategy:
 
-- **Active Focus Set**: The prompt builder scans the last 10 entries of the character's working memory buffer. Any entity targeted by, spoken to, or mentioned in these entries is added to the Active Focus set.
+- **Active Focus Set**: The prompt builder scans the last 10 entries of the character's Cognitive Buffer. Any entity targeted by, spoken to, or mentioned in these entries is added to the Active Focus set.
 - **Dynamic Capacity Limits**:
-  - If the number of co-located characters is small ($\le 3$), long-term memory is retrieved for all of them.
-  - If the environment is crowded ($> 3$), long-term retrieval is strictly restricted to the top 3 characters in the Active Focus set.
-- This creates a realistic attention loop: when a new character interacts with the actor, they enter the working buffer, triggering the retrieval of their long-term history on the subsequent turn.
+  - If the number of co-located characters is small ($\le 3$), Memory Ledger entries are retrieved for all of them.
+  - If the environment is crowded ($> 3$), Memory Ledger retrieval is strictly restricted to the top 3 characters in the Active Focus set.
+- This creates a realistic attention loop: when a new character interacts with the actor, they enter the Cognitive Buffer, triggering the retrieval of their Memory Ledger history on the subsequent turn.
 
 ---
 
@@ -130,15 +130,15 @@ In crowded settings (e.g., a room with many characters), retrieving long-term me
 
 Retrieved ledger entries are formatted into the prompt chronologically and mapped to subjective aliases. Internal metrics (e.g., importance numbers and raw system IDs) are omitted to preserve immersion.
 
-- Working memory entries are injected under `=== RECENT EVENTS ===` (narrated relative to the present moment).
-- Recalled ledger entries are injected under `=== YOUR MEMORIES ===` (presented as long-term recollections).
+- Cognitive Buffer entries are injected under `=== COGNITIVE BUFFER ===` (narrated relative to the present moment).
+- Recalled Memory Ledger entries are injected under `=== MEMORY LEDGER ===` (presented as episodic recollections).
 
 ```text
-=== RECENT EVENTS ===
+=== COGNITIVE BUFFER ===
 Moments ago
   - You spoke to Strider: "Hello there"
 
-=== YOUR MEMORIES ===
+=== MEMORY LEDGER ===
 A couple days ago
   - You met a hooded figure named Strider at The Prancing Pony.
     Quote: "I can avoid being seen, if I wish, but to disappear entirely, that is a rare gift."