Skip to content

memory.md

Latest commit

 

History

History
196 lines (136 loc) · 8.74 KB

memory.md

File metadata and controls

196 lines (136 loc) · 8.74 KB

Память агента (Agent Memory)

Spec Kit использует персистентную память, которая позволяет ИИ-агенту накапливать знания между сессиями. Агент запоминает уроки, паттерны и архитектурные решения — и применяет их в последующих задачах.

Уровни памяти

Уровень Тип Хранилище Описание
Level 1 Сессионная Контекст разговора Естественная память текущей сессии Claude Code. Не требует настройки
Level 2 Файловая .claude/memory/*.md Markdown-файлы с уроками, паттернами и решениями. Основной уровень
Level 3 Векторная ~/.claude/memory/vector/embeddings.json Семантический поиск через Ollama embeddings. Опциональный уровень

Как уровни взаимодействуют

Level 1 (Session)     — агент помнит всё в рамках текущего разговора
    ↕ read/write
Level 2 (File)        — markdown-файлы, доступны между сессиями
    ↕ search/store
Level 3 (Vector)      — семантический поиск по всей базе знаний

Если Ollama недоступен, Level 3 отключается автоматически. Файловая память (Level 2) работает всегда.

Файловая память (Level 2)

Структура файлов

.claude/memory/
├── lessons.md        # Уроки: баги, ошибки, подводные камни
├── patterns.md       # Паттерны: переиспользуемые решения
└── architecture.md   # Архитектура: ключевые технические решения

Формат записей

## Название записи

**Date:** 2026-03-13
**Type:** Bug Fix | Pattern | Architecture | Lesson

**Problem/Context:**
Описание ситуации или проблемы

**Solution/Decision:**
Что было сделано и почему

**Tags:** #tag1 #tag2

Чтение памяти

Каждая команда /speckit.* при запуске:

  1. Проверяет наличие .claude/memory/ (если нет — создаёт с файлами-заглушками)
  2. Читает заголовки (## ...) из всех файлов памяти (~80-120 токенов)
  3. Подгружает полное содержание только релевантных секций
  4. Применяет знания при выполнении задачи (молча, без вывода пользователю)

Запись в память

Запись происходит немедленно при обнаружении важного знания — не в конце сессии, а сразу. Это защищает от потери данных при неожиданном завершении сессии.

Исключение: команда /speckit.implement использует отложенную запись (после завершения всех задач), т.к. прерывание для записи может нарушить ход реализации.

Порог важности — записывается только то, что:

  • Баг с нетривиальной причиной (не очевидный фикс)
  • Паттерн, применимый в других задачах (не одноразовый хак)
  • Решение, влияющее на дальнейшую разработку (не косметическое)

Векторная память (Level 3)

Требования

  • Ollama установлен и запущен
  • Модель mxbai-embed-large загружена: ollama pull mxbai-embed-large

Скрипт

# Расположение
~/.claude/scripts/vector_memory.py
# Исходник в репозитории
scripts/memory/vector_memory.py

Команды

# Проверить статус (Ollama, модель, количество записей)
python ~/.claude/scripts/vector_memory.py status

# Сохранить знание
python ~/.claude/scripts/vector_memory.py store \
  --content "Описание урока или паттерна" \
  --type episodic \
  --project "spec-kit" \
  --tags "bugfix,python"

# Семантический поиск
python ~/.claude/scripts/vector_memory.py search \
  --query "проблемы с производительностью" \
  --limit 5 \
  --project "spec-kit"

# Переиндексировать файловую память в векторную
python ~/.claude/scripts/vector_memory.py reindex --project "spec-kit"

Типы записей

Тип Файл-источник Описание
episodic lessons.md Что произошло — баги, инциденты
procedural patterns.md Как делать — решения, подходы
semantic architecture.md Что есть — архитектура, домен

Технические детали

  • 1024-мерные векторы (модель mxbai-embed-large)
  • Косинусное сходство для поиска
  • Хранилище: JSON-файл ~/.claude/memory/vector/embeddings.json
  • Единственная зависимость: requests

Graceful Degradation

Система памяти спроектирована с плавной деградацией:

Состояние Level 1 Level 2 Level 3
Всё доступно Session File Vector
Ollama недоступен Session File --
Первый запуск (пустая память) Session File (создаётся автоматически) --

При недоступности Ollama система выводит предупреждение один раз за сессию и продолжает работу на файловой памяти.

Глобальная vs локальная память

Тип Расположение Область
Локальная .claude/memory/ в корне проекта Знания конкретного проекта
Глобальная ~/.claude/memory/projects/{project-id}/ Кросс-проектные знания

project-id генерируется из git remote URL или имени директории (слэши заменяются на дефисы).

Векторный поиск умеет маршрутизировать запросы:

  • Запросы вроде «в этом проекте», «здесь» → локальная память
  • Запросы вроде «best practice», «в других проектах» → глобальная память
  • По умолчанию: локальный поиск, fallback на глобальный если < 3 результатов

Python API

В src/specify_cli/memory/ находится Python-библиотека для программного доступа к памяти:

from specify_cli.memory.orchestrator import MemoryOrchestrator
from specify_cli.memory.file_manager import FileMemoryManager

Ключевые классы:

Класс Модуль Назначение
MemoryOrchestrator orchestrator.py Координация file + vector поиска
FileMemoryManager file_manager.py Чтение/запись markdown-файлов
MemoryAwareAgent agent.py Before/When/After workflow API
MemoryConfigManager config.py Управление путями и конфигурацией
FourLevelMemory vector/memory_types.py Полная 4-уровневая система

Инициализация памяти

Память инициализируется автоматически при первом запуске любой команды /speckit.*. Для ручной инициализации:

python scripts/memory/init_memory.py

Это создаст:

  • .claude/memory/ с файлами lessons.md, patterns.md, architecture.md
  • Глобальную директорию ~/.claude/memory/projects/{project-id}/