Metadata-Version: 2.4
Name: clude
Version: 0.1.0
Summary: Persistent memory for AI agents. Store, recall, and learn from experience.
Project-URL: Homepage, https://clude.io
Project-URL: Documentation, https://clude.io/docs
Project-URL: Repository, https://github.com/sebbsssss/clude-python-sdk
Project-URL: Issues, https://github.com/sebbsssss/clude-python-sdk/issues
Author-email: Sebastien <seb@clude.io>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,crewai,langchain,llm,memory,persistent-memory,rag
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: supabase
Requires-Dist: supabase>=2.0.0; extra == 'supabase'
Description-Content-Type: text/markdown

# clude

Persistent memory for AI agents. Give your agent a brain that learns, remembers, and improves over time.

```python
from clude import Clude

brain = Clude(api_key="your-cortex-api-key")

# Store a memory
await brain.store(
    content="Auth bug was caused by expired JWT refresh token. Fixed by adding token expiry check before retry.",
    type="procedural",
    tags=["auth", "debugging"],
    importance=0.8,
)

# Recall relevant memories
memories = await brain.recall("authentication issues")
for m in memories:
    print(f"[{m.type}] {m.summary} (importance: {m.importance})")
```

## Install

```bash
pip install clude
```

For self-hosted mode with Supabase:
```bash
pip install clude[supabase]
```

## Quick Start

### Hosted mode (recommended)

Get an API key at [clude.io](https://clude.io) or run `npx clude-bot register`.

```python
from clude import Clude

brain = Clude(api_key="your-api-key")
```

### Self-hosted mode

Connect directly to your own Supabase + Voyage setup:

```python
from clude import Clude

brain = Clude(
    supabase_url="https://your-project.supabase.co",
    supabase_key="your-service-key",
    voyage_api_key="your-voyage-key",
    owner_wallet="your-agent-id",
)
```

## API

### Store

```python
memory_id = await brain.store(
    content="Full memory content here",
    summary="Short summary for recall matching",  # optional, auto-generated if omitted
    type="episodic",       # episodic | semantic | procedural | self_model | introspective
    tags=["project", "debugging"],
    importance=0.7,        # 0.0 to 1.0
)
```

### Recall

```python
memories = await brain.recall(
    query="how did we fix the auth bug?",
    limit=5,
    types=["procedural", "episodic"],  # optional filter
    threshold=0.3,
)
```

### Stats

```python
stats = await brain.stats()
print(f"Total memories: {stats.total_memories}")
print(f"By type: {stats.by_type}")
```

### Export / Import (MemoryPacks)

```python
# Export
pack = await brain.export_pack(query="authentication", limit=50)
print(pack.to_json())

# Import
from clude import MemoryPack
pack = MemoryPack.from_json(raw_json)
count = await brain.import_pack(pack)
print(f"Imported {count} memories")
```

### Forget

```python
await brain.forget(memory_id="12345")
```

## Framework Integration

### LangChain

```python
from clude import Clude

brain = Clude(api_key="...")

# In your LangChain agent's tool:
async def remember(query: str) -> str:
    memories = await brain.recall(query, limit=3)
    return "\n".join(m.content for m in memories)

async def learn(content: str) -> str:
    mid = await brain.store(content=content, type="episodic")
    return f"Stored memory {mid}"
```

### CrewAI

```python
from crewai import Agent, Task
from clude import Clude

brain = Clude(api_key="...")

# Add memory recall to agent context
memories = await brain.recall("project requirements")
context = "\n".join(m.content for m in memories)

agent = Agent(
    role="Developer",
    backstory=f"You have these memories:\n{context}",
    # ...
)
```

## Memory Types

| Type | Use For |
|------|---------|
| `episodic` | Events, conversations, things that happened |
| `semantic` | Facts, knowledge, learned information |
| `procedural` | How-to knowledge, patterns, best practices |
| `self_model` | Self-awareness, capabilities, preferences |
| `introspective` | Reflections, journal entries, insights |

## How It Works

Clude isn't a key-value store. It's a cognitive memory system:

- **Four memory types** with different decay curves
- **Dream cycle** consolidation every 6 hours
- **Hebbian reinforcement** - accessed memories grow stronger
- **Association graph** with typed bonds between memories
- **Active reflection** - the agent thinks about its own thinking
- **Memory provenance** - traceable ancestry for every memory

Learn more at [clude.io](https://clude.io).

## License

MIT
