📝 MAGI

🎯 Motivation & Introduction

Large Language Models (LLMs) and AI agents increasingly rely on processing diverse content, but standard formats often lack the necessary structure and context for optimal performance. Converting complex web pages or documents into LLM-friendly plain text can be imprecise, losing valuable metadata and structural information.

MAGI (Markdown for Agent Guidance & Instruction) addresses this challenge by extending standard Markdown with optional, structured components designed specifically for AI consumption. It enhances content for Retrieval-Augmented Generation (RAG), seamless integration with LLM agents, and robust knowledge graph construction. MAGI elegantly combines Markdown's readability with enhanced data for AI systems.

🧩 Core Components

MAGI enhances standard Markdown by incorporating three key, optional components:

• Structured Metadata (YAML Front Matter): Provides rich context (e.g., doc-id, title, tags, purpose).
• Embedded AI Instructions (ai-script Code Blocks): Embeds structured JSON instructions for LLM processing directly within the content.
• Explicit Document Relationships (Footnotes with JSON): Defines typed relationships between documents using structured JSON within standard footnotes (e.g., parent, child, cites).

Key Principle: All MAGI components are optional. Use only what you need, offering flexibility.

🕸️ Knowledge Graph Construction

Leverage standard Markdown footnotes [^ref-id] with embedded JSON to define explicit, typed relationships between documents (identified by their unique doc-id in the Front Matter). This is essential for building robust knowledge graphs automatically.

Relationship types include parent, child, related, cites, supports, contradicts, and more.

Benefits: Human-readable syntax combines with machine-processable structured data, enabling explicit connections and graph-ready content.

🚀 Use Cases

MAGI is designed to solve real-world problems at the intersection of human and AI content processing:

• Enhanced RAG Systems: Transform knowledge bases into MAGI format to improve retrieval quality and context understanding.
• Multi-Agent Content Orchestration: Coordinate specialized AI agents working on the same content using embedded ai-script instructions.
• Dynamic Documentation: Create living documentation where embedded scripts can trigger updates, while maintaining version relationships.
• Automated Knowledge Graphs: Generate graphs from MAGI documents where relationships are explicitly defined.
• Cross-Language Content Transformation: Maintain consistent document relationships across translations using UUID-based references.