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

Munder Difflin stores every agent’s identity and memory as plain‑text files inside the on‑disk Hive directory (<harnessHome>/hive/), utilizing identity.md for static metadata, memory.md for durable notes, and 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:

<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 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 using Node’s synchronous filesystem API. According to the source code in src/main/hive.ts, the implementation calls:

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

This operation occurs at lines 56–58 of 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 captures static attributes, the system maintains mutable runtime data—such as sessionId, status, lastSeen, and cwdValid—in 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.

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 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.

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

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 operates a background mining process. Every ten minutes by default, it invokes the external mempalace CLI to index modified 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 implement this through MemoryManager.env():

// 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 or 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 at lines 56–58.
• Runtime state including sessionId and status persists in registry.json, updated at lines 73–78 of hive.ts.
• Long‑term memories append to 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 (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 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 at lines 56–58.

How does registry.json differ from identity.md?

While identity.md contains static metadata like id, name, role, and cwd that rarely change, 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 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 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, memory.md, or any file in the Hive using standard text editors. Changes to memory.md will be picked up by the next mempalace mine cycle for semantic indexing, though manual edits to registry.json should be avoided while the harness is running to prevent state corruption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}