adaptive-memory

# 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 ``` memory/ ├── YYYY-MM-DD.md # Daily notes (raw, append-only) ├── active_context.md # Working memory (current tasks, blockers) ├── channel_context/ # Per-channel conversation summaries (optional) │ └── {channel-name}.md └── pending_tasks.json # Task tracker (structured) MEMORY.md # Long-term memory (curated, distilled) ``` ### Layer 1: Daily Notes (`memory/YYYY-MM-DD.md`) Raw log of what happened each day. Append-only, minimal editing. ```markdown # 2026-04-01 ## Tasks - Implemented login flow for project X - Fixed timezone bug in cron scheduler ## Decisions - Chose SQLite over JSON for data storage (performance at scale) - API rate limit: 100 req/min with exponential backoff ## Learned - Library Y requires v3+ for async support - Browser cookies are not shared across profiles ## Blockers - Waiting on API key approval from service Z ``` **Rules:** - Create `memory/` directory if it doesn't exist - One file per day, named `YYYY-MM-DD.md` - 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. ```markdown # Active Context ## In Progress - **Project X login flow**: OAuth integration, 70% complete - Next: token refresh logic ## Blocked / Waiting - **API key for service Z**: Requested 2026-03-30, awaiting approval ## Recently Completed - **Timezone fix**: Deployed, cron jobs now fire correctly (2026-04-01) ``` **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. ```markdown # Long-Term Memory ## Systems Built - **Data pipeline**: SQLite-based, runs daily at 6 AM, stores in project.db - **Monitoring**: 3-tier alert system (info → warning → critical) ## Lessons Learned 1. SQLite > JSON for anything over 100 records 2. Always set explicit timeouts on HTTP requests 3. Browser automation: check for virtual scroll before scraping ## Key Decisions - Chose framework A over B (reason: better async support, MIT license) - API integration uses webhook push, not polling ``` **Rules:** - This is curated, not a dump — every entry should justify its space - Review and update periodically (see [Distillation Cycle](#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. ```markdown # channel-name ## Current Topics - Discussing migration plan for database X - Reviewing PR #42 ## Recent Decisions - Approved new CI pipeline config (2026-04-01) ## Unresolved - Performance regression in endpoint /api/users — investigating ``` **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. ```json { "lastUpdated": "2026-04-01T10:00:00Z", "tasks": [ { "id": "unique-id", "title": "Short description", "status": "in_progress", "priority": "high", "createdAt": "2026-04-01T09:00:00Z", "note": "Additional context" } ] } ``` Valid statuses: `pending`, `in_progress`, `blocked`, `done` ## Session Start Routine At the beginning of every session, load context in this order: 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) — `memory/channel_context/{name}.md` 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): ```json { "lastConsolidatedAt": "2026-04-01T10:00:00Z" } ``` ### 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. Initialize the memory directory structure: ```bash # Using the bundled script (recommended) ./scripts/init_memory.sh # Or manually mkdir -p memory/channel_context touch memory/active_context.md echo '{"lastUpdated":"","tasks":[]}' > memory/pending_tasks.json ``` 2. Add to your `AGENTS.md` or session start routine: ``` Before responding, read: 1. memory/active_context.md 2. memory/YYYY-MM-DD.md (today + yesterday) 3. MEMORY.md ``` 3. Start logging to daily notes as you work 4. Set up weekly distillation (cron, heartbeat, or manual) The system grows organically from here.