mcal-ai 0.2.0

Memory-Context Alignment Layer for Goal-Coherent AI Agents

MCAL: Memory-Context Alignment Layer

Intent-Preserving Memory for Goal-Coherent AI Agents

Why MCAL?

Current AI memory systems store facts but lose meaning:

What's Stored	What's Lost
"User chose PostgreSQL"	WHY they chose it over MongoDB
"User wants to visit Japan"	HOW this fits their overall travel goals

MCAL preserves the reasoning behind decisions, not just the conclusions.

Installation

pip install mcal-ai

Framework integrations:

pip install mcal-ai-langgraph  # LangGraph integration
pip install mcal-ai-crewai     # CrewAI integration  
pip install mcal-ai-autogen    # AutoGen integration

Quick Start

import asyncio
from mcal import MCAL

async def main():
    mcal = MCAL(
        llm_provider="anthropic",     # or "openai", "bedrock"
        embedding_provider="openai",  # or "bedrock"
    )
    
    messages = [
        {"role": "user", "content": "I'm building a fraud detection pipeline"},
        {"role": "assistant", "content": "Let's start with data ingestion..."},
        {"role": "user", "content": "I chose PostgreSQL over MongoDB for storage"},
    ]
    
    # Extract goals, decisions, and reasoning
    result = await mcal.add(messages, user_id="user_123")
    print(f"Extracted {result.unified_graph.node_count} nodes")
    
    # Search with goal-aware retrieval
    results = await mcal.search("What database?", user_id="user_123")
    
    # Get context for LLM prompts
    context = mcal.get_context("What's next?", user_id="user_123")

asyncio.run(main())

Key Features

• Intent Graph - Hierarchical goal structures (Mission → Goal → Task)
• Reasoning Chains - Store WHY decisions were made, not just conclusions
• Goal-Aware Retrieval - Retrieve based on objective alignment, not just similarity
• Multi-Provider - Works with Anthropic, OpenAI, and AWS Bedrock
• Standalone - No external dependencies, JSON file persistence

Environment Variables

# Choose your LLM provider
ANTHROPIC_API_KEY=sk-ant-...    # For Claude
OPENAI_API_KEY=sk-...           # For GPT-4 / embeddings

# Optional: AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1

Documentation

• GitHub Repository
• Design Document

License

MIT License - see LICENSE for details.

Author

Created by Shiva Koreddi