Mem Auto

mem-auto — Unified Memory Autopilot

Runs the automatic memory loop; delegate detailed work to the narrow mem-* skills.

Memory Scopes

• Long-term memory: global durable instructions, preferences, facts, and reusable conventions in ~/.agents/AGENTS.md (the canonical core read natively by every agent); project durable rules in AGENTS.md or CLAUDE.md.
• Short-term memory: daily [Candidate] logs in ~/.agents/memories/YYYY-MM-DD.md and .memories/YYYY-MM-DD.md; active [Handoff] state lives in per-task files under .memories/handoffs/ (one file per task). Both the daily logs and the handoffs/ subdirectory sync through /mem-sync.

Delegation

Use /mem-recall for short-term lookups, /mem-promote for durable promotion/prune, /mem-clean for destructive cleanup, and /mem-sync for project log status/diff/pull/push.

Autopilot Loop

• [ ] Start / Handoff In
• In cross-device projects, run /mem-sync pull first.
• Legacy handoff migration runs at most once. If the sentinel .memories/.handoff-migrated exists, skip this step — do not re-scan. Otherwise run the one-time migration in references/handoff-migration.md: it greps project and global daily logs for inline [Handoff] residue, migrates any found, and writes the sentinel so later sessions never re-check. Legacy handoffs that arrive later via /mem-sync are surfaced on demand by /mem-recall's fallback grep, not by checking at every start.
• Resolve handoffs by listing .memories/handoffs/ — one file per active task, named YYYY-MM-DD__<slug>.md. Read only the relevant task file(s); do not load the whole .memories/ tree into context. If several handoffs are open, list them and let the user pick.
• If the handoff is stale or its branch is merged/gone, ask before resuming.
• Treat auto-loaded AGENTS.md / CLAUDE.md as the normal source for durable instructions; use /mem-recall for short-term logs, and inspect durable files only when their loaded content seems incomplete or exact wording matters.
• [ ] Capture
• Before writing task state, apply references/security.md and references/session-handoff.md.
• Capture gate — write only if it passes. Ask: would a fresh agent be wrong, blocked, or materially slower without this note? If not, write nothing. Capturing nothing is a valid and common outcome; never log just to fill the step.
• Never capture (avoids running-log noise): routine successful steps, restatements of the task or request, or anything already recoverable from code, tests, git log, docs, or external trackers (e.g., GitHub/GitLab Issues). If a suitable external tracker is available, ask the user whether to open an issue instead of logging it.
• At milestones, blockers, quota/context limits, or session boundaries, write or update the task's handoff file .memories/handoffs/YYYY-MM-DD__<slug>.md (date = creation day; <slug> an agent-chosen name fitting the task). Keep it a single live delta — update the file in place, do not stack entries — holding only what a fresh agent would need to continue: goal, progress, verification, next actions, blockers/assumptions, and suggested skills.
• Reference existing artifacts by path or URL instead of duplicating contents.
• Treat the handoff file as transient active state: not a [Candidate], not promotable directly, and deleted on completion rather than promoted into durable memory.
• Log verified durable insights to today's log (.memories/YYYY-MM-DD.md locally or memories/ globally) as [Candidate] entries with a daily time stamp (e.g., [HH:MM]). A [Candidate] must generalize beyond the current task — good: a reusable convention, a non-obvious environment constraint, a gotcha that will recur; bad: one-off task progress or a past fix (that is [Handoff] or git history).
• [ ] Sync
• Use /mem-sync for project daily-log Git operations. Its mem-sync-git.sh status and diff commands are read-only checks for local/remote .memories/ differences.
• Pull before reading remote handoffs; push at session end or after promotion/capture changes that should be available on other devices.
• [ ] Manual Governance
• Delegate promotion/prune to /mem-promote; delegate expired logs and conflict copies to /mem-clean. Do not delete or rewrite history from mem-auto.
• [ ] Closure
• When the task is achieved and verified, delete that task's handoff file from .memories/handoffs/. Active handoff state is transient — completion removes it; any durable insight should already be captured as a [Candidate] note.

Handoff Migration (one-time)

Earlier versions stored [Handoff] blocks inside the daily logs (.memories/YYYY-MM-DD.md) and closed them by appending [Handoff:done]. Handoffs now live in per-task files under .memories/handoffs/ (see session-handoff.md). Migrate once per project (and once for global ~/.agents/memories/) to move any old-style blocks out of the daily logs.

When to run (at most once)

Track completion with a sentinel file, not the existence of .memories/handoffs/ — a single new per-task handoff creates that directory, which would mask un-migrated legacy blocks still inline in older daily logs.

• Skip when the sentinel .memories/.handoff-migrated exists (global:

~/.agents/memories/.handoff-migrated).

• Otherwise detect → migrate → write the sentinel (final step), so later sessions never

re-scan.

Stragglers that arrive later (for example a /mem-sync pull of un-migrated logs from a device that never upgraded) are surfaced on demand by /mem-recall's fallback grep, which prompts a one-off re-run — they do not justify re-checking at every start.

Detect

# project + global daily logs that still hold legacy handoff blocks
# (dir-based grep: tolerates a missing/empty dir; modern handoffs/ files carry no
# "[Handoff" literal so they are never matched)
grep -rln "\[Handoff" .memories ~/.agents/memories 2>/dev/null

If grep finds nothing, there is no residue — just write the sentinel (step 6) and stop.

Plan, then migrate

1. In cross-device projects, run /mem-sync pull first so migration runs on the freshest logs; the daily logs are git-synced, so the pre-migration state stays restorable. 2. For each task, find its newest [Handoff] block:

• Open (no later [Handoff:done] for that task):
• In a project log (.memories/), move it into

.memories/handoffs/YYYY-MM-DD__<slug>.md, where YYYY-MM-DD is the block's original creation date and <slug> an agent-chosen name fitting the task. Keep only the latest delta — do not carry forward stacked older blocks.

• In a global log (~/.agents/memories/) there is no handoff scope — handoffs are

project active state. Surface the block to the user; if the task is still live, recreate it as a project handoff under that project's .memories/handoffs/, otherwise drop it.

• Closed ([Handoff:done]): drop it. Completed handoffs are transient and are not

migrated. 3. Remove the migrated/closed/dropped [Handoff] and [Handoff:done] blocks from the daily logs. Leave every [Candidate] entry untouched. 4. Present the full plan (files read, handoff files to create, blocks to strip, sentinels to write) and get explicit confirmation before editing daily logs, since this rewrites them. 5. After confirmation, apply the edits. 6. Write the sentinel so later sessions skip this step: touch .memories/.handoff-migrated (and touch ~/.agents/memories/.handoff-migrated if you scanned global). In cross-device setups, /mem-sync push so the sentinel and the rewritten logs travel together.

Memory Security Specifications

This reference outlines strict security restrictions, quality constraints, and branch protection rules for memory management.

1. Strictly Prohibited Data

Never record, log, or persist the following sensitive information under any circumstances:

• Authentication: Passwords, API keys, access tokens, SSH keys, private certificates.
• Environment: Cloud provider credentials, private registry logins, local system tokens.
• Privacy: Customer personal identifiable information (PII), proprietary private datasets, or confidential database records.

2. Quality & Authenticity Safeguards

• No Speculations: Never promote AI-generated guesses, unverified assumptions, or speculative coding ideas directly into durable memory.
• Diligence Rule: Only persist knowledge that has been validated as working in the active environment.
• Redact Handoffs: Short-term handoff notes and daily logs must redact secrets, PII, private records, and credential-adjacent values. Refer to safe artifact paths or URLs when possible instead of copying sensitive content.
• Transient Handoffs: Handoff files (.memories/handoffs/) are transient active state, not durable history. They are updated in place and deleted on task completion — deleting a completed handoff is expected, not a destructive action requiring backup.

Session Handoff

Use a [Handoff] file to transfer active task state across sessions. Each active task gets its own file, kept separate from the date-anchored [Candidate] daily logs because its lifetime follows the task, not the calendar.

[Handoff] state is transient active state, not durable memory. It must not be promoted directly; durable insights belong in [Candidate] notes. A handoff is closed by deleting its file, not by accumulating a step-by-step journal.

Location & naming

One file per active task under the project memory directory:

.memories/handoffs/YYYY-MM-DD__<slug>.md

• YYYY-MM-DD is the creation day (for ordering and recognition).
• <slug> is an agent-chosen short name fitting the current task context.
• The handoffs/ subdirectory syncs across devices through /mem-sync along with the

daily logs.

Format

The file's location under .memories/handoffs/ already identifies it as a handoff — no [Handoff] marker or fixed heading is needed inside. Use whatever Markdown structure best fits the task; the sections below are a suggested shape, not a required template. Drop the ones that do not apply.

# <short task name>

## Goal
The ultimate objective and the immediate sub-goals.

## Progress
What is implemented so far; files edited or created; key decisions.

## Verification
Tests passed, compilers run, pre-existing failures.

## Next Actions
Clear, step-by-step actions the next agent should execute immediately.

## Blockers & Assumptions
Current obstacles or unverified assumptions.

## Suggested Skills
The next relevant skills or workflows to invoke, if any.

Keep it a single live delta: include only facts a fresh agent would need to continue, and update the file in place as the task progresses rather than appending new blocks. Reference existing artifacts by path or URL instead of duplicating code, logs, screenshots, or long command output. Several tasks may each have their own open handoff file; resume by listing .memories/handoffs/ and picking the relevant one.

Closure

Once the task is fully achieved and verified, delete its handoff file. Completion removes the transient state; nothing about it needs to persist, because any durable insight should already be captured as a [Candidate] note.