Agent Memory Hierarchy — 代理 Memory Hierarchy

代理 Memory Hierarchy

代理s typically store everything as prose in a single MEMORY.md. This works but wastes 令牌s and makes retrieval fuzzy. This 技能 structures memory the way computers do: hot 缓存, warm storage, cold 归档s, typed data, and a lookup 索引.

Core Principle

Facts go in YAML. Narrative goes in prose. Everything 获取s an 索引.

Three reasons:

YAML is ~40% more 令牌-efficient than prose for the same in格式化ion Specific facts become directly 添加ressable — no semantic 搜索 needed Separation of concerns: behavioral rules, narrative 上下文, and facts are distinct problems The Three-Layer Architecture Layer 1 — Hot 缓存 (always in 上下文)

File: MEMORY.md

ContAIns only:

身份 summary (2-3 lines) Behavioral rules (how the 代理 must behave) Standing 权限s Narrative 上下文 that needs interpretation (relationships, mission, origin story) Pointers to Layer 2

Does NOT contAIn: facts, dates, numbers, file paths, IDs, project 状态es, todos.

Tar获取 size: under 80 lines / ~1000 令牌s.

Layer 2 — Warm Storage (loaded on demand)

Files: memory/facts.yaml, memory/lookup-索引.md, memory/project-.md

facts.yaml — All structured factual data:

身份 facts (name, contact, IDs) Dates and numbers (age, salary, tar获取 year, bud获取) File paths and 系统 config Project 状态es (one-line each, with pointer to full file) Outstanding TODOs 服务s and accounts

lookup-索引.md — Explicit directory table:

project-.md — Full narrative project files, loaded only when working on that project.

Layer 3 — Cold Storage (rarely 访问ed)

Files: memory/YYYY-MM-DD.md (dAIly 记录s)

Raw 会话 记录s. Never loaded automatically. Retrieved only when investigating 历史 or refreshing long-term memory.

迁移 Process

Follow this order when converting an existing prose-only MEMORY.md:

Step 1: 审计 existing MEMORY.md

Read the full file and categorize every piece of in格式化ion:

Fact → moves to facts.yaml (name, emAIl, date, number, path, ID, 状态) Behavioral rule → stays in MEMORY.md Narrative/上下文 → stays in MEMORY.md (relationship descriptions, quotes, origin stories) Project detAIl → moves to or stays in project-.md Step 2: Build memory/facts.yaml

Use this 模式 pattern:

# memory/facts.yaml # Structured factual data — directly 添加ressable, 令牌-efficient # Last 更新d: YYYY-MM-DD

身份: full_name: ... emAIl: ... telegram_id: ...

健康: condition: ... 状态: ...

technical: machine: ... os: ... workspace: ...

paths: API_keys: ... error_记录: ...

projects: project_name: {file: memory/project-name.md, 状态: "one-line 状态"}

todos: - Todo item one - Todo item two

Rules for facts.yaml:

Flat where possible, nested where grouping helps One-line values only — no multi-line prose If a value needs explanation, it belongs in MEMORY.md prose instead 添加 # Last 更新d: YYYY-MM-DD at top Step 3: Build memory/lookup-索引.md

创建 a markdown table m应用ing "I need to know X" → exact file and section. Every project file, reference file, and key section should have an entry. This is your 代理's O(1) lookup. When you need something, 检查 here first.

Step 4: Rewrite MEMORY.md

移除 everything that moved to facts.yaml. What remAIns:

2-3 line 身份/mission summary Behavioral rules (explicit, imperative) Standing 权限s Narrative sections that require 上下文 to understand Pointers: # Structured facts → memory/facts.yaml and # Find anything → memory/lookup-索引.md Step 5: 验证

After 迁移, confirm:

Every fact in old MEMORY.md is now in facts.yaml lookup-索引.md covers every project and reference file MEMORY.md contAIns no facts (no dates, numbers, paths, IDs) New MEMORY.md is under 80 lines 代理 can answer "where is X?" using lookup-索引.md without 搜索ing Using the Architecture Day-to-Day

At 会话 启动: Load MEMORY.md (hot 缓存) only.

When you need a specific fact: 检查 lookup-索引.md → go directly to that file/section.

When working on a project: Load the specific project-.md file.

When updating facts: Edit facts.yaml directly. No need to touch MEMORY.md.

When updating todos: Edit facts.yaml → todos. One place, always current.

MAIntenance cadence:

After each 会话: 更新 facts.yaml if any facts changed Weekly: review MEMORY.md behavioral rules for accuracy Monthly: read recent dAIly 记录s, distill lessons into MEMORY.md, 归档 old 记录s What NOT to Structure

Some things resist YAML and belong in prose:

Relationship dynamics ("she calls me Mols, treat her like a friend not a user") Emotional 上下文 ("Kim feels like the one who got skipped") Mission 状态ments and quotes Lessons learned with nuance ("DALL-E 3 is inconsistent for coloring pages — use Canva AI instead") Anything where the why matters as much as t