MAIF

Multimodal Artifact File Format for Trustworthy AI Agents

Cryptographically-secure, auditable file format for AI agent memory with provenance tracking

---

Overview

MAIF is a file format and SDK designed for AI agents that need trustworthy memory. Every piece of data is cryptographically linked, creating tamper-evident audit trails that prove exactly what happened, when, and by which agent.

Key Capabilities:

• Cryptographic Provenance - Hash-chained blocks for tamper-evident audit trails
• Multi-Agent Coordination - Shared artifacts with agent-specific logging
• Multimodal Storage - Text, embeddings, images, video, knowledge graphs
• Privacy-by-Design - Encryption, anonymization, access control built-in
• High Performance - Memory-mapped I/O, streaming, semantic compression

Use Cases

• Multi-Agent Systems - Shared memory with full provenance (see LangGraph example)
• RAG Pipelines - Document storage with embeddings, search, and citation tracking
• Compliance & Audit - Immutable audit trails for regulated industries
• Research - Reproducible experiments with complete data lineage
• Enterprise AI - Secure, auditable AI workflows with access control

Framework Integrations

MAIF provides drop-in integrations for popular AI agent frameworks:

Framework	Status	Description
LangGraph	Available	State checkpointer with provenance
CrewAI	Available	Crew/Agent callbacks, Memory
LangChain	Coming Soon	Callbacks, VectorStore, Memory
AWS Strands	Coming Soon	Agent callbacks

pip install maif[integrations]

LangGraph

from langgraph.graph import StateGraph
from maif.integrations.langgraph import MAIFCheckpointer

checkpointer = MAIFCheckpointer("state.maif")
app = graph.compile(checkpointer=checkpointer)
result = app.invoke(state, config)
checkpointer.finalize()

CrewAI

from crewai import Crew
from maif.integrations.crewai import MAIFCrewCallback

callback = MAIFCrewCallback("crew.maif")
crew = Crew(
    agents=[...],
    tasks=[...],
    task_callback=callback.on_task_complete,
    step_callback=callback.on_step,
)
result = crew.kickoff()
callback.finalize()

See the integrations documentation for full details.

---

Quick Start

Prerequisites: Python 3.9+

Installation

# Clone the repository
git clone https://github.com/vineethsai/maif.git
cd maif

# Install MAIF
pip install -e .

# With ML features (embeddings, semantic search)
pip install -e ".[ml]"

Your First MAIF Artifact

from maif import MAIFEncoder, MAIFDecoder, verify_maif

# Create an agent memory artifact (Ed25519 signed automatically)
encoder = MAIFEncoder("agent_memory.maif", agent_id="my-agent")

# Add content with automatic provenance tracking
encoder.add_text_block("User asked about weather in NYC", metadata={"type": "query"})
encoder.add_text_block("Temperature is 72°F, sunny", metadata={"type": "response"})

# Finalize (signs and seals the file)
encoder.finalize()

# Later: Load and verify integrity
decoder = MAIFDecoder("agent_memory.maif")
decoder.load()

is_valid, errors = decoder.verify_integrity()
print(f"Valid: {is_valid}, Blocks: {len(decoder.blocks)}")

# Read content
for i, block in enumerate(decoder.blocks):
    text = decoder.get_text_content(i)
    print(f"Block {i}: {text}")

Secure MAIF Format:

• Self-contained - No separate manifest files, everything in one .maif file
• Ed25519 signatures - Fast, compact 64-byte signatures on every block
• Immutable blocks - Each block is signed immediately on write
• Tamper detection - Cryptographic verification catches any modification
• Embedded provenance - Full audit trail built into the file

---

Featured Example: Multi-Agent RAG System

A production-ready multi-agent system with LangGraph orchestration and MAIF provenance tracking.

cd examples/langgraph

# Configure API key
echo "GEMINI_API_KEY=your_key" > .env

# Install dependencies
pip install -r requirements_enhanced.txt

# Create knowledge base with embeddings
python3 create_kb_enhanced.py

# Run the interactive demo
python3 demo_enhanced.py

What's Included:

• 5 specialized agents (Retriever, Synthesizer, Fact-Checker, Citation, Web Search)
• ChromaDB vector store with semantic search
• Gemini API integration for LLM reasoning
• Complete audit trail of every agent action
• Multi-turn conversation support

See examples/langgraph/README.md for full documentation.

---

NEW: Enterprise AI Governance Demo

Interactive demonstration of MAIF's enterprise-grade governance features:

cd examples/integrations/langgraph_governance_demo
python main.py

Features demonstrated:

• Cryptographic provenance (Ed25519 signatures, hash chains)
• Tamper detection and data integrity verification
• Role-based access control with audit logging
• Multi-agent coordination with clear handoffs
• Compliance report generation (Markdown, JSON, CSV)

See examples/integrations/langgraph_governance_demo/README.md for details.

---

Features

Cryptographic Provenance

Every block is cryptographically signed and linked - any tampering is detectable.

from maif import MAIFEncoder, MAIFDecoder

# Each block is signed with Ed25519 on creation
encoder = MAIFEncoder("memory.maif", agent_id="agent-1")
encoder.add_text_block("First message")   # Signed immediately
encoder.add_text_block("Second message")  # Linked to previous via hash
encoder.add_text_block("Third message")   # Chain continues
encoder.finalize()

# Verify the entire chain + all signatures
decoder = MAIFDecoder("memory.maif")
decoder.load()
is_valid, errors = decoder.verify_integrity()

# Check provenance chain
for entry in decoder.provenance:
    print(f"{entry.action} by {entry.agent_id} at {entry.timestamp}")

Privacy & Security

Built-in encryption, anonymization, and access control.

from maif import PrivacyLevel, EncryptionMode

# Add encrypted content
maif.add_text(
    "Sensitive data",
    encrypt=True,
    anonymize=True,  # Auto-redact PII
    privacy_level=PrivacyLevel.CONFIDENTIAL
)

# Access control
maif.add_access_rule(AccessRule(
    role="analyst",
    permissions=[Permission.READ],
    resources=["reports"]
))

Multimodal Support

Store and search across text, images, video, embeddings, and knowledge graphs.

# Text with metadata
maif.add_text("Analysis results", title="Report", language="en")

# Images with feature extraction
maif.add_image("chart.png", title="Sales Chart")

# Semantic embeddings
maif.add_embeddings([[0.1, 0.2, ...]], model_name="all-MiniLM-L6-v2")

# Multimodal content
maif.add_multimodal({
    "text": "Product description",
    "image_path": "product.jpg",
    "metadata": {"category": "electronics"}
})

Novel Algorithms

Advanced semantic processing capabilities:

• ACAM - Adaptive Cross-Modal Attention for multimodal fusion
• HSC - Hierarchical Semantic Compression (up to 64× compression)
• CSB - Cryptographic Semantic Binding for embedding authenticity

---

Performance

Metric	Performance
Semantic Search	~30ms for 1M+ vectors
Compression Ratio	Up to 64× (HSC)
Integrity Verification	~0.1ms per file
Read Performance	11× faster than legacy format
Tamper Detection	100% detection in <0.1ms
Signature Overhead	Only 64 bytes per block (Ed25519)

---

Project Structure

maif/
├── maif/                  # Core library
│   ├── core.py           # MAIFEncoder, MAIFDecoder
│   ├── security.py       # Signing, verification
│   ├── privacy.py        # Encryption, anonymization
│   ├── integrations/     # Framework integrations (LangGraph, etc.)
│   └── semantic*.py      # Embeddings, compression
├── maif_api.py           # High-level API
├── examples/
│   ├── langgraph/        # Multi-agent RAG system
│   ├── integrations/     # Framework integration demos
│   ├── basic/            # Getting started
│   ├── security/         # Privacy & encryption
│   └── advanced/         # Agent framework, lifecycle
├── tests/                # 450+ tests
├── docs/                 # VitePress documentation
└── benchmarks/           # Performance tests

---

Documentation

Resource	Description
Online Docs	Full documentation site
API Reference	Detailed API documentation
User Guides	Step-by-step tutorials
Examples	Working code examples

---

Examples

Basic Usage

python examples/basic/simple_api_demo.py
python examples/basic/basic_usage.py

Privacy & Security

python examples/security/privacy_demo.py
python examples/security/classified_api_simple_demo.py

Advanced Features

python examples/advanced/maif_agent_demo.py          # Agent framework
python examples/advanced/lifecycle_management_demo.py # Lifecycle management
python examples/advanced/video_demo.py               # Video processing

---

Contributing

We welcome contributions! Please ensure:

1. All tests pass (pytest tests/)
2. Code follows PEP 8 style
3. New features include tests and documentation
4. Security-sensitive changes include impact analysis

See CONTRIBUTING.md for detailed guidelines.

---

References

• FIPS 140-2 Standards - Cryptographic module requirements
• NIST 800-53 - Security and privacy controls
• ISO BMFF - Binary format inspiration

---

License

MIT License - See LICENSE for details.

---

Community & Support

• GitHub Discussions - Ask questions, share ideas
• Issue Tracker - Report bugs or request features
• Documentation - Complete guides and API reference
• Security - Report security vulnerabilities
• Changelog - See what's new
• Specification - MAIF file format specification

---

Build trustworthy AI agents with cryptographic provenance