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

> Discover Nallely MIDI's git-based versioned memory system. It stores JSON snapshots as tracked Git files, offering full version history and rollback without servers.

- Repository: [dr-schlange/nallely-midi](https://github.com/dr-schlange/nallely-midi)
- Tags: internals
- Published: 2026-02-28

---

**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)](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.

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

```python

# 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)](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`](https://github.com/dr-schlange/nallely-midi/blob/main/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`](https://github.com/dr-schlange/nallely-midi/blob/main/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.