Adaptive Memory

Hierarchical memory management for AI agents. Three layers — daily notes, active context, and long-term memory — with periodic distillation to keep knowledge fresh and relevant.

Problem This Solves

AI agents lose context between sessions and after context compaction. Without structured memory:

• - Decisions get re-debated
• Completed work gets redone
• Lessons learned are forgotten
• Active tasks fall through the cracks

Memory Architecture

CODEBLOCK0

Layer 1: Daily Notes (memory/YYYY-MM-DD.md)

Raw log of what happened each day. Append-only, minimal editing.

CODEBLOCK1

Rules:

• - Create memory/ directory if it doesn't exist
• One file per day, named INLINECODE2
• Append throughout the day, don't restructure
• Include: decisions, discoveries, errors, context that future-you needs
• Exclude: secrets, tokens, passwords, API keys (reference file paths instead)

Layer 2: Active Context (memory/active_context.md)

Working memory — what's in progress right now. Updated as tasks start, complete, or block.

CODEBLOCK2

Rules:

• - Keep current — stale entries erode trust
• Move completed items to "Recently Completed" (prune after a few days)
• Always check this file at session start — it's the fastest way to resume context
• Any channel, any session should be able to read this and understand what's happening

Layer 3: Long-Term Memory (MEMORY.md)

Curated knowledge distilled from daily notes. The agent's permanent memory.

CODEBLOCK3

Rules:

• - This is curated, not a dump — every entry should justify its space
• Review and update periodically (see Distillation Cycle)
• Organize by topic, not by date
• No secrets or credentials — reference file paths only (e.g., "Auth: see ~/.secrets/service.env")

Optional: Channel Context (memory/channel_context/{name}.md)

For multi-channel setups (Slack, Discord, etc.), maintain per-channel summaries so context survives compaction.

CODEBLOCK4

Rules:

• - Update at natural conversation boundaries (topic complete, day change)
• Keep concise — this is a summary, not a transcript
• One file per channel

Optional: Task Tracker (memory/pending_tasks.json)

Structured tracking for tasks that must not be forgotten.

CODEBLOCK5

Valid statuses: pending, in_progress, blocked, INLINECODE11

Session Start Routine

At the beginning of every session, load context in this order:

1. 1. memory/active_context.md — what's in progress
2. memory/YYYY-MM-DD.md (today + yesterday) — recent events
3. MEMORY.md — long-term knowledge (main/private sessions only)
4. Channel context (if applicable) — INLINECODE15
5. memory/pending_tasks.json — unfinished tasks

Do not respond to messages until context is loaded. "I don't know what you're talking about" is never acceptable when the answer is in these files.

Writing Guidelines

What to Capture

Write it down	Skip it
Decisions and their reasoning	Routine operations that went smoothly
Errors and how they were fixed

Intermediate debugging steps | | Key facts about the environment | Information already in code comments | | User preferences and patterns | Temporary values that change hourly | | Lessons that prevent future mistakes | Obvious things any model would know |

Security Rules

• - Never write secrets (API keys, passwords, tokens) to memory files
• Reference paths instead: "Auth config: ~/.secrets/service.env"
• If a credential appears in chat, acknowledge it without repeating the value
• Memory files may be shared or version-controlled — treat them as semi-public

Distillation Cycle

Periodically consolidate daily notes into long-term memory. Recommended: weekly or when daily notes accumulate (3+ unprocessed files).

Four-Phase Process

Phase 1: Orient

Read MEMORY.md to understand current state. Note what's already captured.

Phase 2: Gather

Read recent daily notes (memory/YYYY-MM-DD.md) that haven't been consolidated yet.

Phase 3: Consolidate

For each daily note, extract what deserves long-term storage:

• - New systems or tools built
• Lessons learned (especially from mistakes)
• Decisions with lasting impact
• Changed preferences or workflows
• Facts about the environment that won't change soon

Add these to the appropriate section in MEMORY.md.

Phase 4: Prune

Remove from MEMORY.md:

• - Entries that are no longer relevant
• Information superseded by newer entries
• Overly detailed entries that can be summarized

Tracking Distillation

Record when distillation last ran to avoid redundant work:

In memory/heartbeat-state.json (or a similar state file):

CODEBLOCK6

Automation

Distillation can be triggered by:

• - Cron job — weekly scheduled task (recommended)
• Heartbeat — check if 48h+ since last distillation and 3+ unprocessed daily notes
• Manual — user requests "consolidate memory" or "review notes"

Integration with Session-Recall

This skill manages what gets stored. A retrieval skill like session-recall (which searches transcripts, memory files, and channel context) manages how to find it. They complement each other:

• - adaptive-memory → organizes memory into searchable layers
• session-recall → searches those layers when context is missing

Using both together provides full coverage: structured storage + intelligent retrieval.

Quick Start

1. 1. Initialize the memory directory structure:

CODEBLOCK7

1. 2. Add to your AGENTS.md or session start routine:

CODEBLOCK8

1. 3. Start logging to daily notes as you work

1. 4. Set up weekly distillation (cron, heartbeat, or manual)

The system grows organically from here.