Skip to content
MIF

Overview

Abstract

Section titled “Abstract”

MIF (Modeled Information Format) is an opinionated, OKF-compliant content model for agent-readable knowledge. The Open Knowledge Format (OKF) defines a minimal interoperability surface — a directory of .md concept files with YAML frontmatter, one required type field, and a concept graph of standard markdown links — and deliberately refuses to define a content model. MIF fills that envelope: it supplies a concrete type system, typed relationships, provenance/trust tiers, and validity/freshness semantics.

Markdown is the canonical representation; JSON-LD is a derived, regenerable projection. AI memory is the first domain profile of MIF, not its identity (see profiles/ai-memory/).

OKF compliance is achieved as a superset, not by subordination: every MIF bundle validates as a conformant OKF bundle, but MIF remains an independent specification with its own identity model and governance, pinned to OKF v0.1.

MIF is designed to be:

  • OKF-compliant: every bundle is a valid OKF bundle (a tested invariant)
  • Markdown-canonical: the .md file is the source of truth; JSON-LD is a derived projection
  • Human-Readable: valid CommonMark notes that work in any Markdown editor
  • Machine-Processable: JSON-LD with semantic web compatibility
  • Extensible: domain profiles extend the base without breaking compatibility

Terminology

Section titled “Terminology”

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Definitions

Section titled “Definitions”
  • Concept: A discrete unit of knowledge — a single .md file in a bundle, including its content, metadata, relationships, and provenance. The atomic element of MIF.
  • Bundle: A directory tree of .md concept files; a valid OKF bundle.
  • Entity: A named thing (person, organization, technology, concept, or file) that can participate in relationships.
  • Relationship: A typed, directed connection between two concepts, or between a concept and an entity.
  • Namespace: A hierarchical scope for organizing concepts (e.g., org/user/project/session).
  • Provider: An implementation that can import or export MIF format.

Design Principles

Section titled “Design Principles”

Dual Representation

Section titled “Dual Representation”

MIF defines two representations, with markdown as the canonical source:

  1. Markdown Format (.md): Canonical, human-readable, plain CommonMark
  2. JSON-LD Format (.jsonld): Derived, machine-processable, semantically linked

The .md file is the source of truth; the JSON-LD form is a derived projection, regenerable from markdown with scripts/mif_convert.py. The round trip MUST be lossless. A conforming implementation MAY support either or both formats; if the two disagree, markdown wins.

Markdown Conventions

Section titled “Markdown Conventions”

The Markdown format is plain, vendor-neutral CommonMark — readable in any text editor or Markdown processor, and tied to no single tool. Concept relationships are expressed as standard bundle-relative markdown links, so any generic OKF consumer sees every edge.

Markdown conventions:

  • YAML Frontmatter: Structured metadata at the top of files, enclosed in --- delimiters, supporting typed fields (text, number, date, list).

  • Standard Markdown Links: Concept-graph edges use bundle-relative markdown links, [text](/path/to/target.md), in a ## Relationships section — the OKF-legible representation of relationships.

  • Aliases: The aliases frontmatter property lets a concept be referred to by alternative names.

  • Tags: Both inline #tags and frontmatter tags: [a, b] are supported, with hierarchical tags using forward slashes (#category/subcategory).

  • Standard Markdown: All content uses CommonMark-compatible Markdown, ensuring portability across tools and platforms.

Semantic Web Compatibility

Section titled “Semantic Web Compatibility”

The JSON-LD format MUST be valid JSON-LD 1.1:

  • Use @context for vocabulary mapping
  • Use @id for unique identifiers
  • Use @type for entity classification
  • Compatible with RDF tooling

Local-First

Section titled “Local-First”

MIF is designed for local-first storage:

  • No required network dependencies
  • Files can be read with any text editor
  • No proprietary database required
  • Full user data ownership