mcal-ai-crewai 0.3.0
CrewAI integration for MCAL - Goal-aware memory for AI agent crews
Requires Python: >=3.10
Keywords: agents, ai, crewai, goal-tracking, mcal, memory

# mcal-ai-crewai

Goal-aware memory integration for [CrewAI](https://github.com/crewAIInc/crewAI) agent crews, powered by [MCAL](https://github.com/Shivakoreddi/mcal-ai).

## Installation

```bash
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:

```python
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:

```python
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.3.0

- **Expanded Relationship Edge Types** — 10 new edge types (`family`, `friend`, `colleague`, `likes`, `prefers`, `lives_in`, `works_at`, etc.) for richer social and personal 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
- **Higher Extraction Fidelity** — Increased message processing window reduces information loss during ingestion

## What's New in 0.2.9

- **Configurable Extraction Profiles** — Choose `decision` (rationale/alternatives/trade-offs), `conversational` (preferences/relationships), or `comprehensive` (both)
- **Hybrid Retrieval with ChunkStore** — Graph traversal + embedding search for maximum recall
- **FACT/PERSON Node Protection** — Graph compaction preserves factual and identity nodes
- **Benchmark Results** — Decision profile achieves 93.3% detail retention, 62% token reduction in 150-turn CTO advisor tests

```python
# New v0.2.8 — 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:

```python
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:

```python
# 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:

```python
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

```python
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