mcal-ai 0.2.7

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"
    
    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 = await 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 Storage — Built-in JSON and SQLite persistence, no external services needed
• Thread-Safe — Safe for concurrent multi-user access
• Tiered Models — Fast/smart model routing for cost-efficient extraction
• Extraction Cache — Skip redundant LLM calls with per-turn cache hits
• Graph Compaction — Automatic deduplication and summarization at scale
• GDPR-Ready — Full user data erasure with clear_user_data()

Configuration

mcal = MCAL(
    llm_provider="bedrock",              # "openai", "anthropic", or "bedrock"
    anthropic_api_key="sk-ant-...",       # Or set ANTHROPIC_API_KEY env var
    openai_api_key="sk-...",              # Or set OPENAI_API_KEY env var
    storage_path="~/.mcal",              # Persistent storage location
    enable_persistence=True,              # Cross-session persistence (default)
    max_graph_nodes=500,                  # Max nodes per user graph
    # Bedrock options
    bedrock_model="llama-3.3-70b",        # Default extraction model
    bedrock_region="us-east-1",           # AWS region
    # Tiered model routing (fast for simple, smart for complex)
    enable_tiered_extraction=True,
    bedrock_fast_model="llama-3.1-8b",
    bedrock_smart_model="llama-3.3-70b",
    # Extraction cache
    enable_extraction_cache=True,         # Skip repeated LLM calls (default)
    cache_ttl_seconds=86400,              # Cache lifetime (default: 24h)
    # Graph compaction
    compaction_policy="moderate",         # "none", "moderate", or "aggressive"
    compaction_interval=10,               # Compact every N turns
)

LangGraph Integration

from mcal import MCAL
from mcal_langgraph import MCALMemory, MCALMemoryConfig, MCALStore

# Declarative config — all Bedrock/tiered params supported
config = MCALMemoryConfig(
    llm_provider="bedrock",
    bedrock_model="llama-3.3-70b",
    bedrock_region="us-east-1",
    enable_tiered_extraction=True,
    enable_persistence=True,
)

# Or create directly
mcal = MCAL(llm_provider="bedrock")
memory = MCALMemory(mcal=mcal, user_id="user_123")

# Use as LangGraph BaseStore
store = MCALStore(mcal)

# Memory accepts both LangChain Message objects and plain dicts
await memory.add([
    {"role": "user", "content": "We chose Kafka for event streaming"},
    {"role": "assistant", "content": "Good choice for high throughput."},
])

# Search returns goal-aware results
results = await memory.search("streaming architecture")

User Data Management

# Full user data erasure (GDPR Article 17 compliant)
await mcal.clear_user_data("user_123")
# Removes all files, graphs, caches, and in-memory state for the user

# In-memory-only mode — zero disk writes
mcal = MCAL(
    llm_provider="openai",
    storage_path="/tmp/session",
    enable_persistence=False,   # No files written to disk
)

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

MCAL auto-detects API keys from environment variables when not passed explicitly.

What's New in 0.2.7

• GDPR-compliant data erasure — clear_user_data() now removes the entire user directory from disk, not just the graph file
• Dict-format message support — MCALMemory accepts plain dicts ({"role": "user", "content": "..."}) alongside LangChain Message objects
• In-memory-only mode — enable_persistence=False guarantees zero disk writes, including extraction cache
• Full MCALMemoryConfig — Declarative config now supports all Bedrock, tiered model, persistence, and cache parameters
• Tiered routing accuracy — Complexity classifier now routes on raw user messages for reliable fast/smart splits
• Extraction cache per-turn support — Cache hits work with agents that pass one turn at a time (not full history)
• Deduplication improvements — Enhanced label normalization and forced embedding loads for reliable semantic merges

Documentation

• GitHub Repository
• Design Document
• LLM Selection Guide
• LangGraph Integration

License

MIT License — see LICENSE for details.

Author

Created by Shiva Koreddi