cemaf 0.1.0

Context Engineering Multi-Agent Framework - A pluggable, modular framework for building AI agent systems

CEMAF

Context Engineering Multi-Agent Framework

Open source context engineering infrastructure that solves the hard problems in AI agent systems. CEMAF can be used standalone or plugged into existing frameworks like LangGraph, AutoGen, and CrewAI.

---

Table of Contents

• Overview
• The Hard Problems We Solve
• Installation
• Quick Start
• Integration Modes
• Key Features
• Documentation
• Configuration
• Testing
• Contributing
• Getting Help
• License

---

Overview

CEMAF is a protocol-first framework designed for context engineering in multi-agent AI systems. It provides:

• Token budgeting and automatic context optimization
• Deterministic run recording and replay capabilities
• Full provenance tracking for every context change
• Memory management with strict scoping and TTL
• Zero-config defaults with environment-based customization

Philosophy: Own the hard infrastructure problems while remaining framework-agnostic.

---

The Hard Problems We Solve

Problem	What Happens	CEMAF Solution
Context Growth	Token limits blow up	Token budgeting + automatic summarization
Reliability	Non-deterministic behavior	Patch-based provenance tracking
Cost	Wasteful token usage	Smart context compilation
Reproducibility	Can't replay/debug runs	Run recording + deterministic replay
Memory Leaks	State bleeds between scopes	Strict memory boundaries with TTL

---

Installation

# Core installation (minimal dependencies)
pip install cemaf

# With optional integrations
pip install "cemaf[openai]"        # OpenAI + tiktoken
pip install "cemaf[anthropic]"    # Anthropic
pip install "cemaf[tiktoken]"     # Accurate token counting only
pip install "cemaf[all]"          # All optional dependencies

# Development installation
git clone https://github.com/drchinca/cemaf.git
cd cemaf
pip install -e ".[dev]"

Requirements: Python 3.14+

---

Quick Start

from cemaf.context import Context, ContextPatch
from cemaf.observability import InMemoryRunLogger
from cemaf.replay import Replayer

# Create context with provenance tracking
ctx = Context()
patch = ContextPatch.from_tool("search", "results", {"items": [...]})
ctx = ctx.apply(patch)

# Record runs for replay
logger = InMemoryRunLogger()
logger.start_run("run-123", initial_context=ctx)
logger.record_patch(patch)
record = logger.end_run(final_context=ctx)

# Replay deterministically
replayer = Replayer(record)
result = await replayer.replay()
assert result.final_context == record.final_context  # Deterministic!

See the Quick Start Guide for more detailed examples.

---

Integration Modes

Mode A: CEMAF Orchestrates

CEMAF owns execution, external frameworks are "engines":

from cemaf.orchestration import DAGExecutor
from cemaf.observability import InMemoryRunLogger

executor = DAGExecutor(
    node_executor=LangGraphNodeExecutor(langgraph_app),
    run_logger=InMemoryRunLogger(),
)
result = await executor.run(dag, context)

# Replay later for debugging
replayer = Replayer(run_logger.get_record("run-123"))
await replayer.replay()

Mode B: CEMAF as Library

External frameworks orchestrate, CEMAF provides infrastructure:

from cemaf.context import Context, ContextPatch
from cemaf.observability import InMemoryRunLogger

@langgraph_node
def my_node(state):
    ctx = Context.from_dict(state)

    # Track provenance of every change
    patch = ContextPatch.from_tool("search", "results", search_results)
    ctx = ctx.apply(patch)
    run_logger.record_patch(patch)

    # Compile within budget
    compiled = compiler.compile(ctx, budget)
    return compiled.to_dict()

See the Integration Guide for detailed patterns.

---

Key Features

• 📍 Context Patches: Track every context change with full provenance
• 🔄 Deterministic Replay: Record and replay runs for debugging
• 💾 Token Budgeting: Stay within limits with smart compilation
• ⏱️ TTL & Cleanup: Memory items expire automatically
• 🔒 Memory Boundaries: Strict scoping prevents state leaks
• ⚡ Cancellation: Cooperative cancellation with timeouts
• 🔧 Protocol-Based: Plug into any framework
• ⚙️ Configuration-Driven: Zero-config defaults with .env customization

---

Documentation

Full Documentation →

Core Guides:

• Architecture Overview
• Context Management - Patches, provenance, budgeting
• Replay & Recording - Deterministic replay
• Tools, Skills, Agents

Module References:

• LLM Integration
• Caching
• Persistence
• Observability

---

Configuration

CEMAF is designed for zero-config startup with production-ready defaults. Customize via environment variables:

# Copy example configuration
cp .env.example .env

# Configure your setup
CEMAF_LLM_PROVIDER=openai
CEMAF_LLM_API_KEY=your-key
CEMAF_CACHE_BACKEND=redis
CEMAF_CACHE_MAX_SIZE=10000

Use factory functions for automatic configuration loading:

from cemaf.llm import create_llm_client_from_config
from cemaf.cache import create_cache_from_config

# Automatically loads from .env or environment
client = create_llm_client_from_config()
cache = create_cache_from_config()

See the Configuration Guide for all available settings.

---

Testing

# Run all tests
pytest tests/

# Unit tests only
pytest tests/unit/

# Skip slow tests
pytest tests/ -m "not slow"

# With coverage
pytest tests/ --cov=cemaf

# Pre-commit checks
pre-commit run --all-files

Project Stats: 814 tests | 100% passing | TDD from day one

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development setup:

# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/cemaf.git
cd cemaf

# Install dependencies with uv
uv venv
uv sync

# Install pre-commit hooks
uv run pre-commit install

See HOW_TO_USE.md for detailed usage examples.

---

Getting Help

We're here to help! Here are the best ways to get support:

Documentation

• Full Documentation - Comprehensive guides for all features
• Quick Start Guide - Get started in minutes
• HOW_TO_USE.md - Detailed usage patterns
• Architecture Guide - Understand CEMAF's design

Community

• Discord Server - Join our community for real-time help
• GitHub Discussions - Ask questions and share ideas
• GitHub Issues - Report bugs or request features

Contributing

Want to contribute? Check out our Contributing Guide to get started!

We're in Alpha and actively seeking feedback!

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Authors

Hikuri Bado Chinca (@drchinca) Email: [e-mail]

Copyright (c) 2026 | Published on 1.1.2026 🎉

---

Links

• Documentation: docs/README.md
• Issues: GitHub Issues
• Contributing: CONTRIBUTING.md