What are working, session, and long-term memory tiers?

Substrate choices answer where similarity and structure live. Layered memory answers how long a fact should survive. Working memory is the live scratchpad inside the current task. Session memory carries compact state across tasks in one sitting. Long-term memory is what should still help next week—preferences, durable decisions, consolidated lessons. Mixing those lifetimes in one undifferentiated Engram dump recreates the ranking sludge problem with a calendar flavor: yesterday’s half-finished plan outranks a standing preference because it is newer and wordier.

This chapter defines the three tiers, shows how promotion and eviction keep them honest, maps long-term (and optionally session) storage onto Weaviate Engram scopes and fetches, and walks a tapestry warping desk through a cascade retrieve. After tiers by volatility comes a caution against locking the whole product to one rigid cognitive taxonomy.

What is each tier responsible for, and what must it refuse to hold?

Working memory is whatever must be in the prompt right now to finish the active step: the latest user message, the last tool payload, the partial plan. Its lifetime is minutes. When the task ends, most of it should vanish. If you persist every tool trace into long-term search, hybrid retrieval will keep resurfacing scaffolding the user never asked to remember.

Session memory bridges tasks inside one sitting. The user named a warp project in task one and now says “use the same sett.” Working memory of task three does not contain that name unless you carry a session digest forward. Session state is structured and small: active project id, decisions already taken today, open questions. It should expire when the conversation closes or after a short TTL. It is not a second copy of the entire transcript.

Long-term memory is cross-session continuity. In this stack, Weaviate Engram is the default home: user-scoped preferences, standing constraints, consolidated summaries, lessons worth recalling next month. Organizational SOPs still sit in a separate collection plane. Long-term Engram should refuse ephemeral chatter, rejected experiments, and raw multi-turn transcripts that never passed a write gate. If a note cannot survive the question “will this still help on a cold start next month,” it does not belong in the long-term tier.

How do promotion and eviction keep the layers from collapsing?

Tiers without movement rules become four labels on one pile. Promotion is the upward path. A working-memory fact becomes session state when later tasks in the sitting will need it—project nicknames, chosen options, mid-session corrections. Session state becomes long-term Engram content only when it is durable: a preference stated as standing policy, a decision the user wants honored next visit, a corrected fact that supersedes an older memory. Eviction is the downward or outward path. Working scratch clears on task end. Session digests expire. Long-term notes soft-forget, supersede, or archive under the maintenance jobs from earlier chapters.

Retrieval should cascade with priority, not with a single blended top-k over all lifetimes. Read working memory first because it is authoritative for the live step. Merge in session digest next for sitting continuity. Query Engram for long-term personalization when the turn needs history beyond today. Fetch pinned long-term summary ids with bounded retrieval when you already know which preference block matters. Only then, if required, hit organizational collections or graphs. That order prevents a stale long-term anecdote from overriding a correction the user made ten minutes ago in session state.

Token budget is part of the architecture. Working memory gets the largest immediate share because the model must act now. Session digests stay short on purpose. Long-term Engram contributes a handful of high-signal hits, not the whole user corpus. Layering is compression discipline as much as storage topology. Teams that skip eviction eventually “fix” retrieval by raising limits, which only moves the sludge further down the prompt.

How should Engram map onto session and long-term without swallowing working memory?

Keep working memory out of Engram. Hold it in process state or a short-lived store keyed by run id. For session memory, either use an application cache with TTL or an Engram group such as session keyed by session_id in properties—with aggressive expiry and a ban on treating session notes as permanent personalization. For long-term, use personalization (or equivalent) under user_id, write only through the durable gate, and prefer summaries plus supersession over endless episodic clones.

A practical pattern is dual long-term shapes inside Engram: episodic notes with timestamps for “what happened,” and semantic preference memories that consolidation jobs promote from those episodes. Search can bias recent episodic hits for “what did we try yesterday” while pinned semantic memories answer “who is this user.” FetchRetrieval keeps the pinned block cheap and stable. HybridRetrieval explores when the query is open-ended.

Do not let organizational documents enter the session tier as writable memory. Cite them from the collection plane each time policy matters, or cache a content hash of the in-force SOP version in session state so you know what was consulted—without turning the SOP text into a user memory. Session state may remember which rule version you used; it must not become a shadow policy store that drifts from the source.

What does the cascade look like at a tapestry warping desk?

A studio assistant helps a weaver at a warping desk across several tasks in one afternoon, then again next week. Working memory holds the current bout reckoning. Session memory holds today’s chosen sett and colorway nickname. Long-term Engram holds how Noa likes draft notes formatted and which looms they prefer for sample warps. Scenario id: tapestry-warping-desk-5.

from weaviate.engram import EngramClient
from weaviate.engram.retrieval import HybridRetrieval, FetchRetrieval

engram = EngramClient()
user_id = "weaver-noa"
scenario = "tapestry-warping-desk-5"

# Working: in-process only
working = {
    "task": "wind_section_3",
    "last_tool": {"ends_wound": 120, "target": 360},
}

# Session: TTL'd digest (cache or Engram group=session)
session = {
    "session_id": "sit-2026-09-05",
    "project_nickname": "river-sett",
    "sett_epi": 12,
    "colorway": "slate-warp-a",
}

# Long-term: Engram personalization
long_term = engram.memories.search(
    query="draft note format loom preference sample warps",
    retrieval=HybridRetrieval(alpha=0.5, limit=5),
    scopes={"user_id": user_id, "properties": {"group": "personalization"}},
)
pinned = engram.memories.get(
    memory_id="mem_noa_draft_note_style_v3",
    retrieval=FetchRetrieval(),
)

def assemble_prompt():
    return {
        "scenario": scenario,
        "working": working,
        "session": session,
        "long_term": [m.content for m in long_term]
        + ([pinned.content] if pinned else []),
        "priority": "working overrides session; session overrides stale long-term on same fact",
    }

def end_of_sitting_promote(durable_preference: str | None):
    if not durable_preference:
        return
    engram.memories.add(
        content=durable_preference,
        scopes={
            "user_id": user_id,
            "properties": {"group": "personalization", "scenario": scenario},
        },
    )

During the sitting, “same sett” resolves from session, not from a long-term guess. Next week, session is gone; Engram still knows Noa’s note style and loom preference. The half-finished end count from working memory never becomes a permanent “memory” that confuses future warps. That separation is the entire point of layering by lifetime.

Layered memory keeps volatility honest: working for the live step, session for the sitting, Engram for durable personalization—with promotion, eviction, and cascade reads so lifetimes do not collapse into one noisy index. Our next chapter, How do you design adaptable memory models?, argues for keeping these layers flexible instead of freezing one academic taxonomy into the product forever.