# How Agent Identities and Memories Are Stored in Munder Difflin: Hive Architecture Explained

> Discover how Munder Difflin stores agent identities and memories in plain text files within the Hive directory. Learn about identity.md, memory.md, and registry.json for metadata, notes, and runtime state.

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

---

**Munder Difflin stores every agent’s identity and memory as plain‑text files inside the on‑disk Hive directory (`<harnessHome>/hive/`), utilizing [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) for static metadata, [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) for durable notes, and [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) for mutable runtime state.**

Munder Difflin is an open‑source agent harness that treats the filesystem as the source of truth for agent state. Unlike traditional databases, the project persists agent identities and memories as human‑readable files in a structured Hive directory, enabling Git version control and direct manipulation without database drivers.

## The Hive Directory Structure

Munder Difflin organizes all agent data under a single root directory called the **Hive**, located at `<harnessHome>/hive/`. This directory acts as both a filesystem database and a version‑controlled repository, eliminating external database dependencies while maintaining full observability.

Within the Hive, each agent receives a dedicated subdirectory structured as follows:

```text
<harnessHome>/hive/
├── agents/
│   └── <agent‑id>/
│       ├── identity.md      // Static identity metadata
│       ├── memory.md        // Durable agent notes
│       ├── inbox/           // Inbound messages
│       └── outbox/          // Outbound messages
├── registry.json            // Runtime agent registry
└── board.md, log.jsonl      // Shared blackboard & event log

```

This layout ensures that every aspect of an agent’s existence—from its core identity to its long‑term memory—exists as a discrete, human‑readable file that works identically across Windows, macOS, and Linux using Node’s `fs` API.

## Identity Persistence: From Spawn to Storage

When an agent spawns, the `Hive` class in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) orchestrates identity creation through the `ensureAgent` method. This method performs two critical write operations that establish the agent’s presence on disk and track its runtime state.

### Writing Static Identity to identity.md

The harness generates the agent’s immutable metadata—`id`, `name`, `role`, and `cwd`—and persists it to [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) using Node’s synchronous filesystem API. According to the source code in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts), the implementation calls:

```typescript
writeFileSync(identity, this.identityText(meta), 'utf8');

```

This operation occurs at lines 56–58 of [`hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/hive.ts) and executes on every agent spawn, ensuring the identity file reflects the current configuration. The file uses markdown formatting to maintain readability for developers inspecting the Hive directly.

### Managing Runtime State in registry.json

While [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) captures static attributes, the system maintains mutable runtime data—such as `sessionId`, `status`, `lastSeen`, and `cwdValid`—in [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json). During the spawn process, `ensureAgent` updates this JSON file to merge new metadata with existing session‑specific fields, as implemented at lines 73–78 of [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts).

The registry serves as the authoritative source for UI components rendering agent rosters and enables inter‑agent communication through addressing (e.g., `to: <agentId>`).

## Memory Storage and Semantic Indexing

Agent memories in Munder Difflin follow an append‑only model where raw storage remains separate from searchable indexes, creating a clean separation between durable logs and queryable knowledge.

### Raw Memory Persistence in memory.md

Each agent maintains a [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) file that functions as a durable markdown log. During initial directory creation, the Hive ensures this file exists and seeds it with a descriptive header (e.g., `# Memory — <agent‑name>`), as seen at lines 65–68 of [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts).

Crucially, the harness never modifies this file after creation. Agents append observations and facts using standard filesystem operations:

```typescript
import { appendFileSync } from 'node:fs';
import { join } from 'node:path';

const memPath = join(process.env.AGENT_DIR!, 'memory.md');
appendFileSync(memPath, '\n- Resolved API pagination issue.\n');

```

This design makes the agent the sole writer of its own memories while keeping the format universally parsable and Git‑friendly.

### Background Semantic Mining with MemoryManager

To enable cross‑agent memory search, the `MemoryManager` class in [`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts) operates a background mining process. Every ten minutes by default, it invokes the external `mempalace` CLI to index modified [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) files into a shared semantic database located at `<harnessHome>/palace`.

The harness prepares the environment for this indexing by injecting the palace path into each agent’s process environment. Lines 14–21 of [`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts) implement this through `MemoryManager.env()`:

```typescript
// Environment setup for mempalace integration
env.MEMPALACE_PALACE_PATH = join(this.hiveHome, 'palace');

```

Agents query these indexed memories using CLI commands like `mempalace search "<query>"` or `mempalace wake‑up`, allowing the system to recall relevant information without storing embeddings within the harness itself.

## Why Plain‑Text Files Over Databases?

Munder Difflin’s file‑based architecture provides three distinct advantages over traditional database storage:

- **Human Readability**: Developers can directly open [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) or [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) to inspect exactly what an agent knows and how it identifies itself, crucial for debugging autonomous systems.
- **Git Version Control**: Because the entire Hive exists as standard files, a single‑committer Git repository can track changes to agent identities and memories over time without merge conflicts.
- **Cross‑Platform Compatibility**: The harness relies solely on Node’s `fs` API, eliminating native binary dependencies and ensuring identical behavior across operating systems.

## Summary

- **Agent identities** live in `<harnessHome>/hive/agents/<agent‑id>/identity.md` as markdown files written by `ensureAgent` in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) at lines 56–58.
- **Runtime state** including `sessionId` and `status` persists in [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json), updated at lines 73–78 of [`hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/hive.ts).
- **Long‑term memories** append to [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) by the agents themselves, with the harness only initializing the file at lines 65–68.
- **Semantic search** delegates to the external `mempalace` tool, configured via `MemoryManager.env()` in [`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts) (lines 14–21) to index the `<harnessHome>/palace` directory.
- The entire system uses plain‑text files to ensure Git compatibility, human readability, and cross‑platform operation without database drivers.

## Frequently Asked Questions

### Where exactly are agent identities stored in the Munder Difflin repository?

Agent identities are stored as individual [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) files within the Hive directory structure at `<harnessHome>/hive/agents/<agent‑id>/identity.md`. The `Hive` class creates these files during the spawn process by calling `writeFileSync` with the agent’s metadata in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) at lines 56–58.

### How does registry.json differ from identity.md?

While [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) contains static metadata like `id`, `name`, `role`, and `cwd` that rarely change, [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) maintains mutable runtime state including `sessionId`, `status`, `lastSeen`, and `cwdValid`. The registry updates every time an agent spawns to preserve session continuity, whereas the identity file is overwritten with current static properties.

### What triggers the semantic indexing of agent memories?

The `MemoryManager` class triggers indexing every ten minutes through a background mining loop that executes the `mempalace mine` command. This process scans for changes in [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) files and updates the vector index in `<harnessHome>/palace`. The harness configures this through `MemoryManager.env()` at lines 14–21 of [`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts) by setting the `MEMPALACE_PALACE_PATH` environment variable.

### Can I manually edit an agent's memory or identity files?

Yes. Because Munder Difflin uses plain‑text markdown files, you can manually edit [`identity.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md), [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md), or any file in the Hive using standard text editors. Changes to [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/memory.md) will be picked up by the next `mempalace mine` cycle for semantic indexing, though manual edits to [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) should be avoided while the harness is running to prevent state corruption.