Skip to content

VSAMemory

Dictionary-style symbol table for managing named hypervectors.

VSAMemory provides a convenient interface for creating, storing, and accessing hypervectors associated with symbolic names. It automatically handles vector sampling and wrapping using the model's configuration.

vsax.core.memory.VSAMemory

Symbol table for storing and managing named basis vectors.

VSAMemory provides a dictionary-style interface for creating, storing, and retrieving named hypervectors. Each symbol is associated with a randomly sampled hypervector from the model's sampling distribution.

Parameters:

Name Type Description Default
model VSAModel

VSAModel instance defining the representation and operations.

 required
key Optional[Array]

Optional JAX PRNG key for reproducible sampling. If None, uses a default key.

 None
Example

from vsax import create_fhrr_model, VSAMemory model = create_fhrr_model(dim=512) memory = VSAMemory(model) memory.add("dog") memory.add_many(["cat", "bird"]) dog = memory["dog"] assert "cat" in memory print(memory.keys()) ['dog', 'cat', 'bird']

Source code in vsax/core/memory.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class VSAMemory:
    """Symbol table for storing and managing named basis vectors.

    VSAMemory provides a dictionary-style interface for creating, storing, and
    retrieving named hypervectors. Each symbol is associated with a randomly
    sampled hypervector from the model's sampling distribution.

    Args:
        model: VSAModel instance defining the representation and operations.
        key: Optional JAX PRNG key for reproducible sampling. If None, uses a
            default key.

    Example:
        >>> from vsax import create_fhrr_model, VSAMemory
        >>> model = create_fhrr_model(dim=512)
        >>> memory = VSAMemory(model)
        >>> memory.add("dog")
        >>> memory.add_many(["cat", "bird"])
        >>> dog = memory["dog"]
        >>> assert "cat" in memory
        >>> print(memory.keys())
        ['dog', 'cat', 'bird']
    """

    def __init__(self, model: VSAModel, key: Optional[jax.Array] = None) -> None:
        """Initialize VSAMemory with a model.

        Args:
            model: VSAModel instance defining the VSA algebra.
            key: Optional JAX PRNG key for reproducible sampling.
        """
        self._model = model
        self._symbols: dict[str, AbstractHypervector] = {}
        self._key = key if key is not None else jax.random.PRNGKey(0)
        self._counter = 0

    @property
    def model(self) -> VSAModel:
        """Get the underlying VSAModel."""
        return self._model

    def add(self, name: str) -> AbstractHypervector:
        """Add a new symbol to memory with a randomly sampled hypervector.

        If the symbol already exists, returns the existing hypervector without
        resampling.

        Args:
            name: Name of the symbol to add.

        Returns:
            The hypervector associated with the symbol.

        Example:
            >>> memory = VSAMemory(model)
            >>> dog = memory.add("dog")
            >>> assert "dog" in memory
        """
        if name in self._symbols:
            return self._symbols[name]

        # Split key for this sample
        self._key, subkey = jax.random.split(self._key)

        # Sample a new vector
        vec = self._model.sampler(self._model.dim, 1, subkey)[0]

        # Wrap in representation
        hv = self._model.rep_cls(vec)

        # Store and return
        self._symbols[name] = hv
        self._counter += 1
        return hv

    def add_many(self, names: Iterable[str]) -> list[AbstractHypervector]:
        """Add multiple symbols to memory.

        Args:
            names: Iterable of symbol names to add.

        Returns:
            List of hypervectors corresponding to the added symbols.

        Example:
            >>> memory = VSAMemory(model)
            >>> colors = memory.add_many(["red", "green", "blue"])
            >>> assert len(colors) == 3
        """
        return [self.add(name) for name in names]

    def get(self, name: str) -> AbstractHypervector:
        """Get a hypervector by name.

        Args:
            name: Name of the symbol to retrieve.

        Returns:
            The hypervector associated with the symbol.

        Raises:
            KeyError: If the symbol does not exist in memory.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add("dog")
            >>> dog = memory.get("dog")
        """
        return self._symbols[name]

    def __getitem__(self, name: str) -> AbstractHypervector:
        """Get a hypervector by name using dictionary syntax.

        Args:
            name: Name of the symbol to retrieve.

        Returns:
            The hypervector associated with the symbol.

        Raises:
            KeyError: If the symbol does not exist in memory.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add("dog")
            >>> dog = memory["dog"]
        """
        return self.get(name)

    def __contains__(self, name: str) -> bool:
        """Check if a symbol exists in memory.

        Args:
            name: Name of the symbol to check.

        Returns:
            True if the symbol exists, False otherwise.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add("dog")
            >>> assert "dog" in memory
            >>> assert "cat" not in memory
        """
        return name in self._symbols

    def keys(self) -> list[str]:
        """Get all symbol names in memory.

        Returns:
            List of symbol names.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add_many(["a", "b", "c"])
            >>> assert memory.keys() == ["a", "b", "c"]
        """
        return list(self._symbols.keys())

    def __len__(self) -> int:
        """Get the number of symbols in memory.

        Returns:
            Number of stored symbols.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add_many(["a", "b", "c"])
            >>> assert len(memory) == 3
        """
        return len(self._symbols)

    def clear(self) -> None:
        """Remove all symbols from memory.

        Example:
            >>> memory = VSAMemory(model)
            >>> memory.add_many(["a", "b", "c"])
            >>> memory.clear()
            >>> assert len(memory) == 0
        """
        self._symbols.clear()
        self._counter = 0

    def __repr__(self) -> str:
        """String representation of VSAMemory."""
        return f"VSAMemory(model={self._model.rep_cls.__name__}, symbols={len(self._symbols)})"

Attributes

model property

Get the underlying VSAModel.

Functions

__init__(model, key=None)

Initialize VSAMemory with a model.

Parameters:

Name Type Description Default
model VSAModel

VSAModel instance defining the VSA algebra.

 required
key Optional[Array]

Optional JAX PRNG key for reproducible sampling.

 None
Source code in vsax/core/memory.py 
36
37
38
39
40
41
42
43
44
45
46
def __init__(self, model: VSAModel, key: Optional[jax.Array] = None) -> None:
    """Initialize VSAMemory with a model.

    Args:
        model: VSAModel instance defining the VSA algebra.
        key: Optional JAX PRNG key for reproducible sampling.
    """
    self._model = model
    self._symbols: dict[str, AbstractHypervector] = {}
    self._key = key if key is not None else jax.random.PRNGKey(0)
    self._counter = 0

add(name)

Add a new symbol to memory with a randomly sampled hypervector.

If the symbol already exists, returns the existing hypervector without resampling.

Parameters:

Name Type Description Default
name str

Name of the symbol to add.

 required

Returns:

Type Description
AbstractHypervector

The hypervector associated with the symbol.
Example

memory = VSAMemory(model) dog = memory.add("dog") assert "dog" in memory

Source code in vsax/core/memory.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def add(self, name: str) -> AbstractHypervector:
    """Add a new symbol to memory with a randomly sampled hypervector.

    If the symbol already exists, returns the existing hypervector without
    resampling.

    Args:
        name: Name of the symbol to add.

    Returns:
        The hypervector associated with the symbol.

    Example:
        >>> memory = VSAMemory(model)
        >>> dog = memory.add("dog")
        >>> assert "dog" in memory
    """
    if name in self._symbols:
        return self._symbols[name]

    # Split key for this sample
    self._key, subkey = jax.random.split(self._key)

    # Sample a new vector
    vec = self._model.sampler(self._model.dim, 1, subkey)[0]

    # Wrap in representation
    hv = self._model.rep_cls(vec)

    # Store and return
    self._symbols[name] = hv
    self._counter += 1
    return hv

add_many(names)

Add multiple symbols to memory.

Parameters:

Name Type Description Default
names Iterable[str]

Iterable of symbol names to add.

 required

Returns:

Type Description
list[AbstractHypervector]

List of hypervectors corresponding to the added symbols.
Example

memory = VSAMemory(model) colors = memory.add_many(["red", "green", "blue"]) assert len(colors) == 3

Source code in vsax/core/memory.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def add_many(self, names: Iterable[str]) -> list[AbstractHypervector]:
    """Add multiple symbols to memory.

    Args:
        names: Iterable of symbol names to add.

    Returns:
        List of hypervectors corresponding to the added symbols.

    Example:
        >>> memory = VSAMemory(model)
        >>> colors = memory.add_many(["red", "green", "blue"])
        >>> assert len(colors) == 3
    """
    return [self.add(name) for name in names]

get(name)

Get a hypervector by name.

Parameters:

Name Type Description Default
name str

Name of the symbol to retrieve.

 required

Returns:

Type Description
AbstractHypervector

The hypervector associated with the symbol.

Raises:

Type Description
KeyError

If the symbol does not exist in memory.
Example

memory = VSAMemory(model) memory.add("dog") dog = memory.get("dog")

Source code in vsax/core/memory.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def get(self, name: str) -> AbstractHypervector:
    """Get a hypervector by name.

    Args:
        name: Name of the symbol to retrieve.

    Returns:
        The hypervector associated with the symbol.

    Raises:
        KeyError: If the symbol does not exist in memory.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add("dog")
        >>> dog = memory.get("dog")
    """
    return self._symbols[name]

__getitem__(name)

Get a hypervector by name using dictionary syntax.

Parameters:

Name Type Description Default
name str

Name of the symbol to retrieve.

 required

Returns:

Type Description
AbstractHypervector

The hypervector associated with the symbol.

Raises:

Type Description
KeyError

If the symbol does not exist in memory.
Example

memory = VSAMemory(model) memory.add("dog") dog = memory["dog"]

Source code in vsax/core/memory.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def __getitem__(self, name: str) -> AbstractHypervector:
    """Get a hypervector by name using dictionary syntax.

    Args:
        name: Name of the symbol to retrieve.

    Returns:
        The hypervector associated with the symbol.

    Raises:
        KeyError: If the symbol does not exist in memory.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add("dog")
        >>> dog = memory["dog"]
    """
    return self.get(name)

__contains__(name)

Check if a symbol exists in memory.

Parameters:

Name Type Description Default
name str

Name of the symbol to check.

 required

Returns:

Type Description
bool

True if the symbol exists, False otherwise.
Example

memory = VSAMemory(model) memory.add("dog") assert "dog" in memory assert "cat" not in memory

Source code in vsax/core/memory.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def __contains__(self, name: str) -> bool:
    """Check if a symbol exists in memory.

    Args:
        name: Name of the symbol to check.

    Returns:
        True if the symbol exists, False otherwise.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add("dog")
        >>> assert "dog" in memory
        >>> assert "cat" not in memory
    """
    return name in self._symbols

keys()

Get all symbol names in memory.

Returns:

Type Description
list[str]

List of symbol names.
Example

memory = VSAMemory(model) memory.add_many(["a", "b", "c"]) assert memory.keys() == ["a", "b", "c"]

Source code in vsax/core/memory.py 
158
159
160
161
162
163
164
165
166
167
168
169
def keys(self) -> list[str]:
    """Get all symbol names in memory.

    Returns:
        List of symbol names.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add_many(["a", "b", "c"])
        >>> assert memory.keys() == ["a", "b", "c"]
    """
    return list(self._symbols.keys())

__len__()

Get the number of symbols in memory.

Returns:

Type Description
int

Number of stored symbols.
Example

memory = VSAMemory(model) memory.add_many(["a", "b", "c"]) assert len(memory) == 3

Source code in vsax/core/memory.py 
171
172
173
174
175
176
177
178
179
180
181
182
def __len__(self) -> int:
    """Get the number of symbols in memory.

    Returns:
        Number of stored symbols.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add_many(["a", "b", "c"])
        >>> assert len(memory) == 3
    """
    return len(self._symbols)

clear()

Remove all symbols from memory.

Example

memory = VSAMemory(model) memory.add_many(["a", "b", "c"]) memory.clear() assert len(memory) == 0

Source code in vsax/core/memory.py 
184
185
186
187
188
189
190
191
192
193
194
def clear(self) -> None:
    """Remove all symbols from memory.

    Example:
        >>> memory = VSAMemory(model)
        >>> memory.add_many(["a", "b", "c"])
        >>> memory.clear()
        >>> assert len(memory) == 0
    """
    self._symbols.clear()
    self._counter = 0

__repr__()

String representation of VSAMemory.

Source code in vsax/core/memory.py 
196
197
198
def __repr__(self) -> str:
    """String representation of VSAMemory."""
    return f"VSAMemory(model={self._model.rep_cls.__name__}, symbols={len(self._symbols)})"