Metadata-Version: 2.4
Name: mcal-ai-crewai
Version: 0.5.0
Summary: CrewAI integration for MCAL - Goal-aware memory for AI agent crews
Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai/docs
Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai
Author: MCAL Team
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,crewai,goal-tracking,mcal,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: crewai>=0.100.0
Requires-Dist: mcal-ai>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

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

<details>
<summary>Older releases</summary>

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

</details>

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