Layered Memory Architecture

Build cheap, truthful long-term memory for agents with a layered architecture instead of a memory blob. Design, explain, audit, or improve a system that sepa...

Security Scan

This is an instruction-only skill consisting of design docs and patterns for layered agent memory; its claims, required resources, and runtime instructions are internally consistent and proportional.

Purpose & Capability

The name and description (layered memory architecture) match the included SKILL.md and reference documents. There are no unrelated requirements (no env vars, binaries, or install steps) and all referenced materials are documentation for designing or migrating memory systems.

Instruction Scope

The runtime instructions are purely prescriptive guidance about classification, layering, promotion/demotion, retrieval order, and audit practices. They do not tell the agent to read arbitrary system files, access credentials, call external endpoints, or transmit data. The skill only references internal document files bundled with the skill.

Install Mechanism

There is no install spec and no code files; this is instruction-only. No downloads, package installs, or extracts are declared, so nothing is written to disk by an installer.

Credentials

The skill declares no required environment variables, credentials, or config paths. That is proportionate for a documentation/design skill. There are no hidden references to external secrets in the instructions or bundled references.

Persistence & Privilege

The skill does not request persistent or elevated privileges (always is false). It does not modify other skills or system-wide settings in the documentation. Autonomous invocation is allowed by default on the platform, but that is normal and not excessive here given the skill's benign content.

Scan Findings in Context

[no-findings] expected: The regex-based scanner had no code files to analyze; this is an instruction-only skill composed of documentation files, so the absence of code findings is expected.

Assessment

This skill is documentation and guidance for designing layered memory systems and appears coherent. Before you adopt it operationally, consider: 1) how you will implement the storage layer (databases, vector stores) — that implementation will need access controls and credentials and is where real risk lives; 2) avoid automations that auto-promote summaries into canon without human review (the docs warn about this); and 3) if you or a developer implements helpers/automation based on these patterns, review that code/install process for network calls, secret usage, or persistent installs. In short: the skill content is safe and consistent, but any concrete implementation built from it should be audited separately for credentials, network access, and persistence behaviors.

Memory Architecture

Design memory as a system, not a bucket.

Core stance

Optimize for:

1. truthful retrieval
2. low token cost
3. clear boundaries
4. maintainable long-horizon continuity
5. project isolation where needed

Do not default to "store more and search later." First decide what kind of memory something is.

The five-layer model

Use these layers consistently:

1. Hot canon

   • Small, frequently loaded, cross-session truths.
   • Identity, preferences, standing doctrine, current priorities, compact cross-project lessons.
   • Keep it aggressively bounded.

2. Durable topic doctrine

   • Stable architecture notes, decisions, playbooks, operating rules, and domain context.
   • More detailed than hot canon, but still curated.

3. Project-scoped working memory

   • Raw or evolving material tied to one initiative.
   • Research notes, migration plans, transcripts, experiment outputs, snapshots.
   • Promote only distilled lessons upward.

4. Episodic logs

   • What happened today or in a specific work session.
   • Events, observations, intermediate findings, next steps.
   • Default landing zone for fresh information.

5. Generated live summaries

   • Rebuildable operator read models for current state.
   • Queue views, alerts, health snapshots, status summaries, compact log digests.
   • Treat as derived state, not durable canon.

Memory classification rule

Before writing memory, classify the item:

• Cross-cutting durable truth → hot canon
• Durable but detailed rule / doctrine / architecture → topic doc
• Project-bound raw or changing context → project memory
• Fresh event or observation → episodic log
• Current operational snapshot → generated summary only

If uncertain, bias downward:

• daily/project first
• promote later
• avoid prematurely canonizing noise

Promotion / demotion flow

Use this ladder:

• fresh event → episodic log or project artifact
• repeated / stable lesson → topic doc
• hottest compact cross-cutting truth → hot canon
• volatile state → generated summary
• stale bulky detail → keep in project/archive, not hot canon

Truthfulness rules

Never let memory blur these categories:

• durable truth
• project-specific context
• current live status
• historical event log
• derived summary

Do not promote temporary red/yellow/green conditions, queue counts, disk snapshots, or stale alerts into canon unless they reveal a durable rule.

Retrieval policy

Retrieve in this order:

1. hot canon
2. compact index/selector
3. relevant topic docs
4. project memory only if the task is project-specific
5. generated summaries before raw logs for live-state questions
6. raw logs only when summary is insufficient or needs verification
7. episodic logs only when recent event history matters

The goal is not maximum recall. The goal is the right recall.

Comparison frame

When comparing layered memory against generic persistent-memory tools, use this lens:

Generic persistent-memory systems usually optimize for:

• saving more facts
• retrieving facts later
• one-store convenience
• simple demo value

Layered memory systems optimize for:

• memory boundaries
• retrieval trust
• token hygiene
• long-term maintainability
• project isolation
• separation of canon vs live state

Use this summary line:

• "Persistent memory is a feature. Memory architecture is a system."

If needed, read references/scorecard.md for a compact comparison rubric.

Anti-patterns

Flag these quickly:

• one giant memory blob with weak boundaries
• logs and durable truths mixed together
• live status stored as long-term canon
• duplicated facts across layers without summary/detail distinction
• always-append workflows with no dedupe or demotion
• semantic search over stale and current facts without authority separation
• project details contaminating global memory

Output patterns

For comparisons or teaching material, prefer one of these structures:

• scorecard: category-by-category ratings and winners
• analogy: bucket/backpack vs compartments/ship
• thesis: "remember more" vs "remember the right things in the right places"
• migration plan: how to move from blob memory to layered memory

Use bundled references only when needed

• Read references/scorecard.md when preparing a digestible comparison, talk track, or publishable rubric.
• Read references/migration-pattern.md when helping someone convert an existing persistent-memory setup into a layered one.
• Read references/layout-template.md when the user wants a concrete starter structure for implementing layered memory in a workspace.
• Read references/audit-checklist.md when the user wants a repeatable audit of an existing memory setup instead of a high-level philosophy discussion.
• Read references/classifier-pattern.md when the user wants a lightweight routing rule for deciding where fresh information belongs.
• Read references/promotion-trigger-pattern.md when the user wants a safe promotion model for moving notes upward over time.
• Read references/summary-generator-pattern.md when the user wants live-state summaries that remain derived and rebuildable rather than polluting canon.

Reliability rules

• Prefer the smallest useful memory change over a total rewrite.
• Do not invent hidden automation or magical persistence claims.
• Keep implementation recommendations explicit about which layer is authoritative.
• If offering migration advice, separate immediate low-risk fixes from optional later refinements.
• If the user wants operational memory, keep generated summaries distinct from canon.
• Treat lightweight automations as helpers that nominate or summarize, not as silent canon-writing authorities.

Keep the explanation compact unless the user explicitly wants a deep comparison.