mcal-ai-crewai

Goal-aware memory integration for CrewAI agent crews, powered by MCAL.

Installation

pip install mcal-ai-crewai

This installs mcal-ai and crewai as dependencies.

Quick Start

Using MCALStorage with CrewAI Memory

MCAL provides a storage backend that integrates directly with CrewAI's memory system:

from crewai import Crew, Agent, Task, Process
from crewai.memory.short_term.short_term_memory import ShortTermMemory
from crewai.memory.long_term.long_term_memory import LongTermMemory
from crewai.memory.entity.entity_memory import EntityMemory
from mcal_crewai import MCALStorage

# Create MCAL-backed memories
short_term = ShortTermMemory(
    storage=MCALStorage(type="short_term", user_id="john")
)
long_term = LongTermMemory(
    storage=MCALStorage(type="long_term", user_id="john")
)
entity_memory = EntityMemory(
    storage=MCALStorage(type="entities", user_id="john")
)

# Use with CrewAI
crew = Crew(
    agents=[agent],
    tasks=[task],
    memory=True,
    short_term_memory=short_term,
    long_term_memory=long_term,
    entity_memory=entity_memory,
)

Using External Memory

For cross-session persistence with goal awareness:

from crewai.memory.external.external_memory import ExternalMemory
from mcal_crewai import MCALStorage

external = ExternalMemory(
    embedder_config={
        "provider": "mcal",
        "config": {
            "user_id": "john",
            "llm_provider": "anthropic",
            "enable_goal_tracking": True,
        }
    }
)

crew = Crew(
    agents=[...],
    tasks=[...],
    external_memory=external,
    process=Process.sequential,
)

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. 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.
• 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).
• LoCoMo-10 Evaluation — Full 10-conversation, 1,540 QA binary evaluation: 46.1% overall accuracy.

What's New in 0.4.1

• First-Class FACT Nodes — 3 new typed edges (measures, evidence_for, quantifies) improve fact retrieval; quantitative queries automatically boost fact content
• Importance Scoring Boost — FACT nodes with numeric values score higher in retrieval
• search_facts() API — Filter facts by category and value range on UnifiedGraph
• Version Metadata Fix — __version__ now correctly reports 0.4.1 (was stuck at 0.2.9)

What's New in 0.4.0

• Graph Compaction Fixes — Improved retrieval quality with facts-in-context, expanded edge types, chunk boost scoring
• CTO-1020 Benchmark — 85.3% decision retention over 1020 turns, 95.6% cross-era recall, 88% token reduction
• Statistical Rigor — Multi-run validation with Fisher's exact test, Wilson score confidence intervals

What's New in 0.3.0

• Expanded Relationship Edge Types — 10 new edge types (family, friend, colleague, likes, prefers, lives_in, works_at, etc.) for richer relationship graphs
• Key Facts & Entities in Search Context — search() now surfaces extracted facts and background entities directly in result.context
• Improved Chunk Retrieval — More results returned with equal weighting; conversation excerpts prioritized in context

# Pass extraction profile via config
storage = MCALStorage(
    type="long_term",
    user_id="project_manager",
    config={
        "llm_provider": "anthropic",
        "extraction_profile": "decision",
        "enable_chunk_store": True,
    }
)

Features

Goal-Aware Memory

Unlike basic memory systems, MCAL tracks user goals and priorities:

storage = MCALStorage(
    type="long_term",
    user_id="project_manager",
    enable_goal_tracking=True,
    config={
        "llm_provider": "anthropic",
        "embedding_provider": "openai",
    }
)

Context Preservation

MCAL maintains reasoning context across agent handoffs:

# Agent 1 saves with context (sync API)
storage.save(
    "Research findings on market trends",
    metadata={
        "agent": "researcher",
        "goal": "market_analysis",
        "confidence": 0.95
    }
)

# Agent 2 retrieves with keyword search
results = storage.search(
    "What do we know about market trends?",
    limit=5,
    score_threshold=0.7
)

TTL Support

Automatic expiration for short-term memories:

storage = MCALStorage(
    type="short_term",
    user_id="session_user",
    default_ttl=3600,  # 1 hour in seconds
)

Thread Safety

All operations are thread-safe via internal RLock, safe for concurrent agent access.

Configuration

Constructor Parameters

Config Dictionary Keys

API Reference

MCALStorage

class MCALStorage:
    """MCAL storage backend for CrewAI memory."""
    
    def save(self, value: Any, metadata: dict) -> None:
        """Save value with goal-aware processing."""
    
    def search(
        self, 
        query: str, 
        limit: int = 5, 
        score_threshold: float = 0.6
    ) -> list:
        """Search with keyword matching. Filters expired TTL entries."""
    
    def reset(self) -> None:
        """Clear all stored memories."""
    
    def get_all(self) -> list:
        """Return all non-expired memory items."""
    
    def delete(self, key: str) -> None:
        """Delete a specific memory entry by key."""

Note: MCALMemoryStorage is available as a backward-compatible alias for MCALStorage.

Comparison with Mem0

Requirements

• Python >= 3.11
• mcal-ai >= 0.2.0
• crewai >= 0.100.0

License

MIT License