MCAL: Memory-Context Alignment Layer

Intent-Preserving Memory for Goal-Coherent AI Agents

Why MCAL?

Current AI memory systems store facts but lose meaning:

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
• Extraction Profiles — decision (rationale/alternatives/trade-offs), conversational (preferences/relationships), comprehensive (both)
• Hybrid Retrieval — Graph traversal + ChunkStore embedding search for maximum recall
• 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 with FACT/PERSON node protection
• 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
    # Extraction profiles — choose the right depth for your domain
    extraction_profile="decision",        # "decision", "conversational", "comprehensive"
    # Hybrid retrieval — embedding search over raw text chunks
    enable_chunk_store=True,              # Combine graph + chunk retrieval
    chunk_size=512,                       # Tokens per chunk
    chunk_overlap=64,                     # Overlap between chunks
    max_chunks_per_user=1000,             # Max chunks stored per user
    # 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.

Benchmark Results

MCAL has been evaluated on two benchmarks spanning 150 to 1020+ conversation turns:

• DRR = keyword-matched probe scoring across all decisions in the conversation
• Cross-era recall = early-session decisions still retrievable after 34 sessions (1020 turns)
• Query-aware subgraph retrieval improved DRR by 4.5pp at 1020 turns while reducing context tokens by 53%
• CTO-300 multi-run: 88.8% ± 2.4% across 3 temperatures × 3 repetitions (9 runs)
• LoCoMo-10: 46.1% overall (single-hop 63.5%, temporal 25.5%, multi-hop 31.2%, open-domain 49.8%)

What's New in 0.5.0

• Query-Aware Subgraph Retrieval — New seed-and-expand pipeline replaces 6 query-blind retrieval paths with a single query-aware pass. Semantic FAISS search finds seed nodes, then 1-hop BFS expansion pulls in connected decisions, goals, and facts. Reduces context tokens by 53% at 1020 turns while improving DRR by 4.5pp.
• QuerySubgraph dataclass — New public API for structured subgraph results, partitioned by node type (goals, decisions, facts, entities, actions) with structural edge resolution.
• Adjacency index — Lazy-built bidirectional adjacency index on UnifiedGraph enables O(1) neighbor lookups for graph traversal. Automatically invalidated on edge mutations.
• get_neighbors() method — BFS traversal returning neighbor IDs and connecting edges within configurable hop distance, with optional edge-type filtering.
• Improved DRR at scale — CTO-1020 DRR improved from 85.3% to 89.9% (+4.6pp); CTO-300 improved from 92.2% to 94.4% (+2.2pp). Cross-era recall: 84.4% of decisions from 300+ turns earlier remain accessible.
• LoCoMo-10 Evaluation — Full 10-conversation, 1,540 QA binary evaluation: 46.1% overall accuracy (single-hop 63.5%, temporal 25.5%, multi-hop 31.2%, open-domain 49.8%).

What's New in 0.4.1

• First-Class FACT Nodes (#143) — 3 new typed edges (measures, evidence_for, quantifies) replace generic relates edges on FACT nodes, improving edge degree from 1 to 2-4 edges per fact
• Importance Scoring Boost — FACT nodes with concrete numeric values get a +2.0 scoring bonus, making quantitative facts more retrievable
• Query-Aware Fact Retrieval — Quantitative queries ("how much", "what cost", "what percentage") automatically double the fact retrieval budget
• search_facts() API — New method on UnifiedGraph for filtering facts by category and value range
• Richer FACT Formatting — Context assembly now includes value/unit annotations on fact entries
• Version Metadata Fix — Integration packages now report correct __version__ (was stuck at 0.2.9)

What's New in 0.4.0

• Graph Compaction Fixes (#141, #142) — Improved retrieval quality with facts-in-context, expanded edge types, and chunk boost scoring
• CTO-1020 Benchmark — First 1000+ turn evaluation: 85.3% DRR, 95.6% cross-era recall, 88% token reduction
• Statistical Rigor — Multi-run validation with Fisher's exact test (p < 0.05), Wilson score confidence intervals
• LLM-Judged Probes — J-Score evaluation (1-5 scale) complements keyword DRR for nuanced quality measurement

Documentation

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

License

MIT License — see LICENSE for details.

Author

Created by Shiva Koreddi