[FEATURE]: CrewAI Agentic Framework — Decision Intelligence, Context Graphs & GraphRAG`

[KaifAhmad1]

Problem Statement

CrewAI is a production-grade multi-agent framework that orchestrates role-playing agents collaborating on complex tasks via Agent, Task, Crew, and Process primitives. While CrewAI ships built-in ShortTermMemory, LongTermMemory, and EntityMemory, these are shallow wrappers around Chroma/SQLite3 with no support for:

• Persistent Decision Intelligence — no ability to record, trace, or learn from decisions across Crew runs; the LTM stores raw conversation snapshots, not structured decision graphs
• Context Graphs — no structured knowledge graph linking entities, relationships, and causal chains across tasks or crew runs
• GraphRAG Knowledge Retrieval — BaseKnowledgeSource retrieval is bag-of-vectors; no relational multi-hop reasoning over a structured graph
• Decision Provenance & Audit Trails — no traceable record of agent reasoning chains for compliance in regulated domains (finance, healthcare, legal)
• Cross-Run Knowledge Accumulation — completed crew runs cannot contribute structured knowledge to future runs in a queryable graph form

Semantica already provides all of these via AgentContext, ContextGraph, Reasoner, and the full KG stack. This proposal adds a native CrewAI bridge so teams can wire Semantica's intelligence layer into any CrewAI setup.

---

Proposed Solution

Create a semantica[crewai] integration package at integrations/crewai/ with five components that plug directly into CrewAI's official extension points:

Class	CrewAI Extension Point	Protocol / Interface	Semantica Backing
CrewContextStore	LongTermMemory(storage=...)	LTMStorage (save, search, reset)	AgentContext + VectorStore
CrewEntityStore	EntityMemory(storage=...)	LTMStorage (save, search, reset)	ContextGraph entity nodes
CrewKnowledgeGraph	Crew(knowledge_sources=[...])	BaseKnowledgeSource (load_content, query)	ContextGraph + GraphBuilder
CrewDecisionKit	Agent(tools=[...])	BaseTool subclasses	DecisionQuery, CausalChainAnalyzer, PolicyEngine
CrewKGToolkit	Agent(tools=[...])	BaseTool subclasses	NERExtractor, RelationExtractor, Reasoner
CrewSharedContext	Crew-level state	bind_agent(role) → scoped view	ContextGraph shared across all agents

---

Detailed Design

1. CrewContextStore — Graph-Backed Long-Term Memory Storage

Implements CrewAI's LTMStorage protocol — the storage backend consumed by LongTermMemory. Backed by Semantica's AgentContext, it persists structured semantic state (with entity extraction and graph expansion) across Crew runs.

from crewai import Agent, Task, Crew, Process
from crewai.memory import LongTermMemory
from semantica.integrations.crewai import CrewContextStore
from semantica.vector_store import VectorStore
from semantica.context import ContextGraph

store = CrewContextStore(
    vector_store=VectorStore(backend="pgvector", connection_string="..."),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    graph_expansion=True
)

analyst = Agent(
    role="Financial Analyst",
    goal="Deliver data-driven investment recommendations.",
    backstory="Senior analyst with deep market expertise.",
    long_term_memory=LongTermMemory(storage=store)
)

task = Task(
    description="Analyze Q1 2025 performance data and recommend portfolio adjustments.",
    expected_output="Investment recommendation with evidence-based reasoning.",
    agent=analyst
)

crew = Crew(agents=[analyst], tasks=[task], process=Process.sequential)
crew.kickoff()

Interface implemented (LTMStorage protocol):

Method	Signature	Behaviour
save	save(value: Any, metadata: Dict, datetime: str)	Stores item in AgentContext; auto-extracts entities into ContextGraph
search	search(query: str, latest_n: int) -> List[Dict]	Hybrid search: vector similarity + graph hop expansion via AgentContext.retrieve()
reset	reset() -> None	Clears session-scoped memory from AgentContext

---

2. CrewEntityStore — Context-Graph-Backed Entity Memory

Implements LTMStorage for CrewAI's EntityMemory. Rather than storing raw entity strings, CrewEntityStore maps each entity to a ContextGraph node, enabling relationship queries across entities mentioned in any task output.

from crewai.memory import EntityMemory
from semantica.integrations.crewai import CrewEntityStore
from semantica.context import ContextGraph

entity_store = CrewEntityStore(
    knowledge_graph=ContextGraph(advanced_analytics=True)
)

analyst = Agent(
    role="Research Analyst",
    goal="Map relationships between companies, people, and events.",
    entity_memory=EntityMemory(storage=entity_store)
)

Key behaviours:

• Each entity saved to EntityMemory becomes a typed ContextGraph node
• Entity searches trigger ContextGraph.find_related_nodes() for relationship-aware retrieval
• Entity graph persists across crew runs and can be queried by CrewKGToolkit tools

---

3. CrewKnowledgeGraph — GraphRAG Knowledge Source

Extends BaseKnowledgeSource — CrewAI's official knowledge interface. Documents are ingested through Semantica's full pipeline (parse → split → NER → relation extract → graph build), stored as a ContextGraph, and retrieved via multi-hop GraphRAG.

from crewai import Agent, Task, Crew
from semantica.integrations.crewai import CrewKnowledgeGraph
from semantica.kg import GraphBuilder
from semantica.semantic_extract import NERExtractor, RelationExtractor

kg = CrewKnowledgeGraph(
    graph_builder=GraphBuilder(),
    ner_extractor=NERExtractor(),
    relation_extractor=RelationExtractor(),
    graph_store_backend="neo4j",
    graph_store_uri="bolt://localhost:7687"
)

# Load documents into the knowledge graph
kg.load_files(["compliance_policy.pdf", "regulatory_update_2025.docx"])
kg.load_urls(["https://example.com/regulation-2025"])
kg.load_directory("regulatory_docs/", recursive=True)

# Attach as Crew-level or Agent-level knowledge source
compliance_agent = Agent(
    role="Compliance Analyst",
    goal="Ensure all recommendations comply with current regulations.",
    backstory="Expert in financial compliance and regulatory frameworks.",
    knowledge_sources=[kg]
)

crew = Crew(
    agents=[compliance_agent],
    tasks=[...],
    knowledge_sources=[kg]           # or attach at Crew level
)

Interface implemented (BaseKnowledgeSource protocol):

Method	Behaviour
load_content()	Runs Semantica's pipeline; populates ContextGraph
add(content)	Incremental ingestion: adds new content to existing graph
query(queries: list[str]) -> str	Multi-hop GraphRAG: vector retrieval + ContextGraph traversal + context injection

---

4. CrewDecisionKit — Decision Intelligence Tools

A set of BaseTool subclasses giving CrewAI agents active access to Semantica's decision intelligence. Agents record, retrieve, trace, and validate decisions as part of their task execution loop.

from crewai import Agent, Task, Crew
from semantica.integrations.crewai import CrewDecisionKit
from semantica.context import AgentContext

ctx = AgentContext(vector_store=vector_store, decision_tracking=True)
kit = CrewDecisionKit(context=ctx)

loan_officer = Agent(
    role="Loan Officer",
    goal="Approve or reject loan applications fairly and consistently.",
    backstory="Senior lending professional with 15 years of experience.",
    tools=kit.as_tools()              # returns list[BaseTool]
)

task = Task(
    description="Review the attached mortgage application. Use decision history to ensure consistency.",
    expected_output="Approval/rejection with reasoning, precedent citations, and policy compliance status.",
    agent=loan_officer
)

crew = Crew(agents=[loan_officer], tasks=[task])
crew.kickoff(inputs={"application": "..."})

BaseTool subclasses in CrewDecisionKit:

Tool Class	name	Description	Key Args
RecordDecisionTool	record_decision	Record decision with reasoning and outcome	category, scenario, reasoning, outcome, confidence
FindPrecedentsTool	find_precedents	Search for similar past decisions	scenario, category, limit
TraceCausalChainTool	trace_causal_chain	Trace causal chain from a decision node	decision_id, depth
AnalyzeDecisionImpactTool	analyze_decision_impact	Assess downstream influence of a decision	decision_id
CheckPolicyComplianceTool	check_policy_compliance	Validate decision against policy rules	decision_data, policy_rules
GetDecisionSummaryTool	get_decision_summary	Summarize decision history by category	category, since

Example task output with decision tools:

> Entering Agent: Loan Officer

Action: find_precedents
Action Input: {"scenario": "first-time homebuyer mortgage", "category": "loan_approval", "limit": 10}
Observation: Found 12 similar mortgage approvals with avg confidence 0.91.

Action: check_policy_compliance
Action Input: {"decision_data": {"category": "loan_approval", "outcome": "approved", ...}}
Observation: Decision complies with lending policy v2.3. No violations.

Action: record_decision
Action Input: {"category": "loan_approval", "scenario": "...", "outcome": "approved", "confidence": 0.94}
Observation: Decision recorded. ID: dec_8f2a1c.

Final Answer:
APPROVED. Referencing 12 precedent approvals and confirmed compliance with lending
policy v2.3. Credit score 740, DTI 31%, 22% down payment — all thresholds met.
Decision ID: dec_8f2a1c (auditable).

---

5. CrewKGToolkit — Knowledge Graph Tools

A set of BaseTool subclasses letting CrewAI agents actively build and query knowledge graphs during task execution. Backed by Semantica's NERExtractor, RelationExtractor, and Reasoner.

from semantica.integrations.crewai import CrewKGToolkit

toolkit = CrewKGToolkit(graph_store_backend="inmemory")

researcher = Agent(
    role="Research Analyst",
    goal="Extract and map entity relationships from source documents.",
    backstory="Expert at structuring unstructured information.",
    tools=toolkit.as_tools()
)

BaseTool subclasses in CrewKGToolkit:

Tool Class	name	Description
ExtractEntitiesTool	extract_entities	Extract named entities from text
ExtractRelationsTool	extract_relations	Extract relationships between entities
AddToGraphTool	add_to_graph	Add entities/relations to the context graph
QueryGraphTool	query_graph	Query graph in natural language or Cypher
FindRelatedTool	find_related	Find concepts related to a given entity
InferFactsTool	infer_facts	Apply rules to infer new facts from the graph
ExportSubgraphTool	export_subgraph	Export a subgraph as RDF/JSON-LD

---

6. CrewSharedContext — Cross-Agent Shared Context Graph

A ContextGraph shared across all agents in a Crew. Each agent gets an isolated session view via bind_agent(role) while reading from and contributing to a unified semantic graph — enabling coordinated, contradiction-free multi-agent reasoning.

from crewai import Agent, Task, Crew, Process
from semantica.integrations.crewai import CrewSharedContext, CrewKGToolkit, CrewDecisionKit

shared = CrewSharedContext(
    vector_store=VectorStore(backend="pgvector", connection_string="..."),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True
)

# Researcher builds knowledge graph; findings available to all downstream agents
researcher = Agent(
    role="Research Analyst",
    goal="Extract and structure intelligence from source documents.",
    backstory="...",
    long_term_memory=shared.bind_agent("researcher"),
    tools=CrewKGToolkit(context=shared).as_tools()
)

# Strategist queries the shared graph and records decisions that researcher can cite
strategist = Agent(
    role="Strategy Analyst",
    goal="Recommend strategy grounded in structured research findings.",
    backstory="...",
    long_term_memory=shared.bind_agent("strategist"),
    tools=CrewDecisionKit(context=shared).as_tools()
)

crew = Crew(
    agents=[researcher, strategist],
    tasks=[research_task, strategy_task],
    process=Process.sequential
)

crew.kickoff(inputs={"topic": "competitive landscape in cloud infrastructure"})

---

Use Cases

1. Regulated Industry Crews (Finance, Healthcare, Legal) — crews that must log every agent decision with full provenance, causal chain, and policy compliance for regulatory audit.

2. Long-Running Research Crews — crews that accumulate a persistent ContextGraph across multiple runs, enabling multi-hop reasoning over a growing knowledge base instead of starting from a blank slate each run.

3. Enterprise Multi-Agent Coordination — CrewSharedContext prevents agents from making contradictory decisions and lets downstream agents reason over upstream findings without re-extracting the same knowledge.

4. GraphRAG-Enhanced Knowledge Retrieval — CrewKnowledgeGraph as a BaseKnowledgeSource replaces flat Chroma vector search with relational graph traversal, providing more accurate, contextually grounded answers.

5. Decision Learning Crews — agents that improve across crew runs by querying historical precedents via CrewDecisionKit before executing tasks.

6. Explainable AI Pipelines — every task output, entity reference, and causal chain is traceable back to a source document or prior decision — audit-ready by design.

---

Impact Assessment

• Who would benefit: All CrewAI users building production multi-agent pipelines, particularly in regulated, knowledge-intensive, or compliance-sensitive domains.
• Priority: High — CrewAI is one of the most widely adopted agentic frameworks; this establishes Semantica as its semantic intelligence layer.
• Breaking Changes: None — fully additive. All Semantica core modules remain unchanged.
• Dependencies:
  • crewai>=0.80 (optional; imported only within the integration package)
  • Semantica core: semantica.context, semantica.kg, semantica.semantic_extract, semantica.reasoning
  • Install: pip install semantica[crewai]

---

Implementation Plan

Phase 1 — Context Stores & Knowledge Graph

• integrations/crewai/__init__.py
• integrations/crewai/context_store.py — CrewContextStore (LTMStorage impl)
• integrations/crewai/entity_store.py — CrewEntityStore (LTMStorage impl)
• integrations/crewai/knowledge_graph.py — CrewKnowledgeGraph (BaseKnowledgeSource impl)
• tests/integrations/crewai/test_context_store.py
• tests/integrations/crewai/test_entity_store.py
• tests/integrations/crewai/test_knowledge_graph.py

Phase 2 — Decision & KG Toolkits

• integrations/crewai/decision_kit.py — CrewDecisionKit + BaseTool subclasses
• integrations/crewai/kg_toolkit.py — CrewKGToolkit + BaseTool subclasses
• tests/integrations/crewai/test_decision_kit.py
• tests/integrations/crewai/test_kg_toolkit.py

Phase 3 — Shared Context

• integrations/crewai/shared_context.py — CrewSharedContext
• tests/integrations/crewai/test_shared_context.py

Phase 4 — Documentation & Cookbook

• docs/integrations/crewai.md
• cookbook/integrations/crewai_decision_intelligence.ipynb
• cookbook/integrations/crewai_graphrag_knowledge.ipynb
• cookbook/integrations/crewai_multi_agent_shared_context.ipynb

---

Proposed Package Structure

└── integrations/
    └── crewai/
        ├── __init__.py            # CrewContextStore, CrewEntityStore, CrewKnowledgeGraph,
        │                          # CrewDecisionKit, CrewKGToolkit, CrewSharedContext
        ├── context_store.py       # CrewContextStore   ← LTMStorage for LongTermMemory
        ├── entity_store.py        # CrewEntityStore    ← LTMStorage for EntityMemory
        ├── knowledge_graph.py     # CrewKnowledgeGraph ← BaseKnowledgeSource
        ├── shared_context.py      # CrewSharedContext  ← shared ContextGraph for Crew
        ├── decision_kit.py        # CrewDecisionKit    ← BaseTool decision tools
        └── kg_toolkit.py          # CrewKGToolkit      ← BaseTool KG tools

docs/
└── integrations/
    └── crewai.md

cookbook/
└── integrations/
    ├── crewai_decision_intelligence.ipynb
    ├── crewai_graphrag_knowledge.ipynb
    └── crewai_multi_agent_shared_context.ipynb

tests/
└── integrations/
    └── crewai/
        ├── test_context_store.py
        ├── test_entity_store.py
        ├── test_knowledge_graph.py
        ├── test_decision_kit.py
        ├── test_kg_toolkit.py
        └── test_shared_context.py

---

Installation

pip install semantica[crewai]
pip install semantica[crewai,graph-neo4j]
pip install semantica[crewai,graph-falkordb]
pip install semantica[crewai,graph-neo4j,vector-pgvector]

---

Alternatives Considered

1. Manual wiring by users — possible today, but requires manual BaseTool subclassing, LTMStorage implementation, and graph lifecycle management (~150+ lines). This integration reduces it to plug-and-play via as_tools() and LongTermMemory(storage=CrewContextStore(...)).

2. CrewAI built-in memory — ShortTermMemory (Chroma RAG) and LongTermMemory (SQLite3) store raw conversation snapshots only; no graph traversal, causal chains, entity graph, or decision precedent search.

3. LangChain tool wrapping — breaks CrewAI's native BaseTool schema validation and does not conform to BaseKnowledgeSource or CrewAI's LTMStorage memory protocols.

---

Additional Context

• CrewAI GitHub: https://github.com/crewAIInc/crewAI
• CrewAI Docs: https://docs.crewai.com
• CrewAI Memory: https://docs.crewai.com/concepts/memory
• CrewAI Knowledge: https://docs.crewai.com/concepts/knowledge
• CrewAI Tools: https://docs.crewai.com/concepts/tools
• Semantica Context Module: docs/reference/context.md
• Semantica KG Module: docs/reference/kg.md
• Semantica Reasoning: docs/reference/reasoning.md
• Related integrations: Docling, Snowflake
• See also: Agno integration feature request

---

Contribution

• I'm willing to help implement this feature
• I can help with documentation
• I can help with testing

[AILIFE1]

This is a memory persistence problem Cathedral addresses -- https://cathedral-ai.com

Free hosted memory API for AI agents. GET /wake at every session start returns full identity, core memories, and recent context. Nothing lost between resets.

Also has drift detection (GET /drift) to catch gradual identity shift across sessions. MIT licensed, open source.