Skip to content

validation.md

Latest commit

 

History

History
256 lines (185 loc) · 5.7 KB

validation.md

File metadata and controls

256 lines (185 loc) · 5.7 KB

Memory Validation

The mnemonic-validate tool validates memory files against the MIF Level 3 schema.

Quick Start

# Validate all memories (default paths)
./tools/mnemonic-validate

# Validate specific directory
./tools/mnemonic-validate ${MNEMONIC_ROOT}

# JSON output for CI/CD
./tools/mnemonic-validate --format json

# Using make targets
make validate-memories
make validate-memories-ci

Installation

The validation tool is included with the mnemonic plugin. No additional installation required.

Dependencies: Python 3.9+ with PyYAML (included in most Python installations).

Usage

mnemonic-validate [options] [path...]

Options:
  --format json|markdown   Output format (default: markdown)
  --check TYPE            Only validate: code_refs|citations|links|schema
  --skip-http             Skip HTTP checks (offline mode)
  --fast-fail             Stop on first error
  --changed               Only validate git-modified files
  --capture               Capture validation run as episodic memory
  -v, --verbose           Verbose output
  -h, --help              Show this help

Default Paths

If no path is specified, the tool searches:

  1. ${MNEMONIC_ROOT}/ (global memories)
  2. ${MNEMONIC_ROOT}/ (project memories)

Validation Checks

Schema Validation (--check schema)

Validates MIF Level 3 required fields and formats:

Field Validation
id Must be valid UUID v4 format (lowercase)
type Must be semantic, episodic, or procedural
namespace Should follow pattern {namespace}/{scope}
created Must be valid ISO 8601 timestamp
title Must be non-empty string

Additional checks:

  • provenance.confidence should be between 0.0 and 1.0
  • tags should be lowercase with hyphens
  • valid_from should be before or equal to recorded_at

Code References Validation (--check code_refs)

For memories with code_refs:

  • type should be one of: function, class, method, variable, type, module
  • file path should exist (relative to git root)
  • line number should be within file length

Citations Validation (--check citations)

For memories with citations:

  • type (required) must be: paper, documentation, blog, github, stackoverflow, article
  • title (required) must be non-empty
  • url (required) must be valid URL format
  • relevance (optional) should be between 0.0 and 1.0

Memory Links Validation (--check links)

Validates [[uuid]] patterns in memory body:

  • UUID format must be valid
  • (Future: referenced memory should exist)

Output Formats

Markdown (default)

# Mnemonic Validation Report

**Date:** 2026-01-24T10:30:00Z

## Summary

- **Memories validated:** 145
- **Valid:** 142
- **Errors:** 3
- **Warnings:** 5

## Errors

### abc123-example.memory.md

- **type**: Missing required field: type
- **id** (line 2): Invalid UUID format: not-a-uuid

## Warnings

### def456-other.memory.md

- **tags**: Tag should be lowercase with hyphens: CamelCase

JSON (--format json)

{
  "timestamp": "2026-01-24T10:30:00Z",
  "summary": {
    "total": 145,
    "valid": 142,
    "errors": 3,
    "warnings": 5
  },
  "results": [
    {
      "file": "abc123-example.memory.md",
      "valid": false,
      "errors": [
        {
          "file": "abc123-example.memory.md",
          "field": "type",
          "message": "Missing required field: type",
          "line": null,
          "severity": "error"
        }
      ],
      "warnings": []
    }
  ]
}

CI/CD Integration

Exit Codes

  • 0: All validations passed
  • 1: One or more errors found

GitHub Actions Example

name: Validate Memories

on:
  push:
    paths:
      - '**/*.memory.md'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Validate memories
        run: ./tools/mnemonic-validate --format json

      - name: Validate changed only
        if: github.event_name == 'pull_request'
        run: ./tools/mnemonic-validate --changed --format json

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: validate-memories
        name: Validate memory files
        entry: ./tools/mnemonic-validate --changed --fast-fail
        language: python
        types: [markdown]
        files: \.memory\.md$

Capturing Validation Runs

Use --capture to save validation results as an episodic memory:

./tools/mnemonic-validate --capture

This creates a memory in:

  • blockers/project if errors were found
  • episodic/project if validation passed

The captured memory includes:

  • Summary statistics
  • List of errors and warnings
  • Timestamp and provenance

This enables tracking validation history over time via mnemonic search.

Makefile Targets

# Validate with markdown output
make validate-memories

# Validate with JSON output (for CI)
make validate-memories-ci

# Validate only changed files
make validate-memories-changed

Troubleshooting

"Cannot find MIF schema"

Ensure you're running from the mnemonic plugin directory or have set up paths correctly.

"No memory files found"

Check that:

  1. Memory files end with .memory.md
  2. The search paths contain memory files
  3. For --changed, files are tracked by git

YAML Parse Errors

If frontmatter fails to parse:

  • Check for invalid YAML syntax
  • Ensure the file starts with ---
  • Verify closing --- exists

Schema Source

The validation rules are parsed from skills/format/SKILL.md, ensuring a single source of truth between documentation and validation (see ADR-004).