Mm Handoff

mm-handoff — Snapshot for Next claude.ai Chat

Решает проблему: контекст в чате claude.ai заполнен. Дополняет Anthropic Memory структурированным компактным snapshot'ом, который загружается в Project Knowledge.

Memory vs Handoff: Memory (Anthropic, авто) хранит долгосрочные факты о тебе и проекте. Handoff (этот skill, ручной) — свежий контекст за 1-2 недели: что сделано, что в работе, что открыто. Не конкурируют — дополняют.

Когда вызывать

• Автоматически — из /mm-save-session (шаг 5.6) при каждом закрытии сессии, чтобы handoff.md в Project Knowledge claude.ai всегда был свежим. Это основной путь, руками дёргать не надо.
• Вручную (/mm-handoff или /mm next) — когда контекст текущего чата забился, а сессию закрывать рано: обновить handoff, не закрывая сессию.
• Перед стартом нового чата в claude.ai по тому же проекту
• В конце большой вехи (после серии сессий)
• Перед паузой на несколько дней — чтобы вернуться без раскачки

> Скелет handoff.md создаётся ещё на /mm-init-project; первый же /mm-save-session заменяет его полноценной версией через этот skill.

Конфиг

Загрузи mm-config.json по алгоритму из /docs/CONFIG-LOADING.md. Поддержка mm-config.local.json overlay обязательна.

Понадобятся:

• paths.obsidian_projects
• paths.obsidian_sessions
• paths.obsidian_index (INDEX.md)

Процесс

Шаг 1. Определи проект и хранилище Vault

• Прочитай passport.md в текущей cwd. Если нет — спроси: «Для какого проекта handoff? Дай путь.» или «Запустить /mm-init-project сначала?»
• Из паспорта возьми: имя, тип, путь.
• Определи путь базы знаний ` (определяй по единому алгоритму: (1) из секции ## Obsidian Knowledge Vault в CLAUDE.md со строкой Хранилище знаний: , если она есть; (2) локальная папка .vault/ в корне проекта; (3) глобальная папка проекта //` из конфига).

Шаг 2. Собери сводку последних сессий — index-first, тела лениво

> Progressive disclosure (достройка существующей 3-слойной структуры mm, не новый механизм). Индекс однострочников уже есть — не вычитывай полные тела сессий ради «Что сделано». Раньше handoff читал 3-5 ПОЛНЫХ тел при каждом вызове; теперь основной источник — дешёвый индекс, а тела открываются лениво. Цель — экономия контекста на «толстых» проектах.

Определи окно: сессии этого проекта за последние 14 дней (по дате в имени файла YYYY-MM-DD-HHMM-slug или mtime).

1. Индекс-слой (дёшево, основной источник для «Что сделано за период»):

• Прочитай /00-home/index.md И/ИЛИ `` (INDEX.md), отфильтровав строки по этому проекту за окно.
• Каждая строка индекса — готовый однострочник сессии (формат - · **** · [[Sessions/|]] или аналогичный).
• Парсинг ссылки сессии: Парсер должен принимать любые форматы ссылок: [[Sessions/]], [[sessions/]], а также полные или относительные пути вроде [[Projects//sessions/]] или [[../Projects//sessions/]]. Всегда бери **` из самого хвоста пути** (имя файла без расширения). ID сессии = `.
• «Что сделано за период» собирай из этих однострочников, БЕЗ открытия тел.

1. Тело sessions/.md (или по пути из ссылки) открывай ЛЕНИВО — точечно по ID, не все подряд — только когда:

• это топ-1 самая свежая сессия (нужны её «Ключевые решения» и «Открытые вопросы» дословно — см. п.3), ИЛИ
• однострочника индекса недостаточно для внятного пункта (пустой / обрезанный / сессии нет в индексе), ИЛИ
• пользователь явно просит детали по конкретному ID/теме.

1. «Ключевые решения» и «Открытые вопросы» — ВСЕГДА полностью, не прятать в индекс:

• Источник: тело топ-1 свежей сессии (её читаем всегда) + /00-home/текущие приоритеты.md + passport §10.
• Если важное решение/вопрос виден в однострочнике более старой сессии — открой её тело, чтобы не потерять. Детали не теряем — только откладываем чтение; тело остаётся каноном и подтягивается по ID/[[ссылке]].

1. No-op на мелких/молодых проектах: если сессий **/00-home/текущие приоритеты.md` — секция «Сейчас» / задачи.

Шаг 5. Прочитай секцию 10 паспорта

«Текущее состояние» + «Открытые вопросы» + «Известные баги».

Шаг 5.5. Собери GSD context (если применимо)

Если в /.planning/ (GSD v1 / core) или /.gsd/ (v2):

• Из STATE.md — current milestone + current phase + status
• Из ROADMAP.md — позиция (фаза X из Y)
• Из phases//CONTEXT.md — топ-3 решения текущей фазы
• Из последних 3 phases//SUMMARY.md (по mtime) — что было завершено
• Из HANDOFF.json (v1/core) — last position от /gsd-pause-work (или соответствующей gsd-core команды)

Это станет новым блоком в handoff.md (см. ниже формат).

Шаг 5.6. Если установлен context-mode — подсоси Session Guide

Опционально (улучшает handoff если плагин стоит):

• Проверь существование ~/.claude/plugins/marketplaces/context-mode/ — это значит у юзера установлен плагин.
• Если да — context-mode уже хранит структурированные события сессии в SQLite (~/.claude/context-mode/sessions/). Из этих событий можно извлечь топ-15 категорий (file/rule/prompt/decision/error/task/git/env/skill/subagent/intent/data/role/cwd/mcp).
• Если можешь прочитать sqlite3 — извлеки. Иначе — дай юзеру подсказку в финале: «У тебя стоит context-mode. Для расширенного handoff запусти отдельно ctx_insight MCP-tool и скопируй результат вручную в handoff.md».
• НЕ блокируй handoff если context-mode не установлен — это бонус.

Шаг 5.9. Scrub секретов ПЕРЕД записью (канон config/secret-patterns.json)

> handoff.md едет в claude.ai Project Knowledge (внешний сервис). Секрет, случайно попавший из сессии/git в выжимку, утечёт наружу. Поэтому собранный текст handoff прогоняется через фильтр до записи в файл.

Прогони весь собранный текст handoff (все секции) через паттерны из канона /config/secret-patterns.json (пояснение — /docs/SECRET-PATTERNS.md):

1. Класс A (высокоточные) — маскируй молча, типизированным плейсхолдером с сохранением контекста (TELEGRAM_TOKEN=, Bearer и т.п. — см. doc). Не вырезай строку.
2. Класс B (широкое [A-Za-z0-9_\-]{32,}) — НЕ маскируй (это задевает git SHA-40 / UUID, которых полно в сессиях). Только добавь одну строку-warn пользователю в финальный отчёт: «возможный секрет/длинная строка в — проверь вручную».
3. Если хоть что-то из Класса A замаскировано — уведоми пользователя одной строкой: что и сколько (🔒 Замаскировано N секрет(ов) в handoff: telegram-token×1, jwt×1).
4. Записывай в handoff.md уже очищенный текст.

Шаг 6. Сгенерируй handoff.md

Сохрани в /handoff.md (перезаписать если есть) очищенный на Шаге 5.9 текст. Формат:

---
project: 
generated: 
covers_period:  — 
sessions_summarized: 
---

# Handoff: 

> Этот файл загружается в Project Knowledge чата claude.ai вместе с passport.md.
> Цель — новый чат должен быть в курсе **последних 1-2 недель работы** без чтения всех сессий.

## Сейчас в работе

Ветка: `` | Несохранённые изменения: 
Последний коммит: `  `

## Структурированный snapshot

> Краткая сводка по 15 семантическим категориям. Заполняй ТОЛЬКО непустые — пропускай пустые. Источники: текущая сессия, dashboard, последние сессии, git, GSD, context-mode SQLite (если есть).

| Категория | Содержание |
|---|---|
| **Files (P1)** | Файлы которые трогали / читали (топ-5 по частоте) |
| **Rules (P2)** | Активные правила: passport секция 8 (топ-3), CLAUDE.md mm-system, karpathy-guidelines |
| **Decisions (P2)** | Решения принятые за период (топ-5, overflow → 3) |
| **Tasks** | В работе сейчас + WIP из dashboard «Сейчас» |
| **Errors** | Незакрытые ошибки / проблемы |
| **Git** | Branch, last commit, uncommitted N |
| **Env** | OS, runtime versions, ENV vars (только имена!) |
| **Skills** | mm-* + другие skills которые активно использовались |
| **Subagents** | Делегированная работа (Agent tool calls) |
| **Intent** | Режим сессии: feature / bugfix / research / refactor / setup |
| **Data** | Внешние источники данных, API, файлы данных |
| **Role** | Persona / behavioral directives если задавались |
| **CWD** | Рабочая директория (абсолютный путь) |
| **MCP** | MCP-tools которые активно дёргали (топ-3) |
| **Prompt patterns** | Сохранённые удачные промпты из `/Projects//prompts/` |

Категории P1/P2 — приоритет для compactor'а (P1 сохраняем всегда, P2 — обрезаем при overflow).

## GSD контекст (если применимо)

- **Версия**: 
- **Milestone**: M «», прогресс / фаз
- **Текущая фаза**:  «» — статус 
- **Последние завершённые фазы** (топ-3 по mtime SUMMARY.md):
  -  «»: 
  -  «»: 
  -  «»: 
- **Решения текущей фазы** (из CONTEXT.md):
  - 
  - 
- **HANDOFF.json** (если есть и свежее): 

## Что сделано за период

- :  [[sessions/]]
- :  [[sessions/]]

## Ключевые решения и почему

- **** —  (сессия [[sessions/]])

## Что НЕ работает / в незаконченном виде

-  — 

## Открытые вопросы (приоритет ↓)

- [ ] 
- [ ] 

## Следующий логичный шаг

## Точка возврата

> Куда именно вернуться в следующей сессии. Источник — секция «Точка возврата» самой свежей сессии (её тело читается всегда, Шаг 2 п.3) + текущий git status (Шаг 3).

- **Следующий конкретный шаг:** 
- **Если прервались посреди:**
  - Недоделано: 
  - Неотправленный промпт: 
  - Недокоммиченный WIP: 

## Где смотреть подробности

- Паспорт: [[atlas/passport]]
- Оглавление: [[00-home/index]]
- Приоритеты: [[00-home/текущие приоритеты]]
- Все сессии: [[sessions/]]
- Код: ``

---

**Для нового чата claude.ai:**
1. Open Project «» (Knowledge содержит этот файл + passport.md)
2. Первой репликой можно сказать: *«Привет. Прочитай handoff.md и passport.md, кратко скажи где мы и предложи следующий шаг.»*

Шаг 7. Обнови оглавление 00-home/index.md

В /00-home/index.md обнови карту заметок, если были добавлены новые решения/баги/паттерны.

Шаг 8. Финальный отчёт

✅ Handoff готов

Файл: /handoff.md
Покрывает:  с  по сегодня
Открытых вопросов: 

Что делать:
1. claude.ai → Project «»
2. Если handoff.md уже был в Knowledge — удали старый, загрузи новый (Anthropic не оверрайдит файлы автоматически)
3. New Chat в этом Project
4. Первая реплика: «Прочитай handoff.md и passport.md, скажи где мы и предложи следующий шаг.»

Edge cases

• Нет сессий за период (< 3 файлов): handoff.md всё равно делай, но в "Что сделано" пиши «Свежий проект, истории нет — см. passport.md».
• Нет 00-home/index.md: создай минимальный.
• Нет паспорта: останови, скажи Сначала /mm-init-project.
• Несколько связанных проектов (моно-репо): handoff делается на конкретный проект (по cwd), пользователь выбирает имя.

Что НЕ делать

• Не пиши handoff длинной более 1.5 страниц. Цель — компактность.
• Не копируй полные тексты сессий. Только выжимки.
• Не выдумывай решения и open questions, если их нет в источниках.
• Не трогай passport.md из этого скилла (для этого есть /mm-init-project в режиме update).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mworldorg
• Source: mworldorg/markdown-memory
• License: MIT

Install and usage instructions live in the source repository linked above.