Skip to content

00-overview.md

Latest commit

 

History

History
82 lines (61 loc) · 5.27 KB

00-overview.md

File metadata and controls

82 lines (61 loc) · 5.27 KB
Raw

Code Memory Service — обзор

Проблема

LLM-агент на растущей кодовой базе теряет контекст:

  • Дорогое исследование. Чтобы понять область кода, агент делает каскад Read. Каждое чтение оседает в контексте навсегда.
  • Потеря рассуждения между сессиями. Решения, проговорённые в диалоге («пробовали X, не сработало из-за Y, выбрали Z»), исчезают при закрытии сессии. Commit фиксирует что сделано, не почему именно так.
  • Разрастание спецификации. Проектная документация множится и сама пожирает контекст — приходится постоянно её чистить, и это урезает объём работы по каждой задаче.

Что это

Сервис хранения и поиска знаний о коде — заметок о том, как и почему пришли к текущему коду, привязанных к нему гибкими якорями. Заметка отвечает на вопрос «как пришли»; код и docstring — на «как пользоваться».

Работает как MCP-сервер. Source of truth — markdown-файлы в .memory/ внутри репозитория проекта. SQLite рядом — производный индекс для скорости поиска.

Разворачивается как постоянный Docker-контейнер рядом с проектом — отдельный сервис в его docker-compose.yml, со своим .memory/ и своим индексом. Claude Code обращается к нему по MCP через HTTP. Подробности — в 08-technical-design.md.

Три сущности

  • Заметка — запись знания.
  • Якорь — связь заметки с файлом, символом, доменной сущностью или env.
  • Доменная сущность — поименованный концепт предметной области.

См. 01-domain-model.md.

Ключевые принципы

  • Связность — только через якоря. Ни тегов, ни графа отношений.
  • Markdown — source of truth; SQLite — производное, пересобираемое.
  • Ленивая выдача: компактный список → разворот по требованию.
  • Главное в поиске — отсечка шума, а не точная сортировка.
  • Устаревание — явным статусом, не молчаливым автоапдейтом.
  • Минимализм: поле или механизм существует, только если меняет поведение и не дублирует другое.

Что сервис не делает

  • Не индексирует код фреймворка и библиотек — это Context7 и веса модели.
  • Не делает cross-reference анализ (call graph, поиск usage'ей). tree-sitter используется только для «какие символы определены в каком файле».
  • Не хранит метаинформацию внутри файлов кода.
  • Не привязывается к git-SHA — логическая единица это знание, не коммит.
  • Не реконструирует «почему так» без явного источника.

Композиция

  • Context7 — знание о фреймворках и публичных библиотеках.
  • Code Memory Service — решения по вашему коду.
  • Векторный (семантический) слой — опционально, добавляется позже.

Каждый слой отвечает за одну вещь; пересечений нет.

Один сервис — один проект

Один контейнер обслуживает одну кодовую базу. Нет multi-tenancy, .memory/ лежит рядом с кодом, исключён класс багов с подтягиванием чужого контекста.

Карта документов

Документ Содержание
00-overview.md Этот документ
01-domain-model.md Три сущности на уровне бизнес-логики
02-data-model.md Поля, типы, связи, индекс
03-search-and-retrieval.md Поиск, ранжирование, навигация
04-note-authoring.md Дисциплина создания заметки
05-interfaces.md MCP-инструменты и CLI
06-onboarding.md Онбординг существующих проектов
07-skill.md Скилл на стороне Клода
08-technical-design.md Техническое видение, стек