Metadata-Version: 2.4
Name: totalrecallagent
Version: 0.6.0
Summary: On-chain memory infrastructure for AI agents — built on the Internet Computer
Project-URL: Homepage, https://www.totalrecallagent.com
Project-URL: Repository, https://github.com/cleo3llc/total-recall-python
Project-URL: Issues, https://github.com/cleo3llc/total-recall-python/issues
Author-email: Cleo 3 LLC <hello@totalrecallagent.com>
License: MIT
Keywords: agent-memory,ai,icp,internet-computer,langchain,on-chain,persistent-memory,total-recall
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
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Provides-Extra: all
Requires-Dist: httpx>=0.25.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Provides-Extra: async
Requires-Dist: httpx>=0.25.0; extra == 'async'
Provides-Extra: langchain
Requires-Dist: httpx>=0.25.0; extra == 'langchain'
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Description-Content-Type: text/markdown

# Total Recall Python SDK

On-chain persistent memory for AI agents — built on Internet Computer Protocol.

**Zero dependencies. Pure stdlib.**

## Install

```bash
pip install total-recall-sdk
```

## Quick Start

```python
from total_recall import TotalRecallClient

# Initialize with your API key from totalrecallagent.com
memory = TotalRecallClient(api_key="tr_your_key_here")

# Store anything
memory.store("agent/context", {"task": "active", "step": 3, "notes": "HVAC rough-in complete"})
memory.store("agent/notes", "Remember: laser lab requires ISO class 5 HVAC")

# Retrieve
ctx = memory.get("agent/context")  # returns dict
note = memory.get("agent/notes")   # returns string

# List all keys
keys = memory.list_keys()
agent_keys = memory.list_keys(prefix="agent/")

# Delete
memory.delete("agent/notes")

# Usage stats
stats = memory.stats()
print(f"Storage: {stats['storage_bytes']} bytes, Calls today: {stats['calls_today']}")
```

## Agent Session Pattern

```python
from total_recall import TotalRecallClient

memory = TotalRecallClient(api_key="tr_your_key_here")
AGENT_ID = "hvac-specialist"

# On session START — load previous context
ctx = memory.get_session(AGENT_ID) or {}
print(f"Resuming from: {ctx}")

# During session — save continuously
memory.store_session(AGENT_ID, {
    "current_task": "Data center HVAC inspection",
    "phase": "rough-in",
    "completed_rooms": ["server-room-a", "server-room-b"],
    "next_up": "server-room-c",
})

# On session END — post handoff to Basecamp
memory.handoff(
    agent_id   = AGENT_ID,
    agent_name = "HVAC Specialist",
    message    = "Inspection complete. Rooms A and B done. Next: Room C. Context saved."
)
```

## Use with LangChain

```python
from total_recall import TotalRecallClient
from langchain.memory import ConversationBufferMemory

memory_client = TotalRecallClient(api_key="tr_your_key")

class TotalRecallMemory(ConversationBufferMemory):
    def save_context(self, inputs, outputs):
        super().save_context(inputs, outputs)
        memory_client.store("langchain/history", self.chat_memory.messages_to_dict())

    def load_memory_variables(self, inputs):
        saved = memory_client.get("langchain/history")
        if saved:
            self.chat_memory.load_from_dict(saved)
        return super().load_memory_variables(inputs)
```

## API Reference

| Method | Description |
|--------|-------------|
| `store(key, value, tags=None, ttl_seconds=None)` | Store any value |
| `get(key)` | Retrieve a value |
| `delete(key)` | Delete a key |
| `list_keys(prefix=None)` | List all keys |
| `get_all(prefix=None)` | Get all entries |
| `search(query, tags=None)` | Search by tags |
| `stats()` | Usage statistics |
| `store_session(agent_id, data)` | Save agent session |
| `get_session(agent_id)` | Load agent session |
| `handoff(agent_id, agent_name, message)` | Post to Basecamp |

## Get Your API Key

1. Go to [totalrecallagent.com](https://totalrecallagent.com)
2. Connect with Internet Identity
3. Click **⚡ API Keys** → Generate Key

## License

MIT © 2026 Cleo 3 LLC
