How Nallely MIDI's Git-Based Versioned Memory System Works

Nallely MIDI implements a git-based versioned memory system by storing JSON session snapshots as individually tracked files in a local Git repository, enabling full version history and rollback capabilities without external servers.

The open-source nallely-midi project by dr-schlange uses a lightweight git-based versioned memory system to persist MIDI session states. This approach stores every "address snapshot" as a Git-tracked JSON file within a local repository, providing robust version control directly in the working directory.

Core Architecture and Repository Initialization

The Session class in [nallely/session.py](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/session.py) drives the entire workflow. When instantiated, it automatically initializes the Git backend through _init_memory_repo(), which resolves the ./memory folder (or another specified universe) and either creates a fresh repository using porcelain.init() or opens an existing one via dulwich.repo.Repo.

The repository stores one .nly file per memory address, with each file containing a JSON representation of the complete session—including MIDI devices, virtual devices, and connection mappings. This file-per-address design allows Git to track each snapshot independently while maintaining a cohesive history of the entire system state.

Saving Session Snapshots to Memory Addresses

The save_address() method handles persistence through a strict validation and commit workflow:

1. Address validation: The method expects a hexadecimal string (e.g., "1A2B") validated by ADDRESS_CHECKER. If malformed, the system generates a random free address automatically.

2. Snapshot serialization: The session converts to a dictionary via snapshot(), then writes to <address>.nly using save_all().

3. Git tracking: The file is staged with porcelain.add() and committed using porcelain.commit(), which includes a human-readable summary containing MIDI class counts, virtual device statistics, and connection details.

from nallely.session import Session

# Initialize session (auto-creates/opens git store)

sess = Session()

# Save current state to address 0x1A2B

address_file = sess.save_address("1A2B", save_defaultvalues=True)
print(f"Snapshot saved to {address_file}")

Retrieving and Managing Stored Sessions

Loading snapshots uses the reverse path resolution via address2path. The load_address() method reads the JSON from the specified address file and reconstructs the session state.

For system administration, get_used_addresses() walks the universe directory, returning each stored address as a dictionary with path and hex keys. To remove state, clear_address() deletes the .nly file, stages the deletion, and creates a commit explicitly indicating the clear operation.

# Load previously saved snapshot

sess2 = Session()
snapshot = sess2.load_address("1A2B")
print("Loaded snapshot contains", len(snapshot["virtual_devices"]), "virtual devices")

# List all stored addresses

print(sess.get_used_addresses())

# → [{'path': 'memory/1A2B.nly', 'hex': '1A2B'}, ...]

# Delete specific address

sess.clear_address("1A2B")

Version History Inspection and Rollback

Because every change creates a Git commit, the git-based versioned memory system provides complete chronological tracking of all session states. Users can inspect the full history of any address using standard Git commands like git log and git diff, or programmatically via the Dulwich API.

This architecture leverages Git's robustness without requiring external servers, making configurations easy to inspect, share, or roll back directly from the file system. Each commit contains structured metadata about the session composition, enabling precise state reconstruction from any point in the repository history.

Command-Line Interface Integration

The CLI in [nallely/cli.py](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/cli.py) exposes the --load-address flag, which passes the address string directly to Session.load_address(). This allows users to bootstrap new processes from stored states immediately upon startup, bridging the gap between persistent storage and runtime initialization.

Summary

• Nallely MIDI stores session snapshots as JSON files in a local Git repository (default ./memory folder), with one .nly file per hex address.
• The Session class in nallely/session.py manages repository initialization via _init_memory_repo() and handles all CRUD operations through methods like save_address(), load_address(), and clear_address().
• Dulwich powers the Git operations, using porcelain.add() and porcelain.commit() to track every snapshot change with descriptive metadata.
• Address validation ensures hexadecimal formatting (e.g., "1A2B"), with automatic fallback to random address generation for invalid inputs.
• Full version history is available through Git commits, enabling inspection and rollback using standard Git tools or the Dulwich API.
• The --load-address CLI option in nallely/cli.py enables direct loading of stored states during application startup.

Frequently Asked Questions

What file format does the git-based versioned memory system use?

The system uses .nly files containing JSON representations of the complete session state. Each file tracks MIDI devices, virtual devices, connections, and configuration parameters as a structured snapshot.

How does Nallely MIDI handle invalid memory addresses?

The save_address() method validates inputs against ADDRESS_CHECKER to ensure proper hexadecimal formatting. If the provided string fails validation, the system automatically generates a random free address through an internal loop that checks existing files for collisions.

Can I view the history of changes to a specific address?

Yes. Since every snapshot creates a Git commit in the underlying repository, you can use standard Git commands (git log, git diff, git show) or the Dulwich API to inspect the complete chronological history of any .nly file. Each commit includes a human-readable summary of the session's MIDI classes and device statistics.

What Git library does Nallely MIDI use for its versioned memory?

The implementation uses Dulwich, a pure-Python Git library. The Session class utilizes dulwich.repo.Repo for repository handling and dulwich.porcelain functions (init, add, commit) for high-level Git operations, eliminating dependencies on external Git binaries while maintaining full compatibility with standard Git toolchains.

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