Caches¶

ExactCache¶

memory_reuse.cache.exact.ExactCache ¶

ExactCache(backend: AbstractBackend, config: CacheConfig, stats: StatsTracker)

Hash-based cache for exact-match lookups (e.g. LLM responses).

Entries are keyed by the SHA-256 hash of the input key_parts list, scoped under the configured prefix, scope, and scope-ID. Values are gzip-compressed JSON so large language-model responses are stored efficiently.

This class is intentionally low-level; most users interact with it through the higher-level :class:~memory_reuse.core.MemoryCache API or the LangGraph decorators.

Parameters:

Name	Type	Description	Default
`backend`	`AbstractBackend`	The storage backend to use.	required
`config`	`CacheConfig`	Cache configuration.	required
`stats`	`StatsTracker`	Statistics tracker shared with the parent :class:`MemoryCache`.	required

Example::

cache = ExactCache(backend, config, stats)
result = await cache.get(["prompt", "v1"], scope="global", scope_id=None)
if result is None:
    result = call_llm(...)
    await cache.set(["prompt", "v1"], result, scope="global",
                    scope_id=None, ttl=3600)

get `async` ¶

get(key_parts: list, scope: str, scope_id: str | None) -> Any | None

Look up a cached value by its key parts.

Parameters:

Name	Type	Description	Default
`key_parts`	`list`	Ordered list of values that together identify the cached item. These are JSON-serialised and hashed.	required
`scope`	`str`	Cache scope — `"global"`, `"user"`, or `"session"`.	required
`scope_id`	`str \| None`	User ID or session ID. Required for non-global scopes.	required

Returns:

Type	Description
`Any \| None`	The cached value, or `None` on a cache miss.

Raises:

Type	Description
`ScopeViolationError`	If `scope` requires a `scope_id` but none is provided.

set `async` ¶

set(key_parts: list, value: Any, scope: str, scope_id: str | None, ttl: int | None = None) -> None

Store a value in the cache.

Parameters:

Name	Type	Description	Default
`key_parts`	`list`	Ordered list of values identifying the cached item.	required
`value`	`Any`	The value to cache. Must be JSON-serialisable.	required
`scope`	`str`	Cache scope.	required
`scope_id`	`str \| None`	User or session identifier for non-global scopes.	required
`ttl`	`int \| None`	Time-to-live in seconds. Falls back to :attr:`~memory_reuse.config.CacheConfig.default_ttl` when `None`.	`None`

Raises:

Type	Description
`ScopeViolationError`	If `scope` requires a `scope_id` but none is provided.

invalidate `async` ¶

invalidate(key_parts: list, scope: str, scope_id: str | None) -> None

Remove a specific cache entry.

Parameters:

Name	Type	Description	Default
`key_parts`	`list`	Key parts that identify the entry to remove.	required
`scope`	`str`	Cache scope.	required
`scope_id`	`str \| None`	User or session identifier for non-global scopes.	required

Raises:

Type	Description
`ScopeViolationError`	If `scope` requires a `scope_id` but none is provided.

ToolCache¶

memory_reuse.cache.tool.ToolCache ¶

ToolCache(backend: AbstractBackend, config: CacheConfig, stats: StatsTracker)

Cache for tool/function call results, keyed by tool name and arguments.

Unlike :class:~memory_reuse.cache.exact.ExactCache, every set operation requires an explicit TTL — tool outputs are typically time-sensitive (API responses, database queries) and should not be cached indefinitely.

Parameters:

Name	Type	Description	Default
`backend`	`AbstractBackend`	Storage backend.	required
`config`	`CacheConfig`	Cache configuration.	required
`stats`	`StatsTracker`	Shared statistics tracker.	required

Example::

tool_cache = ToolCache(backend, config, stats)
result = await tool_cache.get("search_web", {"query": "AI news"},
                               scope="user", scope_id="alice")
if result is None:
    result = search_web(query="AI news")
    await tool_cache.set("search_web", {"query": "AI news"},
                          result, scope="user", scope_id="alice", ttl=120)

get `async` ¶

get(tool_name: str, args: dict, scope: str, scope_id: str | None) -> Any | None

Look up a cached tool result.

Parameters:

Name	Type	Description	Default
`tool_name`	`str`	The name of the tool/function (used as part of the key).	required
`args`	`dict`	The arguments passed to the tool. Must be JSON-serialisable.	required
`scope`	`str`	Cache scope — `"global"`, `"user"`, or `"session"`.	required
`scope_id`	`str \| None`	User ID or session ID for non-global scopes.	required

Returns:

Type	Description
`Any \| None`	The cached return value, or `None` on a miss.

Raises:

Type	Description
`ScopeViolationError`	If a non-global scope is requested without a `scope_id`.

set `async` ¶

set(tool_name: str, args: dict, value: Any, scope: str, scope_id: str | None, ttl: int) -> None

Cache a tool result.

Parameters:

Name	Type	Description	Default
`tool_name`	`str`	Name of the tool/function.	required
`args`	`dict`	Arguments the tool was called with.	required
`value`	`Any`	Return value to cache. Must be JSON-serialisable.	required
`scope`	`str`	Cache scope.	required
`scope_id`	`str \| None`	User or session identifier for non-global scopes.	required
`ttl`	`int`	Time-to-live in seconds. Must be a positive integer.	required

Raises:

Type	Description
`InvalidTTLError`	If `ttl` is not a positive integer.
`ScopeViolationError`	If a non-global scope is requested without a `scope_id`.

SemanticCache¶

memory_reuse.cache.semantic.SemanticCache ¶

SemanticCache(index: VectorIndex, embedder: EmbeddingProvider, config: CacheConfig, stats: StatsTracker)

Similarity-based cache backed by a :class:VectorIndex.

On :meth:get, the query text is embedded, the scope's namespace is searched for the single closest stored vector, and the associated value is returned when its similarity score is at or above the effective threshold. On :meth:set, the query text is embedded (or a precomputed embedding is reused) and stored alongside the value in the scope's namespace.

Parameters:

Name	Type	Description	Default
`index`	`VectorIndex`	The vector index used to store and search embeddings.	required
`embedder`	`EmbeddingProvider`	The embedding provider that turns query text into vectors.	required
`config`	`CacheConfig`	Cache configuration. Supplies the default `similarity_threshold` and `default_ttl`.	required
`stats`	`StatsTracker`	Statistics tracker shared with the parent :class:`~memory_reuse.core.MemoryCache`.	required

Example::

cache = SemanticCache(index, embedder, config, stats)
await cache.set("What is 128 times 47?", 6016, scope="global",
                scope_id=None)
# A reworded but equivalent query hits the cache:
result = await cache.get("What is 128 multiplied by 47?",
                         scope="global", scope_id=None)

get `async` ¶

get(query_text: str, scope: str, scope_id: str | None, threshold: float | None = None) -> Any | None

Look up a cached value by semantic similarity to query_text.

Embeds the query, searches the scope's namespace for the closest stored vector, and returns its value when the best match's similarity score is at or above the effective threshold.

Parameters:

Name	Type	Description	Default
`query_text`	`str`	The natural-language query to match semantically.	required
`scope`	`str`	Cache scope — `"global"`, `"user"`, or `"session"`.	required
`scope_id`	`str \| None`	User ID or session ID. Required for non-global scopes.	required
`threshold`	`float \| None`	Optional per-call similarity threshold overriding :attr:`~memory_reuse.config.CacheConfig.similarity_threshold`. Must lie in `[0.0, 1.0]`.	`None`

Returns:

Type	Description
`Any \| None`	The cached value of the best match at or above the effective
`Any \| None`	threshold, or `None` on a miss.

Raises:

Type	Description
`ScopeViolationError`	If `scope` requires a `scope_id` but none is provided.

set `async` ¶

set(query_text: str, value: Any, scope: str, scope_id: str | None, ttl: int | None = None, precomputed_embedding: list[float] | None = None) -> None

Store a query embedding and its value in the scope's namespace.

Parameters:

Name	Type	Description	Default
`query_text`	`str`	The natural-language query whose embedding is stored.	required
`value`	`Any`	The value to cache. Must be JSON-serialisable.	required
`scope`	`str`	Cache scope — `"global"`, `"user"`, or `"session"`.	required
`scope_id`	`str \| None`	User or session identifier for non-global scopes.	required
`ttl`	`int \| None`	Time-to-live in seconds. Falls back to :attr:`~memory_reuse.config.CacheConfig.default_ttl` when `None`.	`None`
`precomputed_embedding`	`list[float] \| None`	An embedding for `query_text` computed earlier in the same lookup cycle, reused to avoid embedding the same text twice. When `None` the query is embedded here.	`None`

Raises:

Type	Description
`ScopeViolationError`	If `scope` requires a `scope_id` but none is provided.

Caches¶

ExactCache¶

memory_reuse.cache.exact.ExactCache ¶

get async ¶

set async ¶

invalidate async ¶

ToolCache¶

memory_reuse.cache.tool.ToolCache ¶

get async ¶

set async ¶

SemanticCache¶

memory_reuse.cache.semantic.SemanticCache ¶

get async ¶

set async ¶

get `async` ¶

set `async` ¶

invalidate `async` ¶

get `async` ¶

set `async` ¶

get `async` ¶

set `async` ¶