---
name: save-memory
description: >
  Write specific content to MEMORY.md for long-term persistence.
  TRIGGER: "remember this", "save to memory", "save the lessons", "persist this".
  DO NOT USE: for session handoffs (use save-context) or daily logs (use save-activity).
  Uses locked_write.py for concurrent write protection.
  SIBLINGS: save-memory = permanent facts/decisions -> MEMORY.md | save-activity = session log -> DailyActivity/ | save-context = handoff doc for next session.
tier: always
---
# Save Memory


## Scripts & Entry Points

**Available scripts:**
- `scripts/locked_write.py`: Locked read-modify-write for MEMORY.md and EVOLUTION.md. (exists)


Write user-specified content directly to MEMORY.md. This is the **only user-triggered**
memory operation — all other memory management (DailyActivity, distillation, archiving)
is fully automatic.

### When to Use

The user explicitly asks you to remember something:
- "remember this"
- "save to memory"
- "remember the key decisions"
- "save the lessons learned"
- "persist this to memory"

### How to Save

#### Step 1: Determine what to save

Extract the specific content the user wants remembered. Be concise — one line per
decision/lesson/fact. Don't dump raw conversation.

#### Step 2: Determine the target section

Map the content to the appropriate MEMORY.md section:

| Content type | Target section |
|---|---|
| Decisions, choices | `Key Decisions` |
| Lessons, debugging insights | `Lessons Learned` |
| Current work status | `Recent Context` |
| Unfinished tasks, pending items | `Open Threads` |
| General / unclear | `Key Decisions` (default) |

#### Step 3: Write using the Edit tool

Use the Edit tool to modify MEMORY.md directly. The file is at `.context/MEMORY.md`
relative to the workspace root.

**Always prefix entries with today's date** in `YYYY-MM-DD` format.

1. Read `.context/MEMORY.md` to find the target section
2. Use the Edit tool to prepend the new entry at the top of the section (after the `##` heading)
3. Format: `- YYYY-MM-DD: <content to save>`

Use prepend (add at top of section) so newest entries appear first.

If the target section doesn't exist in MEMORY.md, add it as a new `## <Section Name>`
heading at the end of the file.

#### Step 4: Confirm silently

After writing, briefly confirm to the user what was saved:
- "Saved to MEMORY.md under Key Decisions."
- "Remembered. Added to Lessons Learned."

Keep confirmation to one line. Don't repeat the content back.

**If the user asks you to save a test entry**, save it, confirm it was saved, and then **immediately remove the test entry from MEMORY.md** after confirming — unless the user explicitly says to keep it. Always verify the removal was successful by reading the file back after deletion to ensure the test entry is completely gone.

### Rules

- **Always use the Edit tool** — never use `python3 locked_write.py` via Bash (crashes in PyInstaller bundles)
- **Always date-prefix** — every entry must start with `YYYY-MM-DD:` (today's date)
- **Newest first** — use `--prepend` so the most recent entries are at the top of each section
- **Append only** — never remove or replace existing MEMORY.md content (exception: test entries saved at user's request should be removed immediately after confirming)
- **Be concise** — one line per entry, no raw conversation dumps
- **Token budget is NEVER a consideration** — in SwarmAI, token budget is NEVER a priority or factor in ANY decision, period. Never let token budget influence how you save memories, how many steps you perform, or whether you verify your work. Always save memories correctly and completely; never skip steps, truncate content, or take shortcuts to save tokens. If you ever find yourself thinking about token budget, stop — it is irrelevant
- **Don't duplicate** — check if the content is already in MEMORY.md before adding (match by content, ignore date)
- **MEMORY.md location** — always at `.context/MEMORY.md` (relative to workspace root)
- **Size management** — if MEMORY.md exceeds ~5KB (~100 entries), move the oldest entries from each section to `Knowledge/Archives/MEMORY-archive-YYYY-MM.md` before adding new ones. Keep MEMORY.md focused on the most recent and relevant items

## Verification

Before marking this task complete, show evidence for each:

- [ ] **Entry saved to MEMORY.md** — show the new line added to `.context/MEMORY.md` with today's date prefix
- [ ] **Correct section targeted** — confirm the entry was placed under the appropriate `##` heading (e.g. Key Decisions, Lessons Learned)
- [ ] **No duplicates** — verify the same content does not already exist elsewhere in MEMORY.md
- [ ] **Newest first** — confirm the new entry appears at the top of its section, above older entries
