mcal-ai-crewai 0.4.2

CrewAI integration for MCAL - Goal-aware memory for AI agent crews

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.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

Older releases

What's New in 0.2.9

• Configurable Extraction Profiles — Choose decision, conversational, or comprehensive
• Hybrid Retrieval with ChunkStore — Graph traversal + embedding search for maximum recall
• FACT/PERSON Node Protection — Graph compaction preserves factual and identity nodes

# 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

Parameter	Type	Default	Description
type	str	required	Memory type: "short_term", "long_term", "entities", "external"
crew	Any	None	Optional CrewAI Crew instance
config	dict	None	Configuration dict (see below)
user_id	str	"default"	User identifier for memory isolation
default_ttl	int	None	Default TTL in seconds
enable_goal_tracking	bool	True	Enable goal extraction from content

Config Dictionary Keys

Key	Type	Default	Description
llm_provider	str	"anthropic"	LLM provider for goal extraction
embedding_provider	str	"openai"	Embedding model provider
storage_path	str	None	Path for persistent storage
user_id	str	"default"	Fallback user_id (constructor param takes priority)

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

Feature	Mem0	MCAL
Basic Memory	✓	✓
Goal Tracking	✗	✓
Priority Extraction	✗	✓
Context Preservation	✗	✓
TTL Support	✗	✓
Local Storage	✓	✓
Thread Safety	—	✓
Cloud API	✓	Coming

Requirements

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

License

MIT License