Skip to content
MIF

Markdown Format

The .md file is the canonical representation of a MIF concept. Relationships are authoritative in frontmatter relationships[] and mirrored as OKF-legible markdown links in a ## Relationships body section.

Structure

Section titled “Structure”
---
# YAML Frontmatter (required)
id: 550e8400-e29b-41d4-a716-446655440000   # UUID
type: semantic
created: 2026-01-15T10:30:00Z
relationships:
  - type: relates-to
    target: /semantic/other-concept.md
  - type: derived-from
    target: /episodic/source-incident.md
---


# Title (optional, first H1)


Concept content in Markdown format.


## Relationships (optional section, mirrors frontmatter)


- relates-to [Other Concept](/semantic/other-concept.md)
- derived-from [Source Incident](/episodic/source-incident.md)

Entity references are declared in the frontmatter entities[] array (see Entity Types).

Frontmatter Schema

Section titled “Frontmatter Schema”
---
# === REQUIRED ===
id: 550e8400-e29b-41d4-a716-446655440000  # UUID v4
type: semantic                              # Base type: semantic|episodic|procedural
created: 2026-01-15T10:30:00Z              # ISO 8601 datetime


# === RECOMMENDED ===
modified: 2026-01-20T14:22:00Z             # Last modification
ontology:                                   # Applied ontology reference
  id: mif-base                             # Ontology identifier
  version: "1.0.0"                         # Ontology version
  uri: https://mif-spec.dev/ontologies/mif-base  # Ontology URI
namespace: org/user/project                 # Hierarchical scope
title: "Human-readable title"               # Display title
tags:                                       # Classification
  - preference
  - ui


# === OPTIONAL: Temporal ===
temporal:
  validFrom: 2026-01-15T00:00:00Z          # When fact becomes valid
  validUntil: null                          # When fact expires (null = indefinite)
  recordedAt: 2026-01-15T10:30:00Z         # When recorded (transaction time)
  ttl: P90D                                 # Time-to-live (ISO 8601 duration)
  decay:
    model: exponential                      # Decay model
    halfLife: P7D                          # Half-life duration
    strength: 0.85                          # Current strength (0-1)
  accessCount: 5                            # Times accessed
  lastAccessed: 2026-01-20T14:22:00Z       # Last access time


# === OPTIONAL: Provenance ===
provenance:
  sourceType: user_explicit                 # How memory was created
  sourceRef: conversation:conv_456          # Reference to source
  agent: claude-3-opus                      # Creating agent
  confidence: 0.95                          # Confidence score (0-1)
  trustLevel: user_stated                   # Trust classification


# === OPTIONAL: Embedding ===
embedding:
  model: text-embedding-3-small             # Embedding model
  modelVersion: "2024-01"                   # Model version
  dimensions: 1536                          # Vector dimensions
  sourceText: "User prefers dark mode"      # Text that was embedded
  # Note: Actual vectors stored externally via vectorUri


# === OPTIONAL: Aliases ===
aliases:
  - "Dark Mode Preference"
  - "UI Theme Choice"


# === OPTIONAL: Extensions ===
extensions:
  subcog:
    domain: user
    hash: sha256:abc123...
  custom_provider:
    custom_field: value
---

Relationship Syntax

Section titled “Relationship Syntax”

Typed relationships are authoritative in frontmatter and mirrored in the body as standard bundle-relative markdown links, so a generic OKF consumer sees every edge. The body form is - <type> [Text](/path/target.md):

## Relationships


- relates-to [Other Concept](/semantic/other-concept.md)
- derived-from [Source Incident](/episodic/source-incident.md)
- supersedes [Old Policy](/semantic/old-policy.md)

The corresponding frontmatter:

relationships:
  - type: relates-to
    target: /semantic/other-concept.md
  - type: derived-from
    target: /episodic/source-incident.md
  - type: supersedes
    target: /semantic/old-policy.md

Every frontmatter relationships entry MUST have a corresponding body markdown link in the ## Relationships section, and every such body link maps back to a frontmatter entry. Entity references are declared in the frontmatter entities[] array (see Entity Types).

Citations (Level 3)

Section titled “Citations (Level 3)”

Citations provide structured references to external sources that inform, support, or relate to the memory content. Citations are a Level 3 (Full) optional feature.

Frontmatter Schema

Section titled “Frontmatter Schema”
# === OPTIONAL: Citations (Level 3) ===
citations:
  - "@type": Citation                      # REQUIRED: object type
    citationType: article                  # REQUIRED: Source category
    title: "Memory Systems in AI Agents"   # REQUIRED: Citation title
    url: https://arxiv.org/abs/2024.12345  # REQUIRED: Valid URL
    citationRole: supports                 # REQUIRED: Relationship to memory
    author: "Jane Smith"                   # OPTIONAL: string, EntityReference, or array
    date: 2024-06-15                       # OPTIONAL: Publication date
    accessed: 2026-01-20                   # OPTIONAL: Access date
    relevance: 0.95                        # OPTIONAL: Relevance score (0-1)
    note: "Foundational paper on semantic memory"  # OPTIONAL: Annotation

Citation Fields

Section titled “Citation Fields”
Field Required Type Description
@type REQUIRED Const Always Citation
citationType REQUIRED Enum Source category (see Citation Types)
title REQUIRED String Citation title
url REQUIRED URI Valid URL or URI
citationRole REQUIRED Enum Relationship to memory (see Citation Roles)
author OPTIONAL EntityReference, array of EntityReference, or String One or more entity references, or plain text
date OPTIONAL Date Publication date (ISO 8601)
accessed OPTIONAL Date Access date (ISO 8601)
relevance OPTIONAL Decimal Relevance score (0.0-1.0)
note OPTIONAL String Free-form annotation

Citation Types

Section titled “Citation Types”
Type Description Example
article Journal article, blog post arXiv paper, Medium article
book Published book O’Reilly book, academic text
paper Conference/research paper ACM paper, IEEE publication
website General website Documentation site, homepage
documentation Technical documentation API docs, user guides
repository Code repository GitHub repo, GitLab project
video Video content YouTube tutorial, conference talk
podcast Podcast episode Tech podcast, interview
specification Technical specification W3C spec, RFC document
dataset Data source Kaggle dataset, research data
tool Software tool or service SaaS product, CLI tool
other Miscellaneous source Catch-all category

Custom types MAY use namespace prefixes: acme:internal-memo, research:lab-notes

Citation Roles

Section titled “Citation Roles”
Role Description Use Case
supports Provides supporting evidence Confirming research, alignment
refutes Contradicts or disputes Opposing viewpoint, correction
background General context/reference Related reading, foundation
methodology Method or approach source Technique borrowed, framework
contradicts Conflicts with claims Disagreement, alternative view
extends Builds upon cited work Evolution, expansion
derived Direct derivation source Adapted from, based on
source Primary source material Original data, quote
example Illustrative example Case study, demo
review Critical review/analysis Critique, evaluation

Custom roles MAY use namespace prefixes: research:replicates, legal:cites-precedent

Body Section Syntax

Section titled “Body Section Syntax”

An optional ## Citations section MAY appear in the memory body for detailed annotations. When present, corresponding entries MUST exist in frontmatter.

## Citations


- [Memory Systems in AI Agents](https://arxiv.org/abs/2024.12345) by Jane Smith (2024)
  - **Type**: article
  - **Role**: supports
  - **Relevance**: 0.95
  - Foundational paper on semantic memory structures. Introduces bi-temporal
    model that informed MIF's temporal design.


- [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) by W3C
  - **Type**: documentation
  - **Role**: background
  - **Accessed**: 2026-01-18
  - Reference for the JSON-LD projection format.

Author Entity References

Section titled “Author Entity References”

A citation author MAY be plain text or one or more EntityReference objects (see Entity Types):

# Plain text
author: "Jane Smith et al."


# Single author as an entity reference
author:
  "@type": EntityReference
  entity: { "@id": urn:mif:entity:person:jane-smith }
  entityType: Person
  name: Jane Smith

Citation Validation

Section titled “Citation Validation”

Implementations SHOULD validate citations according to these rules:

Required Field Constraints:

Field Constraint
@type MUST be Citation
citationType MUST be a value from Citation Types or a custom namespaced type (e.g., acme:memo)
title MUST be a non-empty string
url MUST be a valid URI (http, https, or custom schemes)
citationRole MUST be a value from Citation Roles or a custom namespaced role (e.g., legal:precedent)

Optional Field Constraints:

Field Constraint
author SHOULD be an EntityReference (or array of them) or plain text
date MUST be ISO 8601 date format (YYYY-MM-DD)
accessed MUST be ISO 8601 date format (YYYY-MM-DD)
relevance MUST be decimal between 0.0 and 1.0 inclusive
note SHOULD be under 1000 characters; longer notes SHOULD use body section

Validation Errors:

Error Severity Action
Missing required field Error Reject citation
Invalid type value Warning Accept with type: "other" fallback
Invalid role value Warning Accept with role: "background" fallback
Malformed URL Error Reject citation
relevance out of range Warning Clamp to 0.0-1.0
Invalid date format Warning Accept as plain text

Compression (Level 3)

Section titled “Compression (Level 3)”

Compression allows large memories to be summarized while preserving the original content. Compression is typically applied by garbage collection processes to reduce memory footprint while retaining semantic value.

Compression Fields

Section titled “Compression Fields”
Field Required Type Description
summary OPTIONAL String Concise 2-3 sentence summary (max 500 characters)
compressedAt OPTIONAL DateTime When compression was applied (ISO 8601)

Frontmatter Schema:

# === OPTIONAL: Compression (Level 3) ===
summary: "User prefers dark mode for reduced eye strain during extended coding sessions. Applies to IDE, terminal, and web applications."
compressedAt: 2026-01-24T10:00:00Z

Compression Criteria

Section titled “Compression Criteria”

Implementations MAY apply compression when memories meet these criteria:

Condition Threshold
Age AND Size Age > 30 days AND content > 100 lines
Decay AND Size Strength < 0.3 AND content > 100 lines

Compression Behavior

Section titled “Compression Behavior”
  • The content field SHOULD be replaced with the compressed summary
  • The original content MAY be preserved in extensions.original_content
  • The summary field contains the generated summary text
  • The compressedAt timestamp indicates when compression occurred
  • Compressed memories retain all other metadata (relationships, entities, etc.)

Compression Validation

Section titled “Compression Validation”
Field Constraint
summary MUST be 500 characters or fewer
compressedAt MUST be ISO 8601 datetime format