This is the abridged developer documentation for Modeled Information Format (MIF) # Introduction > MIF — the Modeled Information Format specification: a vendor-neutral data model for portable AI memory. # Modeled Information Format [Section titled “Modeled Information Format”](#modeled-information-format) > A vendor-neutral data model for portable AI memory, with dual human-readable Markdown and machine-processable JSON-LD representations. This site is the **normative specification** for MIF (Modeled Information Format). It defines the data model, the two on-disk formats, the type system, and the conformance rules, and it serves the canonical JSON Schemas. ## Read the specification [Section titled “Read the specification”](#read-the-specification) Start with the [Specification Overview](/specification/overview/), then work through the core model, the Markdown and JSON-LD formats, the data types, and the reference sections (conformance, conversion, security, appendices) from the sidebar. ## Schemas [Section titled “Schemas”](#schemas) The canonical JSON Schemas are served under [`/schema/`](https://mif-spec.dev/schema/index.json): * `https://mif-spec.dev/schema/mif.schema.json` * `https://mif-spec.dev/schema/citation.schema.json` * `https://mif-spec.dev/schema/ontology/ontology.schema.json` * `https://mif-spec.dev/schema/definitions/entity-reference.schema.json` `$id` values are stable and unversioned; immutable per-release mirrors are available at `/schema//…`. See the [schema catalog](https://mif-spec.dev/schema/index.json) and [versioning notes](https://mif-spec.dev/schema/VERSIONING.md). ## Guides, tutorials, and design records [Section titled “Guides, tutorials, and design records”](#guides-tutorials-and-design-records) Task-oriented guides, tutorials, API references, and the Architecture Decision Records live in the ecosystem documentation at [modeled-information-format.github.io](https://modeled-information-format.github.io/). # MIF Namespace > The MIF JSON-LD vocabulary served at https://mif-spec.dev/ns/, with human and machine-readable forms. Base IRI: `https://mif-spec.dev/ns/` The MIF vocabulary defines the terms used by the JSON-LD projection of MIF concept documents. It is the `@vocab` base of the canonical context at [`/schema/context.jsonld`](/schema/context.jsonld). Term IRIs follow the pattern `https://mif-spec.dev/ns/` (for example `https://mif-spec.dev/ns/Concept`). This page is derived from the canonical context, so it stays in step with the schema. The same vocabulary is available as a machine-readable RDFS document: * Machine-readable vocabulary: [`/ns/vocabulary.jsonld`](/ns/vocabulary.jsonld) * Canonical JSON-LD context: [`/schema/context.jsonld`](/schema/context.jsonld) MIF also reuses Dublin Core (`dc`), Schema.org (`schema`), W3C PROV (`prov`), and XML Schema (`xsd`) terms. Those are defined by their own vocabularies and are not redefined here. ## Classes [Section titled “Classes”](#classes) | Term | IRI | Description | | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `AgentInferred` | `mif:AgentInferred` | Inferred by an AI agent. | | `Citation` | `mif:Citation` | A citation or bibliographic reference. | | `Concept` | `mif:Concept` | The concept document type: every MIF concept declares @type Concept. Also used as the entity type for an abstract idea or topic. | | `ConflictsWith` | `mif:ConflictsWith` | Contradicts another concept. | | `Created` | `mif:Created` | Authored by an entity. | | `DerivedFrom` | `mif:DerivedFrom` | Created based on a source. | | `DocumentReference` | `mif:DocumentReference` | A reference to an external document, by URI and hash, rather than embedded content. | | `EmbeddingReference` | `mif:EmbeddingReference` | A reference to a vector embedding. | | `Entity` | `mif:Entity` | A named entity. | | `EntityData` | `mif:EntityData` | Structured entity data. | | `EntityReference` | `mif:EntityReference` | A reference to an entity within a concept. | | `EpisodicType` | `mif:EpisodicType` | Concept type for events, experiences, sessions, and incidents. | | `ExternalImport` | `mif:ExternalImport` | Imported from an external system. | | `File` | `mif:File` | A file or document. | | `HighConfidence` | `mif:HighConfidence` | High confidence inference. | | `Implements` | `mif:Implements` | Realizes a concept or pattern. | | `LowConfidence` | `mif:LowConfidence` | Low confidence inference. | | `Memory` | `mif:Memory` | The concept document type under the v0.1 name. Deprecated alias of Concept. | | `MentionedIn` | `mif:MentionedIn` | Referenced in a concept. | | `ModerateConfidence` | `mif:ModerateConfidence` | Moderate confidence inference. | | `OntologyReference` | `mif:OntologyReference` | A reference to an ontology definition. | | `Organization` | `mif:Organization` | A company, institution, or group. | | `PartOf` | `mif:PartOf` | Component of a larger whole. | | `Person` | `mif:Person` | A human individual. | | `ProceduralType` | `mif:ProceduralType` | Concept type for processes, runbooks, patterns, and how-to guides. | | `RelatesTo` | `mif:RelatesTo` | General relationship. | | `Relationship` | `mif:Relationship` | A typed relationship between concepts or entities. | | `SemanticType` | `mif:SemanticType` | Concept type for facts, concepts, decisions, preferences, and knowledge. | | `Supersedes` | `mif:Supersedes` | Replaces an older concept. | | `SystemGenerated` | `mif:SystemGenerated` | Generated by the system. | | `Technology` | `mif:Technology` | A technology, framework, or tool. | | `TemporalMetadata` | `mif:TemporalMetadata` | Temporal validity and decay metadata. | | `Uncertain` | `mif:Uncertain` | Uncertain or unverified. | | `UserExplicit` | `mif:UserExplicit` | Directly stated by the user. | | `UserImplicit` | `mif:UserImplicit` | Inferred from user behavior. | | `UserStated` | `mif:UserStated` | Stated by the user. | | `Uses` | `mif:Uses` | Uses a technology or tool. | | `Vector` | `mif:Vector` | An embedding vector. | | `Verified` | `mif:Verified` | Independently verified. | ## Properties [Section titled “Properties”](#properties) | Property | IRI | Range | Description | | ---------------------- | -------------------------- | -------------- | --------------------------------------------------------------------- | | `accessCount` | `mif:accessCount` | `xsd:integer` | Number of times accessed. | | `accessed` | `mif:accessed` | `xsd:dateTime` | When the citation was last accessed. | | `agent` | `mif:agent` | — | The agent that created the concept. | | `agentVersion` | `mif:agentVersion` | — | Version of the creating agent. | | `algorithm` | `mif:algorithm` | — | Hash algorithm. | | `aliases` | `mif:aliases` | — | Alternative names or identifiers. | | `blocks` | `mif:blocks` | — | Named content blocks. | | `byteLength` | `mif:byteLength` | `xsd:integer` | Size of the referenced document in bytes. | | `citationRole` | `mif:citationRole` | — | How the citation relates to the concept. | | `citationType` | `mif:citationType` | — | Category of the citation source. | | `citations` | `mif:citations` | — | Collection of citations. | | `conceptType` | `mif:conceptType` | — | The base concept type classification. | | `confidence` | `mif:confidence` | `xsd:decimal` | Confidence score (0.0-1.0). | | `content` | `mif:content` | `xsd:string` | The textual content of a concept. | | `contentType` | `mif:contentType` | — | MIME type of the referenced document. | | `currentStrength` | `mif:currentStrength` | `xsd:decimal` | Current concept strength (0.0-1.0). | | `data` | `mif:data` | — | Raw vector data. | | `decay` | `mif:decay` | — | Decay model container. | | `dimensions` | `mif:dimensions` | `xsd:integer` | Vector dimensions. | | `documentType` | `mif:documentType` | — | Category of the referenced document. | | `documents` | `mif:documents` | — | Collection of external document references. | | `embedding` | `mif:embedding` | — | Embedding reference container. | | `encoding` | `mif:encoding` | — | Vector encoding format. | | `entities` | `mif:entities` | — | Entity references. | | `entity` | `mif:entity` | — | Reference to a single entity. | | `entityType` | `mif:entityType` | — | Type classification of an entity. | | `entity_id` | `mif:entity_id` | — | Entity identifier. | | `entity_type` | `mif:entity_type` | — | Alias for entityType. | | `extensions` | `mif:extensions` | — | Vendor-specific extension data. | | `halfLife` | `mif:halfLife` | `xsd:duration` | Decay half-life duration. | | `hash` | `mif:hash` | — | Content hash of a referenced document. | | `lastAccessed` | `mif:lastAccessed` | `xsd:dateTime` | When the concept was last accessed. | | `lastReinforced` | `mif:lastReinforced` | `xsd:dateTime` | When the concept was last reinforced. | | `memoryType` | `mif:memoryType` | — | The base memory type classification. Deprecated alias of conceptType. | | `metadata` | `mif:metadata` | — | Arbitrary relationship metadata, carried as a JSON literal. | | `model` | `mif:model` | — | Decay model type (none, linear, exponential, step). | | `modelVersion` | `mif:modelVersion` | — | Embedding model version. | | `namespace` | `mif:namespace` | — | Hierarchical scope for categorization. | | `normalized` | `mif:normalized` | `xsd:boolean` | Whether the vector is normalized. | | `note` | `mif:note` | — | Annotation or note text. | | `ontology` | `mif:ontology` | — | Ontology reference container. | | `provenance` | `mif:provenance` | — | Provenance metadata container. | | `recordedAt` | `mif:recordedAt` | `xsd:dateTime` | Transaction time (when recorded). | | `reinforcementHistory` | `mif:reinforcementHistory` | — | Ordered list of reinforcement events. | | `relationshipType` | `mif:relationshipType` | — | The type of relationship. | | `relationships` | `mif:relationships` | — | Relationship references. | | `relevance` | `mif:relevance` | `xsd:decimal` | Relevance score (0.0-1.0). | | `retrievedAt` | `mif:retrievedAt` | `xsd:dateTime` | When the referenced document was retrieved. | | `role` | `mif:role` | — | Role in the concept context. | | `sourceRef` | `mif:sourceRef` | — | Reference to the original source. | | `sourceText` | `mif:sourceText` | — | Text that was embedded. | | `sourceType` | `mif:sourceType` | — | How the concept was created. | | `strength` | `mif:strength` | `xsd:decimal` | Relationship strength (0.0-1.0). | | `tags` | `mif:tags` | — | Classification tags. | | `target` | `mif:target` | — | The target of the relationship. | | `temporal` | `mif:temporal` | — | Temporal metadata container. | | `trustLevel` | `mif:trustLevel` | — | Trust classification level. | | `ttl` | `mif:ttl` | `xsd:duration` | Time-to-live duration. | | `uri` | `mif:uri` | — | URI reference. | | `validFrom` | `mif:validFrom` | `xsd:dateTime` | When the fact becomes valid. | | `validUntil` | `mif:validUntil` | `xsd:dateTime` | When the fact expires. | | `value` | `mif:value` | — | Hash value. | | `vector` | `mif:vector` | — | Vector data container. | | `vectorUri` | `mif:vectorUri` | — | URI to external vector data. | | `version` | `mif:version` | — | Version string. | # Appendices > Quick references for YAML frontmatter, relationship types, entity syntax, and citations. ## Appendix A: YAML Frontmatter Quick Reference [Section titled “Appendix A: YAML Frontmatter Quick Reference”](#appendix-a-yaml-frontmatter-quick-reference) ```yaml --- # Required id: uuid-v4 type: semantic|episodic|procedural created: ISO-8601-datetime # Recommended modified: ISO-8601-datetime ontology: id: ontology-identifier # Matches ontology.id in definition version: "1.0.0" # Semantic version (optional) uri: https://example.com/ont # Ontology URL (optional) namespace: hierarchical/path title: "Human Title" tags: [tag1, tag2] # Optional aliases: ["Alt Name 1", "Alt Name 2"] temporal: validFrom: ISO-8601-datetime validUntil: ISO-8601-datetime | null recordedAt: ISO-8601-datetime ttl: ISO-8601-duration decay: model: none|linear|exponential|step halfLife: ISO-8601-duration strength: 0.0-1.0 accessCount: integer lastAccessed: ISO-8601-datetime provenance: sourceType: user_explicit|user_implicit|agent_inferred|external_import|system_generated sourceRef: uri agent: string confidence: 0.0-1.0 trustLevel: verified|user_stated|high_confidence|moderate_confidence|low_confidence|uncertain embedding: model: string modelVersion: string dimensions: integer sourceText: string extensions: provider_name: custom_field: value --- ``` *** ## Appendix B: Relationship Types Quick Reference [Section titled “Appendix B: Relationship Types Quick Reference”](#appendix-b-relationship-types-quick-reference) Relationships appear in a `## Relationships` body section as `- [Text](/path/target.md)`, mirroring the authoritative frontmatter `relationships[]`. | Body Markdown Syntax | JSON-LD `type` | Description | | ---------------------------------- | ---------------- | -------------------- | | `- relates-to [X](/path/x.md)` | `relates-to` | General relationship | | `- derived-from [X](/path/x.md)` | `derived-from` | Created from source | | `- supersedes [X](/path/x.md)` | `supersedes` | Replaces older | | `- conflicts-with [X](/path/x.md)` | `conflicts-with` | Contradicts | | `- part-of [X](/path/x.md)` | `part-of` | Component of | | `- implements [X](/path/x.md)` | `implements` | Realizes | | `- uses [X](/path/x.md)` | `uses` | Utilizes | | `- created-by [X](/path/x.md)` | `created-by` | Authored by | | `- mentioned-in [X](/path/x.md)` | `mentioned-in` | Referenced in | *** ## Appendix C: Entity Reference Syntax [Section titled “Appendix C: Entity Reference Syntax”](#appendix-c-entity-reference-syntax) | Markdown | Meaning | | ----------------------------- | ---------------------------- | | `@[[Name]]` | Reference entity by name | | `@[[Name\|Person]]` | Reference with explicit type | | `@[[Name\|uses]]` | Reference with relationship | | `@[[Name\|Technology\|uses]]` | Type and relationship | *** ## Appendix D: Citations Quick Reference [Section titled “Appendix D: Citations Quick Reference”](#appendix-d-citations-quick-reference) ### Citation Types [Section titled “Citation Types”](#citation-types) | Type | Description | | --------------- | -------------------------- | | `article` | Journal article, blog post | | `book` | Published book | | `paper` | Conference/research paper | | `website` | General website | | `documentation` | Technical documentation | | `repository` | Code repository | | `video` | Video content | | `podcast` | Podcast episode | | `specification` | Technical specification | | `dataset` | Data source | | `tool` | Software tool or service | | `other` | Miscellaneous source | ### Citation Roles [Section titled “Citation Roles”](#citation-roles) | Role | Description | | ------------- | ---------------------------- | | `supports` | Provides supporting evidence | | `refutes` | Contradicts or disputes | | `background` | General context/reference | | `methodology` | Method or approach source | | `contradicts` | Conflicts with claims | | `extends` | Builds upon cited work | | `derived` | Direct derivation source | | `source` | Primary source material | | `example` | Illustrative example | | `review` | Critical review/analysis | ### Frontmatter Syntax [Section titled “Frontmatter Syntax”](#frontmatter-syntax) ```yaml citations: - type: article # REQUIRED title: "Citation Title" # REQUIRED url: https://example.com # REQUIRED role: supports # REQUIRED author: "@[[Name|Person]]" # OPTIONAL date: 2024-06-15 # OPTIONAL accessed: 2026-01-20 # OPTIONAL relevance: 0.95 # OPTIONAL (0-1) note: "Annotation" # OPTIONAL ``` ### Body Section Syntax [Section titled “Body Section Syntax”](#body-section-syntax) ```markdown ## Citations - [Title](url) by @[[Author|Person]] (date) - **Type**: article - **Role**: supports - **Relevance**: 0.95 - Long-form annotation here. ``` *** ## References [Section titled “References”](#references) * [RFC 2119: Key words for use in RFCs](https://www.rfc-editor.org/rfc/rfc2119) * [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) * [Dublin Core Metadata Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) * [W3C PROV-DM](https://www.w3.org/TR/prov-dm/) * [ISO 8601: Date and Time Format](https://www.iso.org/iso-8601-date-and-time-format.html) * [Obsidian Help](https://help.obsidian.md/) # Conformance Levels > Level 1, 2, and 3 conformance requirements for MIF implementations. ### Level 1: Core (REQUIRED for conformance) [Section titled “Level 1: Core (REQUIRED for conformance)”](#level-1-core-required-for-conformance) * `id` (UUID), `type`, `content`, `created` fields * Valid OKF bundle shape (a directory of `.md` concept files) * Markdown-link relationship edges in a `## Relationships` section ### Level 2: Standard (RECOMMENDED) [Section titled “Level 2: Standard (RECOMMENDED)”](#level-2-standard-recommended) * All Level 1 requirements * Namespace support * Entity references * Relationship types * Temporal metadata (timestamps) ### Level 3: Full (OPTIONAL) [Section titled “Level 3: Full (OPTIONAL)”](#level-3-full-optional) * All Level 2 requirements * Bi-temporal model * Decay functions * W3C PROV provenance * Embedding references * Citations with rich metadata * Compression support * Extension support ### Conformance Statement [Section titled “Conformance Statement”](#conformance-statement) Implementations SHOULD declare their conformance level: .mif/config.yaml ```yaml mif_version: "1.0.0" conformance_level: 2 extensions: - subcog - custom-provider ``` # Conversion Rules > Rules for converting between Markdown and JSON-LD formats. Markdown is canonical; the JSON-LD projection is regenerated from it. The round trip MUST be lossless. ### Markdown to JSON-LD [Section titled “Markdown to JSON-LD”](#markdown-to-json-ld) 1. Parse the YAML frontmatter, including the authoritative `relationships[]`, and map each property into the JSON-LD projection: `id` becomes `@id` (`urn:mif:`), `type` becomes `conceptType`, and the remaining fields pass through under the context. 2. Take the full Markdown body, verbatim, as the `content` field. The OKF-legible `## Relationships` body mirror is part of the body, so it is carried inside `content`. 3. Add the projection mirror fields the converter always emits: `timestamp` (= `modified`, else `created`) and, when `summary` is present, `description` (= `summary`). ### JSON-LD to Markdown [Section titled “JSON-LD to Markdown”](#json-ld-to-markdown) 1. Recover the frontmatter from the JSON-LD properties: `@id` (`urn:mif:`) becomes `id` (``), `conceptType` becomes `type`, and the remaining properties (including `relationships[]`) pass through. 2. Write the `content` field back as the Markdown body, verbatim. Any `## Relationships`/`## Entities` body mirror is authored content preserved unchanged, which is what keeps the round trip lossless. ### Example Conversion [Section titled “Example Conversion”](#example-conversion) **Input (JSON-LD):** ```json { "@context": "https://mif-spec.dev/schema/context.jsonld", "@type": "Concept", "conceptType": "semantic", "@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000", "title": "Dark Mode", "content": "User prefers dark mode\n\n## Relationships\n\n- relates-to [UI Preferences](/semantic/ui-prefs.md)", "created": "2026-01-15T10:30:00Z", "relationships": [ {"type": "relates-to", "target": "/semantic/ui-prefs.md"} ] } ``` **Output (Markdown):** ```markdown --- id: 550e8400-e29b-41d4-a716-446655440000 type: semantic created: 2026-01-15T10:30:00Z title: Dark Mode relationships: - type: relates-to target: /semantic/ui-prefs.md --- User prefers dark mode ## Relationships - relates-to [UI Preferences](/semantic/ui-prefs.md) ``` ### Citations Conversion [Section titled “Citations Conversion”](#citations-conversion) `citations` is authored in frontmatter in its final shape and passes through to the JSON-LD projection verbatim (it is part of the converter’s passthrough set, so the frontmatter and projection forms are identical). Each entry is a `Citation` object: `@type`, `citationType`, `citationRole`, `title`, and `url` are required; `author`, `date`, `accessed`, `relevance`, and `note` are optional. The `author` value is a wiki-link string and is preserved as written. Any `## Citations` body mirror is authored content carried inside `content`. **Example (frontmatter, identical in the JSON-LD projection):** ```yaml citations: - "@type": Citation citationType: article citationRole: supports title: "Research Paper" url: https://example.com/paper author: "@[[Jane Smith|Person]]" date: "2025-11-15" accessed: "2026-01-18" relevance: 0.92 ``` # Data Model > Required and optional fields, schema definitions, and core data structures. ### Concept [Section titled “Concept”](#concept) A concept is the atomic element of MIF — a single `.md` file in a bundle. It contains: | Property | Required | Type | Description | | --------------- | ----------- | -------- | ----------------------------------------------------- | | `id` | REQUIRED | UUID | Globally unique identifier (stable across relocation) | | `content` | REQUIRED | String | The concept content (Markdown) | | `type` | REQUIRED | Enum | Knowledge classification (see below) | | `created` | REQUIRED | DateTime | When the memory was created | | `modified` | RECOMMENDED | DateTime | When last modified | | `ontology` | RECOMMENDED | Object | Reference to applied ontology | | `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 | 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”](#knowledge-types) Every concept declares one of 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:** * **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”](#ontology-extended-types) Ontologies MAY define extended types using namespace prefixes: ```yaml # 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: ```yaml --- type: semantic namespace: _semantic/decisions ontology: id: mif-base --- ``` This allows ontologies to define rich taxonomies while maintaining interoperability through the base type foundation. ### Ontology Reference [Section titled “Ontology Reference”](#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:** ```yaml ontology: id: regenerative-agriculture version: "1.0.0" uri: https://raw.githubusercontent.com/modeled-information-format/MIF/main/ontologies/examples/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 # Embeddings > Embedding reference specifications for vector search integration. ### Model-Agnostic Approach [Section titled “Model-Agnostic Approach”](#model-agnostic-approach) MIF stores embedding metadata, not raw vectors: ```yaml embedding: model: text-embedding-3-small modelVersion: "2024-01" dimensions: 1536 sourceText: "The text that was embedded" normalized: true ``` This allows: * Re-embedding on import with different models * Smaller file sizes * Model migration without data loss ### Optional Vector Storage [Section titled “Optional Vector Storage”](#optional-vector-storage) For providers that need vector portability: **External Reference:** ```yaml embedding: model: text-embedding-3-small sourceText: "..." vectorUri: "urn:mif:vector:550e8400-e29b-41d4-a716-446655440000" ``` **JSON-LD with external vector URI:** ```json "embedding": { "model": "text-embedding-3-small", "sourceText": "...", "vectorUri": "urn:mif:vector:550e8400-e29b-41d4-a716-446655440000" } ``` # Entity Types > Person, Organization, Technology, Concept, and File entity type definitions. MIF provides an **extensible entity type system**. Implementations SHOULD support the core types for interoperability, but MAY define custom types for domain-specific needs. ### Entity Type Architecture [Section titled “Entity Type Architecture”](#entity-type-architecture) Entity types are **not hard-coded**. They are defined in vault configuration and can be extended per-project: .mif/config.yaml ```yaml entity_types: # Core types (RECOMMENDED for interoperability) - name: Person description: Human individual icon: "\U0001F464" color: blue - name: Organization description: Company, team, or group icon: "\U0001F3E2" color: purple - name: Technology description: Tool, language, or framework icon: "\U0001F527" color: green - name: Concept description: Abstract idea or topic icon: "\U0001F4A1" color: yellow - name: File description: Document or code file icon: "\U0001F4C4" color: gray # Custom types (domain-specific) - name: Project description: Work initiative or product icon: "\U0001F4E6" color: orange - name: Event description: Meeting, deadline, or occurrence icon: "\U0001F4C5" color: red - name: Location description: Physical or virtual place icon: "\U0001F4CD" color: teal ``` ### Core Entity Types (Recommended) [Section titled “Core Entity Types (Recommended)”](#core-entity-types-recommended) For maximum interoperability, implementations SHOULD recognize these five core types: | Type | Description | Example | URI | | -------------- | ---------------------------- | ----------------- | ------------------ | | `Person` | Human individual | User, team member | `mif:Person` | | `Organization` | Company, team, or group | Acme Corp | `mif:Organization` | | `Technology` | Tool, language, or framework | Python, React | `mif:Technology` | | `Concept` | Abstract idea or topic | Dark Mode | `mif:Concept` | | `File` | Document or code file | src/main.py | `mif:File` | ### Custom Entity Types [Section titled “Custom Entity Types”](#custom-entity-types) Providers MAY define additional entity types using namespaced URIs: ```yaml # Custom type definition entity_types: - name: Animal namespace: farm # Results in URI: farm:Animal description: Livestock or pet properties: - name: breed type: string - name: birth_date type: date - name: registry_id type: string ``` **JSON-LD representation of custom types:** ```json { "@context": [ "https://mif-spec.dev/schema/context.jsonld", {"farm": "https://example.org/farm/"} ], "@type": "farm:Animal", "@id": "urn:mif:entity:animal:sheep-001", "name": "Dolly", "farm:breed": "Dorper", "farm:birth_date": "2025-03-15" } ``` ### Entity Subtyping (`subtype_of`) [Section titled “Entity Subtyping (subtype\_of)”](#entity-subtyping-subtype_of) An entity type MAY declare `subtype_of`, naming one or more parent entity types it specializes. A subtype is **substitutable** for any of its supertypes wherever the supertype is admissible — most notably a relationship endpoint domain: an edge whose `from`/`to` names a parent type also admits any of its subtypes. ```yaml entity_types: - name: incident-report base: episodic - name: security-incident base: episodic subtype_of: [incident-report] # substitutable wherever incident-report is admissible ``` Rules (enforced by `scripts/validate-ontologies.py`): * Every parent MUST resolve to a declared entity type — in this ontology, or in one it `extends` (resolved across the full extends chain). * A subtype’s `required` set MUST include every `required` field of each parent (substitutability). A subtype SHOULD add, not retype, parent fields (retyping is not machine-checked). * The `subtype_of` graph MUST be acyclic, and a type cannot be its own subtype. `subtype_of` is optional and additive; ontologies that omit it are unaffected. It projects to JSON-LD as `mif:subtypeOf` (a set of entity-type `@id`s). ### Entity Schema [Section titled “Entity Schema”](#entity-schema) **Markdown (in `.mif/entities/` directory):** .mif/entities/person/jane-doe.yaml ```yaml id: jane-doe type: Person name: Jane Doe aliases: - J. Doe - jdoe properties: email: jane@example.com role: Engineer ``` **JSON-LD:** ```json { "@context": "https://mif-spec.dev/schema/context.jsonld", "@type": "Person", "@id": "urn:mif:entity:person:jane-doe", "name": "Jane Doe", "aliases": ["J. Doe", "jdoe"], "properties": { "email": "jane@example.com", "role": "Engineer" } } ``` ### Entity References in Memories [Section titled “Entity References in Memories”](#entity-references-in-memories) **Markdown:** ```markdown ## Entities - mentions @[[Jane Doe]] - uses @[[Python|Technology]] - about @[[Dark Mode|Concept]] ``` **JSON-LD:** ```json "entities": [ { "@type": "EntityReference", "entity": {"@id": "urn:mif:entity:person:jane-doe"}, "role": "mentions" } ] ``` # File Format > File extensions, encoding requirements, and YAML frontmatter structure. ### File Extensions [Section titled “File Extensions”](#file-extensions) | Extension | Format | MIME Type | | --------- | ---------------------------- | ----------------------------------------------------- | | `.md` | Markdown (canonical) | `text/markdown; variant=mif` | | `.jsonld` | JSON-LD (derived projection) | `application/ld+json; profile="https://mif-spec.dev"` | Concept files use the `.md` extension only. The derived JSON-LD projection uses `.jsonld` (never `.md`), so OKF’s `*.md` glob never ingests it. ### Concept Identity [Section titled “Concept Identity”](#concept-identity) A concept’s OKF identity is its bundle-relative path minus the `.md` extension. The frontmatter `id` field MUST be a UUID, providing a stable identity that survives concept relocation; it is MIF-only and invisible to OKF. ### File Naming [Section titled “File Naming”](#file-naming) Human-readable, path-meaningful names are RECOMMENDED, since the OKF concept ID is derived from the path: ```plaintext dark-mode-preference.md ``` The UUID lives in frontmatter rather than the filename: ```plaintext _semantic/preferences/dark-mode-preference.md ``` The derived projection sits alongside as `dark-mode-preference.jsonld`. ### Directory Structure [Section titled “Directory Structure”](#directory-structure) A MIF vault SHOULD follow this structure: ```plaintext vault/ ├── .mif/ # MIF configuration │ ├── config.yaml # Vault configuration │ ├── context.jsonld # Local JSON-LD context │ └── entities/ # Entity definitions │ ├── person/ │ ├── organization/ │ ├── technology/ │ ├── concept/ │ └── file/ ├── memories/ # Concept files │ ├── {namespace}/ # Namespace directories │ │ ├── {slug}.md # Canonical concept │ │ └── {slug}.jsonld # Derived projection │ └── ... └── README.md # Vault documentation ``` # JSON-LD Context > The MIF JSON-LD context definition and namespace mappings. ### Context URL [Section titled “Context URL”](#context-url) ```plaintext https://mif-spec.dev/schema/context.jsonld ``` ### Context Definition [Section titled “Context Definition”](#context-definition) The following is a representative subset of `schema/context.jsonld`; the full context includes additional term definitions. ```json { "@context": { "@version": 1.1, "mif": "https://mif-spec.dev/ns/", "schema": "https://schema.org/", "dc": "http://purl.org/dc/terms/", "prov": "http://www.w3.org/ns/prov#", "xsd": "http://www.w3.org/2001/XMLSchema#", "Memory": "mif:Memory", "Entity": "mif:Entity", "Relationship": "mif:Relationship", "TemporalMetadata": "mif:TemporalMetadata", "EmbeddingReference": "mif:EmbeddingReference", "EntityReference": "mif:EntityReference", "OntologyReference": "mif:OntologyReference", "Person": "mif:Person", "Organization": "mif:Organization", "Technology": "mif:Technology", "Concept": "mif:Concept", "File": "mif:File", "id": "@id", "type": "@type", "content": "mif:content", "conceptType": { "@id": "mif:conceptType", "@type": "@vocab" }, "memoryType": { "@id": "mif:memoryType", "@type": "@vocab" }, "title": "dc:title", "namespace": "mif:namespace", "tags": "mif:tags", "aliases": "mif:aliases", "created": { "@id": "dc:created", "@type": "xsd:dateTime" }, "modified": { "@id": "dc:modified", "@type": "xsd:dateTime" }, "ontology": "mif:ontology", "entities": "mif:entities", "relationships": { "@id": "mif:relationships", "@container": "@set", "@context": { "@vocab": "https://mif-spec.dev/ns/", "type": { "@id": "mif:relationshipType", "@type": "@vocab" }, "target": { "@id": "mif:target", "@type": "@id" } } }, "temporal": "mif:temporal", "provenance": "mif:provenance", "embedding": "mif:embedding", "extensions": "mif:extensions", "relationshipType": "mif:relationshipType", "target": "mif:target", "strength": "mif:strength", "validFrom": { "@id": "mif:validFrom", "@type": "xsd:dateTime" }, "validUntil": { "@id": "mif:validUntil", "@type": "xsd:dateTime" }, "recordedAt": { "@id": "mif:recordedAt", "@type": "xsd:dateTime" }, "ttl": "mif:ttl", "decay": "mif:decay", "accessCount": "mif:accessCount", "lastAccessed": { "@id": "mif:lastAccessed", "@type": "xsd:dateTime" }, "sourceType": "mif:sourceType", "sourceRef": "mif:sourceRef", "agent": "mif:agent", "confidence": "mif:confidence", "trustLevel": "mif:trustLevel", "model": "mif:model", "modelVersion": "mif:modelVersion", "dimensions": "mif:dimensions", "sourceText": "mif:sourceText", "vectorUri": "mif:vectorUri", "citations": { "@id": "mif:citations", "@container": "@set" }, "Citation": "mif:Citation", "citationType": { "@id": "mif:citationType", "@type": "@vocab" }, "citationRole": { "@id": "mif:citationRole", "@type": "@vocab" }, "url": { "@id": "schema:url", "@type": "@id" }, "author": "schema:author", "date": { "@id": "schema:datePublished", "@type": "xsd:date" }, "relevance": { "@id": "mif:relevance", "@type": "xsd:decimal" }, "accessed": { "@id": "mif:accessed", "@type": "xsd:dateTime" }, "note": "mif:note", "summary": "mif:summary", "compressedAt": { "@id": "mif:compressedAt", "@type": "xsd:dateTime" } } } ``` The canonical terms are `conceptType` (the knowledge taxonomy) and, inside each `relationships[]` entry, `type` (the kebab-case relationship type, scoped to `mif:relationshipType`) and `target`. The legacy terms `memoryType`, the document `@type` value `Memory`, `relationshipType`, and the PascalCase relationship terms (`RelatesTo`, `DerivedFrom`, and so on) are retained as deprecated aliases so existing documents continue to expand. # JSON-LD Format > The derived .jsonld projection for machine-processable concept documents. Markdown is canonical. The JSON-LD form below is a **derived projection**: regenerate it from the `.md` source with `scripts/mif_convert.py`. It uses the `.jsonld` extension (never `.md`, so OKF’s `*.md` glob never ingests it) and MUST round-trip losslessly back to markdown. If the two disagree, markdown wins. ### Structure [Section titled “Structure”](#structure) ```json { "@context": "https://mif-spec.dev/schema/context.jsonld", "@type": "Concept", "@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000", "content": "User prefers dark mode for all applications", "conceptType": "semantic", "title": "Dark Mode Preference", "created": "2026-01-15T10:30:00Z", "modified": "2026-01-20T14:22:00Z", "timestamp": "2026-01-20T14:22:00Z", "namespace": "_semantic/preferences", "tags": ["preference", "ui", "accessibility"], "entities": [...], "relationships": [...], "temporal": {...}, "provenance": {...}, "embedding": {...}, "extensions": {...} } ``` The projection always includes the OKF-legible mirror field `timestamp` (the value of `modified`, or `created` when there is no `modified`). When the source has a `summary`, it also includes `description` (mapped from `summary`). These are derived mirrors of the canonical frontmatter; markdown remains authoritative. ### Full Example [Section titled “Full Example”](#full-example) ```json { "@context": [ "https://mif-spec.dev/schema/context.jsonld", { "prov": "http://www.w3.org/ns/prov#", "subcog": "https://github.com/zircote/subcog/ns/" } ], "@type": ["Concept", "prov:Entity"], "@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000", "content": "User prefers dark mode for all applications. This applies to:\n- IDE themes\n- Terminal colors\n- Web applications\n- Mobile apps", "conceptType": "semantic", "title": "Dark Mode Preference", "created": "2026-01-15T10:30:00Z", "modified": "2026-01-20T14:22:00Z", "timestamp": "2026-01-20T14:22:00Z", "ontology": { "@type": "OntologyReference", "id": "mif-base", "version": "1.0.0" }, "namespace": "_semantic/preferences", "tags": ["preference", "ui", "accessibility"], "aliases": ["Dark Mode Preference", "UI Theme Choice"], "entities": [ { "@type": "EntityReference", "entity": {"@id": "urn:mif:entity:person:jane-doe"}, "role": "subject" }, { "@type": "EntityReference", "entity": {"@id": "urn:mif:entity:concept:dark-mode"}, "role": "topic" } ], "relationships": [ { "type": "relates-to", "target": "urn:mif:memory:ui-preferences", "strength": 0.85 }, { "type": "supersedes", "target": "urn:mif:memory:old-theme-preference" } ], "temporal": { "@type": "TemporalMetadata", "validFrom": "2026-01-15T00:00:00Z", "validUntil": null, "recordedAt": "2026-01-15T10:30:00Z", "ttl": "P90D", "decay": { "model": "exponential", "halfLife": "P7D", "currentStrength": 0.85 }, "accessCount": 5, "lastAccessed": "2026-01-20T14:22:00Z" }, "provenance": { "@type": "prov:Entity", "sourceType": "user_explicit", "prov:wasGeneratedBy": { "@type": "prov:Activity", "prov:wasAssociatedWith": { "@id": "urn:mif:agent:claude-3-opus", "@type": "prov:SoftwareAgent" } }, "prov:wasDerivedFrom": { "@id": "urn:mif:conversation:conv-456" }, "prov:wasAttributedTo": { "@id": "urn:mif:entity:person:jane-doe" }, "confidence": 0.95, "trustLevel": "user_stated" }, "embedding": { "@type": "EmbeddingReference", "model": "text-embedding-3-small", "modelVersion": "2024-01", "dimensions": 1536, "sourceText": "User prefers dark mode for all applications", "vectorUri": "urn:mif:vector:550e8400-e29b-41d4-a716-446655440000" }, "citations": [ { "@type": "Citation", "citationType": "article", "citationRole": "supports", "title": "Dark Mode UI Benefits for Developer Productivity", "url": "https://example.com/dark-mode-research", "author": { "@type": "EntityReference", "entity": {"@id": "urn:mif:entity:person:jane-smith"}, "entityType": "Person", "name": "Jane Smith" }, "date": "2024-03-15", "accessed": "2026-01-18", "relevance": 0.92, "note": "Research supporting dark mode preference for reduced eye strain" } ], "extensions": { "subcog:domain": "user", "subcog:hash": "sha256:4c04b32ddc2053b5..." } } ``` # Markdown Format > The canonical .md format specification for human-readable concept files. 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”](#structure) ```markdown --- # 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) ## Entities (optional section) - mentions @[[Person Name]] - uses @[[Technology Name]] ``` ### Frontmatter Schema [Section titled “Frontmatter Schema”](#frontmatter-schema) ```yaml --- # === 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”](#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 `- [Text](/path/target.md)`: ```markdown ## 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: ```yaml 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 use `@[[Name|Type]]` syntax (see Entity Types). ### Block References [Section titled “Block References”](#block-references) Blocks can be referenced for granular linking within a file: ```markdown This is an important statement. ^important-point - Key insight about the system ^insight-1 ``` ### Citations (Level 3) [Section titled “Citations (Level 3)”](#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”](#frontmatter-schema-1) ```yaml # === OPTIONAL: Citations (Level 3) === citations: - type: article # REQUIRED: Source category title: "Memory Systems in AI Agents" # REQUIRED: Citation title url: https://arxiv.org/abs/2024.12345 # REQUIRED: Valid URL role: supports # REQUIRED: Relationship to memory author: "@[[Jane Smith|Person]]" # OPTIONAL: Entity ref or text 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”](#citation-fields) | Field | Required | Type | Description | | ----------- | -------- | ------- | ------------------------------------------- | | `type` | REQUIRED | Enum | Source category (see Citation Types) | | `title` | REQUIRED | String | Citation title | | `url` | REQUIRED | URI | Valid URL or URI | | `role` | REQUIRED | Enum | Relationship to memory (see Citation Roles) | | `author` | OPTIONAL | String | Entity reference 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”](#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”](#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”](#body-section-syntax) An optional `## Citations` section MAY appear in the memory body for detailed annotations. When present, corresponding entries MUST exist in frontmatter. ```markdown ## Citations - [Memory Systems in AI Agents](https://arxiv.org/abs/2024.12345) by @[[Jane Smith|Person]] (2024) - **Type**: article - **Role**: supports - **Relevance**: 0.95 - Foundational paper on semantic memory structures. Introduces bi-temporal model that informed MIF's temporal design. - [Obsidian Help](https://help.obsidian.md/) by @[[Obsidian Team|Organization]] - **Type**: documentation - **Role**: background - **Accessed**: 2026-01-18 - Reference for wiki-link syntax and block references. ``` #### Author Entity References [Section titled “Author Entity References”](#author-entity-references) Authors MAY use wiki-link syntax to reference MIF entities: ```yaml # Single author entity author: "@[[Jane Smith|Person]]" # Multiple authors (comma-separated) author: "@[[Jane Smith|Person]], @[[John Doe|Person]]" # Organization author author: "@[[Anthropic|Organization]]" # Plain text (no entity reference) author: "Jane Smith et al." ``` #### Citation Validation [Section titled “Citation Validation”](#citation-validation) Implementations SHOULD validate citations according to these rules: **Required Field Constraints:** | Field | Constraint | | ------- | ----------------------------------------------------------------------------------------- | | `type` | 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) | | `role` | MUST be a value from Citation Roles or a custom namespaced role (e.g., `legal:precedent`) | **Optional Field Constraints:** | Field | Constraint | | ----------- | ----------------------------------------------------------------------------------------------- | | `author` | SHOULD be entity reference(s) `@[[Name\|Type]]` or plain text; multiple authors comma-separated | | `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-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”](#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:** ```yaml # === 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”](#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”](#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”](#compression-validation) | Field | Constraint | | -------------- | -------------------------------- | | `summary` | MUST be 500 characters or fewer | | `compressedAt` | MUST be ISO 8601 datetime format | # Namespace Model > Namespace hierarchy, reserved prefixes, and organizational patterns for concepts. ### Namespace Structure [Section titled “Namespace Structure”](#namespace-structure) Namespaces use a flexible scoping model with reserved prefixes for cross-organization sharing: ```plaintext {root}/{scope}+[/{session}] ``` Where `{root}` is either: * **Organization name** - private to that organization * **Reserved prefix** - special namespace with defined semantics ### Reserved Namespace Prefixes [Section titled “Reserved Namespace Prefixes”](#reserved-namespace-prefixes) Names beginning with underscore (`_`) are reserved for special namespaces: | Prefix | Visibility | Description | | --------- | -------------- | --------------------------------------------------- | | `_public` | Global | Publicly accessible by anyone | | `_shared` | Negotiated | Cross-organization sharing with explicit agreements | | `_local` | Local only | Never synchronized or exported | | `_system` | Implementation | Reserved for system/implementation use | **Examples:** ```plaintext # Public knowledge (globally accessible) _public/python/async-patterns _public/react/hooks-best-practices _public/security/owasp-top-10 # Shared between organizations (requires agreement) _shared/cncf/kubernetes/patterns # CNCF member consortium _shared/acme+bigcorp/integration-api # Bilateral agreement _shared/industry-healthcare/hipaa-compliance # Organization-private (default) acme-corp/jane-doe/preferences acme-corp/project-x/architecture-decisions acme-corp/team-frontend/patterns ``` ### Flexible Scopes Within Organizations [Section titled “Flexible Scopes Within Organizations”](#flexible-scopes-within-organizations) Within an organization, scopes are **peer-level** - users, projects, teams, and other organizational units are treated equally: ```plaintext {organization}/{scope}+ Examples: - acme-corp/jane-doe # user scope - acme-corp/project-x # project scope - acme-corp/team-frontend # team scope - acme-corp/jane-doe/project-x # user + project (order flexible) - acme-corp/project-x/jane-doe # same as above - acme-corp/team-frontend/project-x # team + project ``` **Key principle:** Within an organization, there is no enforced hierarchy between users, projects, or teams. The path segments represent scope intersection, not parent-child relationships. ### Shared Namespace Agreements [Section titled “Shared Namespace Agreements”](#shared-namespace-agreements) The `_shared` prefix requires explicit agreements between organizations: .mif/shared-agreements/acme+bigcorp.yaml ```yaml id: acme+bigcorp type: bilateral parties: - acme-corp - bigcorp-inc created: 2026-01-15T00:00:00Z namespaces: - _shared/acme+bigcorp/integration-api - _shared/acme+bigcorp/data-formats access: read: [acme-corp, bigcorp-inc] write: [acme-corp, bigcorp-inc] ``` For consortiums or communities: .mif/shared-agreements/cncf.yaml ```yaml id: cncf type: consortium admin: cncf-foundation members: - google - microsoft - redhat # ... (member list or reference) namespaces: - _shared/cncf/* access: read: members write: approved-contributors ``` ### Custom Reserved Prefixes [Section titled “Custom Reserved Prefixes”](#custom-reserved-prefixes) Implementations MAY define additional reserved prefixes following the underscore convention: .mif/config.yaml ```yaml reserved_prefixes: _archive: description: Archived memories (read-only) access: read-only _experimental: description: Experimental/unstable memories ttl: P30D _imported: description: Memories imported from external systems provenance_required: true ``` ### Namespace URIs [Section titled “Namespace URIs”](#namespace-uris) Full URI form for cross-system references: ```plaintext mif://{domain}/{namespace}/{memory-id} ``` Examples: * `mif://github.com/modeled-information-format/acme-corp/project-x/550e8400...` * `mif://registry/_public/python/async-patterns/abc123...` * `mif://local/_local/scratch/memory-123` ### Namespace Inheritance [Section titled “Namespace Inheritance”](#namespace-inheritance) Child namespaces MAY inherit properties from parents: .mif/namespaces/acme-corp.yaml ```yaml id: acme-corp type: organization default_ttl: P365D default_visibility: private # .mif/namespaces/acme-corp/project-x.yaml id: project-x parent: acme-corp default_tags: [project-x] # Inherits default_ttl and default_visibility from parent ``` ### Ontology Definition [Section titled “Ontology Definition”](#ontology-definition) Ontologies define namespace hierarchies, entity types, and discovery patterns. They enable domain-specific customization while maintaining MIF compatibility. #### Ontology Files [Section titled “Ontology Files”](#ontology-files) Ontologies are defined in YAML files with optional JSON-LD export: ```plaintext .mif/ontologies/ ├── mif-base.ontology.yaml # Base ontology (semantic/episodic/procedural) ├── mif-base.ontology.jsonld # JSON-LD export for semantic web └── domain/ └── software-engineering.ontology.yaml ``` #### Base Type Hierarchy [Section titled “Base Type Hierarchy”](#base-type-hierarchy) The base ontology uses a three-tier hierarchy based on the base knowledge types: ```yaml namespaces: semantic: # Facts, concepts, relationships type_hint: semantic children: decisions: {} knowledge: {} entities: {} episodic: # Events, experiences, timelines type_hint: episodic children: incidents: {} sessions: {} blockers: {} procedural: # Step-by-step processes type_hint: procedural children: runbooks: {} patterns: {} migrations: {} ``` #### Entity Type Definition [Section titled “Entity Type Definition”](#entity-type-definition) Entity types define structured data with traits and JSON Schema: ```yaml entity_types: - name: component base: semantic traits: [versioned, documented] schema: required: [name, responsibility] properties: name: { type: string } responsibility: { type: string } dependencies: { type: array, items: { type: string } } ``` #### Discovery Patterns [Section titled “Discovery Patterns”](#discovery-patterns) Ontologies can define patterns for suggesting entity types: ```yaml discovery: enabled: true confidence_threshold: 0.8 patterns: - content_pattern: "\\b(PostgreSQL|MySQL|MongoDB)\\b" suggest_entity: technology suggest_namespace: _semantic/entities - file_pattern: "**/services/**/*.py" suggest_entity: component suggest_namespace: _semantic/components ``` #### Ontology Resolution [Section titled “Ontology Resolution”](#ontology-resolution) Ontologies are loaded from multiple sources with precedence: 1. MIF base ontology (built-in) 2. User ontology (`~/.claude/mnemonic/ontology.yaml`) 3. Project ontology (`./.claude/mnemonic/ontology.yaml`) Later sources can extend or override earlier definitions. #### Trait Inheritance and Conflict Resolution [Section titled “Trait Inheritance and Conflict Resolution”](#trait-inheritance-and-conflict-resolution) Traits support inheritance via the `extends` field, enabling composition: ```yaml traits: timestamped: fields: created: { type: string, format: date-time } modified: { type: string, format: date-time } auditable: extends: [timestamped] fields: audit_log: { type: array } last_audited: { type: string, format: date-time } lifecycle: extends: [timestamped] fields: status: { type: string, enum: [draft, active, archived] } ``` **Conflict Resolution Strategy:** When multiple traits define the same field (e.g., both `auditable` and `lifecycle` inherit `created` from `timestamped`), implementations MUST apply the following resolution rules: | Scenario | Resolution | Rationale | | ------------------------------------------------- | ------------------------------ | ------------------------------------------------- | | Same field inherited via different paths | Use shared ancestor definition | Diamond inheritance resolved to common base | | Same field defined in multiple independent traits | Error at composition time | Ambiguous definition requires explicit resolution | | Field in trait overrides inherited field | Child definition wins | Explicit override is intentional | | Field in entity overrides trait field | Entity definition wins | Most specific wins | **Example - Diamond Inheritance:** ```yaml # Both auditable and lifecycle inherit timestamped entity_types: - name: document traits: [auditable, lifecycle] # No conflict: `created` from shared `timestamped` ``` **Example - Conflict Requiring Resolution:** ```yaml traits: trait_a: fields: status: { type: string, enum: [open, closed] } trait_b: fields: status: { type: string, enum: [draft, published] } entity_types: - name: conflicting_entity traits: [trait_a, trait_b] # ERROR: `status` defined differently in both traits # Resolution: Override explicitly in entity schema schema: properties: status: { type: string, enum: [draft, open, published, closed] } ``` **Implementation Guidance:** 1. **Validation**: Implementations SHOULD detect conflicts at ontology load time 2. **Error Messages**: Include both conflicting definitions and their sources 3. **Explicit Override**: When conflicts exist, entity-level schema takes precedence 4. **Documentation**: Ontology authors SHOULD document intentional overrides # Overview > Abstract, terminology, and design principles of the Modeled Information Format. ## Abstract [Section titled “Abstract”](#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/`](https://github.com/modeled-information-format/MIF/tree/main/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 Obsidian-compatible 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”](#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](https://www.rfc-editor.org/rfc/rfc2119). ### Definitions [Section titled “Definitions”](#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`). * **Vault**: A collection of MIF files, analogous to an Obsidian vault. * **Provider**: An implementation that can import or export MIF format. *** ## Design Principles [Section titled “Design Principles”](#design-principles) ### Dual Representation [Section titled “Dual Representation”](#dual-representation) MIF defines two representations, with markdown as the canonical source: 1. **Markdown Format** (`.md`): Canonical, human-readable, Obsidian-compatible 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. ### Obsidian Compatibility [Section titled “Obsidian Compatibility”](#obsidian-compatibility) The Markdown format is valid Obsidian-compatible notes, so files work in Obsidian vaults while remaining readable in any text editor or Markdown processor. Concept relationships are expressed as standard bundle-relative markdown links (so a generic OKF consumer sees every edge); Obsidian’s bidirectional features remain available for authoring. **Required Markdown Features:** * **YAML Frontmatter**: Structured metadata at the top of files, enclosed in `---` delimiters. Obsidian’s Properties panel reads and writes this data, supporting typed fields (text, number, date, checkbox, 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. * **Block References**: Unique identifiers (`^block-id`) attached to paragraphs, list items, or other blocks enable granular linking and transclusion within a file. * **Aliases**: The `aliases` frontmatter property allows notes to be found and linked using alternative names, improving discoverability. * **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 to other tools and platforms. **Optional Obsidian Extensions:** * **Callouts**: Admonition blocks using `> [!type]` syntax for notes, warnings, tips, etc. * **Embeds**: Transclusion using `![[Note]]` to embed content from other files * **Dataview Queries**: Compatible with Dataview plugin for vault-as-database queries ### Semantic Web Compatibility [Section titled “Semantic Web Compatibility”](#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”](#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 # Provenance > W3C PROV-based provenance tracking for memory origins. MIF uses W3C PROV vocabulary for provenance tracking. ### Source Types [Section titled “Source Types”](#source-types) | Type | Description | Confidence Range | | ------------------ | -------------------------- | ---------------- | | `user_explicit` | User directly stated | 0.90 - 1.00 | | `user_implicit` | Inferred from user actions | 0.70 - 0.89 | | `agent_inferred` | AI reasoning from context | 0.50 - 0.69 | | `external_import` | From external data source | 0.30 - 0.70 | | `system_generated` | Automatically generated | 0.20 - 0.50 | ### Trust Levels [Section titled “Trust Levels”](#trust-levels) | Level | Description | | --------------------- | ----------------------------- | | `verified` | Confirmed by multiple sources | | `user_stated` | User explicitly provided | | `high_confidence` | Strong inference | | `moderate_confidence` | Reasonable inference | | `low_confidence` | Weak inference | | `uncertain` | Unverified | ### Provenance Schema [Section titled “Provenance Schema”](#provenance-schema) ```yaml provenance: sourceType: user_explicit sourceRef: conversation:conv-456 agent: claude-3-opus agentVersion: "20240229" confidence: 0.95 trustLevel: user_stated wasDerivedFrom: - memory:parent-memory-id wasAttributedTo: entity:person:jane-doe ``` # Relationship Types > The nine core relationship types for connecting concepts. MIF provides an **extensible relationship type system**. Implementations SHOULD support the core types for interoperability, but MAY define custom relationship types for domain-specific needs. ### Relationship Type Architecture [Section titled “Relationship Type Architecture”](#relationship-type-architecture) Relationship types are **not hard-coded**. They are defined in vault configuration and can be extended per-project: .mif/config.yaml ```yaml relationship_types: # Core types (RECOMMENDED for interoperability) - name: relates-to description: General semantic relationship symmetric: true - name: derived-from description: Memory created based on source inverse: derives - name: supersedes description: Replaces an older memory inverse: superseded-by - name: conflicts-with description: Contradicts another memory symmetric: true - name: part-of description: Component of a larger whole inverse: contains - name: implements description: Realizes a concept or pattern inverse: implemented-by - name: uses description: Utilizes a technology or tool inverse: used-by - name: created-by description: Authored by an entity inverse: creates - name: mentioned-in description: Referenced within a memory inverse: mentions # Custom types (domain-specific) - name: reinforces namespace: subcog description: Strengthens confidence in another memory inverse: reinforced-by - name: contradicts namespace: subcog description: Provides evidence against another memory inverse: contradicted-by - name: breeds-with namespace: farm description: Animal breeding relationship symmetric: false properties: - name: breeding_date type: date - name: success type: boolean ``` ### Core Relationship Types (Recommended) [Section titled “Core Relationship Types (Recommended)”](#core-relationship-types-recommended) For maximum interoperability, implementations SHOULD recognize these nine core types: | Type | Description | Inverse | Symmetric | | ---------------- | -------------------------- | ---------------- | --------- | | `relates-to` | General relationship | `relates-to` | Yes | | `derived-from` | Created based on source | `derives` | No | | `supersedes` | Replaces older memory | `superseded-by` | No | | `conflicts-with` | Contradicts another memory | `conflicts-with` | Yes | | `part-of` | Component of larger whole | `contains` | No | | `implements` | Realizes a concept/pattern | `implemented-by` | No | | `uses` | Utilizes a technology/tool | `used-by` | No | | `created-by` | Authored by entity | `creates` | No | | `mentioned-in` | Referenced in memory | `mentions` | No | ### Custom Relationship Types [Section titled “Custom Relationship Types”](#custom-relationship-types) Providers MAY define additional relationship types using namespaced URIs: ```yaml # Custom relationship type definition relationship_types: - name: contradicts namespace: farm # Results in type token: farm:contradicts description: Provides conflicting evidence inverse: contradicted-by properties: - name: contradiction_type type: string enum: [direct, indirect, partial] - name: severity type: decimal range: [0.0, 1.0] ``` **JSON-LD representation of custom relationship types:** ```json { "@context": [ "https://mif-spec.dev/schema/context.jsonld", {"farm": "https://example.org/farm/"} ], "relationships": [ { "type": "farm:breeds-with", "target": "urn:mif:entity:animal:ram-001", "strength": 1.0, "metadata": { "farm:breeding_date": "2025-10-15", "farm:success": true } } ] } ``` ### Relationship Schema [Section titled “Relationship Schema”](#relationship-schema) **Markdown syntax:** Relationships are authoritative in frontmatter `relationships[]` and mirrored as OKF-legible markdown links in a dedicated body section, using the form `- [Text](/path/target.md)`: ```markdown ## Relationships - relates-to [Other Concept](/semantic/other-concept.md) - derived-from [Source Concept](/episodic/source-concept.md) - supersedes [Old Concept](/semantic/old-concept.md) - conflicts-with [Contradicting Concept](/semantic/contradicting-concept.md) - part-of [Parent Concept](/semantic/parent-concept.md) ``` The relationship type name is converted to kebab-case in Markdown. The link target is a bundle-relative path to the target concept’s `.md` file, so a generic OKF consumer sees every edge. The matching frontmatter (one entry per body link): ```yaml relationships: - type: relates-to target: /semantic/other-concept.md - type: derived-from target: /episodic/source-concept.md - type: supersedes target: /semantic/old-concept.md - type: conflicts-with target: /semantic/contradicting-concept.md - type: part-of target: /semantic/parent-concept.md ``` **JSON-LD schema:** ```json "relationships": [ { "type": "derived-from", "target": "urn:mif:memory:source-memory", "strength": 0.9, "metadata": { "reason": "Extracted key insight", "extractedAt": "2026-01-15T10:30:00Z" } } ] ``` ### Relationship Properties [Section titled “Relationship Properties”](#relationship-properties) | Property | Type | Required | Description | | ---------- | ------- | -------- | ----------------------------------------------------- | | `type` | String | Yes | Relationship type in kebab-case (e.g. `derived-from`) | | `target` | String | Yes | Target memory or entity path/URN | | `strength` | Decimal | No | Relationship strength (0.0-1.0) | | `metadata` | Object | No | Additional relationship metadata | # Security > Security considerations and IANA media type registrations. ## Security Considerations [Section titled “Security Considerations”](#security-considerations) ### Data Privacy [Section titled “Data Privacy”](#data-privacy) * MIF files MAY contain sensitive personal information * Implementations SHOULD support encryption at rest * Namespace isolation SHOULD be enforced * Export functions MUST respect access controls ### Integrity [Section titled “Integrity”](#integrity) * Implementations SHOULD compute content hashes * The `extensions.hash` field MAY store integrity hashes * Import functions SHOULD verify integrity when hashes present ### Provenance Trust [Section titled “Provenance Trust”](#provenance-trust) * `provenance.trustLevel` indicates data reliability * Implementations SHOULD NOT elevate trust levels on import * External sources SHOULD be marked as `external_import` *** ## IANA Considerations [Section titled “IANA Considerations”](#iana-considerations) ### Media Type Registration [Section titled “Media Type Registration”](#media-type-registration) **Markdown Format:** * Type name: text * Subtype name: markdown * Required parameters: variant=mif * Optional parameters: version **JSON-LD Format:** * Type name: application * Subtype name: ld+json * Required parameters: profile=“” ### URI Scheme [Section titled “URI Scheme”](#uri-scheme) MIF URIs use the `mif:` scheme: ```plaintext mif://{authority}/{namespace}/{memory-id} ``` # Temporal Model > Validity windows and freshness — bi-temporal tracking and decay models. MIF’s temporal model answers OKF’s open “live vs. stale” question with **validity windows and freshness**. It uses a bi-temporal model distinguishing between: 1. **Transaction Time**: When the concept was recorded in the system 2. **Valid Time**: When the fact represented by the concept is true ### Temporal Properties [Section titled “Temporal Properties”](#temporal-properties) | Property | Type | Description | | -------------- | -------- | ------------------------------------- | | `validFrom` | DateTime | When fact becomes valid | | `validUntil` | DateTime | When fact expires (null = indefinite) | | `recordedAt` | DateTime | When recorded (transaction time) | | `ttl` | Duration | Time-to-live (ISO 8601 duration) | | `decay` | Object | Decay model parameters | | `accessCount` | Integer | Times accessed | | `lastAccessed` | DateTime | Last access time | ### Decay Models [Section titled “Decay Models”](#decay-models) | Model | Formula | Use Case | | ------------- | ------------------------------ | ----------------------- | | `none` | No decay | Permanent concepts | | `linear` | strength = 1 - (t / ttl) | Simple linear decay | | `exponential` | strength = e^(-t/halfLife) | Gradual freshness decay | | `step` | strength = 1 if t < ttl else 0 | Hard expiration | ### Freshness Rationale [Section titled “Freshness Rationale”](#freshness-rationale) In the core model, the temporal decay function expresses **freshness** — how current a piece of knowledge is — and answers OKF’s open “live vs. stale” question. The decay half-life defaults (P7D, P14D, P30D) are **pragmatic defaults** for how quickly knowledge of a given kind loses currency; they are not prescriptive. The `strength = e^(-t/halfLife)` curve models a value that is fully current when recorded and decays gradually toward stale, with `validFrom`/`validUntil` windows bounding the interval in which a fact is asserted to hold. #### Half-Life Defaults [Section titled “Half-Life Defaults”](#half-life-defaults) | Half-Life | Use Case | Rationale | | --------- | -------------------- | ----------------------------------------------------- | | **P7D** | Short-term context | Aligns with weekly work cycles | | **P14D** | Medium-term projects | Spans typical sprint/iteration boundaries | | **P30D** | Long-term knowledge | Corresponds to monthly review cycles | | **P90D** | Default TTL | Quarterly relevance for most organizational knowledge | Implementations SHOULD tune these based on: * Knowledge kind (`episodic` records go stale faster than `semantic` facts) * Organizational context (high-velocity vs. stable environments) * Access patterns (frequently accessed knowledge can reinforce slower decay) The `lastAccessed` and `accessCount` fields let implementations model reinforcement — each access can reset or slow the freshness decay. The cognitive-memory rationale that originally motivated this exponential curve — including the underlying experimental references and decay tuning for retrieval-oriented systems — lives in the AI Memory profile (`profiles/ai-memory/`), keeping the core framed purely as freshness. ### Example [Section titled “Example”](#example) ```yaml temporal: validFrom: 2026-01-15T00:00:00Z validUntil: null recordedAt: 2026-01-15T10:30:00Z ttl: P90D decay: model: exponential halfLife: P7D strength: 0.85 lastReinforced: 2026-01-18T09:00:00Z accessCount: 5 lastAccessed: 2026-01-20T14:22:00Z ```