How Hallmark Uses Project Memory for Diversification

Hallmark maintains a .hallmark/log.json file that records the macrostructure, theme, and enrichment of every generated page, then enforces diversification rules to ensure consecutive pages differ in layout, visual style, and archetype.

Hallmark is an open-source design generation system by Nutlope that prevents repetitive outputs by persisting project memory across runs. According to the source code, the tool reads this lightweight JSON log before each generation and applies strict diversification constraints based on recent entries.

How Project Memory Works in Hallmark

Hallmark stores its project memory in a JSON log file located at .hallmark/log.json in the project root. This file tracks the creative decisions made during every successful page generation.

The Log File Structure

Each entry in the log follows a consistent schema that captures the essential characteristics of a generated page:

• date: ISO date string (e.g., "2026-04-30")
• macrostructure: The layout pattern used (e.g., "Bento Grid", "Marquee Hero")
• theme: The visual theme name (e.g., "Bloom", "Coral")
• enrichment: The enrichment archetype (e.g., "E1 clipped-edge")
• brief: Description of the project context

The log is stored as a JSON array where entries are prepended rather than appended, placing the newest record at index 0 for immediate access during diversification checks.

Log Rotation and Entry Management

The system implements automatic rotation to prevent unbounded growth. After emitting a new page, Hallmark prepends the entry to the array and trims the file to retain only the last 20 entries. If the log does not exist when Hallmark starts, the tool treats the current run as the first generation and creates the file post-build.

This rotation logic is documented in skills/hallmark/SKILL.md at lines 462-466, which describes the append-and-truncate mechanism.

The Three Diversification Rules

Before selecting a macrostructure or theme for a new page, Hallmark reads the recent entries in the log (Step 2.5 in the skill definition) and applies specific diversification constraints to ensure visual variety.

Macrostructure Diversification

Hallmark maintains a palette of 21 named macrostructures indexed in references/macrostructures.md. The diversification rule mandates that the new macrostructure must not match any of the last three macrostructures recorded in the log. This prevents the system from falling into repetitive layout patterns across consecutive generations.

Theme Diversification

Themes are evaluated across three distinct axes defined in the theme specifications (references/themes/<theme>.md):

1. Paper-band lightness
2. Display style
3. Accent hue

The new theme must differ from the previous theme on at least one of these three axes. This ensures that consecutive pages exhibit meaningful visual variation even when working within similar aesthetic families.

Enrichment Diversification

The enrichment archetype (which defines decorative elements and edge treatments) must differ from the most recent entry in the log. This rule prevents the overuse of specific ornamental patterns between back-to-back generations.

Implementation in the Codebase

The diversification logic is implemented in the skill definition at skills/hallmark/SKILL.md. Lines 296-306 detail the "Check project memory" step, explaining how the system reads the log and uses its last 3–5 entries to enforce the diversification constraints.

The project-memory rotation feature is also referenced in the repository's README.md at lines 83-84 as a core component of Hallmark's design flow.

Working with the Log Programmatically

When building tools that interact with Hallmark's project memory, you can read and update the log using standard file system operations:

import { readFileSync, writeFileSync } from 'fs';
const LOG_PATH = '.hallmark/log.json';

// Load existing entries (if any)
let log = [];
try {
  const raw = readFileSync(LOG_PATH, 'utf8');
  log = JSON.parse(raw);
} catch (_) {
  // No log yet – start with an empty array
}

// Get recent macrostructures and themes for diversification
const recent = log.slice(0, 3).map(e => ({
  macrostructure: e.macrostructure,
  theme: e.theme,
}));
console.log('Recent entries for diversification:', recent);

// After generating a new page, prepend a new entry
function appendLog(entry) {
  const updated = [entry, ...log].slice(0, 20); // keep only last 20
  writeFileSync(LOG_PATH, JSON.stringify(updated, null, 2));
}

// Sample entry structure
appendLog({
  date: new Date().toISOString().split('T')[0],
  macrostructure: 'Marquee Hero',
  theme: 'Bloom',
  enrichment: 'E1 clipped-edge',
  brief: 'Tally · SaaS product page',
});

Example log entry as stored in .hallmark/log.json:

{
  "date": "2026-04-30",
  "macrostructure": "Bento Grid",
  "theme": "Coral",
  "enrichment": "E1 clipped-edge",
  "brief": "Tracejam · SaaS observability"
}

Summary

• Hallmark stores project memory in .hallmark/log.json, a JSON array tracking macrostructures, themes, and enrichments from previous runs.
• The log uses a prepend-and-rotate strategy (max 20 entries) to keep recent history readily available at the array's start.
• Macrostructure diversification prevents reuse of any of the last three structures.
• Theme diversification requires variation on at least one of three axes: paper-band lightness, display style, or accent hue.
• Enrichment diversification blocks immediate reuse of the same archetype.
• These rules are defined in skills/hallmark/SKILL.md and ensure structural variety across consecutive page generations.

Frequently Asked Questions

What file does Hallmark use for project memory?

Hallmark uses .hallmark/log.json located in the project root. This file stores a JSON array of previous generation metadata including macrostructures, themes, and enrichment archetypes.

How many previous entries does Hallmark check for diversification?

Hallmark examines the last three entries for macrostructure diversification and the most recent entry for enrichment checks. Theme diversification compares against the previous theme to ensure at least one axis of variation.

What happens when the log file reaches 20 entries?

When appending a new entry, Hallmark prepends it to the array and immediately truncates the log to retain only the last 20 entries. This rotation prevents file bloat while maintaining sufficient history for diversification rules.

Where are the diversification rules defined in the codebase?

The diversification rules are documented in skills/hallmark/SKILL.md between lines 296-306, which describes the "Check project memory" step. The log rotation logic appears at lines 462-466, and the feature is summarized in README.md at lines 83-84.

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