MAGI (Markdown for Agent Guidance & Instruction) is an extension of standard Markdown designed to enhance content for Retrieval-Augmented Generation (RAG) and seamless integration with Large Language Model (LLM) agents and other AI systems. It elegantly combines Markdown’s simplicity and readability with structured metadata and AI-specific instructions, making it ideal for advanced RAG pipelines, intelligent documentation platforms, and autonomous agent workflows. MAGI files typically use the .mda
extension.
MAGI enhances standard Markdown by incorporating three key, but optional components:
doc-id
, title
, tags
, dates
, purpose
).ai-script
Code Blocks: Embeds specific instructions (as JSON) for LLM processing directly within the content (e.g., summarization prompts, entity extraction requests, model parameter settings).parent
, child
, cites
, related
), enabling knowledge graph construction.Key Principle: All components – Front Matter, ai-script
blocks, and Footnotes – are optional, offering flexibility in how MAGI is utilized. Standard Markdown renderers will parse .mda
files perfectly, preserving human readability. For AI processing, sending the raw .mda
file allows processors to leverage the embedded metadata and instructions natively, enabling more sophisticated understanding and interaction with the content.
MAGI offers several advantages over plain Markdown, particularly when working with AI systems:
Enhanced RAG Performance:
doc-id
, tags
, entities
, created-date
, updated-date
) that significantly improves document retrieval relevance and filtering in RAG systems. Instead of just relying on semantic similarity of the content, retrieval can target specific attributes, leading to more precise results.parent
, child
, related
, cites
, supports
, contradicts
) between documents, enabling the construction of knowledge graphs. RAG systems can traverse these graphs to find highly relevant, interconnected information that might be missed by simple vector search alone.Seamless LLM Agent Integration:
ai-script
blocks allow developers and content creators to embed specific prompts or instructions directly within the .mda
content. AI agents can parse these JSON instructions (e.g., “Summarize this section,” “Extract key entities mentioned below,” “Adopt a formal tone for the following explanation,” “Use model X with temperature Y”) and execute them in context, enabling more sophisticated, automated content processing and generation workflows.Improved Content Management & Understanding:
Human Readability & Flexibility:
.mda
) files remain perfectly readable Markdown. Standard tools and viewers will simply display the Front Matter as text, ai-script
blocks as code blocks, and Footnotes normally (showing the raw JSON string as the footnote content).ai-script
, Footnotes) that provide immediate value for their specific use case, without requiring a full rewrite of existing Markdown content.Reference Implementation (url2mda
):
url2mda
tool (see README.md
) demonstrates a practical way to automatically generate MAGI (.mda
) from existing web content, attempting to auto-populate Front Matter metadata and potentially adding initial ai-script
blocks, bootstrapping the process of creating AI-ready documentation from web sources.In summary, MAGI bridges the gap between human-readable content and machine-processable data, creating a powerful format for building next-generation AI applications that rely on understanding, processing, and generating rich textual information with enhanced context and control.
MAGI (Markdown for Agent Guidance & Instruction) is an extension of standard Markdown designed to enhance content for Retrieval-Augmented Generation (RAG) and seamless integration with Large Language Model (LLM) agents and other AI systems. It elegantly combines Markdown’s simplicity and readability with structured metadata and AI-specific instructions, making it ideal for advanced RAG pipelines, intelligent documentation platforms, and autonomous agent workflows. MAGI files typically use the .mda
extension.
MAGI enhances standard Markdown by incorporating three key, but optional components:
doc-id
, title
, tags
, dates
, purpose
).ai-script
Code Blocks: Embeds specific instructions (as JSON) for LLM processing directly within the content (e.g., summarization prompts, entity extraction requests, model parameter settings).parent
, child
, cites
, related
), enabling knowledge graph construction.Key Principle: All components – Front Matter, ai-script
blocks, and Footnotes – are optional, offering flexibility in how MAGI is utilized. Standard Markdown renderers will parse .mda
files perfectly, preserving human readability. For AI processing, sending the raw .mda
file allows processors to leverage the embedded metadata and instructions natively, enabling more sophisticated understanding and interaction with the content.
MAGI offers several advantages over plain Markdown, particularly when working with AI systems:
Enhanced RAG Performance:
doc-id
, tags
, entities
, created-date
, updated-date
) that significantly improves document retrieval relevance and filtering in RAG systems. Instead of just relying on semantic similarity of the content, retrieval can target specific attributes, leading to more precise results.parent
, child
, related
, cites
, supports
, contradicts
) between documents, enabling the construction of knowledge graphs. RAG systems can traverse these graphs to find highly relevant, interconnected information that might be missed by simple vector search alone.Seamless LLM Agent Integration:
ai-script
blocks allow developers and content creators to embed specific prompts or instructions directly within the .mda
content. AI agents can parse these JSON instructions (e.g., “Summarize this section,” “Extract key entities mentioned below,” “Adopt a formal tone for the following explanation,” “Use model X with temperature Y”) and execute them in context, enabling more sophisticated, automated content processing and generation workflows.Improved Content Management & Understanding:
Human Readability & Flexibility:
.mda
) files remain perfectly readable Markdown. Standard tools and viewers will simply display the Front Matter as text, ai-script
blocks as code blocks, and Footnotes normally (showing the raw JSON string as the footnote content).ai-script
, Footnotes) that provide immediate value for their specific use case, without requiring a full rewrite of existing Markdown content.Reference Implementation (url2mda
):
url2mda
tool (see README.md
) demonstrates a practical way to automatically generate MAGI (.mda
) from existing web content, attempting to auto-populate Front Matter metadata and potentially adding initial ai-script
blocks, bootstrapping the process of creating AI-ready documentation from web sources.In summary, MAGI bridges the gap between human-readable content and machine-processable data, creating a powerful format for building next-generation AI applications that rely on understanding, processing, and generating rich textual information with enhanced context and control.