Package: agentmemory
Easy-to-use memory for agents, document search, knowledge graphing and more.InstallationpipinstallagentmemoryQuickstartfromagentmemoryimportcreate_memory,search_memory# create a memorycreate_memory("conversation","I can't do that, Dave.",metadata={"speaker":"HAL","some_other_key":"some value, could be a number or string"})# search for a memorymemories=search_memory("conversation","Dave")# category, search termprint(str(memories))# memories is a list of dictionaries[{"id":int,"document":string,"metadata":dict{...values},"embeddings":(Optional)list[float]|None},{...}]DebuggingYou can enable debugging by passingdebug=Trueto most functions, or by setting DEBUG=True in your environment to get global memory debugging.create_memory("conversation","I can't do that, Dave.",debug=True)DeploymentCLIENT_TYPE='POSTGRES' | 'CHROMA'
POSTGRES_CONNECTION_STRING=postgres://postgres:MagickDatabase123!@db.xnzvmluhwpbngdufsbrd.supabase.co:6543/postgresBy default, agentmemory will use a local ChromaDB instance. If you want to use a Postgres instance, you can set the environment variableCLIENT_TYPEtoPOSTGRESand set thePOSTGRES_CONNECTION_STRINGenvironment variable to your Postgres connection string.You can deploy an agentmemory-based application to the cloud in minutes using Supabase. Here is atutorialand an explanation ofpgvector.Basic Usage GuideImporting into your projectfromagentmemoryimport(create_memory,create_unique_memory,get_memories,search_memory,get_memory,update_memory,delete_memory,delete_similar_memories,count_memories,wipe_category,wipe_all_memories)Create a Memory# category, document, metadatacreate_memory("conversation","I can't do that, Dave.",metadata={"speaker":"HAL","some_other_key":"some value, could be a number or string"})Search memoriesmemories=search_memory("conversation","Dave")# category, search term# memories is a list of dictionaries[{"id":int,"document":string,"metadata":dict{...values},"embeddings":(Optional)list[float]|None},{...}]Get all memoriesmemories=get_memories("conversation")# can be any category# memories is a list of dictionaries[{"id":int,"document":string,"metadata":dict{...values},"embeddings":(Optional)list[float]|None},{...}]Get a memorymemory=get_memory("conversation",1)# category, idUpdate a memoryupdate_memory("conversation",1,"Okay, I will open the podbay doors.")Delete a Memorydelete_memory("conversation",1)Delete Similar Memoriesdelete_similar_memories(category, content, similarity_threshold=0.95)Search for memories that are similar to the one that contains the given content and removes them.Parameterscategory(str): The category of the collection.content(str): The content to search for.similarity_threshold(float, optional): The threshold for determining similarity. Defaults to 0.95.Returnsbool: True if the memory item is found and removed, False otherwise.API ReferenceCreate a Memorycreate_memory(category, text, id=None, embedding=None, metadata=None)Create a new memory in a collection.Arguments# Required
category (str): Category of the collection.
text (str): Document text.

# Optional
id (str): Unique id. Generated incrementally unless set.
metadata (dict): Metadata.
embedding (array): Embedding of the document. Defaults to None. Use if you already have an embedding.Example>>>create_memory(category='sample_category',text='sample_text',id='sample_id',metadata={'sample_key':'sample_value'})Create Unique Memorycreate_unique_memory(category, content, metadata={}, similarity=0.95)Create a new memory only if there aren't any that are very similar to it. If a similar memory is found, the new memory's "novel" metadata field is set to "False" and it is linked to the existing memory.Parameterscategory(str): The category of the collection.content(str): The text of the memory.metadata(dict, optional): Metadata for the memory.similarity(float, optional): The threshold for determining similarity.ReturnsNoneSearch Memorysearch_memory(category, search_text, n_results=5, min_distance=None, max_distance=None, filter_metadata=None, contains_text=None, include_embeddings=True, novel=False)Search a collection with given query texts.A note about distances: the filters are applied after the query, so the n_results may be dramatically shortened. This is a current limitation of Chromadb.Arguments# Required
category (str): Category of the collection.
search_text (str): Text to be searched.

# Optional
n_results (int): Number of results to be returned.
filter_metadata (dict): Metadata for filtering the results.
contains_text (str): Text that must be contained in the documents.
include_embeddings (bool): Whether to include embeddings in the results.
include_distances (bool): Whether to include distances in the results.
max_distance (float): Only include memories with this distance threshold maximum.
    0.1 = most memories will be exluded, 1.0 = no memories will be excluded
min_distance (float): Only include memories that are at least this distance
    0.0 = No memories will be excluded, 0.9 = most memories will be excluded
novel (bool): Whether to return only novel memories.Returnslist: List of search results.Example>>>search_memory('sample_category','search_text',min_distance=0.01,max_distance=0.7,n_results=2,filter_metadata={'sample_key':'sample_value'},contains_text='sample',include_embeddings=True,include_distances=True)[{'metadata':'...','document':'...','id':'...'},{'metadata':'...','document':'...','id':'...'}]Get a Memoryget_memory(category, id, include_embeddings=True)Retrieve a specific memory from a given category based on its ID.Arguments# Required
category (str): The category of the memory.
id (str/int): The ID of the memory.

#optional
include_embeddings (bool): Whether to include the embeddings. Defaults to True.Returnsdict: The retrieved memory.Example>>>get_memory("books","1")Get Memoriesget_memories(category, sort_order="desc", filter_metadata=None, n_results=20, include_embeddings=True, novel=False)Retrieve a list of memories from a given category, sorted by ID, with optional filtering.sort_ordercontrols whether you get from the beginning or end of the list.Arguments# Required
category (str): The category of the memories.

# Optional
sort_order (str): The sorting order of the memories. Can be 'asc' or 'desc'. Defaults to 'desc'.
filter_metadata (dict): Filter to apply on metadata. Defaults to None.
n_results (int): The number of results to return. Defaults to 20.
include_embeddings (bool): Whether to include the embeddings. Defaults to True.
novel (bool): Whether to return only novel memories. Defaults to False.Returnslist: List of retrieved memories.Example>>>get_memories("books",sort_order="asc",n_results=10)Update a Memoryupdate_memory(category, id, text=None, metadata=None)Update a memory with new text and/or metadata.Arguments# Required
category (str): The category of the memory.
id (str/int): The ID of the memory.

# Optional
text (str): The new text of the memory. Defaults to None.
metadata (dict): The new metadata of the memory. Defaults to None.Example# with keyword argumentsupdate_memory(category="conversation",id=1,text="Okay, I will open the podbay doors.",metadata={"speaker":"HAL","sentiment":"positive"})# with positional argumentsupdate_memory("conversation",1,"Okay, I will open the podbay doors.")Delete a Memorydelete_memory(category, id, contains_metadata=None, contains_text=None)Delete a memory by ID.Arguments# Required
category (str): The category of the memory.
id (str/int): The ID of the memory.

# OptionalExample>>>delete_memory("books","1")delete_memories(category, document=None, metadata=None)Delete all memories in the category either by document, or by metadata, or by both.Arguments# Required
category (str): The category of the memory.

# Optional
document (str): Document text to match memories to delete. Defaults to None.
metadata (dict): Metadata to match memories to delete. Defaults to None.Returnsbool: True if memories were deleted, False otherwise.Example>>>delete_memories("books",document="Foundation",metadata={"author":"Isaac Asimov"})Check if a memory existsmemory_exists(category, id, includes_metadata=None)Check if a memory exists in a given category.Arguments# Required
category (str): The category of the memory.
id (str/int): The ID of the memory.

# Optional
includes_metadata (dict): Metadata that the memory should include. Defaults to None.Example>>>memory_exists("books","1")Wipe an Entire Category of Memorieswipe_category(category)Delete an entire category of memories.Arguments# Required
category (str): The category to delete.

# OptionalExample>>>wipe_category("books")Count Memoriescount_memories(category)Count the number of memories in a given category.Argumentscategory (str): The category of the memories.Returnsint: The number of memories.Example>>>count_memories("books")Wipe All Memorieswipe_all_memories()Delete all memories across all categories.Arguments# OptionalExample>>>wipe_all_memories()Memory Management with ChromaDBThis document provides a guide to using the memory management functions provided in the module.FunctionsExport Memories to JSONTheexport_memory_to_jsonfunction exports all memories to a dictionary, optionally including embeddings.Argumentsinclude_embeddings(bool, optional): Whether to include memory embeddings in the output. Defaults to True.Returns:dict: A dictionary with collection names as keys and lists of memories as values.Example>>>export_memory_to_json()Export Memories to FileTheexport_memory_to_filefunction exports all memories to a JSON file, optionally including embeddings.Argumentspath(str, optional): The path to the output file. Defaults to "./memory.json".include_embeddings(bool, optional): Whether to include memory embeddings in the output. Defaults to True.Example>>>export_memory_to_file(path="/path/to/output.json")Import Memories from JSONTheimport_json_to_memoryfunction imports memories from a dictionary into the current database.Argumentsdata(dict): A dictionary with collection names as keys and lists of memories as values.replace(bool, optional): Whether to replace existing memories. If True, all existing memories will be deleted before import. Defaults to True.Example>>>import_json_to_memory(data)Import Memories from FileTheimport_file_to_memoryfunction imports memories from a JSON file into the current database.Argumentspath(str, optional): The path to the input file. Defaults to "./memory.json".replace(bool, optional): Whether to replace existing memories. If True, all existing memories will be deleted before import. Defaults to True.Example>>>import_file_to_memory(path="/path/to/input.json")Event APIA common need for the memory API is "events" -- logging when things happen sequentially. The event API provides a simple way to do this using the idea of "epochs". You can increment epochs as needed, and group events together within epochs. All of the events within a loop, or a conversation turn, for example, could be recorded as an epoch.reset_epoch()Thereset_epochfunction resets the epoch in the agent's memory to 1. It wipes the "epoch" category and creates a new memory of 1.Usage:reset_epoch()Example:reset_epoch()set_epoch(epoch)Theset_epochfunction sets the epoch in the agent's memory to the specified value.Arguments:epoch(int): The desired epoch value.Usage:set_epoch(epoch)Example:set_epoch(5)increment_epoch()Theincrement_epochfunction increments the current epoch value by 1. It retrieves the current epoch from memory, increments it, and then writes the new epoch value to memory.Usage:increment_epoch()Example:increment_epoch()get_epoch()Theget_epochfunction retrieves the current epoch value from the agent's memory.Usage:get_epoch()Example:current_epoch=get_epoch()print(current_epoch)create_event(text, metadata={}, embedding=None)Thecreate_eventfunction creates a new event in the agent's memory.Arguments:text(str): The text content of the event.metadata(dict, optional): Additional metadata for the event. Defaults to {}.embedding(object, optional): An optional embedding for the event.Usage:create_event(text,metadata={},embedding=None)Example:create_event("This is a test event",metadata={"test":"test"})get_events(epoch=None, filter_metadata=None, n_results=10)Theget_eventsfunction retrieves events from the agent's memory.Arguments:epoch(int, optional): If specified, only retrieve events from this epoch.Usage:get_events(epoch=None)Example:events=get_events(1)foreventinevents:print(event["document"])ClusteringOverviewTheclusterfunction inagentmemory.clusteringprovides an implementation of DBScan (Density-Based Spatial Clustering of Applications with Noise) clustering. It is designed to group memories in the agent's memory based on their similarity and proximity in the data space.Function Signaturedefcluster(epsilon,min_samples,category,filter_metadata=None,novel=False)Parametersepsilon(float): The maximum distance between two samples for one to be considered as in the neighborhood of the other.min_samples(int): The number of samples (or total weight) in a neighborhood for a point to be considered as a core point.category(str): The category of the collection to be clustered.filter_metadata(dict, optional): Additional metadata for filtering the memories before clustering. Defaults to None.novel(bool, optional): Whether to return only novel memories. Defaults to False.Memory ClusteringTheclusterfunction updates memories directly with their cluster ID by performing the DBScan clustering algorithm. Memories with similar content and metadata will be grouped together into clusters. The clustering result will be reflected in the metadata of the memories.Memory MarkingMemories with less thanmin_samplesneighbors within a distance ofepsilonwill be marked as noise, and their cluster ID in the metadata will be set to "noise."Memories belonging to a cluster will have their cluster ID stored in the "cluster" field of the metadata.UsageTo perform clustering on a specific category of memories, call theclusterfunction with appropriate parameters:fromagentmemory.clusteringimportcluster# Example usageepsilon=0.1min_samples=3category="conversation"filter_metadata={"speaker":"HAL"}# Optional metadata filternovel=False# Whether to return only novel memoriescluster(epsilon,min_samples,category,filter_metadata=filter_metadata,novel=novel)NoteThe clustering operation will directly update the memories' metadata in the specified category. Please make sure to have a backup of the data before performing clustering if necessary.ReferencesFor more information about DBScan clustering, refer to the original paper:DBScan PaperContributions WelcomeIf you like this library and want to contribute in any way, please feel free to submit a PR and I will review it. Please note that the goal here is simplicity and accesibility, using common language and few dependencies.