crewai-soul 🧠

The soul ecosystem for CrewAI agents.

One package, full stack:

• Persistent Memory — Markdown-native, git-versionable, human-readable
• Hybrid Retrieval — RAG + RLM via soul-agent
• Database Intelligence — Auto-generated semantic layers via soul-schema
• Managed Cloud Option — SoulMate handles memory infrastructure for you

Choose Your Setup

Both use the same soul-agent RAG+RLM under the hood.

Install

pip install crewai-soul

This automatically installs:

• soul-agent — Hybrid RAG+RLM memory
• soul-schema — Database semantic layer generator

Quick Start

Basic Memory

from crewai import Crew, Agent, Task
from crewai_soul import SoulMemory

# Create markdown-based memory with full RAG+RLM
memory = SoulMemory()

# Use it with your crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    memory=memory,
)

result = crew.kickoff()

Your crew's memories are stored in MEMORY.md — human-readable, git-versionable, no database required.

Database Schema Intelligence

Give your agents understanding of database structure:

from crewai_soul import SchemaMemory

# Connect to any SQLAlchemy-compatible database
schema = SchemaMemory("postgresql://user:pass@host/db")

# Auto-generate semantic descriptions using LLM
schema.generate()

# Get context for natural language queries
context = schema.context_for("Show me revenue by region")
# Returns formatted markdown with relevant tables/columns

# Use in agent prompts
agent = Agent(
    role="Data Analyst",
    goal="Answer business questions with SQL",
    backstory=f"You have access to this schema:\n{schema.to_markdown()}"
)

SoulMate: Managed Memory (Recommended for Production)

Don't want to manage files? SoulMate is the managed version of soul-agent — same RAG+RLM, zero infrastructure:

from crewai_soul import SoulMateClient

client = SoulMateClient(
    api_key="your-key",
    tenant_id="your-org"
)

# Store memories in the cloud
client.remember("Critical decision: We're going with PostgreSQL", scope="/project/alpha")

# Semantic search across all memories
results = client.recall("database decisions")

# Full RAG+RLM question answering
answer = client.ask("What database did we choose for Project Alpha?")

Why crewai-soul?

API Reference

SoulMemory

from crewai_soul import SoulMemory

memory = SoulMemory(
    soul_path="SOUL.md",      # Agent identity
    memory_path="MEMORY.md",  # Memory log
    provider="anthropic",     # LLM provider for RAG
    use_hybrid=True,          # Enable RAG+RLM (default: True if soul-agent installed)
)

# Store a memory
memory.remember("We decided to use PostgreSQL.", scope="/decisions")

# Recall relevant memories
matches = memory.recall("What database did we choose?", limit=5)
for m in matches:
    print(f"[{m.score:.2f}] {m.content}")

# Clear memories (optionally by scope)
memory.forget(scope="/decisions")

# Get stats
print(memory.info())

# View structure
print(memory.tree())

SchemaMemory

from crewai_soul import SchemaMemory

schema = SchemaMemory(
    database_url="postgresql://...",
    llm_provider="anthropic",
)

# Generate descriptions for all tables
schema.generate()

# Or specific tables only
schema.generate(tables=["customers", "orders"])

# Get single table description
info = schema.describe("customers")

# Generate context for a query
context = schema.context_for("revenue by region")

# Export in different formats
schema.save("schema.json", format="json")
schema.save("schema.yml", format="dbt")
schema.save("training.jsonl", format="vanna")

# Full markdown documentation
docs = schema.to_markdown()

SoulMateClient

from crewai_soul import SoulMateClient

client = SoulMateClient(
    api_key="...",              # or SOULMATE_API_KEY env var
    base_url="...",             # or SOULMATE_URL env var
    tenant_id="...",            # for multi-tenant isolation
)

# Store memories
client.remember("Important fact", scope="/project")

# Search
results = client.recall("important", limit=10)

# Full RAG+RLM Q&A
answer = client.ask("What do we know about...")

# Clear memories
client.forget(scope="/project")

# Get stats
info = client.info()

The Soul Ecosystem

crewai-soul brings together:

SoulMate API — Enterprise hosted service for production deployments.

Links

• soul.py — Core memory library
• soul-schema — Database documentation
• SoulMate — Enterprise offering
• CrewAI — Multi-agent framework
• The Menon Lab — Research & tools

License

MIT