Summary

MAGI (Markdown for Agent Guidance & Instruction) addresses the limitations of standard Markdown for AI systems by introducing structured metadata, embedded AI instructions, and explicit document relationships. It targets LLMs, AI agents, and developers building RAG and knowledge graph systems, enabling a seamless bridge between human-readable content and machine processing for enhanced context and control.

How It Works

MAGI extends Markdown with three optional, structured components: YAML Front Matter for rich document metadata, ai-script blocks for embedding JSON-formatted LLM instructions (prompts, parameters), and JSON-enhanced footnotes to define typed relationships between documents (e.g., parent, child, cites). This approach maintains human readability while providing explicit, machine-consumable context crucial for advanced AI tasks like knowledge graph construction and granular content processing.

Quick Start & Requirements

• Instant Demo: Convert any public URL to MAGI format (.mda) instantly via the hosted url2mda.sno.ai service.
• Documentation: Official guides and examples are available at docs.magi-mda.org.
• Reference Implementation: The url2mda Cloudflare Worker requires pnpm for installation and a Cloudflare account for deployment.
• Prerequisites: pnpm package manager.

Highlighted Details

• Superset of Markdown: .mda files are fully compatible with standard Markdown renderers, ensuring human readability.
• url2mda Reference Implementation: A Cloudflare Worker demonstrates converting web pages to MAGI format, supporting sub-page crawling and optional LLM-based content filtering.
• Cursor Rules Integration: Fully compatible with .mdc cursor rules files for specialized text processing instructions.

Maintenance & Community

The project encourages community contributions via pull requests and issue discussions. While specific community channels (like Discord/Slack) are not detailed, the project aims to foster a community around AI-native content standards and future ecosystem development.

Licensing & Compatibility

• License: MIT License.
• Compatibility: Permissive MIT license allows for commercial use and integration into closed-source applications. Files are compatible with standard Markdown parsers.

Limitations & Caveats

The MAGI specification is actively evolving, with many features and integrations planned for future development. The url2mda worker's LLM filtering capability requires an AI binding, adding a potential setup dependency.