Hui Yi — Forgetting-aware Cold Memory

Archive low-frequency, high-value knowledge, then resurface it only when it is both relevant now and at risk of being forgotten.

What this skill manages

Hui Yi manages the cold layer, not the whole memory stack.

Memory layers:

• - Active: current chat and current task
• Warm: recent daily files and near-term context
• Cold: durable low-frequency knowledge in INLINECODE0
• Dormant: archived items that should rarely surface unless strongly triggered

Use Hui Yi for:

• - archiving reusable lessons, background, and stable historical context
• recalling older context that would materially improve the current answer
• cooling daily notes into cold memory
• maintaining cold-memory quality, review timing, and retrieval metadata

Do not use Hui Yi for:

• - today's transient notes → INLINECODE1
• high-frequency project or personal facts → INLINECODE2
• tool paths, setup quirks, machine notes → INLINECODE3
• fresh mistakes or unvalidated lessons → INLINECODE4

Core model

The unit is a memory unit, not a raw keyword.
A memory unit can be a reusable lesson, decision, fact, troubleshooting result, or durable background note.

Do not rank memories by word frequency alone.
Use a blend of:

• - semantic relevance
• forgetting risk
• importance
• cross-session reuse
• recall feedback

Working principle:

CODEBLOCK0

Memory metadata

Cold notes remain Markdown, but Hui Yi expects metadata like:

• - Importance: high | medium | low
• INLINECODE6: hot | warm | cold | dormant
• INLINECODE7 — last time this note appeared in a conversation or task
• INLINECODE8 — last time the note was explicitly reviewed for recall quality
• INLINECODE9 — scheduled date for the next spaced review
• INLINECODE10

- interval_days — current review interval (starts at 1, grows with each success)
- review_count
- review_success
- review_fail

• - Confidence — reliability of the note's content (high | medium | low)
• INLINECODE16 — last time the content was confirmed still accurate and current.

This is NOT updated during recall feedback; only update it when you re-verify the
underlying information against source of truth.

• - INLINECODE17

States:

• - hot: recently reinforced, okay to inject when useful
• warm: good prompted-recall candidate
• cold: preserved, lower urgency
• dormant: keep archived, surface only with a strong trigger

Recall rules

Prefer active recall over passive dumping.
Good pattern:

• - “You previously touched on X. Want me to pull that thread back in?”

Avoid:

• - long unsolicited note dumps
• surfacing weakly related archive material
• recalling based on one noisy keyword match

When retrieving:

1. 1. Check current conversation first.
2. Check warm memory / MEMORY.md / TOOLS.md / .learnings/ when appropriate.
3. Use cold memory only when archival context would materially help.
4. Open the fewest notes possible, ideally 1 and no more than 3.
5. Summarize, do not paste raw notes unless asked.
6. Log meaningful cold-memory retrievals in memory/cold/retrieval-log.md.

Requirements

Python 3.10+ (X | Y union-type syntax used throughout the helper scripts).

First-time setup

If memory/cold/ does not exist, bootstrap it:

1. 1. Create memory/cold/ directory.
2. Create memory/cold/index.md with header # Cold Memory Index.
3. Create memory/cold/tags.json:

   { "_meta": { "version": 4 }, "notes": [] }
   

1. 4. Copy references/note-template.md → INLINECODE29

(cold-memory-schema.md is the full schema reference; keep it separate from _template.md).

1. 5. Create memory/cold/retrieval-log.md — just the header line:

   # Retrieval Log
   

The review.py feedback and review.py session commands append rows automatically.

1. 6. Optional — timed recall scheduler:

CODEBLOCK3

Storage layout

CODEBLOCK4

Script roles

• - create.py --title "...": create a new note with Ebbinghaus defaults (interval_days: 1, next_review: tomorrow)
• INLINECODE38: check all notes against the schema; cross-validate tags.json file references
• INLINECODE39: search cold-memory metadata by keyword/query
• INLINECODE40: also search note file bodies (not just metadata)
• INLINECODE41: rebuild index.md and tags.json from note files
• INLINECODE44: decay stale notes; --rebuild syncs tags.json in one step
• INLINECODE46: scan daily notes and update heartbeat cold-memory stats
• INLINECODE47: list notes due for review
• INLINECODE48: interactive batch review — presents each due note's TL;DR, collects y/n/s/q, applies Ebbinghaus intervals, handles graduation
• INLINECODE49: rank resurfacing candidates using a short topic query
• INLINECODE50 / --stdin: rank resurfacing candidates using richer context
• INLINECODE52: single-note feedback; <note> accepts slug, title, or keywords
• INLINECODE54: timed-recall selector driven by schedule config with cooldown, dedupe, and quiet-hours filters
• INLINECODE55: isolated end-to-end smoke test that bootstraps a temp cold-memory root and runs the core scripts in sequence

Scheduler setup

INLINECODE56 reads memory/cold/schedule.json. To enable it:

CODEBLOCK5

The example config runs a daily evening review at 21:00, surfaces one high-importance note, and applies quiet hours from 22:30 to 08:00.

Important:

• - --schedule-id means “run this schedule's filters now”, not “force a candidate for preview”
• INLINECODE59 is the explicit debug mode. It bypasses due, importance, allowed_states, cooldown, and relevance-required gating so you can inspect candidate ranking for that schedule

Review cadence

Default ladder for notes that merit reinforcement:

• - creation
• +1 day
• +3 days
• +7 days
• +14 days
• +30 days

After that:

• - helpful recall → extend interval
• unhelpful recall → shorten interval or cool further
• high-importance notes should degrade more slowly than low-importance notes

Archiving rules

Archive only if at least one is true:

• - it will still matter after 30 days
• it captures a reusable lesson or workflow
• it would materially improve a future answer or decision
• the user explicitly wants it preserved

Before archiving, route elsewhere if it belongs in:

• - INLINECODE60
• INLINECODE61
• INLINECODE62
• INLINECODE63
• INLINECODE64 / INLINECODE65

Never store secrets, tokens, or passwords in cold memory.

Maintenance rules

During maintenance:

• - merge overlapping notes
• sharpen summaries, triggers, and semantic context
• demote stale or noisy notes
• review retrieval-log.md for:

- notes never recalled
- unmatched queries
- unhelpful recalls
- repeatedly useful recalls

Favor a smaller, sharper archive over a large fuzzy one.

Error handling

• - missing memory/cold/ → bootstrap it
• missing or malformed index.md / tags.json → rebuild with INLINECODE70
• missing retrieval-log.md → recreate standard header
• missing heartbeat-state.json → create with top-level INLINECODE73
• dangling note path in metadata → repair index / tags
• noisy resurfacing → tighten thresholds before adding more notes
• unsure where content belongs → ask the user

Development sanity check

Before shipping script changes, run:

CODEBLOCK6

This boots an isolated temporary cold-memory tree and exercises create, validate, search, resurface, feedback, decay, cool, and scheduler.

References

Read only when needed:

• - references/cold-memory-schema.md → note/index/tags structure
• INLINECODE75 → concrete note examples
• INLINECODE76 → cooling workflow
• INLINECODE77 → trigger modes, heartbeat/cron integration, scheduler boundary, preview vs normal mode

Core rule:

archive less, but archive better. recall less, but recall at the right time.

Bridge (桥接层)

INLINECODE78 是一个轻量桥接层，用于在调度 (scheduler.py) 与实际投递之间完成筛选、去重、频控等策略。默认配置位于 skills/hui-yi/bridge/config.example.json，其中已设置 statePath、outputPath 指向 bridge 目录。

关键功能

• - 统一配置：config.example.json 包含 deliveryPolicy（maxCandidates、minScore、globalCooldownHours、perScheduleCooldownHours、maxDeliveriesPerDay、quietHours 等）。
• 投递模式：logOnly（默认，仅记录返回 JSON），stdout（打印），file（写入 deliveries.log），message（占位，后续可接 OpenClaw 消息工具）。
• dry‑run / preview：--dry-run 或 dryRun:true 只输出结果，不修改状态或投递。
• 状态持久化：bridge-state.json 记录上一次运行时间、已投递记录，以实现去重与频控。

使用示例

CODEBLOCK7

如需实际向用户发送消息，请将 delivery.mode 改为 message 并在后续集成中使用 OpenClaw message API。