Metadata-Version: 2.4
Name: agentmemory-py
Version: 0.0.4
Summary: Package for managing agent memory in AI applications
Author-email: Enrico Goerlitz <rico.goerlitz@gmail.com>
Requires-Python: >=3.13
Requires-Dist: pymongo>=4.13.2
Requires-Dist: pytest>=8.4.1
Requires-Dist: redis>=6.2.0
Requires-Dist: requests>=2.32.4
Description-Content-Type: text/markdown

# AgentMemory Package

[![CI](https://github.com/enricogoerlitz/agentmemory-py/actions/workflows/ci.yml/badge.svg)](https://github.com/enricogoerlitz/agentmemory-py/actions/workflows/ci.yml)
[![release](https://github.com/enricogoerlitz/agentmemory-py/actions/workflows/release.yml/badge.svg)](https://github.com/enricogoerlitz/agentmemory-py/actions/workflows/release.yml)

## Description

AgentMemory is a Python package for managing agent memory structures in AI applications. It provides a flexible data model for long-term and short-term memory and supports storing and managing:

- **Persona**: Information and properties of an agent.
- **Conversation**: Conversations between agents and users.
- **ConversationItems**: Individual messages or actions within a conversation.
- **Workflows**: Workflows executed by agents.
- **WorkflowSteps**: Individual steps within a workflow.

Additionally, a cache system is provided for fast access and temporary storage.

## Installation

Install the package using pip or uv:

```bash
pip install agentmemory-py
# or
uv add agentmemory-py
```

## Quickstart

### Create a Memory Object

```python
from agentmemory import AgentMemory
from agentmemory.connection import AgentMemoryConnection
from agentmemory.connection.longterm import MongoDBConnection
from agentmemory.connection.shortterm import RedisConnection

con = AgentMemoryConnection(
    longterm_con=MongoDBConnection(
        mongo_uri="mongodb://localhost:27017",
        database="support-agentmemory"
    ),
    shortterm_con=RedisConnection(
        host="localhost"
    )
)

memory = AgentMemory("support-agentmemory", con=con)
```


## Manage Conversations

### Create a New Conversation

```python
from agentmemory.schema.conversations import Conversation

conversation = Conversation(
    title="New Conversation",
)

created_conversation = memory.conversations.create(conversation)
print(created_conversation)
```

### List Conversations

```python
# Get all conversations
conversations = memory.conversations.list()

# Get only 5 conversations
conversations = memory.conversations.list(limit=5)

# Filter by title
conversations = memory.conversations.list(query={"title": "title1"})
```

### Retrieve and Update a Conversation

```python
id = "<ID>"
conversation = memory.conversations.get(id)
conversation.title = "Updated Title"
memory.conversations.update(conversation)
```

### Delete a Conversation

```python
id = "<ID>"
memory.conversations.delete(id)
```


## Manage ConversationItems

```python
from agentmemory.schema.conversations import ConversationItem

item = ConversationItem(
    conversation_id="<CONVERSATION_ID>",
    content="Hello, how can I help?"
)

created_item = memory.conversation_items.create(item)
print(created_item)

# Get items of a conversation
items = memory.conversation_items.list_by_conversation_id("<CONVERSATION_ID>")
```


## Manage Personas

```python
from agentmemory.schema.personas import Persona

persona = Persona(
    name="SupportAgent",
    description="Helps users with support requests."
)

created_persona = memory.personas.create(persona)
print(created_persona)

# Retrieve persona by name
persona = memory.personas.get_by_name("SupportAgent")
```


## Manage Workflows and WorkflowSteps

```python
from agentmemory.schema.workflows import Workflow, WorkflowStep

workflow = Workflow(
    name="Support Workflow",
    description="Handles support tickets."
)

created_workflow = memory.workflows.create(workflow)
print(created_workflow)

step = WorkflowStep(
    workflow_id=created_workflow.id,
    name="Check Ticket"
)

created_step = memory.workflow_steps.create(step)
print(created_step)
```


## Custom Caching

The integrated cache system enables fast access to frequently used data.

```python
memory.cache.keys("*")              # List all keys
memory.cache.get("<KEY>")           # Get value
memory.cache.set("<KEY>", "value")  # Set value
memory.cache.clear("<PATTERN>")     # Clear cache by pattern
```

## Tests

To run the tests:

```bash
uv run pytest
```

## License

MIT License. See [LICENSE](LICENSE) for details.
