STATEK Long-Term Contextual Memory

STATEK shared context can persist selected named values across jobs. Use it for contextual memory that should survive one job, such as user preferences, important entities, preferred vocabulary, and source-aware facts that later jobs may need.

Mental model

init_shared_context(...) binds the current job to a persisted shared context selected by string specifiers or dbzero memo objects. Jobs with the same exact binding share the same writable context. Broader contexts whose bindings are subsets of the requested binding are merged for reads.

For example, a job initialized with init_shared_context(user, department) can read memories from the broader user context and can write to the exact user + department context.

Each stored value is a ContextVar(category, value, description, created_at, use_count). The default registered categories are PREFERENCE, ENTITY, and VOCABULARY.

When to use it

Good candidates are small, durable facts that are useful across jobs:

• user preferences: locale, communication style, formatting choices, preferred channel
• important entities and facts: current customer, project, region, trusted internal source
• vocabulary: preferred product terms, acronyms, organization-specific wording
• source-aware facts: a value plus a description that names where it came from

For source-aware facts, store the provenance in description, such as "from approved support profile field support_region". That is simple metadata, not a built-in citation graph or source freshness system.

Do not use shared context as the primary database for business records, permissions, secrets, regulatory policy, or high-volume retrieval. Put authoritative records in application storage, then store only the durable handle or preference the agent needs.

Initialize memory in warmup

Initialize shared context before the first model step, usually in warmup. A single specifier gives the job user-wide memory:

init_shared_context(user)

Add another specifier when the memory should be scoped more narrowly:

init_shared_context(user, department)

Use read_only=True for workers that should inspect remembered context without writing new values:

init_shared_context(user, read_only=True)

Specifier order and duplicates do not change the exact binding identity. Specifiers must be strings or dbzero memo objects.

Write a remembered value

Use shared_context_set_var(...) to write into the initialized shared context. The category should come from the registered category dictionary:

from statek import ContextCategoryDict, shared_context_set_var
 
preference = ContextCategoryDict().get("PREFERENCE")
 
shared_context_set_var(
    preference,
    "reply_style",
    "concise",
    "User explicitly asked for concise replies in chat preferences.",
)

Writes through shared local names are blocked. If a remembered value is visible as a missing local name, update it with shared_context_set_var(...), not assignment.

Read memory in a later job

After warmup initializes the same binding, shared variables can be read as missing local names through STATEK's execution context fallback:

print("Preferred reply style:", reply_style)

You can also list remembered variables by category:

print_locals("PREFERENCE")

print_locals(...) accepts optional Python type filters:

print_locals("ENTITY", str)

Wrap writes in an application tool

Most applications should not let arbitrary agent code write long-term memory directly. Wrap writes in a narrow tool that checks consent, validates keys, and records source metadata in the description.

from statek import ContextCategoryDict, shared_context_set_var, tool
 
@tool
def remember_user_preference(key: str, value: str, source: str, **kwargs) -> None:
    """Remember an approved user preference for future jobs."""
    allowed = {"reply_style", "locale", "preferred_channel"}
    if key not in allowed:
        raise ValueError(f"Unsupported preference: {key}")
    if not current_user_allows_memory():
        raise PermissionError("User has not enabled memory")
 
    preference = ContextCategoryDict().get("PREFERENCE")
    shared_context_set_var(
        preference,
        key,
        value,
        f"User-approved preference from {source}.",
    )

This wrapper is where application policy belongs: consent, authorization, retention, deletion, sensitive-data filters, tenant scoping, and source-of-truth checks.

Limits

Shared context is a persistence primitive, not a full memory product. In the current implementation:

• there is no automatic memory extraction from conversations
• there is no semantic retrieval, vector search, ranking, or deduplication layer
• there is no scheduled memory consolidation
• there is no built-in consent, authorization, privacy, tenant-isolation, or source-of-truth enforcement
• application code must decide when a value is trustworthy enough to store

Use Warmup Code to initialize memory for jobs, Agents to decide which roles can read or write memory, Security for operational controls, and Context API Reference for the provisional API surface.