Hierarchical Agent Memory

Hierarchical memory architecture for single-agent systems. Replaces flat memory files with a tiered daily/weekly/monthly/yearly note structure and distillati...

Security Scan

The skill's instructions, requirements, and behavior are internally consistent with its stated purpose of providing a hierarchical on-disk memory organization for a single agent.

Purpose & Capability

The name and description describe a file-based, tiered memory system; the SKILL.md only requires creating and manipulating files under a workspace/memory hierarchy and using agent-provided search/get helpers. No unrelated credentials, binaries, or external services are requested.

Instruction Scope

Instructions explicitly tell the agent to read MEMORY.md and today's/yesterday's daily files at session start and to append/write daily/weekly/monthly/yearly notes during logging and distillation. File reads/writes are expected for this purpose, but a user should understand that the skill directs the agent to modify files in the workspace (create directories, move content, append session logs, and synthesize summaries). It also refers to agent helper calls (memory_search, memory_get) which must be trusted and present.

Install Mechanism

Instruction-only skill with no install spec and no code files. Nothing is written to disk by an installer and no external downloads or package installs are requested.

Credentials

The skill requests no environment variables, credentials, or config paths. All required actions relate directly to on-disk memory management as described.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It does instruct periodic distillation (cron/heartbeats/on-request) which implies scheduled file-write activity when run; this is consistent with its purpose but worth noting because it can lead to regular writes and updates to workspace files.

Assessment

This skill appears coherent and does what it says: it will read and write files under workspace/ (MEMORY.md and memory/{daily,weekly,monthly,yearly}). Before installing, ensure you: (1) trust the agent to modify workspace files and have backups of any important existing MEMORY.md content (the setup/triage steps suggest moving content), (2) confirm your agent environment provides the referenced helpers (memory_search, memory_get, agent-session-state) since the instructions depend on them, and (3) are comfortable with periodic distillation tasks that will create/modify many summary files. If you want to limit risk, run it in a sandboxed workspace or inspect file changes after first runs.

Agent Memory

Agents wake up fresh each session. Files are the only continuity. This skill provides a structure for writing, organizing, and retrieving memory that scales beyond a single flat file.

The Problem

A single MEMORY.md file grows until it degrades retrieval. Content in the middle of a large context window loses attention weight ("lost in the middle" effect). More files loaded at startup = more context consumed = worse salience for any single fact.

Architecture

File Hierarchy

workspace/
├── MEMORY.md              # Lean index — project state, key decisions, cross-refs
├── memory/
│   ├── daily/
│   │   └── YYYY-MM-DD.md  # Raw logs: what happened, decisions made, open threads
│   ├── weekly/
│   │   └── YYYY-WNN.md    # ISO week summaries, synthesized from daily notes
│   ├── monthly/
│   │   └── YYYY-MM.md     # Month summaries, synthesized from weekly notes
│   └── yearly/
│       └── YYYY.md        # Year summaries, synthesized from monthly notes

Principles

1. MEMORY.md stays lean. It is an index, not a journal. Project names, statuses, and pointers to detail files. Target: under 3KB.
2. Daily notes are raw. Log everything worth remembering: sessions, decisions, work done, open threads. Timestamped entries.
3. Higher tiers are synthesized. Weekly notes distill from daily. Monthly from weekly. Each tier drops detail and keeps patterns.
4. Lazy load, don't dump. At session start, load only today + yesterday daily notes and the lean MEMORY.md. Use memory_search for anything else. Never load all files upfront.

Daily Note Format

# YYYY-MM-DD

## Session Log
- HH:MM TZ — [channel/context] — brief summary

## Decisions
- Decision X made because Y

## Open Threads
- Thing still pending

Keep logs factual and searchable. Skip filler, capture decisions.

Weekly Summary Format

# YYYY-WNN (Mon DD – Sun DD)

## Key Events
- ...

## Decisions
- ...

## Patterns
- ...

Setup

On first run, create the directory structure:

mkdir -p memory/daily memory/weekly memory/monthly memory/yearly

If MEMORY.md exists and is large (>5KB), triage it:

1. Move project detail into dedicated files under memory/projects/ or similar
2. Leave only an index with status + pointers in MEMORY.md
3. Move historical entries into the appropriate memory/daily/ files by date

Session Startup

Before responding to the user:

1. Read MEMORY.md (lean index)
2. Read memory/daily/YYYY-MM-DD.md for today and yesterday
3. That's it. Use memory_search for anything older or deeper.

Do not load weekly/monthly/yearly files at startup. They exist for synthesis and search, not for routine context loading.

Session Logging

At the start of any meaningful session, append to memory/daily/YYYY-MM-DD.md:

## Session Log
- HH:MM TZ — [context] — brief summary of what was discussed/done

At session end (or periodically during long sessions), append:

• Work completed
• Decisions made
• Open threads

Distillation

Distillation moves knowledge up the hierarchy. Run it periodically (during heartbeats, cron, or on request).

Daily → MEMORY.md

When daily notes contain decisions, project state changes, or facts worth keeping long-term:

• Update MEMORY.md with the new state (not the history — just current status)
• Keep MEMORY.md as a living snapshot, not a changelog

Daily → Weekly (every 7 days)

1. Read the past 7 daily notes
2. Write memory/weekly/YYYY-WNN.md summarizing: key events, decisions, patterns
3. Drop detail that doesn't matter at the week level

Weekly → Monthly (end of month)

1. Read that month's weekly summaries
2. Write memory/monthly/YYYY-MM.md summarizing: themes, trajectory, significant changes
3. Drop per-week granularity

Monthly → Yearly (end of year)

Same pattern. Themes, major milestones, trajectory.

Pruning

During distillation, also prune:

• Remove outdated info from MEMORY.md (completed projects, resolved issues)
• Don't delete daily notes — they're the audit trail
• Weekly/monthly files can be updated if corrections are needed

Retrieval

When the user asks about something not in today's context:

1. memory_search first — it covers all memory files
2. If search returns a hit, use memory_get to pull the specific lines
3. If low confidence after search, say so — don't fabricate from fragments

Integration with Other Skills

• agent-session-state: Per-channel session files prevent cross-session writes to the same daily note. Use together.
• agent-provenance: Provenance headers on MEMORY.md and other long-lived files track who wrote what and when it was last reviewed.