Metadata-Version: 2.4
Name: strawpot-memory
Version: 0.2.6
Summary: Memory protocol types for StrawPot agent orchestration
Author: StrawPot Contributors
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# strawpot-memory

Interface definition for StrawPot memory providers.

This package defines the `MemoryProvider` protocol and associated types that any memory backend must implement to integrate with the StrawPot agent orchestration system.

## Install

```bash
pip install strawpot-memory
```

## Usage

Implement the `MemoryProvider` protocol to create a custom memory backend:

```python
from strawpot_memory.memory_protocol import (
    MemoryProvider,
    GetResult,
    DumpReceipt,
    RememberResult,
    RecallResult,
)


class MyMemoryProvider:
    name = "my-provider"

    def get(self, *, session_id, agent_id, role, behavior_ref, task,
            budget=None, parent_agent_id=None, group_id=None) -> GetResult:
        ...

    def dump(self, *, session_id, agent_id, role, behavior_ref, task, status, output,
             tool_trace="", parent_agent_id=None, artifacts=None, group_id=None) -> DumpReceipt:
        ...

    def remember(self, *, session_id, agent_id, role, content,
                 keywords=None, scope="project", group_id=None) -> RememberResult:
        ...

    def recall(self, *, session_id, agent_id, role, query,
               keywords=None, scope="", max_results=10, group_id=None) -> RecallResult:
        ...


assert isinstance(MyMemoryProvider(), MemoryProvider)  # runtime check
```

## Protocol Methods

| Method | Purpose |
|--------|---------|
| `get` | Retrieve context cards and control signals before spawning an agent |
| `dump` | Record agent results after completion |
| `remember` | Persist knowledge during agent execution |
| `recall` | Query stored knowledge on-demand during agent execution |

## Types

- `MemoryKind` — enum of memory types (`PM`, `SM`, `STM`, `RM`, `EM`)
- `ContextCard` — single unit of context returned by `get`
- `ControlSignal` — advisory signals (risk level, suggested next step, policy flags)
- `GetResult` — full output of a `get` call
- `DumpReceipt` — receipt returned by `dump`
- `RememberResult` — result returned by `remember`
- `RecallEntry` — single entry returned by `recall`
- `RecallResult` — result returned by `recall`

## License

[MIT](LICENSE)
