# How `.hallmark/log.json` Tracks Project Memory in Hallmark

> Discover how .hallmark/log.json in Hallmark tracks project memory, recording build choices to enable automatic diversification and enhance CSS generation.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: internals
- Published: 2026-08-02

---

**Hallmark maintains a chronological project memory in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) that records every build’s macrostructure, theme, and enrichment choices, enabling automatic diversification across runs by consulting the last 3–5 entries before generating new CSS.**

The open-source **Nutlope/hallmark** skill uses this lightweight JSON persistence mechanism to remember what it has previously generated. By storing a rolling history of generation parameters at the root of each project, the skill ensures that successive executions produce visually distinct outputs without requiring manual configuration.

## The Project Memory File Structure

[`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) is an ordered JSON array stored inside the `.hallmark/` directory at the project root. As specified in the repository’s `.gitignore` (line 36), this folder is ignored by version control, ensuring the memory remains local to each developer’s environment.

The file uses a **prepend-only** pattern (newest entry first) to provide constant-time access to recent history. Each entry captures the state of a single Hallmark run, creating a durable record that the skill consults before making creative decisions.

## Core Functions of the Memory Log

### Enforcing Diversification

According to **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** §2.5 (lines 462–463), Hallmark reads the most recent entries to prevent creative repetition. Before selecting a macrostructure or theme, the skill consults the **last 3–5 entries** to verify that the next build differs in at least one of the following:

- **Macrostructure** (e.g., Bento Grid vs. Long Document)
- **Theme axis** or **enrichment archetype**

If the file is empty or missing, the run proceeds without diversification constraints.

### Guiding Theme-Axis Rotation

For custom theme runs, the log stores the three axis values defined in **[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)** §F (lines 240–246):

- `paper-band`
- `display-style`
- `accent-hue`

The next execution reads these axes to guarantee a different combination, preventing the same custom aesthetic from repeating immediately.

### Providing a Durable Stamp

As documented in **SKILL.md** §6 (lines 60–62), after emitting CSS, Hallmark inserts the same metadata that will be logged into the first non-empty comment line of the stylesheet. This stamp and the log entry together constitute the *project memory* consulted on subsequent runs.

## Lifecycle of [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)

The file follows a strict four-phase lifecycle during every execution:

### 1. Creation

If [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) does not exist, Hallmark creates the `.hallmark/` folder and initializes the file with an empty array before writing the first entry.

### 2. Prepend

After a successful build, Hallmark **prepends** a new JSON object to the array (placing the newest entry at index 0). Standard entries include:

- `date`: ISO date string
- `macrostructure`: The layout archetype used
- `theme`: Theme name or "custom"
- `enrichment`: Enrichment archetype (e.g., "E1 clipped-edge")
- `brief`: Short project description

Custom runs additionally include `theme_axes` and an optional `vibe` field.

### 3. Trim

To limit file size, Hallmark retains only the **last 20 entries**. Older entries are automatically dropped after each write operation.

### 4. Read

At the start of the next run (Step 2.5 in the execution flow), Hallmark loads the file into memory. The diversification logic scans the recent history to determine eligible macrostructures and themes for the current build.

## JSON Structure and Examples

A standard log entry captures the essential generation parameters:

```json
[
  {
    "date": "2026-04-30",
    "macrostructure": "Bento Grid",
    "theme": "Coral",
    "enrichment": "E1 clipped-edge",
    "brief": "Tracejam · SaaS observability"
  },
  {
    "date": "2026-04-28",
    "macrostructure": "Long Document",
    "theme": "Garden",
    "enrichment": "E5 hand-built SVG",
    "brief": "Maple Street Bread · bakery"
  }
]

```

Custom entries append axis-specific data to support rotation logic:

```json
{
  "date": "2026-05-02",
  "macrostructure": "Stat-Led",
  "theme": "custom",
  "theme_axes": "paper-band: pastel / display-style: modern / accent-hue: teal",
  "vibe": "quiet-tech-craft",
  "enrichment": "E3 SVG-logo",
  "brief": "Nova Analytics dashboard"
}

```

## Why a JSON Array?

Using an ordered array with the newest entry first allows **O(1) access** to the most recent history, which is all the diversification logic requires. The format remains human-readable for debugging or manual edits, and the 20-entry cap ensures the file never grows large enough to impact performance.

## Summary

- [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) stores a chronological, prepend-only JSON array of every Hallmark build.
- The file lives in a git-ignored `.hallmark/` folder at the project root to keep memory local.
- Hallmark consults the last 3–5 entries to enforce diversification of macrostructures, themes, and enrichments.
- Custom theme runs record `theme_axes` (paper-band, display-style, accent-hue) to guarantee axis rotation.
- The log is automatically trimmed to the last 20 entries and mirrored in the CSS output as a durable stamp.

## Frequently Asked Questions

### Where is [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) located, and should it be committed to git?

The file resides at [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) relative to your project root. According to the `.gitignore` in **Nutlope/hallmark**, this directory is excluded from version control, keeping the project memory local to each development environment.

### How many previous builds does Hallmark check for diversification?

The skill reads the **last 3–5 entries** from the log before generating new CSS. This window, specified in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) §2.5, provides sufficient history to prevent immediate repetition of macrostructures, theme axes, or enrichment archetypes.

### What additional fields are stored for custom theme runs?

Custom runs append a `theme_axes` string containing the paper-band, display-style, and accent-hue values, along with an optional `vibe` descriptor. These fields are defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) §F and enable the rotation logic for bespoke aesthetics.

### What happens when the log file reaches 20 entries?

Hallmark automatically trims the array to retain only the **last 20 entries**, dropping older records to maintain a bounded file size. This trimming occurs immediately after prepending the newest entry, ensuring the log never grows beyond its practical working set.