eta.memory

Tools for storing and retrieving eventualities in Eta’s semantic memory.

Classes

Memory	Represents a single memory, which consists of a temporally bounded event with some importance value.
MemoryStorage	Stores memories and a context of "true now" facts, keyed on both episode names and predicates for efficient lookup.

class Memory(event, importance=0.25)

Bases: object

Represents a single memory, which consists of a temporally bounded event with some importance value.

Parameters:

• event (Eventuality) – The eventuality of this memory.

• importance (float, optional) – A numerical score representing how important this memory is.

event

Type:

Eventuality

start_time

The earliest time at which the event in this memory is known to be true. This is initialized as the current time upon initialization of a new memory.

Type:

TimePoint

end_time

The latest time at which the event in this memory is known to be true. This is initialized as None, interpreted as the event being “true now”.

Type:

TimePoint, optional

last_access

The most recent time that this memory was accessed from memory storage, initialized as the start time.

Type:

TimePoint

importance

Type:

float

Notes

The start time only marks the earliest time point at which an episode is known to be true; likewise for the end time. Thus, their logical interpretation should be as follows:

• (<start_time> during <event>.ep)

• (<end_time> during <event>.ep)

Where <end_time> is to be read as an indexical variable ^now if no value is supplied.

update_last_access()

Update the most recent access of this memory to the current time.

end()

Declare that this memory is no longer true by storing the current time as its end time.

get_ep()

Get the episode of the event of this memory.

get_wff()

Get the wff of the event of this memory.

get_time_wffs()

Get the wffs corresponding to the beginning and end of this memory.

is_telic()

Check whether this memory represents a telic event (i.e., one that is essentially instantaneous).

class MemoryStorage(embedder=None, importance_threshold=0.5)

Bases: object

Stores memories and a context of “true now” facts, keyed on both episode names and predicates for efficient lookup.

Parameters:

• embedder (Embedder, optional) – If provided, an embedder to embed all memories that are added to storage.

• importance_threshold (float, optional) – The threshold to place on importance values when retrieving memories (i.e., only memories above this threshold will be retrieved). If not given, the default threshold defined in eta.constants will be used.

memories

A set containing all stored memories.

Type:

set[Memory]

ep_ht

A hash table mapping episode variables/constants to memories of events that characterize those episodes.

Type:

dict[str, Memory]

wff_ht

A hash table mapping tuples of wff keys to memories of events with wffs matching those keys. Valid keys may be:

1. A single predicate string, e.g., pred.

2. A binary predicate tuple, e.g., (subj, pred).

3. A tuple containing the predicate of a wff with one other argument, with other arguments being replaced with None, e.g.,

• (subj, pred, None, None, ...)

• (None, pred, obj1, None, ...)

• (None, pred, None, obj2, ...)

Type:

dict[str or tuple, Memory]

context

A set containing all memories that are “true now”.

Type:

set[Memory]

embedder

Type:

Embedder or None

importance_threshold

Type:

float

access(memory)

“Access” a memory (or list of memories) by updating the most recent access date of that memory.

If the event is telic (i.e., assumed to be “instantaneous”), remove it from context as well.

Parameters:

memory (Memory or list[Memory]) –

Return type:

Memory or list[Memory]

store(memory, context=True)

Store a memory (or list of memories), adding to each hash table as well as to context.

Parameters:

• memory (Memory or list[Memory]) –

• context (bool, default=True) – Whether to store the given memory in context.

Notes

TODO: this should be extended so that storing a fact such as (not <wff>) actually removes the embedded wff from context. However, in addition to removing the negated WFF, should the negative WFF then be kept in context? In that case, we would need to remove the negative WFF once the positive version is added, and so on… It seems like, in general, we need some sort of contradiction detection for removing facts from context once contradicting facts are added.

TODO: in the case of events with duplicate wffs but different episode constants being inserted (e.g., (^you reply-to.v E1) ** E3 and (^you reply-to.v E1) ** E4)), we should probably merge them into a single memory/event with a new episode constant, e.g., E5. We may then either replace all other occurrences of E3 and E4 throughout memory with E5, or we may somehow store that E3 and E4 are both sub-events of E5.

remove(memory)

Remove a memory (or list of memories) from all sets and hash tables.

Parameters:

memory (Memory or list[Memory]) –

remove_from_context(memory)

Remove a memory (or list of memories) from context.

Parameters:

memory (Memory or list[Memory]) –

Notes

TODO: currently, this only removes the individual memory from context. However, since multiple memories may characterize the same episode, if one memory characterizing a particular episode is removed from context, should all memories characterizing the same episode be removed from context? This is currently unclear; in the future, we may need to add partial characterization (i.e., (<wff> * <ep>)) to account for this.

instantiate(event, importance=0.25, context=True)

Instantiate an event (or list of events) as a new memory and store it.

Parameters:

• event (Eventuality or list[Eventuality]) – The eventuality object(s) to store as new memories.

• importance (float or list[float], optional) – The importance value(s) to assign to each new memory.

• context (bool, default=True) – Whether to store the instantiated memory in context.

get_episode(ep, access=False)

Get memories that characterize a specific episode.

Parameters:

• ep (str) – An episode symbol.

• access (bool, default=False) – Whether to update the last access time of the memories.

Return type:

list[Memory]

get_matching(pred_patt, access=False)

Get memories matching a given predicate pattern potentially containing variables.

Parameters:

• pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

• access (bool, default=False) – Whether to update the last access time of the memories.

Return type:

list[Memory]

Notes

TODO: currently, due to the indexing scheme used by wff_ht, we only allow variables in the top level of a predication (i.e., variables may not be nested within an S-expression). In the future, we may wish to allow for more general matching.

get_from_context(pred_patt, access=False)

Get a memory from context matching a given predicate pattern potentially containing variables.

Parameters:

• pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

• access (bool, default=False) – Whether to update the last access time of the memories.

Return type:

list[Memory]

remove_episode(ep)

Remove all memories characterizing a given episode.

Parameters:

ep (str) – An episode symbol.

remove_matching(pred_patt)

Remove all memories matching a given predicate pattern potentially containing variables.

Parameters:

pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

remove_episode_from_context(ep)

Remove all memories from context characterizing a given episode.

Parameters:

ep (str) – An episode symbol.

remove_matching_from_context(pred_patt)

Remove all memories from context matching a given predicate pattern potentially containing variables.

Parameters:

pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

flush_context()

Remove from context all “telic” events (i.e., events that we regard as essentially instantaneous).

get_characterizing_episode(pred_patt, ep)

Get all memories that both match a given predicate pattern and characterize a given episode.

Parameters:

• pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

• ep (str) – An episode symbol.

Return type:

list[Memory]

does_characterize_episode(pred_patt, ep)

Check whether a given predicate pattern matches a memory characterizing a given episode.

Parameters:

• pred_patt (str or s-expr) – A predicate symbol or predicate pattern, i.e., an S-expression possibly containing variables at the top level, e.g., between.p or [Block1, between.p, ?x, Block2].

• ep (str) – An episode symbol.

Return type:

bool

retrieve(query=None, n=5, coeffs=(1.0, 1.0, 1.0))

Retrieve some number of relevant memories according to recency, importance, and salience.

The following three sub-criteria are used to determine which memories are retrieved: - recency : the latest access time of each memory. - importance : the importance values assigned to each memory. - salience : the embedding similarity between each memory and a query (if given).

Each sub-criteria score is mapped to a score in [0,1], and the final score is a linear sum of each sub-score multiplied by the respective coefficient in ‘coeffs’. The highest scoring memories are returned.

Parameters:

• query (str, optional) – The query to use in computing salience scores. If no query is given, or if no embedder is defined, the salience score will be 1 for every memory.

• n (int, default=5) – The number of memories to retrieve.

• coeffs (tuple[float, float, float], default=(1., 1., 1.)) – A tuple of coefficients to be used to weight each respective sub-score.

Return type:

list[Memory]

forget()

Evict some facts from memory in order to reduce memory size (TBC).

Notes

TODO: this function should be implemented to permanently evict facts from memory as memory sizes become too large for tractable retrieval. It should remove facts where the combined relevance and importance values fall below some threshold.