Skip to content
MIF

Getting Started

This guide walks you through implementing the Modeled Information Format (MIF) in your project.

Prerequisites

  • Basic understanding of JSON-LD or YAML
  • A text editor or IDE
  • (Optional) Python 3.8+ for tooling

Quick Start

Step 1: Create Your First Concept

A MIF concept is a canonical Markdown file; JSON-LD is a derived projection. Start with Markdown:

---
id: 550e8400-e29b-41d4-a716-446655440000
type: semantic
created: 2026-01-26T10:00:00Z
---


User prefers dark mode for all applications.

Save this as my-first-concept.md.

Step 2: Add Metadata

Expand with recommended fields:

---
id: a1b2c3d4-5678-90ab-cdef-1234567890ab
type: semantic
created: 2026-01-26T10:00:00Z
modified: 2026-01-26T10:00:00Z
namespace: _semantic/preferences
title: "Dark Mode Preference"
tags:
  - ui
  - accessibility
  - preference
---


# Dark Mode Preference


User prefers dark mode for all applications including:
- IDE and code editors
- Terminal emulators
- Web applications
- Mobile apps

Step 3: Declare an Ontology (Optional)

If using a custom ontology, declare it:

---
id: a1b2c3d4-5678-90ab-cdef-1234567890ab
type: semantic
created: 2026-01-26T10:00:00Z
ontology:
  id: regenerative-agriculture
  version: "1.0.0"
namespace: _semantic/livestock
---


Herd of 85 Angus-cross beef cattle managed with adaptive multi-paddock grazing.

Base Knowledge Types

Every MIF concept declares one of three base knowledge types:

TypeDescriptionUse For
semanticDeclarative knowledge: facts, concepts, schemasDecisions, preferences, facts, domain knowledge
episodicTime-bound records: events, incidentsIncidents, changelog/deprecation, timelines
proceduralHow-to knowledge: processes, patternsRunbooks, patterns, migration guides, workflows

Specific categorization is expressed through namespaces (e.g., _semantic/decisions, _episodic/incidents).

Conformance Levels

MIF supports three conformance levels:

Level 1: Core (Minimal)

Required fields only:

---
id: uuid-here
type: semantic
created: 2026-01-26T10:00:00Z
---


Memory content here.

Add namespaces, entities, and relationships:

---
id: 7b3c1e90-5a2f-4c8d-9e10-2f6a4b8c1d3e
type: semantic
created: 2026-01-26T10:00:00Z
modified: 2026-01-26T10:00:00Z
namespace: _semantic/decisions
title: "Use PostgreSQL for Data Storage"
tags:
  - database
  - architecture
relationships:
  - type: relates-to
    target: /_semantic/database-requirements.md
  - type: supersedes
    target: /_semantic/sqlite-investigation.md
---


# Use PostgreSQL for Data Storage


## Context


We need a relational database for the new service.


## Decision


PostgreSQL for:
- Strong JSON support
- Excellent performance
- Team familiarity


## Relationships


- relates-to [Database Requirements](/_semantic/database-requirements.md)
- supersedes [SQLite Investigation](/_semantic/sqlite-investigation.md)

Relationships are authoritative in frontmatter and mirrored as OKF-legible body markdown links so a generic OKF consumer sees every edge.

Level 3: Full

Add temporal metadata, provenance, and citations:

---
id: uuid-here
type: semantic
created: 2026-01-26T10:00:00Z
temporal:
  valid_from: 2026-01-26T00:00:00Z
  recorded_at: 2026-01-26T10:00:00Z
  ttl: P365D
  decay:
    model: exponential
    halfLife: P30D
    strength: 1.0
provenance:
  source_type: user_explicit
  agent: claude-opus-4
  confidence: 0.95
  trust_level: user_stated
citations:
  - type: documentation
    title: "PostgreSQL Documentation"
    url: https://www.postgresql.org/docs/
    role: background
    relevance: 0.9
---

Freshness Values: The halfLife: P30D means freshness strength halves every 30 days. Common values: P7D (short-term), P14D (medium-term), P30D (long-term). These are pragmatic validity/freshness defaults; the cognitive-memory rationale lives in the AI Memory profile. See the Specification for details.

Directory Structure

Organize your MIF vault using the three base types:

my-project/
├── .mif/
│   ├── config.yaml           # Vault configuration
│   └── entities/             # Entity definitions
├── memories/
│   ├── semantic/             # Facts, concepts, knowledge
│   │   ├── decisions/
│   │   ├── knowledge/
│   │   └── entities/
│   ├── episodic/             # Events, experiences
│   │   ├── incidents/
│   │   └── sessions/
│   └── procedural/           # Processes, how-to
│       ├── runbooks/
│       └── patterns/
└── ontology.yaml             # Custom ontology (optional)

Using Custom Ontologies

Create an Ontology

ontology.yaml
ontology:
  id: my-project
  version: "1.0.0"
  description: "Custom ontology for my project"


namespaces:
  features:
    description: "Product features"
    type_hint: semantic
  sprints:
    description: "Sprint records"
    type_hint: episodic


entity_types:
  - name: feature
    base: semantic
    traits: [lifecycle]
    schema:
      required: [name, status]
      properties:
        name: { type: string }
        status: { type: string, enum: [planned, active, deprecated] }

Reference in Memories

---
id: feature-dark-mode
type: semantic
created: 2026-01-26T10:00:00Z
ontology:
  id: my-project
  version: "1.0.0"
namespace: _semantic/features
---


# Dark Mode Feature


Status: active
Priority: high

JSON-LD Format

For machine processing, use JSON-LD:

{
  "@context": "https://mif-spec.dev/schema/context.jsonld",
  "@type": "Memory",
  "@id": "urn:mif:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "memoryType": "semantic",
  "content": "User prefers dark mode for all applications.",
  "created": "2026-01-26T10:00:00Z",
  "ontology": {
    "@type": "OntologyReference",
    "id": "mif-base",
    "version": "1.0.0"
  },
  "namespace": "_semantic/preferences",
  "tags": ["ui", "accessibility"]
}

Validation

Validate MIF documents using JSON Schema:

Terminal window
# Install ajv-cli
npm install -g ajv-cli


# Validate a memory
npx ajv validate -s https://mif-spec.dev/schema/mif.schema.json -d my-memory.json


# Validate a citation
npx ajv validate -s https://mif-spec.dev/schema/citation.schema.json -d citation.json


# Validate an ontology
npx ajv validate -s https://mif-spec.dev/schema/ontology/ontology.schema.json -d ontology.yaml

Converting Ontologies

Convert YAML ontologies to JSON-LD:

Terminal window
# Single file
python scripts/yaml2jsonld.py ontologies/my-ontology.ontology.yaml


# All ontologies
python scripts/yaml2jsonld.py --all

Next Steps

Getting Help