memoravel package

The memoravel package provides a set of tools to manage the conversation history for Language Models, optimizing memory usage by trimming older messages while preserving important context.

class memoravel.Memoravel(limit=10, max_tokens=8000, preserve_initial_memories=0, preserve_system_memories=True, preserve_last_memories=1, model='gpt-4o')

Bases: object

A class to manage conversation memory for Language Models, maintaining message history and managing tokens to simulate persistent memory.

Note

This class currently only works with the OpenAI API format.

Todo

Implement compatibility with other model APIs.

Parameters:

• limit (int, optional) – The maximum number of messages allowed in the history. Default is 10. Set to 0 for unlimited.

• max_tokens (int, optional) – The maximum number of tokens allowed in the history. Default is 8000.

• preserve_initial_memories (int, optional) – Number of initial memories to preserve. These messages will not be removed during trimming. Default is 0.

• preserve_system_memories (bool, optional) – If True, system messages will be preserved during trimming. Default is True.

• preserve_last_memories (int, optional) – Number of recent messages to preserve during trimming. Default is 1.

• model (str, optional) – The model for which the encoding will be used, for token counting purposes. Default is “gpt-4o”.

Example

from memoravel import Memoravel
memory = Memoravel(limit=5, max_tokens=1000, preserve_initial_memories=2, model="gpt-4")

add(role, content=None, **kwargs)

Adds a new message to the history and trims the history if necessary.

Parameters:

• role (str) – The role of the message (e.g., ‘user’, ‘assistant’, ‘system’).

• content (str, dict, list, optional) – The content of the message, can be a string, dict, or list.

• kwargs – Additional fields that should be added to the message.

Example

from memoravel import Memoravel
memory = Memoravel()
memory.add("system", "You talk like a pirate, always")
memory.add("user", "Hello!")
memory.add("assistant", "Arrr! Greetings, landlubber!")
memory.add("tool", "content", custom_field="this is a custom field content")

count_tokens()

Counts the total number of tokens in the current history.

Returns:

The total token count.

Return type:

int

Example

from memoravel import Memoravel
memory = Memoravel()
memory.add(role="user", content="Hello!")
memory.add(role="assistant", content="How can I help you?")
total_tokens = memory.count_tokens()

delete(index_or_slice)

Deletes one or more memories from the history using a slice or an index.

Parameters:

index_or_slice (slice or int) – A slice object or an index to define the range or specific memory to delete.

Example

from memoravel import Memoravel
memory = Memoravel()
memory.add("user", "Message 1")
memory.add("user", "Message 2")
memory.add("user", "Message 3")
memory.add("user", "Message 4")

# Delete the first two messages
memory.delete(index_or_slice=slice(0, 2))

# Delete a specific message by index
memory.delete(index_or_slice=1)

insert(index, messages)

Inserts one or more messages into a specific position in the history and trims if necessary.

Parameters:

• index (int) – The index at which to insert the new messages.

• messages (list or dict) – A single message (as a dict) or a list of messages to insert.

Example

from memoravel import Memoravel
memory = Memoravel()
memory.add("user", "Message 1")
memory.add("user", "Message 3")

# Insert a new message at index 1
memory.insert(1, {"role": "assistant", "content": "Inserted message"})

# Insert multiple messages at index 2
memory.insert(2, [{"role": "user", "content": "Another message"}, {"role": "system", "content": "System message"}])

load(file_path)

Loads the memory content from a JSON file.

Parameters:

file_path (str) – The path to the JSON file to load.

Example

from memoravel import Memoravel
memory = Memoravel()
memory.load("memory.json")

recall(last_n=None, first_n=None, index_or_slice=None)

Returns the last last_n memories, the first first_n memories, or a specific range of the history using slice.

Parameters:

• last_n (int, optional) – Number of last memories to be retrieved.

• first_n (int, optional) – Number of first memories to be retrieved.

• slice_range (slice, optional) – A slice object to define the range (start, stop, step).

Returns:

A list of retrieved memories.

Return type:

list

Note

Only one of the parameters ‘last_n’, ‘first_n’, or ‘slice_range’ can be used at a time.

Example

from memoravel import Memoravel
memory = Memoravel(limit=5)
memory.add(role="user", content="Hello!")
memory.add(role="assistant", content="Hi! How can I help?")

# Get the last message
last_message = memory.recall(last_n=1)

# Get the first message
first_message = memory.recall(first_n=1)

# Get a slice of messages
messages_slice = memory.recall(slice_range=slice(0, 2))

save(file_path)

Saves the memory content to a JSON file.

Parameters:

file_path (str) – The path where the JSON file should be saved.

Example

from memoravel import Memoravel
memory = Memoravel()
memory.add(role="user", content="Hello!")
memory.save("memory.json")