Data Model
Concept
Section titled “Concept”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.
Knowledge Types
Section titled “Knowledge Types”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/* |
Base Type Descriptions
Section titled “Base Type Descriptions”-
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/).
Ontology-Extended Types
Section titled “Ontology-Extended Types”Ontologies MAY define extended types using namespace prefixes:
# In ontology definitionentity_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: semanticnamespace: _semantic/decisionsontology: id: mif-base---This allows ontologies to define rich taxonomies while maintaining interoperability through the base type foundation.
Ontology Reference
Section titled “Ontology Reference”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 |
Example
Section titled “Example”ontology: id: regenerative-agriculture version: "1.0.0" uri: https://mif-spec.dev/ontologies/regenerative-agriculture.ontology.yamlThe 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:
type(REQUIRED, see Knowledge Types) — the base knowledge type:semantic,episodic, orprocedural.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: semanticnamespace: _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: episodicnamespace: _episodic/sessionstemporal: 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
entitiesarray; they are a distinct axis and do not categorize the concept itself.