turboclaw-memory

name	turboclaw-memory
description	Memory management skill: save conversation highlights to daily logs, consolidate to long-term memory, and recall past context. Use for logging throughout the day, daily consolidation, or searching past memories.

memory

Complete memory management skill with three modes:

1. Log mode (default): Append highlights to today's daily log
2. Consolidate mode (--consolidate): Summarize all daily logs to MEMORY.md and reset conversation
3. Recall mode (--recall <query>): Search and retrieve past memories

When to use this skill

Log mode (throughout the day)

• Heartbeat invocations - Log interesting events/decisions as they happen
• After completing significant tasks - Record outcomes and learnings
• Capture user preferences - Save newly discovered preferences or patterns
• Document decisions - Note why you chose a particular approach

Consolidate mode (end of day)

• Daily memory consolidation - Automatically scheduled at 2am when agent is created
• Before major context switches - Transitioning between different projects
• Conversation getting too long - When history is becoming unwieldy

Clear context mode (regular intervals)

• Context clearing - Automatically scheduled every 6 hours when agent is created
• Prevent context bloat - Keeps conversation history manageable
• Combined with consolidation - Consolidation preserves important info, clearing removes clutter

Recall mode (anytime)

• User asks about past work - "What did we decide about X?"
• Reference previous decisions - Looking up architectural choices
• Find user preferences - "How does the user like Y formatted?"
• Lookup past context - "When did we implement Z?"

CLI commands

All memory operations go through the turboclaw memory CLI. Never read or write memory files directly.

Write (daily log)

turboclaw memory write <agent-id> <tag> <message>

Tags: decision, preference, task, context, bug, note (default: note)

Appends a timestamped entry to today's daily log: - HH:MM @agent-id - [tag] message

Write (long-term memory)

turboclaw memory write <agent-id> --consolidated <raw line>

Appends a raw line to MEMORY.md. You control the format — typically - YYYY-MM-DD HH:MM @agent - [tag] entry text.

Read (daily logs)

turboclaw memory read <agent-id>

Dumps all daily log files to stdout.

Read (long-term memory)

turboclaw memory read <agent-id> --consolidated

Dumps MEMORY.md to stdout.

Search

turboclaw memory search <agent-id> <query>
turboclaw memory search <agent-id> <query> --tag <tag>

Searches across both daily logs and MEMORY.md. Case-insensitive.

Format rules (applies to ALL modes)

Every entry — daily or consolidated — MUST be a single line under ~200 characters:

- HH:MM @agent - [tag] concise summary — key detail if needed                    (daily)
- YYYY-MM-DD HH:MM @agent - [tag] concise summary — key detail if needed         (consolidated)

Never write multi-line entries, bullet lists, headings, or prose paragraphs. One line per entry. This is what makes the files grep-friendly and context-efficient.

What this skill does

Mode 1: Log to daily file (default)

When invoked WITHOUT --consolidate:

1. Generate brief highlights (2-5 entries max)

   • Focus on new information from THIS invocation
   • Don't repeat what's already in today's log
   • One line per entry, under ~200 chars — no multi-line prose
   • Tag each entry with a tag for easy filtering

2. Write each entry using the CLI:

   turboclaw memory write <agent-id> <tag> <message>
   

3. Respond briefly

   • "Logged N entries"
   • Keep it to one line

Example daily log entries (generated by the CLI):

- 18:45 @coder - [decision] Implemented memory skill with dual modes
- 18:46 @coder - [preference] User prefers visible `memory/` folder over hidden `.memory/`
- 18:47 @support - [note] User confused by error messages in login flow
- 18:52 @coder - [task] Added better validation feedback per @support note

Available tags:

• [decision] - Architectural/design choices made
• [preference] - User preferences learned
• [task] - Work completed or next steps
• [context] - Project/domain context
• [bug] - Issues discovered
• [note] - General observations

Mode 2: Consolidate and reset

When invoked WITH --consolidate:

1. Read all daily logs using the CLI:

   turboclaw memory read <agent-id>
   

2. Also read existing long-term memory to avoid duplicating entries:

   turboclaw memory read <agent-id> --consolidated
   

3. Generate consolidated entries

   • The bar is high. Ask: "Will this still matter next week?" If not, drop it.
   • Drop: completed one-off tasks, resolved issues, transient status updates, routine work ("processed N emails"), things that were just done once and won't recur
   • Keep: decisions that affect future work, user preferences, bugs/workarounds you'll hit again, recurring patterns, domain knowledge, ongoing projects
   • Deduplicate — merge entries that say the same thing
   • Drop entries already present in long-term memory
   • Aim for 5-10 entries per consolidation — fewer is better
   • Format: - YYYY-MM-DD HH:MM @agent - [tag] entry text — single line, ~200 chars max
   • Each source daily entry has - HH:MM @agent - [tag] text. Extract the HH:MM and @agent from it. The YYYY-MM-DD comes from the daily log filename. All three MUST appear in the consolidated entry.

4. Write each consolidated entry using the CLI:

   turboclaw memory write <agent-id> --consolidated "- YYYY-MM-DD HH:MM @agent - [tag] entry text"
   

5. Reset conversation

   turboclaw reset-context <agent-id>
   

6. Respond to user

   • "Consolidated X days to MEMORY.md and reset conversation"
   • Brief, 1-2 sentences max

Example MEMORY.md after consolidation:

# Memory

- 2026-02-16 18:45 @coder - [decision] Implemented memory skill with dual log/consolidate modes
- 2026-02-16 18:46 @coder - [preference] User prefers visible `memory/` folder over hidden `.memory/`
- 2026-02-18 09:12 @support - [bug] `gog gmail drafts update` detaches draft from thread — must always delete + recreate
- 2026-02-18 14:30 @coder - [context] Genealogy use case trending — Transkribus is main competitor, we perform better
- 2026-02-20 11:05 @coder - [decision] Data stored in EU but passes through local servers if user outside Europe

Mode 3: Recall from memory

When invoked WITH --recall <query>:

1. Search using the CLI:

   turboclaw memory search <agent-id> <query>
   turboclaw memory search <agent-id> <query> --tag <tag>
   

2. Summarize findings

   • Extract relevant entries found
   • Provide context (which file, when logged)
   • Quote exact log entries with timestamps
   • If nothing found, suggest alternative search terms

3. Respond with results

   • Show matching entries in chronological order
   • Keep response concise but complete

Detecting mode

Parse the skill invocation:

• If contains --consolidate → consolidate mode
• If contains --recall <query> → recall mode
• Otherwise → log mode

File structure

The CLI manages these files — you don't need to know the paths, but for reference:

memory/
├── MEMORY.md              # Consolidated long-term memory
└── daily/
    └── YYYY-MM-DD.md      # Daily incremental logs

Automatic memory management

When you install this skill during agent creation, TurboClaw offers to set up automated memory management:

What gets created:

1. Daily consolidation task - Runs at 2am every day

   • Consolidates all daily logs to MEMORY.md
   • Resets conversation to keep context fresh

2. Context clearing task - Runs every 6 hours

   • Sends turboclaw-memory --clear-context command
   • Prevents conversation context from growing too large
   • Works in conjunction with consolidation to maintain manageable memory

Managing your schedules:

# View all schedules
turboclaw schedule list

# Temporarily disable consolidation
turboclaw schedule disable "{agent-id} Memory Consolidation"

# Re-enable it later
turboclaw schedule enable "{agent-id} Memory Consolidation"

# Adjust timing by removing and recreating
turboclaw schedule remove "{agent-id} Memory Consolidation"
turboclaw schedule add  # Then enter new timing

Important notes

• Log mode does NOT reset - conversation continues
• Consolidate mode DOES reset - starts fresh
• Recall mode does NOT reset - just searches and returns results
• MEMORY.md is append-only - never overwrite
• Daily logs are kept - consolidation only appends to MEMORY.md, daily files stay for detailed recall
• Always use the CLI - never read or write memory files directly
• Agent ID - Use correct agent ID for all commands
• Search is case-insensitive
• Tags are searchable - Use [tag] to filter by entry type
• Agent filtering - Use @agent-id to filter by agent
• Single-line format - Each entry is one complete line for easy searching