# How Munder Difflin Manages Its Agent Registry: In-Memory Store, Persistence, and Hive Synchronization

> Discover how Munder Difflin manages its agent registry using an in-memory store, local storage persistence, and Hive synchronization. Learn about its state management.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-28

---

**Munder Difflin maintains its agent registry through a Zustand-based client-side store that manages an in-memory `agents` array, persists state to local storage, and synchronizes with a global Hive registry for runtime metadata.**

The **agent registry** is the central nervous system of Munder Difflin, tracking every "worker" agent that runs inside the application. According to the source code in `chaitanyagiri/munder-difflin`, the registry combines reactive state management, durable persistence, and distributed metadata lookup to ensure agents remain discoverable and manageable across sessions.

---

## Core Architecture: The Zustand Store

The registry's foundation lives in [`index-j0JdoH0M.js`](https://github.com/chaitanyagiri/munder-difflin/blob/main/index-j0JdoH0M.js), which implements a Zustand store holding three key arrays: `agents` (active), `archivedAgents`, and `restorableAgents`. This design separates lifecycle concerns while keeping all agent data accessible through a unified interface.

### Adding Agents to the Registry

New agents enter the registry through the `addAgent` method. The implementation handles **god agents** (orchestrators) specially by prepending them to the array:

```javascript
addAgent: (agent) => set2((s2) => {
  const agents = agent.isGod 
    ? [agent, ...s2.agents] 
    : [...s2.agents, agent];
  // ... additional logic
  persistAgents(agents, agent.id);
})

```

The `isGod` flag determines insertion order, ensuring orchestrators appear first in the UI. After mutation, `persistAgents` immediately writes the updated list to durable storage.

---

## Persistence Layer: Local Storage with Slimming

Every registry mutation triggers `persistAgents`, which strips transient fields before saving. This **slimming process** prevents local storage bloat and avoids serializing non-persistable state like DOM references or temporary UI flags.

```javascript
persistAgents(agents, selectedId)

```

The function writes to `LS_AGENTS` (the key `cth.agents` in local storage). The implementation in [`index-j0JdoH0M.js`](https://github.com/chaitanyagiri/munder-difflin/blob/main/index-j0JdoH0M.js) lines 7462–7474 handles this serialization, ensuring the registry survives page reloads and browser restarts.

### Restoration on Startup

When the application boots, the store hydrates from local storage using `persistedSlice` and `loadPersistedSelectedId`:

```javascript
const parsed = persistedSlice(LS_AGENTS, fileRoster?.agents);

```

This initialization sequence (lines 7507–7510) merges persisted agent data with any file-based roster, creating the initial state for the reactive store.

---

## Global Hive Registry: Runtime Metadata Lookup

Beyond the local store, Munder Difflin integrates with a **Hive-wide registry** exposed through `window.cth.hiveRegistry()`. This global registry contains session-level metadata not stored locally—items like `sessionId` entries for each agent.

```javascript
const registry2 = await window.cth.hiveRegistry();

```

The Hive registry serves as an authority for runtime data. When operations need to map an agent ID to its current session or verify existence across the distributed system, they consult this registry rather than the local store.

---

## Selection Management and UI Consistency

The registry tracks more than just agent lists. It maintains **selection state** through `selectedId` and `fullscreenAgentId`, ensuring the UI remains coherent as agents come and go.

### Handling Agent Removal

When an agent is removed, `refocusAfterRemoval` (lines 7872–7885) recalculates the selection to prevent pointing to deleted entries:

```javascript
refocusAfterRemoval(s2.fullscreenAgentId, agents, selectedId)

```

This defensive programming guarantees that destructive operations never leave the UI in an invalid state.

---

## Practical Code Examples

### Adding and Persisting a God Agent

```javascript
import { useStore } from './store';

const orchestrator = { 
  id: 'god-1', 
  isGod: true, 
  description: 'Main Orchestrator' 
};
useStore.getState().addAgent(orchestrator);
// Automatically persists to localStorage under 'cth.agents'

```

### Restoring Registry on Application Start

```javascript
import { useStore } from './store';

const persisted = JSON.parse(
  localStorage.getItem('cth.agents') ?? '[]'
);
useStore.setState({ agents: persisted });

```

### Querying Hive Metadata for Session Information

```javascript
async function getAgentSessionId(agentId) {
  const hive = await window.cth.hiveRegistry();
  return hive.agents[agentId]?.sessionId;
}

```

---

## Summary

Munder Difflin's agent registry architecture combines four integrated layers:

- **Zustand store** maintains reactive in-memory state with lifecycle-aware arrays (`agents`, `archivedAgents`, `restorableAgents`)
- **Persistence layer** uses `persistAgents` and `slimAgents` to durable local storage under `cth.agents`
- **Hive registry** provides global runtime metadata through `window.cth.hiveRegistry()`
- **Selection management** via `refocusAfterRemoval` ensures UI consistency during mutations

The registry implementation spans [`index-j0JdoH0M.js`](https://github.com/chaitanyagiri/munder-difflin/blob/main/index-j0JdoH0M.js) for core logic, with the Hive system documented in [`HIVE.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md) and exposed through the preload configuration in [`electron.vite.config.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/electron.vite.config.ts).

---

## Frequently Asked Questions

### What happens when a new agent is added to Munder Difflin?

The `addAgent` method in the Zustand store inserts the agent into the `agents` array—prepending if `isGod` is true—then calls `persistAgents` to write the updated list to local storage. The change becomes immediately reactive across all UI components subscribed to the store.

### Where does Munder Difflin store agent data between sessions?

Agent data persists to browser local storage under the key `cth.agents`. The `persistAgents` function strips transient fields via `slimAgents` before serialization, keeping storage lean. On startup, `persistedSlice` reads this data to rehydrate the store.

### What is the difference between the local store and the Hive registry?

The **local store** holds full agent objects for UI rendering and user management, persisted to disk. The **Hive registry** (`window.cth.hiveRegistry()`) provides distributed runtime metadata like session IDs, consulted when operations need authoritative, cross-instance agent information.

### How does the registry handle agent deletion without breaking the UI?

The `refocusAfterRemoval` helper recalculates `selectedId` and `fullscreenAgentId` whenever an agent is removed. This ensures selection always points to valid entries, preventing crashes or blank states when the active agent disappears.