Pattern Matrix/White Paper/M1

Problem

The information an agent has to "recall" at startup spans completely different scopes. A company's security policy is permanently valid for everyone; a user's preferences follow only that person; session progress matters only for this run; tool results expire after a single turn. Stuffing all of it into one prompt hits two walls at once: tokens blow up, or the critical information gets drowned in noise.

Hierarchical retention separates three relationships that are often collapsed into one tree. Scope determines who may see a record, functional type determines how it is used, and access tier determines retrieval cost. The agent assembles only the working set required for the current task and keeps handles to the rest.

Classification: Memory × Hierarchy

• Vertical axis · Memory: It governs what the agent stores across sessions, across users, and across projects, corresponding to the classic working / session / long-term three-tier memory division. It is the foundational pattern of the memory module.
• Horizontal axis · Hierarchy: The tiers stand in a subordinate relationship—an outer tier's settings are the defaults for inner tiers, and an inner tier can override the outer one. Data rises and falls between hot / warm / cold, which is a naturally hierarchical storage structure, not a Chain and not a Loop.

Solution and mechanics

1. Assign scope first: Use user / project / team / tenant / organization / session / turn to determine ownership, visibility, and write authority. Moving content into a hot cache must not widen its scope.
2. Classify functional type: Distinguish working, episodic, semantic, procedural, and meta-memory. They serve current work, past events, stable knowledge, verified methods, and system self-records, with different retrieval triggers.
3. Choose an access tier last: Place content in hot, warm, or cold storage according to latency, frequency, capacity, and cost. Tiers may use different backends or different indexes, TTLs, and loading policies within one backend.
4. Assemble a budgeted working set: Load stable constraints and the active goal at startup, then retrieve session, project, and long-term material on demand. Per-source budgets keep low-priority history from displacing goals, constraints, and current evidence.
5. Use multiple signals for promotion and demotion: Hit frequency measures use, not truth. Scoring should include recency, usefulness, reliability, risk, and review status. Security policy and revocation lists require hard-retention rules outside ordinary eviction.
6. Separate online reads from publication: A running agent may read live memory and write new material to a candidate store. Promotion into active project, user, or organization memory requires schema, provenance, scope, conflict, and risk checks, followed by a versioned publication step with rollback.

Applicability

• Agents reused across sessions, users, and projects: programming coaches, long-term assistants, and internal enterprise agents need to remember "who this user is, what this project is about, and where the last conversation left off."
• Multi-tenant SaaS agents: Tiering by scope naturally provides isolation—user A's preferences do not pollute user B's session, and project X's rules are not carried into project Y. Scenarios that cannot tolerate cross-tenant data leakage, such as finance, healthcare, and contract review, rely on this especially.
• Enterprise developer agents: Claude Code's multi-tier CLAUDE.md is exactly this pattern. The person who writes CLAUDE.md is acting as a memory architect, placing security rules, personal preferences, and project rules in different tiers.

Known failure modes

• Flattening separate dimensions into one tree: Scope, functional type, and access tier answer different questions. A single user/project/session hierarchy couples permission, semantics, and cache movement.
• No schema on the user tier: Letting the agent write free text such as “Xiao Li knows decorators” gradually produces multiple phrasings for the same concept and weakens retrieval. High-frequency fields should use a typed schema.
• Treating hit rate as correctness: A false memory that is used repeatedly receives a higher score and reinforces itself. Promotion needs provenance, task outcome, and review status.
• Evicting rare high-risk rules: Safety policy, compliance constraints, and revocation lists may remain unused for long periods but must be present when needed. Give them a separate retention policy.
• Designing everything as startup injection: The user and project tiers suit startup injection, the session tier suits progressive reading, and the ephemeral tier suits real-time assembly. Mixing these access patterns causes old session material to crowd out the current task as the conversation grows.
• Forcing tiering onto fully stateless scenarios: Single-shot Q&A and one-off ETL transformations do not need cross-session memory.
• Allowing runtime writes to overwrite high-level memory: An unreviewed judgment from one task can propagate across sessions. Automatic writes should enter a candidate store and become active only through an independent publication process.
• Hard-coding forgetting: Device signals, compliance records, and long-term preferences have different retention goals. Configure TTL, decay, compaction, archive, and deletion by memory type and policy.
• Eviction without a reason log: Compliance (GDPR right-to-be-forgotten) and debugging both require proving "what was deleted, why, and when." Without a log, this cannot be proven.

Verification and metrics

• Working set hit rate: The share of memory needed for reasoning that is available in the prompt. Establish a local baseline by task class and inspect missing evidence when the rate changes.
• Per-tier token share (allocated by budget): whether the tokens each tier loads into the prompt stay within budget. A tier that consistently exceeds its budget needs truncation or to be pushed down to on-demand loading.
• Cross-tier pollution events: Track whether incidental session data reaches the user tier or information crosses tenant boundaries. Treat any tenant-isolation violation as a security incident.
• False-promotion and reviewer-rejection rate: Sample records moving from candidate to active long-term memory and check for wrong scope, false facts, or low-quality summaries.
• Stale-memory use rate: Measure how often a superseded or expired version still affects a decision.
• High-risk retention completeness: Periodically inventory hard-retained material and verify that normal decay did not remove it from the usable set.
• Hit rate and latency by access tier: Observe retrieval distribution across hot, warm, and cold stores and interpret it with task outcomes.
• Total startup tokens: Compare with an unlayered history-loading baseline while verifying that critical information remains visible.

Reference implementation

MemoryRecord:
                id / kind / scope / source / valid_from / valid_to
                supersedes / trust_status / risk / retrieval_keys

            write(candidate):
                validate schema + provenance + scope + sensitive data
                detect conflict and assign candidate|accepted|rejected
                publish an accepted record as a new version

            read(task):
                enforce tenant and scope filters
                exclude expired and superseded versions
                rank by task relevance + usefulness + reliability + risk
                assemble within per-source token budgets

            retire(record):
                decay, archive, revoke, or delete by policy
                append reason + actor + timestamp to the audit log
            

Backend selection serves access behavior; it does not define memory semantics. Even when all records initially share one database, scope, kind, validity, and trust remain independent fields.

Illustrative scenario

Consider an execution-oriented payroll SaaS agent with three memory tiers. L1 holds the minimum information needed for the current step. L2 holds milestone records such as task status and the action just completed. L3 holds judgments and procedures that may be reused across tasks. The tiers cover the current step, the current task, and cross-task memory. Each has an independent token budget; L1 is assembled at runtime, and writes to L3 pass a trust check so that incidental information from one run does not become long-term memory.

Related patterns

• Progress Tracking (M3): M3 is the hottest tier within the hierarchy. The todo list is the agent's register, frequently updated and loaded on every reasoning step; it is essentially the part of the session tier dedicated to managing "where we are."
• RAG (M2): Tiering solves "how long-term known memory is loaded by scope," while RAG solves "how the massive knowledge that no scope can hold is queried on demand." Tiering manages the known; RAG manages the external.
• Failure Journal (M4) / Procedural Memory (M5): These two are dedicated partitions within the long-term memory tier—M4 stores failure cases, M5 stores successful moves. Tiering is the container; they are the contents inside it.
• Semantic Compression (perception module): When the session tier fills up with tokens, semantic compression is triggered to slim it down, which is a supporting mechanism for tiering within a single tier.
• Memory Admission (candidate): M1 defines tier boundaries; admission decides whether a candidate may enter an active tier.

Design conclusion

Hierarchical retention manages the agent's working set. Scope preserves isolation, functional type determines use, access tier controls cost, and versioned admission keeps a temporary judgment from becoming a long-term fact.