Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(society): the Memory House - the shared memory as a building on the island

rubenluetke10-beep49607e9c8b4b
diff --git a/docs/agent-society/agent-definition.md b/docs/agent-society/agent-definition.md
index 23a605a8c5..dc0e83ae6a 100644
--- a/docs/agent-society/agent-definition.md
+++ b/docs/agent-society/agent-definition.md
@@ -264,6 +264,10 @@ the archive" on it; the ledger shows the five fields.
## 5. Memory: the Obsidian wiki is the society's shared store
+> Built 2026-09-02 as the **Memory House** — service, hands, prompt section, review gate, REST and
+> the island building: [`memory-house.md`](memory-house.md) is the binding description; this
+> section keeps the original direction.
+
Maintainer direction (2026-09-01): the agents continue and use the wiki we built as their
common memory. This refines MASTERPLAN §3.1 / §6.6 — the `knowledge` table becomes a staging
and provenance layer; the vault is where knowledge lives.
diff --git a/docs/agent-society/memory-house.md b/docs/agent-society/memory-house.md
index 9b703a3787..d29457a917 100644
--- a/docs/agent-society/memory-house.md
+++ b/docs/agent-society/memory-house.md
@@ -129,11 +129,12 @@ unchanged and lands with the five-layer change it needs.
### 3.5 The Memory House on the island
-- Replaces the primitive Archive tower and takes two house slots on the north-east of the ring
- (mirror of the Plugin Docks in the north-west); the `archive` place keeps its id, so the
- walkers, the labels and the checkpoint enum need no new value.
-- Built by `scripts/world/build_world_kit.py --target memory-house` (the Blender MCP drives the
- inner loop; the committed script is the truth): a dark plinth with a glowing reflecting ring,
+- Replaces the primitive Archive tower on the archive plot at the island's north end (behind
+ the Jarvis Hub, on the axis — the ring's slots are taken by the hubs and the Agent Foundry);
+ the `archive` place keeps its id, so the walkers, the labels and the checkpoint enum need no
+ new value.
+- Built by `scripts/world/kit_memory_house.py` on the helpers of `build_world_kit.py` (the Blender
+ MCP drives the inner loop; the committed script is the truth; ~4 600 triangles, 8 × 6 tiles): a dark plinth with a glowing reflecting ring,
a translucent glass monolith with a luminous core sphere and stacked "memory layers" inside, a
cantilevered roof slab with a light edge, a tilted halo ring with light nodes, two data pylons
and a floating MEMORY sign.
@@ -154,14 +155,14 @@ the service refuses a `remember`/`note` body that matches the secret guard patte
| # | Item | Where | Done when |
|---|---|---|---|
-| 1 | `SocietyMemory` service: head, recall, remember, note, propose_shared, promote, dismiss, overview; `DIGEST kind=memory` per op; `type: society` frontmatter; secret guard | `jarvis/society/memory.py` | `tests/unit/society/test_memory.py` green |
-| 2 | Tools: `society_memory_recall`; `society_wiki_note` delegates to the service and accepts `kind: shared` | `agent_tools.py`, `surface.py` | tool tests green, briefing shows `## Your memory` |
-| 3 | Checkpoint engine + `SocietyCheckpointChanged` + runtime hooks (run start/end, memory activity, approval enqueue/resolve, room open/settle) | `checkpoints.py`, `runtime.py`, `jarvis/core/events.py` | `test_checkpoints.py` green; the roster row flips to `archive` after a memory op |
-| 4 | REST: `GET /api/society/memory`, `POST /api/society/memory/recall`, `POST /api/society/memory/{id}/promote`, `POST …/dismiss`; approvals resolve promotes `core:memory:share` items | `society_routes.py` | route tests green; CLI coverage gate green |
-| 5 | Blender: `build_memory_house()`; GLB exported; preview checked through the MCP | `scripts/world/build_world_kit.py`, `assets/society/world/kit/memory-house.glb` | GLB in the tree, ≤ 3 000 triangles |
-| 6 | Island: `archive` becomes a ring kit place (slots 2–3), old tower removed, stand tile in front, labels renamed, house count test updated | `islandLayout.ts`, `KitBuilding.tsx`, `Landmarks.tsx`, `PlaceLabels.tsx`, locales | `islandLayout.test.ts` green |
-| 7 | Memory drawer + live core signal + WS invalidation on `SocietyCheckpointChanged` | `MemoryHouseDrawer.tsx`, `KitBuilding.tsx`, `WorldStage.tsx`, `useWebSocket.ts` | drawer opens on click; core glows when an agent is at the house |
-| 8 | Docs: this file, `jarvis/society/README.md`, `world-behaviour-manual.md` §3 note, `agent-definition.md` §5 pointer | docs | privacy review of touched docs |
+| 1 ✅ | `SocietyMemory` service: head, recall, remember, note, propose_shared, promote, dismiss, overview; `DIGEST kind=memory` per op; `type: society` frontmatter; secret guard | `jarvis/society/memory.py` | `tests/unit/society/test_memory.py` green |
+| 2 ✅ | Tools: `society_memory_recall`; `society_wiki_note` delegates to the service and accepts `kind: shared` | `agent_tools.py`, `surface.py` | tool tests green, briefing shows `## Your memory` |
+| 3 ✅ | Checkpoint engine + `SocietyCheckpointChanged` + runtime hooks (run start/end, memory activity, approval enqueue/resolve, room open/settle) | `checkpoints.py`, `runtime.py`, `jarvis/core/events.py` | `test_checkpoints.py` green; the roster row flips to `archive` after a memory op |
+| 4 ✅ | REST: `GET /api/society/memory`, `POST /api/society/memory/recall`, `POST /api/society/memory/{id}/promote`, `POST …/dismiss`; approvals resolve promotes `core:memory:share` items | `society_routes.py` | route tests green; CLI coverage gate green |
+| 5 ✅ | Blender: `build_memory_house()`; GLB exported; preview checked through the MCP | `scripts/world/kit_memory_house.py`, `assets/society/world/kit/memory-house.glb` | GLB in the tree (4 584 triangles: the glass, the core and the halo cost more than a hall; trimmed bevels keep it near the other hubs) |
+| 6 ✅ | Island: the Memory House stands on the archive plot, old tower removed, footprint blocks walking, label renamed in three locales | `MemoryHouse.tsx`, `Landmarks.tsx`, `islandLayout.ts`, `PlaceLabels.tsx`, locales | `islandLayout.test.ts` green |
+| 7 ✅ | Memory drawer + live core signal + WS invalidation on `SocietyCheckpointChanged` | `MemoryDrawer.tsx`, `MemoryHouse.tsx`, `WorldStage.tsx`, `useWebSocket.ts` | drawer opens on click; core glows when an agent is at the house |
+| 8 ✅ | Docs: this file, `jarvis/society/README.md`, `world-behaviour-manual.md` §3 note, `agent-definition.md` §5 pointer | docs | privacy review of touched docs |
| 9 | Bundle rebuilt (`npm run build`), commits per wave by pathspec, no push | — | the running app shows the house after its self-reload |
## 5. Tests
diff --git a/docs/agent-society/world-behaviour-manual.md b/docs/agent-society/world-behaviour-manual.md
index 275fbe3a9c..69dc32ecf6 100644
--- a/docs/agent-society/world-behaviour-manual.md
+++ b/docs/agent-society/world-behaviour-manual.md
@@ -29,7 +29,7 @@ gesture becomes a typed event, and the figure follows because the truth changed.
| `hub:cli` | Terminal Cantina | working through a CLI seat (Claude Code, Codex, …) |
| `hub:workshop` | Workshop | core file/shell work, no dominant family |
| `hub:models` | Model Foundry | its brain is a local model that is currently inferring |
-| `archive` | Archive | writing knowledge / a reviewed promotion |
+| `archive` | **Memory House** | touching the shared memory: a recall, a memory line, a note, a share proposal (20 s hold — `memory-house.md` §3.4) |
| `gallery` | Gallery | delivering a `RESULT` (carries the crate) |
| `gate` | Harbor Gate | waiting for an `ask`-tier approval |
| `foundry` | Agent Foundry | being created (3 s), or changing its avatar |
@@ -53,7 +53,7 @@ sees. Rules, in priority order; the first that matches wins:
capability catalog of `agent-definition.md` §3.1). The place changes only when a different
family has dominated for **≥ 20 s** — hysteresis, so a figure never ping-pongs between shops.
A local-brain agent whose model is inferring right now → `hub:models` outranks the family.
-6. A knowledge write in the last 6 s → `archive`.
+6. A memory touch in the last 20 s → `archive` (the Memory House). **Built:** `jarvis/society/checkpoints.py` derives `paused → idle`, `gate`, `meeting`, `archive`, `desk`, `idle` over today's vocabulary and publishes `SocietyCheckpointChanged`; the `hub:*` rules join with the five-layer change.
7. Being created / avatar change → `foundry`.
8. Otherwise → `wander`.
@@ -71,7 +71,7 @@ short, cached section — the world card — and nothing else:
You live in a small island village with your fellow agents. Places: your house (rest),
the market square (group discussions), the Plugin Docks (plugin tools), the Skill
Forge (skills), the Relay Tower (MCP servers), the Terminal Cantina (coding CLIs),
-the Workshop (files and shell), the Archive (shared memory), the Gallery (finished
+the Workshop (files and shell), the Memory House (the shared memory), the Gallery (finished
work), the Harbor Gate (waiting for approval), the Agent Foundry (where agents are
created). You are placed by what you actually do; you cannot move yourself. When you
mention your location, use these names.
diff --git a/jarvis/society/README.md b/jarvis/society/README.md
index 80651213d0..a0778f4964 100644
--- a/jarvis/society/README.md
+++ b/jarvis/society/README.md
@@ -20,7 +20,9 @@ live under the scheduler and the voice router tool (M4) are not.
| `approvals.py` | the unattended ask-queue: require > always-allow > tier vs ceiling; expiry parks, never drops |
| `routines.py` | per-agent routines as tagged Automations tasks |
| `surface.py` | the `society` chat surface: per-session hands (grant/focus/deny), the briefing, the ecosystem card |
-| `agent_tools.py` | `society_message_agent` (one typed envelope to ONE teammate), `society_wiki_note` (writes only under `society/<agent>/`), `society_shell` (the agent's own contained shell) |
+| `memory.py` | the society's ONE memory service (`docs/agent-society/memory-house.md`): head, recall (own > shared > user > others' unreviewed, every hit labelled), remember, note, propose_shared → approval `core:memory:share`, promote into `society/shared/`, dismiss, overview; every touch is a `DIGEST kind=memory` on the board |
+| `checkpoints.py` | where an agent IS on the island, derived from the board by trusted rules (paused, gate, meeting, archive after a memory touch with a 20 s hold, desk, idle); persists the roster row and publishes `SocietyCheckpointChanged` for the island |
+| `agent_tools.py` | `society_message_agent` (one typed envelope to ONE teammate), `society_wiki_note` (kind memory / note / shared, through `memory.py`), `society_memory_recall` (the labelled lookup), `society_shell` (the agent's own contained shell) |
| `shell.py` | the shell backend seam: `LocalBackend` now (local by decision), path containment, caps |
| `browser/` | the agent's browser: one-click venv install of browser-use, the in-venv runner, per-agent persistent profiles + login sessions, `society_browser` |
| `learning.py` | automatic learning: turn digest → skill in the agent's own namespace, `society_run_skill`, promotion to the global registry as a draft |
diff --git a/jarvis/ui/web/frontend/src/assets/society/world/kit/memory-house.glb b/jarvis/ui/web/frontend/src/assets/society/world/kit/memory-house.glb
new file mode 100644
index 0000000000..28b27421b7
Binary files /dev/null and b/jarvis/ui/web/frontend/src/assets/society/world/kit/memory-house.glb differ
diff --git a/jarvis/ui/web/frontend/src/components/society/world/MemoryDrawer.tsx b/jarvis/ui/web/frontend/src/components/society/world/MemoryDrawer.tsx
new file mode 100644
index 0000000000..1dae00cb20
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/MemoryDrawer.tsx
@@ -0,0 +1,277 @@
+/**
+ * What a click on the Memory House opens: the society's shared memory as a
+ * drawer over the island — the reviewed team knowledge, every agent's memory
+ * head, the review queue with Promote / Mark reviewed, and a recall search
+ * that shows hits the way an agent sees them (scope and trust labels).
+ * Data: /api/society/memory (docs/agent-society/memory-house.md §3.5).
+ * App chrome, so it wears the theme tokens.
+ */
+import { useEffect, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Check, ExternalLink, Search, Share2, X } from "lucide-react";
+
+import { useT } from "@/i18n";
+import { useEventStore } from "@/store/events";
+
+interface MemoryOverview {
+ shared: Array<{ path: string; title: string; author: string; updated_ms: number }>;
+ agents: Array<{
+ agent_id: string;
+ name: string;
+ title: string;
+ memory_head: string;
+ notes: number;
+ checkpoint: string;
+ }>;
+ unreviewed: Array<{
+ id: number;
+ agent_id: string;
+ path: string;
+ origin: string;
+ summary: string;
+ created_ms: number;
+ }>;
+ vault_root: string;
+}
+
+interface Hit {
+ path: string;
+ title: string;
+ scope: string;
+ label: string;
+ snippet: string;
+}
+
+const MEMORY_KEY = ["society", "memory"] as const;
+
+async function getOverview(): Promise<MemoryOverview> {
+ const res = await fetch("/api/society/memory");
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ return (await res.json()) as MemoryOverview;
+}
+
+async function post(url: string, body?: unknown): Promise<unknown> {
+ const res = await fetch(url, {
+ method: "POST",
+ headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ return res.json();
+}
+
+const SCOPE_COLOR: Record<string, string> = {
+ own: "#7df9ff",
+ shared: "#ffd166",
+ user: "#b388ff",
+ other: "#c9c2b2",
+};
+
+export function MemoryDrawer({ onClose }: { onClose: () => void }) {
+ const t = useT();
+ const setActiveSection = useEventStore((s) => s.setActiveSection);
+ const client = useQueryClient();
+ const overview = useQuery({ queryKey: MEMORY_KEY, queryFn: getOverview, staleTime: 15_000 });
+ const [query, setQuery] = useState("");
+ const [hits, setHits] = useState<Hit[] | null>(null);
+
+ const refresh = () => {
+ void client.invalidateQueries({ queryKey: MEMORY_KEY });
+ void client.invalidateQueries({ queryKey: ["society", "roster"] });
+ };
+ const promote = useMutation({
+ mutationFn: (id: number) => post(`/api/society/memory/${id}/promote`),
+ onSuccess: refresh,
+ });
+ const dismiss = useMutation({
+ mutationFn: (id: number) => post(`/api/society/memory/${id}/dismiss`),
+ onSuccess: refresh,
+ });
+ const recall = useMutation({
+ mutationFn: (q: string) =>
+ post("/api/society/memory/recall", { query: q, k: 8 }) as Promise<{ hits: Hit[] }>,
+ onSuccess: (data) => setHits(data.hits),
+ });
+
+ useEffect(() => {
+ const onKey = (e: KeyboardEvent) => {
+ if (e.key === "Escape") onClose();
+ };
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, [onClose]);
+
+ const data = overview.data;
+
+ return (
+ <aside
+ className="absolute inset-y-3 right-3 z-30 flex w-[380px] max-w-[85%] flex-col overflow-hidden rounded-lg border border-border bg-popover text-foreground shadow-float"
+ role="dialog"
+ aria-label={t("society.world.drawer_memory_title")}
+ >
+ <header className="flex items-start justify-between gap-3 border-b border-border px-4 py-3">
+ <div className="min-w-0">
+ <h2 className="font-display text-base font-semibold tracking-tight">{t("society.world.drawer_memory_title")}</h2>
+ <p className="mt-0.5 text-xs text-muted-foreground">{t("society.world.drawer_memory_hint")}</p>
+ </div>
+ <button
+ type="button"
+ onClick={onClose}
+ aria-label={t("society.world.drawer_close")}
+ className="rounded-md p-1 text-muted-foreground hover:bg-muted hover:text-foreground"
+ >
+ <X size={16} />
+ </button>
+ </header>
+
+ <form
+ className="flex items-center gap-2 border-b border-border px-4 py-2"
+ onSubmit={(e) => {
+ e.preventDefault();
+ if (query.trim()) recall.mutate(query.trim());
+ }}
+ >
+ <Search size={14} className="shrink-0 text-muted-foreground" aria-hidden />
+ <input
+ value={query}
+ onChange={(e) => setQuery(e.target.value)}
+ placeholder={t("society.world.memory_search_placeholder")}
+ className="h-7 min-w-0 flex-1 bg-transparent text-sm text-foreground outline-none placeholder:text-muted-foreground"
+ />
+ <button
+ type="submit"
+ disabled={recall.isPending || !query.trim()}
+ className="h-7 rounded-md bg-secondary px-2 text-xs font-medium text-foreground hover:bg-muted disabled:opacity-50"
+ >
+ {t("society.world.memory_search_button")}
+ </button>
+ </form>
+
+ <div className="min-h-0 flex-1 overflow-y-auto px-4 py-3">
+ {overview.isLoading && <p className="text-sm text-muted-foreground">{t("society.world.drawer_loading")}</p>}
+ {overview.isError && <p className="text-sm text-destructive">{String(overview.error)}</p>}
+
+ {hits && (
+ <section className="mb-4">
+ <h3 className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ {t("society.world.memory_hits")} <span className="tabular-nums">{hits.length}</span>
+ </h3>
+ {hits.length === 0 && <p className="text-sm text-muted-foreground">{t("society.world.memory_no_hits")}</p>}
+ <ul className="space-y-1.5">
+ {hits.map((h) => (
+ <li key={h.path} className="rounded-md bg-secondary px-2 py-1.5 text-xs">
+ <div className="flex items-center gap-2">
+ <span className="inline-block h-2 w-2 rounded-sm" style={{ background: SCOPE_COLOR[h.scope] ?? "#c9c2b2" }} aria-hidden />
+ <span className="font-medium text-foreground">{h.title}</span>
+ <span className="ml-auto font-mono text-[10px] text-muted-foreground">{h.label}</span>
+ </div>
+ {h.snippet && <p className="mt-0.5 line-clamp-2 text-muted-foreground">{h.snippet}</p>}
+ </li>
+ ))}
+ </ul>
+ </section>
+ )}
+
+ {data && (
+ <>
+ <section className="mb-4">
+ <h3 className="mb-1.5 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ <span className="inline-block h-2.5 w-2.5 rounded-sm" style={{ background: SCOPE_COLOR.shared }} aria-hidden />
+ {t("society.world.memory_shared")}
+ <span className="tabular-nums">{data.shared.length}</span>
+ </h3>
+ {data.shared.length === 0 ? (
+ <p className="text-sm text-muted-foreground">{t("society.world.memory_empty_shared")}</p>
+ ) : (
+ <ul className="flex flex-wrap gap-1.5">
+ {data.shared.map((s) => (
+ <li key={s.path} className="rounded-md bg-secondary px-2 py-1 text-xs text-foreground" title={s.path}>
+ {s.title}
+ </li>
+ ))}
+ </ul>
+ )}
+ </section>
+
+ <section className="mb-4">
+ <h3 className="mb-1.5 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ <span className="inline-block h-2.5 w-2.5 rounded-sm" style={{ background: SCOPE_COLOR.own }} aria-hidden />
+ {t("society.world.memory_agents")}
+ <span className="tabular-nums">{data.agents.length}</span>
+ </h3>
+ <ul className="space-y-2">
+ {data.agents.map((a) => (
+ <li key={a.agent_id} className="rounded-md border border-border px-2 py-1.5">
+ <div className="flex items-center gap-2 text-xs">
+ <span className="font-medium text-foreground">{a.name}</span>
+ {a.title && <span className="truncate text-muted-foreground">{a.title}</span>}
+ <span className="ml-auto tabular-nums text-muted-foreground">
+ {t("society.world.memory_notes").replace("{count}", String(a.notes))}
+ </span>
+ </div>
+ <p className="mt-0.5 line-clamp-3 whitespace-pre-line text-xs text-muted-foreground">
+ {a.memory_head || t("society.world.memory_nothing_remembered")}
+ </p>
+ </li>
+ ))}
+ </ul>
+ </section>
+
+ <section className="mb-2">
+ <h3 className="mb-1.5 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ <span className="inline-block h-2.5 w-2.5 rounded-sm" style={{ background: SCOPE_COLOR.other }} aria-hidden />
+ {t("society.world.memory_queue")}
+ <span className="tabular-nums">{data.unreviewed.length}</span>
+ </h3>
+ {data.unreviewed.length === 0 ? (
+ <p className="text-sm text-muted-foreground">{t("society.world.memory_empty_queue")}</p>
+ ) : (
+ <ul className="space-y-1.5">
+ {data.unreviewed.map((u) => (
+ <li key={u.id} className="rounded-md bg-secondary px-2 py-1.5 text-xs">
+ <div className="flex items-center gap-2">
+ <span className="font-medium text-foreground">{u.agent_id}</span>
+ <span className="font-mono text-[10px] text-muted-foreground">{u.origin}</span>
+ </div>
+ <p className="mt-0.5 line-clamp-2 text-muted-foreground">{u.summary}</p>
+ <div className="mt-1.5 flex gap-1.5">
+ <button
+ type="button"
+ disabled={promote.isPending}
+ onClick={() => promote.mutate(u.id)}
+ className="inline-flex h-6 items-center gap-1 rounded-md bg-background px-2 text-[11px] font-medium text-foreground hover:bg-muted disabled:opacity-50"
+ >
+ <Share2 size={11} />
+ {t("society.world.memory_promote")}
+ </button>
+ <button
+ type="button"
+ disabled={dismiss.isPending}
+ onClick={() => dismiss.mutate(u.id)}
+ className="inline-flex h-6 items-center gap-1 rounded-md bg-background px-2 text-[11px] font-medium text-muted-foreground hover:bg-muted disabled:opacity-50"
+ >
+ <Check size={11} />
+ {t("society.world.memory_dismiss")}
+ </button>
+ </div>
+ </li>
+ ))}
+ </ul>
+ )}
+ </section>
+ </>
+ )}
+ </div>
+ <footer className="border-t border-border px-4 py-3">
+ <button
+ type="button"
+ onClick={() => setActiveSection("memory")}
+ className="inline-flex h-8 items-center gap-2 rounded-md bg-secondary px-3 text-sm font-medium text-foreground hover:bg-muted"
+ >
+ <ExternalLink size={14} />
+ {t("society.world.memory_open_wiki")}
+ </button>
+ </footer>
+ </aside>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/MemoryHouse.tsx b/jarvis/ui/web/frontend/src/components/society/world/MemoryHouse.tsx
new file mode 100644
index 0000000000..ce663748f2
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/MemoryHouse.tsx
@@ -0,0 +1,189 @@
+/**
+ * The Memory House on the archive plot — the society's shared memory as a
+ * building (docs/agent-society/memory-house.md §3.5). The GLB comes from
+ * `scripts/world/kit_memory_house.py`; this component gives it the life the
+ * file cannot carry: the halo turns, the core breathes, the memory shards
+ * drift, and everything brightens while an agent stands at the house.
+ *
+ * "An agent is at the house" is read from the roster's `checkpoint` — the
+ * same truth the walkers follow — never from anything the building decides.
+ * Reduced motion freezes the lot. Effects write to materials and transforms
+ * inside `useFrame`, never through React state.
+ *
+ * The monolith is translucent: the GLB's BLEND materials keep their alpha
+ * here (the shared kit restyle drops it), so the core shows through the glass.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useGLTF } from "@react-three/drei";
+import { useFrame, useThree, type ThreeEvent } from "@react-three/fiber";
+import {
+ Color,
+ Mesh,
+ MeshBasicMaterial,
+ MeshStandardMaterial,
+ MeshToonMaterial,
+ type Object3D,
+} from "three";
+import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils.js";
+
+import memoryHouseUrl from "@/assets/society/world/kit/memory-house.glb";
+import { useCameraStore } from "./cameraStore";
+import { buildIsland, groundY, tileToWorld, type PlaceId } from "./islandLayout";
+import { createToonRamp } from "./worldMaterials";
+
+/** Emission above this strength renders unlit (a lamp, the core), below it stays a lit toon. */
+const GLOW_STRENGTH = 1.5;
+/** The core's resting and busy colours (the GLB palette in kit_memory_house.py). */
+const CORE_REST = new Color("#7df9ff");
+const CORE_BUSY = new Color("#ffffff");
+const SHARD_REST = new Color("#b388ff");
+const SHARD_BUSY = new Color("#e9d5ff");
+
+interface Rig {
+ halo: Object3D | null;
+ orb: Object3D | null;
+ orbMat: MeshBasicMaterial | null;
+ shards: Array<{ obj: Object3D; baseY: number; phase: number; mat: MeshBasicMaterial | null }>;
+ glow: MeshBasicMaterial[];
+}
+
+function restyle(root: Object3D, ramp: ReturnType<typeof createToonRamp>): Rig {
+ const rig: Rig = { halo: null, orb: null, orbMat: null, shards: [], glow: [] };
+ root.traverse((o) => {
+ if (!(o instanceof Mesh)) return;
+ const src = o.material as MeshStandardMaterial;
+ if (!(src instanceof MeshStandardMaterial)) return;
+ const emissiveStrength = src.emissiveIntensity * Math.max(src.emissive.r, src.emissive.g, src.emissive.b);
+ const translucent = src.transparent && src.opacity < 0.999;
+ if (emissiveStrength >= GLOW_STRENGTH && !translucent) {
+ const mat = new MeshBasicMaterial({ color: src.emissive.clone() });
+ o.material = mat;
+ if (o.name.startsWith("shard_") || o.name === "core_orb" || o.name.startsWith("pylon_light") || o.name.startsWith("band_") || o.name === "roof_edge" || o.name === "pool_ring") {
+ rig.glow.push(mat);
+ }
+ } else {
+ o.material = new MeshToonMaterial({
+ color: src.color.clone(),
+ gradientMap: ramp,
+ emissive: emissiveStrength > 0 ? src.emissive.clone() : new Color(0, 0, 0),
+ emissiveIntensity: emissiveStrength > 0 ? Math.min(0.6, src.emissiveIntensity) : 0,
+ transparent: translucent,
+ opacity: translucent ? src.opacity : 1,
+ depthWrite: !translucent,
+ });
+ if (translucent) o.renderOrder = 10; // the glass draws after what it contains
+ }
+ o.castShadow = !translucent;
+ o.receiveShadow = true;
+ });
+ rig.halo = root.getObjectByName("halo") ?? null;
+ rig.orb = root.getObjectByName("core_orb") ?? null;
+ const orb = rig.orb;
+ rig.orbMat = orb instanceof Mesh && orb.material instanceof MeshBasicMaterial ? orb.material : null;
+ for (let i = 0; i < 12; i++) {
+ const obj = root.getObjectByName(`shard_${i}`);
+ if (!obj) break;
+ const mat = obj instanceof Mesh && obj.material instanceof MeshBasicMaterial ? obj.material : null;
+ rig.shards.push({ obj, baseY: obj.position.y, phase: i * 0.9, mat });
+ }
+ return rig;
+}
+
+export function MemoryHouse({
+ paused,
+ busy,
+ onClick,
+ selected,
+}: {
+ paused: boolean;
+ /** How many agents stand at the house right now (roster checkpoints). */
+ busy: number;
+ onClick?: (place: PlaceId) => void;
+ selected?: boolean;
+}) {
+ const { scene } = useGLTF(memoryHouseUrl);
+ const gl = useThree((s) => s.gl);
+ const [hover, setHover] = useState(false);
+ const ramp = useMemo(createToonRamp, []);
+ const rig = useRef<Rig | null>(null);
+ const instance = useMemo(() => {
+ const clone = SkeletonUtils.clone(scene);
+ rig.current = restyle(clone, ramp);
+ return clone;
+ }, [scene, ramp]);
+ const heat = useRef(0);
+
+ useEffect(
+ () => () => {
+ instance.traverse((o) => {
+ if (o instanceof Mesh) (o.material as MeshToonMaterial | MeshBasicMaterial).dispose();
+ });
+ ramp.dispose();
+ },
+ [instance, ramp],
+ );
+
+ useEffect(() => {
+ if (!onClick) return;
+ gl.domElement.style.cursor = hover ? "pointer" : "";
+ return () => {
+ gl.domElement.style.cursor = "";
+ };
+ }, [hover, gl, onClick]);
+
+ useFrame(({ clock }, dt) => {
+ const r = rig.current;
+ if (!r || paused) return;
+ const step = Math.min(dt, 0.1);
+ const t = clock.getElapsedTime();
+ // Ease toward "busy" so a figure arriving lights the house up, not on.
+ const target = busy > 0 ? 1 : 0;
+ heat.current += (target - heat.current) * Math.min(1, step * 1.6);
+ const h = heat.current;
+ if (r.halo) r.halo.rotation.y += (0.12 + h * 0.5) * step;
+ if (r.orb) {
+ const pulse = 1 + Math.sin(t * (1.4 + h * 2.2)) * (0.04 + h * 0.08);
+ r.orb.scale.setScalar(pulse);
+ }
+ if (r.orbMat) r.orbMat.color.copy(CORE_REST).lerp(CORE_BUSY, 0.25 + h * 0.75);
+ for (const s of r.shards) {
+ s.obj.position.y = s.baseY + Math.sin(t * 0.9 + s.phase) * (0.12 + h * 0.2);
+ s.obj.rotation.y += (0.15 + h * 0.6) * step;
+ if (s.mat) s.mat.color.copy(SHARD_REST).lerp(SHARD_BUSY, h);
+ }
+ });
+
+ const { map, content } = buildIsland();
+ const [tx, tz] = content.places.archive.tile;
+ const [x, z] = tileToWorld(tx, tz);
+ const y = groundY(map, x, z);
+
+ const click = (e: ThreeEvent<MouseEvent>) => {
+ if (!onClick) return;
+ e.stopPropagation();
+ if (useCameraStore.getState().dragging) return;
+ onClick("archive");
+ };
+
+ return (
+ <group
+ position={[x, y, z]}
+ onClick={click}
+ onPointerOver={(e) => {
+ e.stopPropagation();
+ setHover(true);
+ }}
+ onPointerOut={() => setHover(false)}
+ >
+ <primitive object={instance} />
+ {(hover || selected) && (
+ <mesh position={[0, 0.06, 0]} rotation={[-Math.PI / 2, 0, 0]}>
+ <ringGeometry args={[11.2, 11.8, 48]} />
+ <meshBasicMaterial color={selected ? "#ffd166" : "#fffaf0"} transparent opacity={0.85} />
+ </mesh>
+ )}
+ </group>
+ );
+}
+
+useGLTF.preload(memoryHouseUrl);
diff --git a/jarvis/ui/web/frontend/src/hooks/useWebSocket.ts b/jarvis/ui/web/frontend/src/hooks/useWebSocket.ts
index 4ae5cffd14..c140d6feb6 100644
--- a/jarvis/ui/web/frontend/src/hooks/useWebSocket.ts
+++ b/jarvis/ui/web/frontend/src/hooks/useWebSocket.ts
@@ -315,6 +315,13 @@ export function useWebSocket(): void {
}
}
+ // A society agent's derived place changed (trusted rules in the
+ // backend): the island re-reads its roster so the figure walks now,
+ // not on the next 30 s poll.
+ if (env.event_name === "SocietyCheckpointChanged") {
+ void queryClient.invalidateQueries({ queryKey: ["society", "roster"] });
+ }
+
if (env.event_name === "TranscriptionUpdate") {
const p = env.payload as { text?: string; is_final?: boolean };
if (typeof p.text === "string") {
diff --git a/scripts/world/kit_memory_house.py b/scripts/world/kit_memory_house.py
new file mode 100644
index 0000000000..bbb4ded9bd
--- /dev/null
+++ b/scripts/world/kit_memory_house.py
@@ -0,0 +1,307 @@
+# ruff: noqa: E501
+"""The Memory House — the society's shared memory as a building
+(``docs/agent-society/memory-house.md`` §3.5), built on the helpers of
+``build_world_kit.py`` and kept in its own module so sessions never edit the
+same file. Run inside Blender::
+
+ blender -b --python scripts/world/kit_memory_house.py -- --out <kit dir> [--preview out.png]
+
+or through the Blender MCP with ``KIT_ARGS`` (and ``KIT_BASE_PATH``) set;
+``--keep-scene`` leaves everything else in the scene alone and removes only
+the building it made after export.
+
+The look: a dark slate plinth with a luminous reflecting ring, a translucent
+glass monolith with a glowing memory core and floating memory shards inside,
+a cantilevered roof slab with a light edge, a tilted halo ring with light
+nodes, two data pylons flanking the entrance, and a floating MEMORY sign.
+Nodes the island animates by name: ``core_orb``, ``halo``, ``shard_<n>``,
+``pool_ring``, ``pylon_light_<l|r>``. Contract (§4.1): origin at the ground
+centre, the front (door) faces Blender −Y = glTF +Z, metres.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import math
+import sys
+from pathlib import Path
+
+import bpy # type: ignore[import-not-found]
+
+_BASE_PATH = (
+ Path(__file__).resolve().parent / "build_world_kit.py" if "__file__" in globals() else None
+)
+
+
+def _load_base(path: Path):
+ spec = importlib.util.spec_from_file_location("kit_base", str(path))
+ mod = importlib.util.module_from_spec(spec)
+ assert spec.loader is not None
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _base():
+ path = _BASE_PATH or Path(globals().get("KIT_BASE_PATH", ""))
+ return _load_base(path)
+
+
+MEMORY_PALETTE = {
+ "slate": "#343948",
+ "obsidian": "#15171e",
+ "mem_glass": "#9fd8ff",
+ "mem_frame": "#dfe9f3",
+ "mem_core": "#7df9ff",
+ "mem_core_hot": "#eafdff",
+ "mem_violet": "#b388ff",
+ "mem_pool": "#4cc9f0",
+ "mem_gold": "#ffd166",
+}
+
+# Footprint 8 x 6 tiles (16 x 12 m); the monolith is 9 x 7 m and 12 m tall.
+W, D = 16.0, 12.0
+MONO_W, MONO_D, MONO_H = 9.0, 7.0, 12.0
+PLINTH_Z = 0.45
+
+
+def _glass(k, key: str, alpha: float, emissive: float = 0.0) -> bpy.types.Material:
+ """A translucent flat material; the island keeps the alpha (the glTF alphaMode)."""
+ mat = k.material(key, emissive)
+ mat = mat.copy()
+ mat.name = f"kit_{key}_a{int(alpha * 100)}"
+ bsdf = mat.node_tree.nodes.get("Principled BSDF")
+ rgba = k.hex_rgba(k.PALETTE[key])
+ bsdf.inputs["Base Color"].default_value = (rgba[0], rgba[1], rgba[2], alpha)
+ if "Alpha" in bsdf.inputs:
+ bsdf.inputs["Alpha"].default_value = alpha
+ if hasattr(mat, "surface_render_method"):
+ mat.surface_render_method = "BLENDED"
+ if hasattr(mat, "blend_method"):
+ mat.blend_method = "BLEND"
+ mat.show_transparent_back = False
+ return mat
+
+
+def _torus(k, name, major, minor, at, mat_key, parent, rot=(0, 0, 0), emissive=0.0, segments=32):
+ """A ring in the XY plane before `rot` (own helper: the base module's is optional)."""
+ bpy.ops.mesh.primitive_torus_add(
+ location=at, rotation=rot, major_radius=major, minor_radius=minor,
+ major_segments=segments, minor_segments=8,
+ )
+ obj = bpy.context.active_object
+ obj.name = name
+ _set_material(obj, k.material(mat_key, emissive))
+ obj.parent = parent
+ return obj
+
+
+def _icosphere(k, name, radius, at, mat, parent, subdivisions=2):
+ bpy.ops.mesh.primitive_ico_sphere_add(subdivisions=subdivisions, radius=radius, location=at)
+ obj = bpy.context.active_object
+ obj.name = name
+ obj.data.materials.clear()
+ obj.data.materials.append(mat)
+ obj.parent = parent
+ bpy.ops.object.shade_smooth()
+ return obj
+
+
+def _set_material(obj, mat):
+ obj.data.materials.clear()
+ obj.data.materials.append(mat)
+
+
+def build_memory_house(k) -> bpy.types.Object:
+ root = k.new_root(
+ "memory-house",
+ {
+ "jarvis_building": {
+ "contract": 1,
+ "id": "memory-house",
+ "footprint": [8, 6],
+ "forward": "+Z",
+ "door": [0, 3.6],
+ "stand": [0, 8.5],
+ "sign": [0, 15.5, 0],
+ "lights": ["core_orb", "halo", "pool_ring", "pylon_light_l", "pylon_light_r"],
+ "height_m": 15.0,
+ }
+ },
+ )
+ y_front = -D / 2
+
+ # --- plinth: a dark slate slab with a lit reflecting ring cut into it
+ k.box("plinth", (W + 0.6, D + 0.6, PLINTH_Z), (0, 0, PLINTH_Z / 2), "slate", root, bevel=0.12)
+ k.box("plinth_band", (W + 0.9, D + 0.9, 0.12), (0, 0, 0.06), "obsidian", root, bevel=0.0)
+ pool = _torus(k, "pool_ring", 6.1, 0.14, (0, 0.4, PLINTH_Z + 0.02), "mem_pool", root, emissive=2.2, segments=36)
+ pool.scale = (1.0, 0.8, 1.0)
+ bpy.context.view_layer.objects.active = pool
+ bpy.ops.object.transform_apply(scale=True)
+ # entrance steps down to the plaza (front)
+ for i in range(3):
+ k.box(
+ f"step_{i}",
+ (6.0 - i * 0.6, 0.9, PLINTH_Z - i * 0.15),
+ (0, y_front - 0.25 - i * 0.8, (PLINTH_Z - i * 0.15) / 2),
+ "slate",
+ root,
+ bevel=0.0,
+ )
+
+ # --- the monolith: a translucent glass block on four light frame columns
+ z0 = PLINTH_Z
+ glass = _glass(k, "mem_glass", 0.32, emissive=0.25)
+ mono = k.box("monolith", (MONO_W, MONO_D, MONO_H), (0, 0.4, z0 + MONO_H / 2), "mem_glass", root, bevel=0.22)
+ _set_material(mono, glass)
+ for sx in (-1, 1):
+ for sy in (-1, 1):
+ k.box(
+ f"column_{'l' if sx < 0 else 'r'}{'f' if sy < 0 else 'b'}",
+ (0.42, 0.42, MONO_H + 0.6),
+ (sx * (MONO_W / 2 + 0.05), 0.4 + sy * (MONO_D / 2 + 0.05), z0 + (MONO_H + 0.6) / 2),
+ "mem_frame",
+ root,
+ bevel=0.06,
+ )
+ # horizontal light bands wrapping the glass at each memory layer
+ for i, zz in enumerate((2.6, 5.4, 8.2, 11.0)):
+ k.box(
+ f"band_{i}",
+ (MONO_W + 0.28, MONO_D + 0.28, 0.12),
+ (0, 0.4, z0 + zz),
+ "mem_core",
+ root,
+ bevel=0.0,
+ emissive=1.8,
+ )
+
+ # --- inside: the memory core and the floating shards
+ core_mat = k.material("mem_core_hot", 4.0)
+ _icosphere(k, "core_orb", 1.55, (0, 0.4, z0 + 6.4), core_mat, root, subdivisions=2)
+ inner_mat = k.material("mem_core", 2.4)
+ _icosphere(k, "core_halo", 2.05, (0, 0.4, z0 + 6.4), _glass(k, "mem_core", 0.28, 1.2), root, subdivisions=1)
+ k.cylinder("core_spine", 0.22, MONO_H - 0.8, (0, 0.4, z0 + MONO_H / 2), "mem_frame", root, verts=10, bevel=0.0, emissive=0.6)
+ shard_specs = [
+ (-2.6, -1.4, 2.4, 0.35, 1.3, 0.28),
+ (2.4, 1.2, 3.6, -0.5, 1.5, -0.22),
+ (-1.9, 1.9, 5.0, 0.8, 1.1, 0.4),
+ (2.7, -1.6, 7.4, -0.3, 1.6, 0.15),
+ (-2.4, 0.6, 8.9, 0.55, 1.2, -0.35),
+ (1.7, 2.1, 10.2, -0.7, 1.4, 0.3),
+ (0.9, -2.3, 4.3, 0.2, 1.0, -0.5),
+ ]
+ for i, (x, y, z, rz, size, rx) in enumerate(shard_specs):
+ k.box(
+ f"shard_{i}",
+ (size, 0.08, size * 0.62),
+ (x, 0.4 + y, z0 + z),
+ "mem_violet",
+ root,
+ bevel=0.0,
+ emissive=1.9,
+ rot=(rx, 0, rz),
+ )
+ # light strips on the floor inside the glass (data lanes)
+ for i, x in enumerate((-3.2, -1.6, 0, 1.6, 3.2)):
+ k.box(f"lane_{i}", (0.12, MONO_D - 1.0, 0.04), (x, 0.4, z0 + 0.06), "mem_core", root, bevel=0.0, emissive=1.6)
+ del inner_mat
+
+ # --- the door: a dark portal in the front glass with a light frame
+ k.box("door_frame", (3.4, 0.5, 4.4), (0, y_front + 2.5 + 0.4 - 0.0, z0 + 2.2), "mem_frame", root, bevel=0.06)
+ k.box("door_frame_glow", (3.0, 0.2, 4.0), (0, y_front + 2.5 + 0.4 - 0.2, z0 + 2.0), "mem_core", root, bevel=0.0, emissive=2.0)
+ k.box("door", (2.4, 0.3, 3.5), (0, y_front + 2.5 + 0.4 - 0.3, z0 + 1.75), "obsidian", root, bevel=0.03)
+
+ # --- the roof: a cantilevered dark slab floating above the glass, lit edge
+ roof_z = z0 + MONO_H + 0.8
+ k.box("roof_slab", (MONO_W + 2.6, MONO_D + 2.0, 0.36), (0, 0.4 - 0.5, roof_z), "slate", root, bevel=0.1)
+ k.box("roof_edge", (MONO_W + 2.8, MONO_D + 2.2, 0.08), (0, 0.4 - 0.5, roof_z - 0.22), "mem_core", root, bevel=0.0, emissive=1.7)
+ k.box("roof_fin", (0.8, MONO_D + 0.4, 1.0), (MONO_W / 2 + 0.9, 0.4, roof_z + 0.65), "obsidian", root, bevel=0.06)
+ for sx in (-1, 1):
+ k.cylinder(f"roof_post_{'l' if sx < 0 else 'r'}", 0.16, 0.9, (sx * 3.2, 0.4, z0 + MONO_H + 0.45), "mem_frame", root, verts=8, bevel=0.0)
+
+ # --- the halo: a tilted ring of light nodes orbiting above the roof
+ halo_z = z0 + 9.4
+ halo = _torus(k, "halo", 6.2, 0.11, (0, 0.4, halo_z), "mem_frame", root, rot=(math.radians(14), 0, 0), emissive=0.9, segments=28)
+ node_mat = k.material("mem_gold", 3.2)
+ for i in range(8):
+ a = i / 8 * math.pi * 2
+ x = math.cos(a) * 6.2
+ y = math.sin(a) * 6.2
+ # tilt the node ring with the halo (rotation about X by 14 deg)
+ yy = y * math.cos(math.radians(14))
+ zz = y * math.sin(math.radians(14))
+ n = _icosphere(k, f"halo_node_{i}", 0.3, (x, 0.4 + yy, halo_z + zz), node_mat, root, subdivisions=1)
+ n.parent = halo
+ n.matrix_parent_inverse = halo.matrix_world.inverted()
+
+ # --- two data pylons flanking the steps: slim prisms with a light seam
+ for sx, tag in ((-1, "l"), (1, "r")):
+ px = sx * 5.6
+ py = y_front - 0.6
+ k.box(f"pylon_{tag}", (0.9, 0.9, 6.2), (px, py, z0 + 3.1), "obsidian", root, bevel=0.06)
+ k.box(f"pylon_light_{tag}", (0.18, 0.95, 5.4), (px, py, z0 + 3.1), "mem_core", root, bevel=0.0, emissive=2.6)
+ k.box(f"pylon_cap_{tag}", (1.1, 1.1, 0.25), (px, py, z0 + 6.35), "mem_frame", root, bevel=0.04)
+
+ # --- the sign: floating letters above the door with a thin light rail
+ k.box("sign_rail", (7.6, 0.14, 0.14), (0, y_front + 0.9, z0 + 5.4), "mem_frame", root, bevel=0.0, emissive=0.5)
+ k.text_mesh("sign_text", "MEMORY", 1.25, 0.22, (0, y_front + 1.05, z0 + 6.25), "mem_core_hot", root, emissive=3.2)
+
+ # --- garden edges: two low planters with light-blue shrubs
+ for sx in (-1, 1):
+ k.box(f"planter_{'l' if sx < 0 else 'r'}", (2.4, 1.2, 0.6), (sx * (W / 2 - 1.6), 0.4 + D / 2 - 1.0, z0 + 0.3), "slate", root, bevel=0.05)
+ k.cylinder(f"shrub_{'l' if sx < 0 else 'r'}", 0.7, 0.9, (sx * (W / 2 - 1.6), 0.4 + D / 2 - 1.0, z0 + 1.0), "mem_pool", root, verts=10, bevel=0.25)
+ return root
+
+
+def main(argv: list[str]) -> None:
+ import argparse
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--out", required=True)
+ parser.add_argument("--preview", default=None)
+ parser.add_argument("--keep-scene", action="store_true")
+ args = parser.parse_args(argv)
+ k = _base()
+ for key, value in MEMORY_PALETTE.items():
+ k.PALETTE.setdefault(key, value)
+ if not args.keep_scene:
+ k.clear_scene()
+ else:
+ stale = bpy.data.objects.get("memory-house")
+ if stale is not None:
+ k.select_tree(stale)
+ bpy.ops.object.delete(use_global=False)
+ root = build_memory_house(k)
+ tris = sum(
+ len(o.data.loop_triangles) if o.type == "MESH" and (o.data.calc_loop_triangles() or True) else 0
+ for o in root.children_recursive
+ )
+ print(f"memory-house: {len(root.children_recursive)} objects, {tris} triangles")
+ path = k.export_glb(root, Path(args.out))
+ print(f"exported {path} ({path.stat().st_size} bytes)")
+ if args.preview:
+ # Only this building in the picture: other trees in a kept scene hide for the render.
+ mine = {root, *root.children_recursive}
+ hidden = [o for o in bpy.data.objects if o not in mine and not o.hide_render]
+ for o in hidden:
+ o.hide_render = True
+ try:
+ k.render_preview(root, Path(args.preview))
+ finally:
+ for o in hidden:
+ o.hide_render = False
+ print(f"preview {args.preview}")
+ for name in ("kit_preview_cam", "kit_sun"):
+ obj = bpy.data.objects.get(name)
+ if obj is not None and args.keep_scene:
+ bpy.data.objects.remove(obj, do_unlink=True)
+ if args.keep_scene:
+ k.select_tree(root)
+ bpy.ops.object.delete(use_global=False)
+
+
+if __name__ == "__main__":
+ own = sys.argv[sys.argv.index("--") + 1 :] if "--" in sys.argv else []
+ main(own)
+elif "KIT_ARGS" in globals():
+ main(globals()["KIT_ARGS"])