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

Hallmark maintains a chronological project memory in .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 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 §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 §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

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

1. Creation

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

[
  {
    "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:

{
  "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 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 located, and should it be committed to git?

The file resides at .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 §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 §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.

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