Skip to content

Data Model

A concept is the atomic element of MIF. It contains:

Property Required Type Description
id REQUIRED UUID Globally unique identifier (stable across relocation)
content REQUIRED String The concept content (Markdown); see note below
type REQUIRED Enum Base knowledge classification (see Knowledge Types)
created REQUIRED DateTime When the concept was created
modified RECOMMENDED DateTime When last modified
ontology RECOMMENDED Object Reference to applied ontology (see Ontology Reference)
namespace RECOMMENDED String Hierarchical scope
tags OPTIONAL Array Classification tags
entities OPTIONAL Array Referenced entities
relationships OPTIONAL Array Typed relationships
temporal OPTIONAL Object Temporal validity data
provenance OPTIONAL Object Source and trust data
embedding OPTIONAL Object Embedding reference
citations OPTIONAL Array Citation references (Level 3)
summary OPTIONAL String Compressed content summary (Level 3)
compressedAt OPTIONAL DateTime When compression was applied (Level 3)
extensions OPTIONAL Object Provider-specific data

content is the Markdown body of the .md file, not a frontmatter key. It appears as a named property only in the JSON-LD projection, where Markdown to JSON-LD maps the body to content. The other properties in this table are frontmatter keys in Markdown.

The frontmatter type field holds the base knowledge classification; in the JSON-LD projection produced by scripts/mif_convert.py, this value is surfaced as conceptType.

MIF uses three base knowledge types, a general taxonomy of how knowledge is structured:

Type Description Namespace Hint
semantic Declarative knowledge: facts, concepts, decisions, schemas _semantic/*
episodic Time-bound records: events, incidents, changelog/deprecation _episodic/*
procedural How-to knowledge: runbooks, processes, patterns, migrations _procedural/*
  • Semantic: Declarative knowledge about the world—facts, concepts, decisions, preferences, and relationships between entities. Examples: architectural decisions, technology choices, schemas, domain knowledge.

  • Episodic: Time-bound records of events—incidents, deprecations, changelog entries. These concepts have strong temporal context and represent “what happened.”

  • Procedural: How-to knowledge—runbooks, migration guides, code patterns, and step-by-step processes. These concepts describe “how to do” something.

The cognitive-memory origin of this triad, and its reinterpretation for agent memory, live in the AI Memory profile (profiles/ai-memory/).

Ontologies MAY define extended types using namespace prefixes:

# In ontology definition
entity_types:
- name: decision
base: semantic
description: "Architectural or design decision"
- name: runbook
base: procedural
description: "Step-by-step operational guide"
- name: incident
base: episodic
description: "Production incident record"

When using ontology-extended types, the type field uses the base type, while specific categorization is expressed through the namespace:

---
type: semantic
namespace: _semantic/decisions
ontology:
id: mif-base
---

This allows ontologies to define rich taxonomies while maintaining interoperability through the base type foundation.

A concept MAY declare which ontology it conforms to using the ontology field:

Property Required Type Description
id REQUIRED String Ontology identifier (matches ontology.id in ontology definition)
version OPTIONAL String Semantic version (e.g., “1.0.0”)
uri OPTIONAL URI URL to the ontology definition file
ontology:
id: regenerative-agriculture
version: "1.0.0"
uri: https://mif-spec.dev/ontologies/regenerative-agriculture.ontology.yaml

The ontology.id MUST match the ontology.id field in the referenced ontology definition file. This enables:

  • Validation that namespace paths conform to the ontology’s defined namespaces
  • Discovery pattern matching for entity type suggestions
  • Schema validation for entity-specific fields

Categorizing Concepts (Fact, Event, and Beyond)

Section titled “Categorizing Concepts (Fact, Event, and Beyond)”

Common categories such as Fact and Event are already expressible with the fields defined above; MIF therefore does not define a separate flat category field. Domain categories are composed from two orthogonal axes that a concept can declare directly:

  1. type (REQUIRED, see Knowledge Types) — the base knowledge type: semantic, episodic, or procedural.
  2. namespace (RECOMMENDED, see Namespace Model) — hierarchical scope that carries the finer-grained label (e.g. _semantic/knowledge, _episodic/sessions).

A concept has no field to name an ontology-extended type directly. Instead, ontologies define extended types and their namespace mappings (OPTIONAL, see Ontology-Extended Types and Ontology Definition): an ontology declares each extended type as an entity_types entry with a base type, and implementations express that extended type by following the referenced ontology’s namespace hierarchy on the namespace axis above (e.g. an incident extended type whose base is episodic, reached via _episodic/incidents). The extended type is therefore a richer label on the namespace axis, not a separate third axis the unit declares.

Note on namespace form. Base-type roots use the underscore-prefixed form (_semantic, _episodic, _procedural); these are reserved base-type prefixes (see Reserved Namespace Prefixes), distinct from the visibility prefixes (_public, _shared, _local, _system) defined alongside them. Where an ontology is referenced, follow the namespace hierarchy it declares; the examples below omit ontology binding for clarity.

A Fact is a semantic concept — declarative knowledge that holds independently of any single moment:

---
type: semantic
namespace: _semantic/knowledge
---

An Event is an episodic concept — something that happened. Events MAY carry temporal validity to bound when they hold (see Temporal Model):

---
type: episodic
namespace: _episodic/sessions
temporal:
validFrom: 2026-01-15T00:00:00Z
validUntil: 2026-01-15T11:00:00Z
---

Finer distinctions are added through the namespace (e.g. _episodic/incidents), whose path MAY map to an ontology-extended type defined by a referenced ontology (e.g. an incident whose base is episodic) — not through a new unit-level field. Implementations SHOULD express domain categories through type + namespace (the namespace path mapping to an ontology-extended type where the referenced ontology defines one) rather than introducing a separate flat category (or memoryCategory) field: such a field would duplicate the type taxonomy, fork it across implementations, and break the interoperability the base types provide.

Note. The entity types in Entity Types (Person, Organization, …) classify the entities a concept references via its entities array; they are a distinct axis and do not categorize the concept itself.