MemoryStore

Unified memory interface across all three tiers.

Usage

Source

MemoryStore()

Provides a single API for storing and retrieving memories, with automatic tier selection and cross-tier search.

Parameters

short_term_max_entries: int = 100

Maximum entries for the short-term tier (default 100).

short_term_default_ttl: float = 3600.0

Default TTL for short-term entries in seconds (default 3600).

long_term_path: str | Path = ":memory:"
Path to the SQLite database for long-term storage. Use ":memory:" for testing (default).

Examples

import talk_box as tb

store = tb.MemoryStore(long_term_path="my_bot.db")

# Store in different tiers
store.remember("user_query", "What is Python?", tier=tb.MemoryTier.WORKING)
store.remember("session_topic", "Python basics", tier=tb.MemoryTier.SHORT_TERM)
store.remember("user_pref", {"theme": "dark"}, tier=tb.MemoryTier.LONG_TERM)

# Recall from any tier
store.recall("user_query")       # Searches working first
store.recall("user_pref")        # Found in long-term

# Search across tiers
store.search(tags=["user"])

store.close()

Methods

Name Description
close() Close underlying resources (SQLite connection).
forget() Remove a memory from the specified tier, or from all tiers.
recall() Retrieve a memory, searching tiers if no specific tier is given.
remember() Store a memory in the specified tier.
search() Search memories across tiers.

close()

Close underlying resources (SQLite connection).

Usage

Source

close()

forget()

Remove a memory from the specified tier, or from all tiers.

Usage

Source

forget(key, *, tier=None)
Parameters
key: str

The key to remove.

tier: MemoryTier | None = None
Specific tier to remove from. None removes from all tiers.
Returns
bool
True if the key was found and removed from at least one tier.

recall()

Retrieve a memory, searching tiers if no specific tier is given.

Usage

Source

recall(key, *, tier=None, default=None)

When tier is None, searches working → short-term → long-term and returns the first match found.

Parameters
key: str

The key to look up.

tier: MemoryTier | None = None

Specific tier to search. None searches all tiers.

default: Any = None
Value to return if not found in any tier.
Returns
Any
The stored value, or default if not found.

remember()

Store a memory in the specified tier.

Usage

Source

remember(
    key, value, *, tier=MemoryTier.WORKING, ttl=None, tags=(), metadata=None
)
Parameters
key: str

The key to store under.

value: Any

The value to store.

tier: MemoryTier = MemoryTier.WORKING

Which memory tier to use (default WORKING).

ttl: float | None = None

Time-to-live in seconds (only used for SHORT_TERM).

tags: tuple[str, …] = ()

Optional tags for categorization.

metadata: dict[str, Any] | None = None
Optional metadata (only used for LONG_TERM).