{"id":51425275,"url":"https://github.com/modeled-information-format/mif","last_synced_at":"2026-07-05T02:01:46.517Z","repository":{"id":334242209,"uuid":"1140594901","full_name":"modeled-information-format/MIF","owner":"modeled-information-format","description":"Open standard for portable AI knowledge interchange — JSON-LD + Markdown dual format with W3C PROV provenance, bi-temporal tracking, entity relationships, and OKF support.","archived":false,"fork":false,"pushed_at":"2026-07-04T23:37:57.000Z","size":1751,"stargazers_count":8,"open_issues_count":3,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T00:12:05.110Z","etag":null,"topics":["ai-agents","ai-memory","claude-code","data-portability","data-standard","interoperability","json-ld","knowledge-graph","llm","markdown","mcp","memory-format","memory-management","obsidian","ontology","open-standard","provenance","semantic-web","specification","yaml"],"latest_commit_sha":null,"homepage":"https://mif-spec.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modeled-information-format.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"zircote"}},"created_at":"2026-01-23T13:53:03.000Z","updated_at":"2026-07-04T23:37:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"87bae1bc-c1c1-437b-81a2-8fe3798bd832","html_url":"https://github.com/modeled-information-format/MIF","commit_stats":null,"previous_names":["zircote/mif"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/modeled-information-format/MIF","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modeled-information-format%2FMIF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modeled-information-format%2FMIF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modeled-information-format%2FMIF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modeled-information-format%2FMIF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modeled-information-format","download_url":"https://codeload.github.com/modeled-information-format/MIF/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modeled-information-format%2FMIF/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35141083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-memory","claude-code","data-portability","data-standard","interoperability","json-ld","knowledge-graph","llm","markdown","mcp","memory-format","memory-management","obsidian","ontology","open-standard","provenance","semantic-web","specification","yaml"],"created_at":"2026-07-05T02:01:45.652Z","updated_at":"2026-07-05T02:01:46.484Z","avatar_url":"https://github.com/modeled-information-format.png","language":"Python","funding_links":["https://github.com/sponsors/zircote"],"categories":[],"sub_categories":[],"readme":"\u003c!-- diataxis_type: explanation --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/social-preview.png\" width=\"860\"\n       alt=\"MIF — the Modeled Information Format specification. Three pillars: canonical schema, two readers one document, fail-closed conformance. The motif: a single source document fans out to a human-readable Markdown panel (amber) and a machine-parseable JSON-LD panel (cyan), joined by a lossless round-trip and a mif-validate conformance badge.\"\u003e\n\u003c/p\u003e\n\n# MIF — Modeled Information Format\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Spec Version](https://img.shields.io/badge/spec-v1.0.0-blue.svg)](./SPECIFICATION.md)\n[![OKF Compliant](https://img.shields.io/badge/OKF-v0.1%20compliant-5c4a32.svg)](./docs/okf-conformance.md)\n[![Docs](https://img.shields.io/badge/docs-mif--spec.dev-5c4a32.svg)](https://mif-spec.dev)\n[![CI](https://github.com/modeled-information-format/MIF/actions/workflows/validate.yml/badge.svg)](https://github.com/modeled-information-format/MIF/actions/workflows/validate.yml)\n[![JSON-LD](https://img.shields.io/badge/format-JSON--LD-orange.svg)](https://json-ld.org/)\n[![PROV-aligned](https://img.shields.io/badge/provenance-PROV--aligned-green.svg)](https://www.w3.org/TR/prov-dm/)\n\n**MIF is the opinionated, OKF-compliant content model that fills OKF's\ndeliberately empty envelope.** [OKF](https://github.com/google/open-knowledge-format)\ndefines the transport surface — a directory of markdown files with YAML\nfrontmatter and one required `type` field — and explicitly leaves the *content\nmodel* open. MIF supplies the concrete type system, typed relationships,\nprovenance/trust, and validity/freshness semantics. **AI memory is the first\ndomain profile of MIF, not its identity.**\n\n\u003e **Brand note (v1.0.0):** The `MIF` mark expands to *Modeled Information Format*. *Memory Interchange Format* is retired. AI Memory is a profile of MIF, not a separate product name.\n\n## Overview\n\nA MIF bundle is a directory tree of `.md` concept files — **a valid OKF\nbundle**. Markdown is the canonical representation; JSON-LD is a derived,\nregenerable projection.\n\n- **Markdown** (`.md`) — canonical, human-readable, plain CommonMark.\n- **JSON-LD** (`*.jsonld`, derived) — machine-processable, semantically linked,\n  regenerated from markdown with `scripts/mif_convert.py`.\n\nEvery concept declares one of three **base knowledge types**:\n\n- `semantic` — declarative knowledge: facts, concepts, decisions, schemas.\n- `episodic` — time-bound records: events, incidents, changelog/deprecation.\n- `procedural` — how-to knowledge: runbooks, processes, patterns, migrations.\n\n## MIF answers OKF's open questions\n\nOKF deliberately refuses to define a content model. MIF supplies opinionated\nanswers to exactly the questions OKF leaves open:\n\n| OKF open design space | MIF's opinionated answer |\n| --- | --- |\n| No concept-type taxonomy | `semantic` / `episodic` / `procedural` base types |\n| Untyped markdown-link edges | Typed relationships (overlay on OKF links) |\n| No merge / contradiction semantics | `Supersedes`, `ConflictsWith` |\n| No trust tiers | Provenance `sourceType` + `trustLevel` |\n| Stale-vs-live left to process | Validity windows + TTL/freshness |\n| No provenance | Lightweight provenance core + optional W3C-PROV-aligned layer |\n| Markdown only | First-class JSON-LD projection |\n\nOKF compliance is achieved as a **superset, not by subordination**: every MIF\nbundle validates as a conformant OKF bundle, but MIF remains an independent\nspecification with its own identity model and governance, pinned to OKF v0.1 in\n[docs/okf-conformance.md](./docs/okf-conformance.md).\n\n## Quick Start\n\nA minimal concept (canonical markdown):\n\n```markdown\n---\nid: 550e8400-e29b-41d4-a716-446655440000\ntype: semantic\ncreated: 2026-01-15T10:30:00Z\nnamespace: _semantic/preferences\n---\n\nA declarative fact stated in plain markdown.\n```\n\nA concept with typed relationships — authoritative in frontmatter, mirrored as\nOKF-legible body links:\n\n```markdown\n---\nid: 7b3c1e90-5a2f-4c8d-9e10-2f6a4b8c1d3e\ntype: semantic\ncreated: 2026-01-15T10:30:00Z\ntitle: API Rate Limit Policy\nrelationships:\n  - type: derived-from\n    target: /episodic/incident-2026-01-rate-spike.md\n---\n\n# API Rate Limit Policy\n\nThe gateway enforces 600 req/min per key.\n\n## Relationships\n\n- derived-from [Rate Spike Incident](/episodic/incident-2026-01-rate-spike.md)\n```\n\nThe derived JSON-LD projection is regenerated, never hand-edited:\n\n```bash\npython scripts/mif_convert.py emit-jsonld examples --out-dir jsonld\n```\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **OKF compliant** | Every bundle is a valid OKF bundle (tested invariant) |\n| **Markdown canonical** | `.md` is the source of truth; JSON-LD is derived |\n| **Typed Relationships** | Typed overlay on standard OKF markdown-link edges |\n| **Base types** | `semantic` / `episodic` / `procedural` knowledge taxonomy |\n| **Bi-Temporal** | Validity windows \u0026 freshness (when recorded AND when valid) |\n| **Provenance \u0026 Trust** | Lightweight `sourceType` / `trustLevel` core + optional W3C-PROV-aligned layer |\n| **Model-Agnostic Embeddings** | Store model + source text for re-embedding |\n| **Stable identity** | UUID `id` survives concept relocation |\n| **JSON Schema** | Automated validation for the JSON-LD projection |\n| **Ontology System** | Base knowledge taxonomy with domain profiles |\n\n## What a MIF memory can carry\n\nA single MIF unit already models **27 top-level properties** — far more than the\nsix required for a minimal record. They are grouped below by\n[conformance level](./SPECIFICATION.md#13-conformance-levels): **Level 1 (Core,\nrequired to conform)**, **Level 2 (Standard, recommended)**, and **Level 3\n(Full, optional)**. Level 1 is the schema's required set plus the structural\nfields validated at that tier; everything in the Standard tier is Level 2; the\nfields the spec marks `(Level 3)` are Level 3.\n\nFor per-field detail, types, patterns, and examples, see the\n[Schema Reference](./docs/SCHEMA-REFERENCE.md). The authoritative, machine-checkable\ndefinition of every property is [`schema/mif.schema.json`](./schema/mif.schema.json).\n\n### Level 1 — Core (required to conform)\n\n| Property | Purpose |\n|----------|---------|\n| `@context` | JSON-LD context binding terms to the MIF vocabulary |\n| `@type` | Document type (`\"Concept\"` or `\"Memory\"`, or an array containing `\"Concept\"`); the projection emits `\"Concept\"` |\n| `@id` | Unique identifier in `urn:mif:` URN form |\n| `conceptType` | Knowledge taxonomy: `semantic` / `episodic` / `procedural` |\n| `memoryType` | **Deprecated** v0.1 alias for `conceptType`, kept for back-compat |\n| `content` | The memory content, in Markdown |\n| `created` | Creation timestamp (ISO 8601) |\n\n\u003e Property names above are the JSON-LD projection. In Markdown frontmatter,\n\u003e `type` maps to `conceptType` in JSON-LD; `memoryType` is a separate deprecated\n\u003e frontmatter key passed through as `memoryType`, not an alias for `type`.\n\u003e\n\u003e The Level 1 rows omit the per-field reference links used for Level 2/3 because\n\u003e these are the core/required fields defined authoritatively in\n\u003e [`schema/mif.schema.json`](./schema/mif.schema.json) — treat that schema as the\n\u003e source of truth for required field names, types, and constraints.\n\n### Level 2 — Standard (recommended)\n\n| Property | Purpose | Reference |\n|----------|---------|-----------|\n| `title` | Human-readable title | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `description` | OKF-recommended description (mapped from MIF `summary`) | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `modified` | Last-modification timestamp (ISO 8601) | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `timestamp` | OKF-recommended mirror of `modified` (or `created`) | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `namespace` | Hierarchical scope for the memory | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `tags` | Classification tags | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `aliases` | Alternative names for the memory | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `properties` | First-class scalar key/value pairs with no concept target | [Basic metadata](./docs/SCHEMA-REFERENCE.md#basic-metadata) |\n| `ontology` | Reference to the ontology this memory conforms to | [Ontology reference](./docs/SCHEMA-REFERENCE.md#ontology-reference) |\n| `entity` | Structured entity data for ontology-typed memories | [Entities](./docs/SCHEMA-REFERENCE.md#entities) |\n| `entities` | Referenced entities (people, orgs, technologies, …) | [Entities](./docs/SCHEMA-REFERENCE.md#entities) |\n| `relationships` | Typed relationships to other memories | [Relationships](./docs/SCHEMA-REFERENCE.md#relationships) |\n| `temporal` | Temporal validity data (timestamps) | [Temporal metadata](./docs/SCHEMA-REFERENCE.md#temporal-metadata) |\n\n\u003e The `temporal` field enters at Level 2 for basic timestamps; its bi-temporal\n\u003e model and decay-function sub-features are Level 3.\n\n### Level 3 — Full (optional)\n\n| Property | Purpose | Reference |\n|----------|---------|-----------|\n| `provenance` | Source and trust data (W3C PROV + `sourceType` / `trustLevel`) | [Provenance](./docs/SCHEMA-REFERENCE.md#provenance) |\n| `embedding` | Embedding-model reference (model + source text for re-embedding) | [Embedding reference](./docs/SCHEMA-REFERENCE.md#embedding-reference) |\n| `citations` | Citation references with rich metadata | [Citations](./docs/SCHEMA-REFERENCE.md#citations) |\n| `summary` | Compressed content summary (max 500 chars) | [Compression](./docs/SCHEMA-REFERENCE.md#compression-level-3) |\n| `compressedAt` | When compression was applied | [Compression](./docs/SCHEMA-REFERENCE.md#compression-level-3) |\n| `extensions` | Provider-specific extension data | [Extensions](./docs/SCHEMA-REFERENCE.md#extensions) |\n\n## LLM-friendly documentation\n\nThe spec site publishes [`llms.txt`](https://mif-spec.dev/llms.txt) for large\nlanguage models, following the [llms.txt convention](https://llmstxt.org/). It is\ngenerated at build time by the `starlight-llms-txt` plugin (never hand-edited),\nalongside `llms-full.txt` (full corpus) and `llms-small.txt` (condensed):\n\n- \u003chttps://mif-spec.dev/llms.txt\u003e\n- \u003chttps://mif-spec.dev/llms-full.txt\u003e\n- \u003chttps://mif-spec.dev/llms-small.txt\u003e\n\n## OKF conformance \u0026 validation\n\n```bash\n# OKF conformance + relationship sync + lossless round-trip\npython scripts/okf_validate.py\n\n# Lossless markdown -\u003e json-ld -\u003e markdown round trip\npython scripts/mif_convert.py roundtrip examples profiles/ai-memory/examples\n\n# JSON Schema validation of the JSON-LD projection.\n# The converter emits .jsonld; ajv-cli reads .json, so validate a .json copy\n# (e.g. cp your-concept.jsonld your-concept.json).\n# Requires: npm install -g ajv-cli ajv-formats\nnpx ajv validate -s schema/mif.schema.json -r \"schema/definitions/*.schema.json\" \\\n  -d your-concept.json --spec=draft2020 -c ajv-formats\n```\n\nSee [docs/okf-conformance.md](./docs/okf-conformance.md) for the pinned OKF v0.1\ncriteria and the MIF → OKF mapping.\n\n## Examples\n\nThe [examples/](./examples/) directory is a generalized (non-memory) core bundle\ndemonstrating the three base types with body-link relationships. Memory-flavored\nexamples live under [profiles/ai-memory/examples/](./profiles/ai-memory/examples/).\n\n## AI Memory profile\n\nMemory-specific material — forgetting-curve decay tuning, episodic *session*\nframing, recall-oriented embeddings, and migration guides for Mem0, Zep, Letta,\nSubcog, and Basic-Memory — lives in the AI Memory profile:\n[profiles/ai-memory/](./profiles/ai-memory/).\n\n## Migration\n\nUpgrading a `0.1.0-draft` bundle? See [MIGRATION.md](./MIGRATION.md) and run:\n\n```bash\npython scripts/migrate_0_1_to_1_0.py \u003cold-bundle\u003e \u003cnew-bundle\u003e\n```\n\n## Specification\n\nSee [SPECIFICATION.md](./SPECIFICATION.md) for the complete v1.0.0 specification,\nand the [Schema Reference](./docs/SCHEMA-REFERENCE.md) for a per-field reference to\nthe top-level properties. The authoritative, machine-checkable definition of every\nproperty is [`schema/mif.schema.json`](./schema/mif.schema.json).\n\n## Contributing\n\nThis specification is open source. Contributions welcome:\n\n1. Open an issue for discussion\n2. Submit PRs for specification changes\n3. Implement and share converters\n\n## Related\n\n- [Subcog](https://github.com/zircote/subcog) - AI memory system implementing MIF\n- [Mnemonic](https://github.com/modeled-information-format/mnemonic) - Claude Code plugin using MIF ontologies\n\n## Citing This Project\n\nIf you use MIF in your research or projects, please cite it:\n\n```bibtex\n@software{allen_mif_2026,\n  author       = {Allen, Robert},\n  title        = {{MIF: Modeled Information Format}},\n  version      = {1.0.0},\n  date         = {2026-06-18},\n  url          = {https://mif-spec.dev},\n  license      = {MIT}\n}\n```\n\nYou can also use GitHub's built-in **\"Cite this repository\"** button on the\nrepository page to get an auto-generated citation in APA or BibTeX format.\n\n### Acknowledgments\n\nMIF builds on the following standards:\n\n\u003e Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Pierre-Antoine Champin, and Niklas Lindstrom. *JSON-LD 1.1: A JSON-based Serialization for Linked Data.* W3C Recommendation, 2020. https://www.w3.org/TR/json-ld11/\n\n\u003e Luc Moreau and Paolo Missier. *PROV-DM: The PROV Data Model.* W3C Recommendation, 2013. https://www.w3.org/TR/prov-dm/\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodeled-information-format%2Fmif","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodeled-information-format%2Fmif","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodeled-information-format%2Fmif/lists"}