Claude Code on Mikhail Shogin

Архитектура памяти для AI-агентов: как я научил Claude Code помнить

Wed, 11 Feb 2026 00:00:00 +0000

Боль: агент с амнезией

Каждый, кто работает с AI-агентами, знает ощущение: ты объяснил контекст проекта, показал структуру, обсудил решения - а в следующей сессии агент всё забыл. Опять здрасьте. Опять “расскажите про ваш проект”.

Это как работать с архитектором, у которого каждое утро стирается память. Он талантлив, быстр, но каждый день - новый человек.

У меня 12+ активных контекстов: рабочие проекты (Wildberries), личные проекты (aitrader, archlint), блог, коучинговая практика, обучение, целеполагание. Переключение между ними без памяти превращалось в ритуал: 5-10 минут на “загрузку контекста” в начале каждой сессии.

Стало ясно: нужна архитектура памяти.

Как устроена человеческая память

Прежде чем проектировать, я посмотрел на то, как работает память у людей. Параллельно с архитектурой я изучаю коучинг - и там постоянно всплывает тема того, как люди обрабатывают информацию. Заметил структурное сходство.

flowchart TD A["Входящие данные"] --> B["Рабочая память\n(Short-Term)\nАктивные задачи,\nтекущий контекст"] B --> C{"Фильтр ценности\n(еженедельный ревью)"} C -->|"Ценно"| D["Долговременная память\n(Long-Term)\nПаттерны, принципы, уроки"] C -->|"Обработано"| E["Архив\n(забыто, но доступно)"]

У людей так же:

Рабочая память (Short-Term) - то, с чем работаешь прямо сейчас. Ограничена: ~7 элементов одновременно. Через 3-6 месяцев без обращения - забывается.
Долговременная память (Long-Term) - дистиллированные знания. Не “что я делал во вторник”, а “какой паттерн я увидел за три месяца работы”.
Архив - не удалено, но не на поверхности. Доступно при целенаправленном поиске.

Ключевой момент: переход из Short-Term в Long-Term - не автоматический. Нужна осознанная обработка. В коучинге это рефлексия. В моей системе - еженедельный ревью.

Архитектура решения

Три уровня памяти

Я реализовал три уровня, зеркалирующих человеческую модель:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


~/my/org-roam/
+-- Short-Term-Memory/ # Рабочая память (3-6 месяцев)
| +-- Wildberries/ # Рабочий контекст
| +-- Coaching/ # Коучинговые сессии
| +-- daily/ # Ежедневные заметки
| +-- todos.md # Задачи
|
+-- Long-Term-Memory/ # Долговременная память
| +-- Coaching/ # Методики, паттерны, кейсы
| +-- Architecture/ # Архитектурные решения
| +-- Posts/ # Публикации
| +-- Personal/ # Личные принципы
|
+-- Archive/ # Архив (по месяцам)
 +-- 2026/
 +-- 01-January/
 +-- 02-February/

Short-Term - inbox для всего нового. Сырые заметки, текущие задачи, эксперименты. Максимум 50 активных файлов. Если больше - пора делать ревью.

Long-Term - база знаний. Сюда попадает только то, что прошло фильтр ценности:

Переиспользуемость (применимо 3+ раз)
Обучающая ценность (ага-момент, важная ошибка)
Референсная ценность (пример для копирования)

Archive - завершенные проекты, обработанные заметки. Не удалено, но убрано с глаз.

Контексты: переключение за секунду

Вторая проблема - переключение между проектами. Решение: система контекстов.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
 "contexts": {
 "coaching": {
 "name": "coaching",
 "description": "Коучинговые сессии и практика развития",
 "directory": "~/my/coaching",
 "memory": {
 "short_term": "~/my/org-roam/Short-Term-Memory/Coaching",
 "long_term": "~/my/org-roam/Long-Term-Memory/Coaching"
 }
 },
 "archlint": {
 "name": "archlint",
 "description": "ArchLint - линтер архитектуры Go проектов",
 "directory": "~/my/archlint",
 "memory": {
 "short_term": null,
 "long_term": null
 }
 }
 }
}

Каждый контекст знает:

directory - рабочая директория проекта
memory.short_term - где хранить текущие заметки
memory.long_term - где хранить дистиллированные знания

Переключение: одна команда /w coaching - и агент знает где он, что помнить, какие файлы читать.

Индекс активностей: навигация по всему

Контексты решают проблему “где я”. Но остается вопрос: “где искать информацию по теме X?”. Для этого - глобальный индекс активностей.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


### Коучинг / Практика

- Keywords: сессия, клиент, практика, рефлексия
- Файлы:
 - Практика: ~/my/org-roam/Long-Term-Memory/Coaching/03-Практика/
 - Гайды сессий: ~/my/org-roam/Long-Term-Memory/Coaching/session-guides/INDEX.md

### Здоровье и психология

- Keywords: психолог, здоровье, границы, стыд
- Файлы:
 - Темы: ~/my/org-roam/Long-Term-Memory/Темы для психолога.md
- Связанные активности: Коучинг / Запросы для проработки

Принцип работы:

flowchart TD A["Промпт пользователя"] --> B["Поиск по keywords\nв memory-index.md"] B --> C{"Найдена\nактивность?"} C -->|"Да"| D["Работай в её контексте"] C -->|"Нет"| E["Спроси пользователя,\nпредложи варианты"]

Кросс-контекстный поиск: связи между контекстами

Самая интересная архитектурная задача. Информация часто пересекает границы контекстов.

Пример: тема “границы” может всплыть в коучинге (запрос клиента), в психологии (тема для терапии), в рабочем контексте (обратная связь коллеге). Как не потерять связь?

Решение: кросс-ссылки на уровне глобального индекса, а не дублирование информации между контекстными индексами.

flowchart TD G["memory-index.md\n(глобальный индекс)"] --> C1["Coaching\nINDEX.md"] G --> C2["Здоровье\n(файлы)"] G --> C3["Работа\nINDEX.md"] G --> C4["..."] C1 -.-|"кросс-ссылка"| C2 C2 -.-|"кросс-ссылка"| C3 style G fill:#0f3460,color:#fff style C1 fill:#533483,color:#fff style C2 fill:#533483,color:#fff style C3 fill:#533483,color:#fff style C4 fill:#333,color:#999

Правило: каждый контекстный индекс отвечает только за свой контекст. Связь между контекстами - через поле “Связанные активности” в глобальном индексе.

1
2
3
4
5
6


## Кросс-ссылки между активностями

| Активность A | Активность B | Связь |
|--------------------------|------------------------|-------------------------------------|
| Коучинг / Запросы | Здоровье и психология | Запрос #11 = Тема #2 (границы) |
| Семья | Коучинг / Запросы | Запрос #3 (темы с супругой) |

Антипаттерн: дублировать ссылки на “Темы для психолога” внутри Coaching/INDEX.md. Это нарушает single responsibility - индекс коучинга не должен знать про психологию. Связь - только через глобальный уровень.

Жизненный цикл знаний

Данные без обработки - мусор. Система памяти работает, только если есть процесс трансформации.

flowchart LR subgraph ST ["Short-Term (сырые данные)"] A1["Заметки по сессии\nс клиентом X"] A2["Тикеты проекта\nархитектуры"] A3["Исследование\nTarjan алгоритма"] end subgraph LT ["Long-Term (знания)"] B1["Паттерн: Работа с\nпрокрастинацией\nчерез ценности"] B2["ADR-0042: Выбор\nмежду монолитом\nи микросервисами"] B3["Библиотека\nалгоритмов\nпоиска циклов"] end A1 -->|"трансформация"| B1 A2 -->|"трансформация"| B2 A3 -->|"трансформация"| B3

Критерии перехода в Long-Term

Не всё заслуживает долговременной памяти. Четыре фильтра:

Переиспользуемость - применимо 3+ раз (методики, шаблоны, чек-листы)
Обучающая ценность - ага-момент, важная ошибка, смена парадигмы
Референсная ценность - пример для копирования (код, кейс, формат)
Паттерн - повторяющаяся проблема + решение

Всё остальное - одноразовые заметки, устаревшие TODO, рутинные логи - удаляется или уходит в архив.

Еженедельный ревью

Раз в неделю - 30-40 минут на обработку Short-Term:

Просмотреть файлы за неделю
Выделить ценное для Long-Term
Трансформировать: сырые данные -> структурированные знания
Архивировать обработанное
Удалить мусор

Метрики здоровой системы:

Short-Term: 30-50 активных файлов
Long-Term: +2-5 новых записей в неделю
Archive: регулярное пополнение

Параллель с коучингом

Когда я проектировал эту систему, я заметил параллели с тем, что изучаю в коучинге.

Short-Term = Рабочая осознанность

Когда человек разбирается в сложной ситуации, он сначала выгружает всё, что на поверхности: факты, эмоции, людей, обстоятельства. Это рабочая память - хаотичная, перегруженная, но актуальная. Short-Term Memory в моей системе работает так же: собирает всё, что сейчас активно, без фильтрации.

Long-Term = Мудрость через рефлексию

Long-Term - это не “запомнить всё”. Это “понять, что важно”. Лучшие инсайты приходят не в момент обсуждения, а позже - когда человек рефлексирует и видит паттерн. Еженедельный ревью - это та самая рефлексия, только для базы знаний.

Кросс-контекст = Системное мышление

Проблема редко живет в одном контексте. Одна и та же тема может всплыть и на работе, и в личных проектах, и в обучении. Кросс-ссылки в системе памяти - это способ видеть одну тему с разных сторон, расширить перспективу.

Architect of Thinking

Изучая коучинг, я разработал авторский фреймворк на стыке архитектуры и работы с мышлением - Architect of Thinking. Формула:

Контекст -> Цель -> Карта -> Узел -> Решение -> Шаг

Это ровно то, как архитектор работает с системой: сначала изучи (контекст), определи цель, построй карту, найди bottleneck (узел), спроектируй решение, сделай первый шаг. Тот же подход - к человеческим задачам.

Результаты

До системы памяти:

5-10 минут на “загрузку контекста” каждую сессию
Потеря решений между сессиями
Дублирование работы
Невозможность связать темы между контекстами

После:

Переключение контекста за 1 команду
Знания накапливаются и структурируются
Связи между контекстами через кросс-ссылки
Еженедельный ревью превращает данные в знания

Что дальше

Система живая - она развивается вместе с моими проектами. Следующие шаги:

Автоматизация ревью (AI-помощник для еженедельной обработки Short-Term)
Семантический поиск по Long-Term Memory
Версионирование знаний (как знания меняются со временем)

Но главный урок не технический. Проектируя память для AI-агента, я лучше понял, как работает моя собственная. И это, пожалуй, самый ценный побочный эффект.

Исходный код и конфигурации описаны для Claude Code (Anthropic CLI). Подход применим к любому AI-агенту с файловой системой.

$HOME in Git: One Config for Claude Code

Fri, 09 Jan 2026 00:00:00 +0000

Multiple projects. Each with its own CLAUDE.md, its own rules. You improve something in one place - you want it elsewhere. Copy. Improve there. Copy back. Round and round.

At some point I had a mess of different versions of the same rules scattered across a dozen projects. The copy-paste circus was annoying, but I kept putting it off.

During the New Year holidays, I decided to fix it.

The Solution

Moved everything to my home directory ~/.claude/. One config for all projects.

Yes, I’m now coupled to my home directory structure. But that structure hasn’t changed in years - ~/my/ for projects, ~/education/ for learning, ~/family/ for family stuff. Risk is minimal.

Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


~/.claude/
 CLAUDE.md # Core principles (task confirmation, formatting)
 HOME_MAP.md # Home directory map for navigation

 rules/ # Rules (auto-loaded)
 architecture.md # Architecture principles
 coaching-layer.md # Coaching questions
 text-dna.md # Writing style
 home-navigation.md # Context detection by keywords
 projects/ # Project-specific rules
 aitrader.md # Rules for aitrader

 commands/ # Slash commands
 ms-todos.md # /ms-todos - task list
 ms-add-note.md # /ms-add-note - add note
 ...

 skills/ # Skills
 blog-writing/ # Blog post writing
 go-review/ # Go code review
 social-content/ # Social media content

 agents/ # Custom agents
 go-reviewer.md # Go code reviewer

 hooks/ # Hooks
 session-logger.py # Session logging

The key file is HOME_MAP.md. It’s a map of the entire home directory with context detection rules.

Claude sees keywords in your request and knows which directory to work in:

aitrader, archlint, blog -> ~/my/
course, book, learning -> ~/education/
memory, remember, mission -> ~/my/org-roam/

If context is ambiguous - it asks.

Project-Specific Rules

Need specific rules for a project? Add them to rules/projects/. For example, aitrader.md contains:

How to run the collector (without proxy for Tinkoff API)
Test commands
Project specifics

These rules load globally but apply only when working in the aitrader context.

Git

Everything under git. One repository, one history.

.gitignore is large - it excludes almost everything that shouldn’t be versioned: credentials, caches, Downloads, Documents, Library, .ssh. But everything else - configs, .claude/, dotfiles - is tracked. Planning to add private repos as submodules, so one git clone restores the entire home directory.

No more copying between projects. Improve a rule once - it works everywhere.

Result

Before: a dozen projects with scattered CLAUDE.md files, constant copying, different versions of the same thing.

After: one ~/.claude/, structured rules, git for versioning. Improve once - works everywhere.

Downside: tight coupling to home directory structure. For me it’s not a problem - the structure is stable.

Spec-driven development: Reproduce a project from specs alone

Mon, 05 Jan 2026 00:00:00 +0000

Ran an experiment: can you reproduce a project if you give AI only specifications without source code?

Setup

Original project: archlint - a Go architecture analysis tool
Input: 10 specifications (Markdown + PlantUML), totaling 73 KB.
Claude Code received an empty directory and specs
Executor: Claude Code, started in an empty directory and implemented the project from scratch.

Specs covered all the basics: module init, Makefile, data model, Go-analyzer, Cobra CLI, collect/trace commands, tracer library, tracelint, and integration tests.

Time

~20 minutes from empty directory to working project.

Results

Final assessment of the cloned repository:

Structural identity: 100%
Cloning success: 85.5%
Semantic equivalence: ~75%
Mutations: 23 (3 critical, 8 medium, 12 minor)

Interesting detail: the clone turned out shorter than the original - 1,845 lines of Go vs 2,159 (-14.5%) with the same number of .go files (13).

Mutations that actually matter

Three “critical” mutations - exactly the places where the specification leaves room for interpretation (i.e., for creativity you didn’t order):

Sequence diagram building: changed the algorithm for forming calls in the diagram (logic for call stack and write conditions).
Tracerlint: clone considers deprecated Exit() call acceptable, while the original does not.
GoAnalyzer: added baseDir and modulePath fields - AI “improved” the model because the specs didn’t explicitly define the analyzer’s responsibility boundary (what to store inside, what to compute outside).

Takeaway

Spec-driven development works as a mechanism for reproducing the “functional core”. 73 KB of specifications was enough to quickly restore structure and core functionality.
Critical deviations occur where the specification describes “what should be” but doesn’t define “how to verify it”. For such places you need:
- precise rules (invariants),
- input/output examples,
- golden tests (byte-by-byte/structural comparison),
- prohibition on “model extension” without an explicit spec item.

In short: AI can clone a project from specs quickly. But if there’s a gap in the specs - it will definitely squeeze in some “engineering optimization”. Sometimes useful. In critical places - usually not.

Clone repository: mshogin/archlint-reproduction