[api][runtime] Introduce long-term memory in python

[wenjin272]

Linked issue: #331

Purpose of change

Introduce the long-term memory interface in python, and provide an implementation based on chroma.

This is the first pr of three to introduce long-term memory in python:

1. interface and one implementation
2. support using long-term memory in action
3. async interface and execution

Tests

Unit test

API

Yes, add long-term memory related api.

Documentation

• doc-needed

[xintongsong]

Not sure about the name Reduce. I think Compact might be better.

[xintongsong]

I'd suggest to name this CompactionStrategy, and make it an abstract class that we can provide different implementations, so we can have strict limit on which arguments should be specified for each strategy. We can call the current ReduceStrategy CompactionStrategyType.

[xintongsong]

I think CompactionStrategy.trim(n) might be more straightforward for users, compared to ReduceSetup.trim_setup(n).

[xintongsong]

Suggested change

	created_time: DatetimeRange
	created_time: DatetimeRange | datetime

[xintongsong]

Why do we need to store ids of all the items?

[xintongsong]

And why do we need to know whether a memory set has been reduced/compacted?

[xintongsong]

what is this directory for?

[xintongsong]

This can be extremely slow. We should proactively do the compaction.

[xintongsong]

I had a feeling that adding items to long-term memory can take time, for embedding. We probably should also provide async apis.

[xintongsong]

Same here.

[xintongsong]

Are these methods specialized for this class?

[wenjin272]

Hi, @alnzng. There's a design issue related to the vector store that I'd appreciate your help reviewing.

As describe in the design doc #339, long-term memory of flink-agents is also based on vector store. Currently, I provide an implementation based on chroma. In this implementation, I directly use chroma client rather than flink-agents BaseVectorStore, because there are some long-term memory needed interface not provided in BaseVectorStore.

@xintongsong believes that we can directly build upon the Flink-Agents BaseVectorStore. Thus, we can support using any already supported vector store as the backend for long-term memory.

I think this make sense, but it requires add some interfaces to BaseVectorStore, which maybe look like:

def get_or_create_collection(self, name: str, metadata: Dict[str, Any]) -> Dict[str, Any]:
    """Get a collection, create if it doesn't already exist."""
    
def get_collection(self, name: str) -> None:
    """Get an existing collection."""
    
def update_collection(self, name: str, metadata: Dict[str, Any]) -> None:
    """Update an existing collection."""

def delete_collection(self, name: str) -> bool:
    """Delete a collection."""
    
def add(self, document: Document, collection_name: str | None = None) -> None:
    """Add a document to the collection."""

def update(self, document: Document, collection_name: str | None = None) -> None:
    """Update a document, can only update metadata."""

def delete(self, offset: int | None, limit: int | None, ids: List[int] | None = None, **kwargs: Any) -> bool:
    """Delete documents from collection."""

def get(self, offset: int | None, limit: int | None, collection_name: str | None = None, **kwargs: Any) -> List[Document]:
    """Get documents from collection."""

These interface may not be achievable for each vector store, I will conduct research and refinement afterward.
WDTY?