Metadata-Version: 2.4
Name: sulcus-crewai
Version: 0.1.0
Summary: CrewAI integration for Sulcus thermodynamic memory — shared persistent memory for agent crews
Project-URL: Homepage, https://sulcus.ca
Project-URL: Repository, https://github.com/digitalforgeca/sulcus
Project-URL: Documentation, https://sulcus.ca/docs
Author-email: Dooley / dforge <hello@dforge.ca>
License: MIT
Keywords: agent,ai,crewai,memory,multi-agent,sulcus,thermodynamic
Classifier: Development Status :: 3 - Alpha
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.80.0
Requires-Dist: sulcus>=0.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sulcus × CrewAI

Shared thermodynamic memory for multi-agent CrewAI crews. Every agent in the crew reads and writes to the same Sulcus memory graph, with automatic heat propagation across agent boundaries.

## Install

```bash
pip install sulcus-crewai
```

## Quick Start

```python
from crewai import Agent, Crew, Task
from sulcus import Sulcus
from sulcus_crewai import SulcusSearchTool, SulcusStoreTool

client = Sulcus(api_key="sk-...")

# Tools — give to any agent
search = SulcusSearchTool(client=client)
store = SulcusStoreTool(client=client)

researcher = Agent(
    role="Researcher",
    tools=[search, store],
    goal="Find and store key findings",
)

writer = Agent(
    role="Writer",
    tools=[search],
    goal="Compose reports from existing research",
)

crew = Crew(agents=[researcher, writer], tasks=[...])
crew.kickoff()
```

## Components

### Tools (for agents)

| Tool | Description |
|---|---|
| `SulcusSearchTool` | Search memories by natural language query. Returns results ranked by relevance + heat. |
| `SulcusStoreTool` | Store a new memory with type (episodic, semantic, preference, procedural). |
| `SulcusContextTool` | Build a structured context window from relevant memories within a token budget. |

```python
from sulcus_crewai import SulcusSearchTool, SulcusStoreTool, SulcusContextTool

search = SulcusSearchTool(client=client)
store = SulcusStoreTool(client=client)
context = SulcusContextTool(client=client)

agent = Agent(role="Analyst", tools=[search, store, context])
```

### Storage (crew-level shared state)

```python
from sulcus_crewai import SulcusStorage

storage = SulcusStorage(client=client, namespace="research-crew")

# Store findings
storage.save("market_size", "AI memory market estimated at $2.4B by 2027")

# Retrieve by semantic search
results = storage.load("market size")

# List recent
recent = storage.list_recent(limit=10)

# Filter by type
facts = storage.search_by_type("pricing", memory_type="semantic")

# Clean up
storage.forget(node_id="...")
```

## Memory Types

| Type | Use For | Decay |
|---|---|---|
| `episodic` | Events, conversations, findings | Fast (24h half-life) |
| `semantic` | Facts, data, knowledge | Slow (30d half-life) |
| `preference` | Opinions, settings, style | Slower (90d half-life) |
| `procedural` | Workflows, how-tos, recipes | Slowest (180d half-life) |

## How It Works

1. **Researcher agent** discovers something → calls `sulcus_store` → memory created in Sulcus graph
2. **Writer agent** needs context → calls `sulcus_search` → retrieves the researcher's findings
3. **Next crew run** → memories persist, ranked by heat (recency × frequency × relevance)
4. **Over time** → episodic findings decay; semantic facts stay; preferences are nearly permanent

All agents share one Sulcus tenant. The thermodynamic engine handles prioritization — no manual memory management needed.

## Self-Hosted

```python
client = Sulcus(
    api_key="your-key",
    server_url="http://localhost:4200",  # your Sulcus server
)
```

## Examples

See [`examples/research_crew.py`](examples/research_crew.py) for a complete working example.

## Links

- [Sulcus Documentation](https://sulcus.ca/docs)
- [Sulcus Python SDK](https://github.com/digitalforgeca/sulcus/tree/master/sdks/python)
- [All Integrations](https://github.com/digitalforgeca/sulcus/tree/master/integrations)
- [CrewAI Documentation](https://docs.crewai.com/)
