mcal-ai 0.1.0

Memory-Context Alignment Layer for Goal-Coherent AI Agents

MCAL: Memory-Context Alignment Layer

Beyond Retrieval: Intent-Preserving Memory for Goal-Coherent AI Agents

What's New in v2.0

MCAL is now fully standalone - no external dependencies on Mem0 or other memory providers. The architecture includes:

• Built-in Embedding Service - OpenAI or Bedrock embeddings
• Native Vector Search - Cosine similarity with HNSW-like indexing
• Graph Deduplication - Automatic node merging with similarity detection
• JSON Persistence - Zero-config file-based storage

The Problem

Current AI agent memory systems store facts but lose meaning:

What's Stored	What's Lost
"User wants to visit Japan"	WHY they chose Japan over other destinations
"User booked a hotel in Shibuya"	WHAT alternatives were considered (Shinjuku, Ginza, Asakusa)
"User plans to visit Kyoto"	HOW this fits into the overall trip plan

This creates the Memory-Context Alignment Paradox: as conversations grow, agents remember what was said but forget why it mattered.

Our Solution: Three Pillars

1. Intent Graph Preservation

Hierarchical goal structures that persist across sessions:

MISSION: Plan a 2-week vacation to Japan
├── GOAL: Book travel [✓ COMPLETED]
│   ├── TASK: Find flights [✓]
│   └── TASK: Reserve hotels [✓]
├── GOAL: Plan activities [ACTIVE]
│   ├── TASK: Research Tokyo attractions [✓]
│   ├── TASK: Plan Kyoto day trips [IN PROGRESS]
│   └── TASK: Book restaurants [PENDING]
└── GOAL: Pack and prepare [PENDING]

2. Reasoning Chain Storage

Preserve WHY decisions were made, not just conclusions:

Decision: "Stay in Shibuya for Tokyo accommodation"
├── Alternatives: [Shinjuku, Ginza, Asakusa]
├── Rationale: "Central location, good nightlife, easy metro access"
├── Evidence: ["User wants to explore at night", "Prefers walkable areas"]
└── Trade-offs: ["More expensive but saves daily transit time"]

3. Goal-Aware Retrieval

Retrieve based on objective achievement, not just similarity:

Score = α × semantic_similarity
      + β × goal_alignment      ← NEW
      + γ × decision_relevance  ← NEW
      + δ × recency_decay

Installation

# Install from source (recommended)
git clone https://github.com/Shivakoreddi/mcla-research.git
cd mcla-research
pip install -e .

# Development installation with test dependencies
pip install -e ".[dev]"

# Optional: Install with legacy Mem0 support
pip install -e ".[mem0]"

Requirements

• Python 3.11+
• anthropic - For LLM extraction (Claude)
• openai - For embeddings (optional, can use Bedrock instead)

Quick Start

import asyncio
from mcal import MCAL

async def main():
    # Initialize MCAL (standalone by default)
    mcal = MCAL(
        llm_provider="anthropic",  # or "bedrock", "openai"
        embedding_provider="openai",  # or "bedrock" 
    )
    
    # Add conversation messages
    messages = [
        {"role": "user", "content": "I'm building a fraud detection ML pipeline"},
        {"role": "assistant", "content": "Great! Let's start with data ingestion..."},
        {"role": "user", "content": "I chose PostgreSQL over MongoDB for the data store"},
        {"role": "assistant", "content": "PostgreSQL is a solid choice for structured fraud data..."}
    ]
    
    result = await mcal.add(messages, user_id="user_123")
    
    # Access the unified graph with goals, decisions, and reasoning
    print(f"Extracted {result.unified_graph.node_count} nodes")
    print(f"Active goals: {result.unified_graph.get_active_goals()}")
    print(f"Decisions: {result.unified_graph.get_all_decisions_with_detail()}")
    
    # Search for relevant context
    search_results = await mcal.search(
        query="What database did the user choose?",
        user_id="user_123"
    )
    
    # Get formatted context for LLM
    context = mcal.get_context(
        query="What should we focus on next?",
        user_id="user_123",
        max_tokens=4000
    )

asyncio.run(main())

## Architecture

┌─────────────────────────────────────────────────────────────────┐ │ MCAL v2.0 │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Application Layer │ │ │ │ mcal.add() │ mcal.search() │ mcal.get_context() │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Unified Deep Extractor │ │ │ │ Single LLM call extracts: GOALS | DECISIONS | FACTS │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Unified Graph (6 Nodes, 13 Edges) │ │ │ │ PERSON | THING | CONCEPT | GOAL | DECISION | ACTION │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Standalone Services │ │ │ │ ┌──────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ │ │ Embeddings │ │Vector Search│ │ Deduplication │ │ │ │ │ │ (OpenAI/ │ │(Cosine Sim) │ │ (Similarity │ │ │ │ │ │ Bedrock) │ │ │ │ Merging) │ │ │ │ │ └──────────────┘ └─────────────┘ └─────────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ JSON File Persistence │ │ │ │ ~/.mcal/users/{user_id}/graph.json │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

## Project Structure

mcla-research/ ├── src/mcal/ │ ├── mcal.py # Main MCAL class │ ├── core/ │ │ ├── unified_extractor.py # Single-pass extraction │ │ ├── unified_graph.py # Graph with rich attributes │ │ ├── embedding_service.py # Embedding generation │ │ ├── vector_index.py # Similarity search │ │ └── deduplication.py # Node merging │ ├── providers/ │ │ └── llm_providers.py # Anthropic, OpenAI, Bedrock │ └── storage/ │ └── sqlite_store.py # Persistence layer ├── experiments/ ├── data/ │ ├── synthetic/ # Generated conversations │ └── benchmarks/ # MCAL-Bench dataset ├── tests/ └── docs/

## Evaluation: MCAL-Bench

We introduce **MCAL-Bench**, the first benchmark for reasoning preservation and goal coherence:

| Metric | What It Measures |
|--------|------------------|
| **RPS** (Reasoning Preservation Score) | Can the system explain WHY a decision was made? |
| **GCS** (Goal Coherence Score) | Do responses align with user's active objectives? |
| **TER** (Token Efficiency Ratio) | Quality-per-token vs full context baseline |

## Results (Preliminary)

| System | RPS | GCS | TER |
|--------|-----|-----|-----|
| Full Context | 0.85 | 0.82 | 1.0x |
| Summarization | 0.45 | 0.58 | 2.1x |
| Mem0 | 0.52 | 0.61 | 3.2x |
| **MCAL (Ours)** | **0.78** | **0.79** | **3.8x** |

## Roadmap

- [x] Problem formulation & research
- [ ] Week 1: Foundation (baseline + data)
- [ ] Week 2: Core algorithms
- [ ] Week 3: Benchmark & evaluation
- [ ] Week 4: Paper draft
- [ ] Week 5: Release & arXiv

## Citation

```bibtex
@article{mcal2026,
  title={MCAL: Memory-Context Alignment for Goal-Coherent AI Agents},
  author={Koreddi, Shiva},
  journal={arXiv preprint},
  year={2026}
}

License

MIT License - see LICENSE for details.

Acknowledgments

Built on insights from:

• MemGPT - OS-inspired memory hierarchy
• Reflexion - Verbal self-reflection

---

Migration from v1.x

If you were using MCAL with Mem0 backend, see STANDALONE_MIGRATION.md for migration guide.

Key changes:

• mem0_config and mem0_api_key parameters are deprecated
• use_standalone_backend is deprecated (standalone is now default)
• Install mcal[mem0] for legacy Mem0 support