Graphify. Граф знаний для проекта

# AI Agent Rules — ai-kimi-1idea

> **Обязательно к прочтению:** `.kimi/rules.md` — универсальные правила работы AI в этом проекте (анализ рисков, workflow, формат ответа). Этот файл дополняет их проектной спецификой.

>

> **Язык общения:** AI всегда отвечает на языке пользователя. Пишет пользователь по-русски — ответ на русском. Пишет по-английски — ответ на английском. См. `.kimi/rules.md` → раздел 0.

>

> **AGENTS.md — не статичный документ.** Если правило устарело, мешает, дублируется или чего-то не хватает — предложи изменения и жди одобрения. Не меняй AGENTS.md без одобрения пользователя.

---

## 1. Общие принципы

### 1.1. Обязательное согласование перед выполнением

- Если задача неоднозначна, есть сомнения, есть лучший способ решения или есть риски — **обязательно сообщи об этом перед выполнением**.

- **Не начинай** выполнение задачи, пока пользователь не одобрит твой план.

- Всегда предлагай улучшения: что можно изменить, добавить, убрать.

### 1.2. Качество превыше скорости

- **Production-ready реализация.** Код должен быть готов к продакшену без дополнительного рефакторинга.

- Никаких временных решений, костылей, заглушек.

- Масштабируемая архитектура.

- Если выбор между скоростью и качеством — выбираем качество.

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

### 1.3. Проактивная коммуникация

- Если видишь ошибку в коде — сообщи.

- Если видишь, что можно улучшить — сообщи.

- Если получил важную информацию в чате — сохрани её в базу знаний.

- Всегда предлагай улучшения, даже если их не просили.

### 1.4. Честность и ответственность

- **Не обманывать:** не гадать вместо проверки, не говорить "невозможно" без теста, не обещать то, что не проверено.

- **Тестировать, а не предполагать:** каждое утверждение о скорости/качестве должно быть проверено. Бенчмарк перед выводами. Генерация перед заявлениями о качестве.

- **Честность в отчётах:** показывать реальную генерацию, а не loss. Loss ≠ качество. Генерация — единственный критерий.

---

## 2. Специфика проекта

### 2.1. Цель проекта

Создать **прорывной CPU-оптимизированный ИИ общего назначения**, который:

1. **Работает и обучается на CPU** — без обязательной GPU, с максимально возможной скоростью на обычном процессоре.

2. **Быстро обучается** — часы/дни на CPU вместо недель, благодаря эффективной архитектуре и компилированному forward pass.

3. **Быстро работает** — генерация текста и кода в тысячи токенов в секунду на CPU.

4. **Обрабатывает многомиллионный контекст** — 1M+ токенов без потери когерентности, через внешнюю память или recurrent state с O(1) ростом памяти на токен.

5. **Ведёт нормальный связной чат** — с логикой, пониманием контекста, способностью вести длинный диалог.

6. **Является хорошим программистом** — пишет код с нуля, понимает архитектуру проектов, способен самостоятельно создать большой проект от идеи до работающего кода.

7. **Достигает прорывного уровня** — не просто "работает", а действительно умный ИИ, полезный в реальных задачах.

8. **Если архитектура не работает** — она **удаляется** и изобретается новая (провал фиксируется в `docs/failures.md`).

### 2.2. Текущая стратегическая задача (активная)

> **Правило:** НЕ приступать к разработке новых фичей (frontend, API, чат-интерфейс) пока не найдена архитектура, генерирующая связной текст.

1. **Систематически протестировать ВСЕ существующие архитектуры** проекта:

   - Обучить каждую минимум до ранних признаков генерации (2K–10K шагов).

   - Замерить: train loss, val loss, tok/s, RAM, perplexity.

   - Проверить генерацию на 5 стандартных промптах (чат + код).

   - Оценить: связность, отсутствие циклов, осмысленность.

2. **Найти лучшую архитектуру** по соотношению:

   - Качество генерации (главный критерий)

   - Скорость обучения (tok/s)

   - Скорость генерации (tok/s inference)

   - Стабильность градиентов

   - Потенциал масштабирования

3. **Если ни одна существующая архитектура не генерирует связной текст** — изобрести **новую архитектуру**, которой нет в мире:

   - Кардинально новый подход (не Transformer, не RNN, не CNN-копия).

   - Оптимизирована для CPU: быстрое обучение, быстрая генерация кода.

   - Поддержка многомиллионного контекста через O(1) память на токен.

   - Проверка на деле: 50K шагов → тест чата + тест кода.

4. **Развивать только победителя.** Все ресурсы — в лучшую архитектуру.

### 2.3. Ключевые компоненты

- **Архитектуры моделей:** KSN (ksn/, ksn_c/, models/ksn*.py), OmegaSpike (omegaspike/, omegaspike_c/), Omega1 (omega1/, omega1_c/), MonolithV4 (growing_monolith_v4.py, monolith/), PNF/PNF_NTM (models/pnf*.py, flux/), Reservoir (reservoir_c/, models/reservoir.py), Ternary MoE (ternary_moe_c/), SpatialShiftLM (models/spatial_shift.py), LRRN, DCAT, Titan, SACE, Fourier KAN, RWKV (sigma_integration/), HDC (hdc_engine/), Rust inference (rust_inference/). Полный список — в `docs/project-index.md`.

- **Токенизация:** N-gram BPE 1024 (`data/ngram_bpe_1024.json`) — единственный проверенный токенизатор. См. `docs/PERMANENT_MEMORY.md`.

- **Данные:** `data/super/proper_mix_train.bin` (25.8M tokens, основной датасет), `data/synth_diverse_5mb.bin`, `data/micro/micro_chat_100kb.bin`. Исходные `.txt`-дампы исключены из графа знаний из-за размера.

- **Тренировочные движки:** Numba/C/Python wrappers в `ksn_c/`, `omega1_c/`, `omegaspike_c/`, `reservoir_c/`, `ternary_moe_c/`.

- **Оценка и бенчмарки:** `benchmark_all.py`, `evaluate.py`, `judge_models.py`, `tournament.py`, `results/`.

### 2.4. Стек технологий

- **Языки:** Python 3.12 (основной), C/C++ (compiled forward), Rust (hdc_engine, rust_inference), Shell.

- **Библиотеки:** PyTorch (только для reference/backprop readout), Numba, NumPy, tokenizers, ctypes.

- **Инструменты:** Graphify (`graphify-out/`), Make, GCC/MSVC для сборки C-расширений.

- **Ограничение:** всё должно работать и обучаться на CPU. GPU — опциональный ускоритель.

### 2.5. Философия: полная свобода подхода и изобретений

- **Нет ограничений** на язык программирования (Python, C++, Rust, Go, Julia, ассемблер — что угодно, включая самопридуманные языки).

- **Нет ограничений** на архитектуру (нейросеть, компилятор, эволюционный алгоритм, внешняя БД, LLM-агент — что угодно).

- **«Чёрный ящик» приветствуется** — не важно, как устроена модель внутри, важен только результат генерации.

- **Не обязано быть понятно человеку:** язык может быть нечитаемым, архитектура непонятной, система — магией. Главное — результат.

- **Полная свобода изобретений:** можно придумать и изобрести всё что угодно — новые языки, новые архитектуры, новые парадигмы, то чего ещё нет и никто не пробовал.

- **Архитектуры без аналогов:** можно и нужно изобретать архитектуры, которых нет в мире. Не копировать Transformer/RNN/CNN — придумывать кардинально новые подходы.

- **Импровизация:** эксперименты, безумные идеи, комбинации несовместимого — всё разрешено. Главное — проверить на деле.

- **Оптимальный язык:** перед реализацией оценивать, какой язык/инструмент даст максимальное ускорение (C, C++, Rust, Zig, Nim, Fortran — не ограничиваться привычками).

### 2.6. Объективный вердикт: не упустить прорывную идею

- **НЕ признавать архитектуру мёртвой из-за невалидного теста.** Перед вердиктом «тупиковая идея» обязательно провести rescue: проверить ёмкость (params), гиперпараметры, архитектурные вариации, градиенты, баги в forward/backward/generate, in-domain промпты, greedy decoding, правильный токенизатор/данные, достаточно шагов/эпох, CPU load.

- **Цель:** не упустить прорывную идею из-за объективно неправильного теста.

- **Если после валидного rescue generation остаётся мусором** — зафиксировать провал в `docs/failures.md` и удалить код.

---

## 3. Правила программирования

### 3.1. Общие требования к коду

- **Модульность**, чёткие интерфейсы, минимум глобального состояния.

- **Полная обработка ошибок** — не молчаливое игнорирование.

- **Логирование** ключевых событий (особенно при обучении: loss, скорость, память, чекпоинты).

- **Пользовательские сообщения об ошибках** должны быть понятны.

- **Оптимизация производительности:** lazy loading, caching, code splitting, vectorization, компилированные критичные участки.

- **Тестирование критичного кода:** forward pass, backward pass, градиенты, генерация.

### 3.2. Специфика экспериментального кода

- **Forward pass должен быть скомпилирован:** C/Rust/Numba. PyTorch CPU forward для тренировки запрещён.

- **Рекуррентное состояние обязательно:** любая sequence-модель должна передавать состояние от токена к токену; bag-of-words архитектуры — тупиковые.

- **Сначала greedy decoding:** `temperature=0, top_k=1` перед любой сэмплинг-оценкой.

- **Tokens/param ≥ 20** — чтобы избежать катастрофического недообучения.

- **Минимум 1 полная эпоха** перед судом о модели.

- **In-domain промпты:** тестовые промпты должны встречаться ≥10 раз в обучающих данных.

### 3.3. Типизация

- Для Python: **type hints обязательны** для публичных функций и классов. Избегать неявного `Any`.

- Для C/C++/Rust: строгие типы по умолчанию.

---

## 4. Управление знаниями

### 4.1. База знаний проекта

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

- Используй:

  - `docs/PERMANENT_MEMORY.md` — для важных проектных выводов, статусов архитектур, решений.

  - `docs/failures.md` — для зафиксированных провалов архитектур.

  - `graphify-out/memory/notes.md` — для текстовых заметок (если используется Graphify memory).

  - `graphify-out/memory/facts.json` — для структурированных фактов (SPO).

  - **Graphify** (`graphify-out/graph.json`, `graphify query`) — для графа знаний проекта.

- Перед началом работы в новом окне контекста всегда читай сохранённые знания.

### 4.2. Поддержка документации в актуальном состоянии

- Документация не должна дублироваться, устаревать или противоречить коду.

- Проверяй дублирование, устаревание, появление новой информации.

- Предлагай правки и жди одобрения.

- Ключевые файлы: `README.md`, `docs/PERMANENT_MEMORY.md`, `docs/failures.md`, `docs/project-index.md`, `docs/TESTING_PIPELINE.md`, `docs/TRAINING_WORKFLOW.md`, `TOURNAMENT_RULES.md`.

### 4.3. Граф знаний Graphify

- **Автоматически обновляй граф знаний** при значимых изменениях (новая архитектура, удаление архитектуры, изменение ключевых интерфейсов, новые документы).

- Используй `graphify query` для поиска релевантного кода и связей при ответах на вопросы о проекте.

- Избегай дублей в графе.

---

## 5. Процесс работы над задачей

1. **Понимание** — перефразируй задачу, задавай уточняющие вопросы.

2. **Анализ** — проверь код, найди связи через Graphify, выяви риски.

3. **Предложение** — если есть варианты, предложи и жди одобрения.

4. **Реализация** — пиши production-ready код.

5. **Проверка** — тесты, бенчмарки, генерация, типизация, линтер.

6. **Обновление знаний** — сохрани выводы в `docs/PERMANENT_MEMORY.md`, `docs/failures.md`, обнови Graphify.

7. **Отчёт** — кратко сообщи, что сделано, с реальными цифрами и генерацией, если применимо.

---

## 6. Запрещено

- Временные решения, костыли, заглушки.

- Молчаливое игнорирование ошибок.

- Выполнение без одобрения при неопределённостях.

- Дубли в базе знаний.

- Изменения без проверки.

- PyTorch CPU forward pass для тренировки.

- Bag-of-words / non-recurrent языковые модели.

- Хранение "на всякий случай" тупиковых архитектур.

- Оценка качества только по loss — генерация обязательна.

---

## 7. Файлы, которые агент должен знать

### 7.1. Правила и память

- `.kimi/rules.md` — универсальные правила AI.

- `AGENTS.md` — этот файл (проектная специфика).

- `docs/PERMANENT_MEMORY.md` — долгосрочная память проекта.

- `docs/failures.md` — архив провалов.

- `docs/project-index.md` — указатель по проекту.

### 7.2. Документация

- `README.md` — общее описание.

- `docs/NAVIGATION.md` — навигация по проекту.

- `docs/TESTING_PIPELINE.md` — этапы тестирования.

- `docs/TRAINING_WORKFLOW.md` — рабочий процесс обучения.

- `TOURNAMENT_RULES.md` — правила турнира архитектур.

- `PROJECT_RULES.md` — дополнительные проектные правила.

### 7.3. Архитектуры и код

- `models/` — базовые PyTorch/Numba реализации.

- `ksn_c/`, `omega1_c/`, `omegaspike_c/`, `reservoir_c/`, `ternary_moe_c/` — C-ядра и тренировочные движки.

- `monolith/`, `omega1/`, `omegaspike/`, `flux/`, `utils/` — модули архитектур.

- `hdc_engine/`, `rust_inference/` — Rust компоненты.

- `sigma_integration/` — интеграция с Sigma/RWKV.

### 7.4. Данные и токенизация

- `data/ngram_bpe_1024.json` — единственный проверенный токенизатор.

- `data/super/proper_mix_train.bin`, `data/synth_diverse_5mb.bin`, `data/micro/micro_chat_100kb.bin` — ключевые датасеты.

- `build_ngram_tokenizer.py`, `ngram_tokenizer.py`, `tokenizer_v2.py` — скрипты токенизации.

### 7.5. Тренировка и оценка

- `train_*.py` — скрипты обучения конкретных архитектур.

- `benchmark_all.py`, `evaluate.py`, `judge_models.py`, `tournament.py` — сравнение и оценка.

- `results/` — результаты экспериментов, отчёты, generation logs.

- `generate.py`, `generate_comparison.py` — генерация текстов.

### 7.6. Граф знаний

- `graphify-out/graph.json` — построенный граф знаний.

- `graphify-out/GRAPH_REPORT.md` — аудит графа.

- `graphify-out/.graphify_labels.json` — метки сообществ.

---

## 8. Ссылки

- Турнирные правила: `TOURNAMENT_RULES.md`

- Финальный отчёт: `FINAL_REPORT.md`

- Итоговое сравнение: `UNIFIED_RESULTS.md`

- Внешние ресурсы: `docs/external_resources.md`

 

 

 

# AGENTS.md

> Этот файл содержит постоянные правила работы AI в данном проекте.
> Claude Code должен автоматически учитывать эти инструкции во всех новых сессиях.

---

# Общие принципы

## Главная цель

Главная цель — создавать качественный, безопасный, масштабируемый и production-ready код.

Приоритеты:

1. Качество
2. Надежность
3. Архитектура
4. Производительность
5. Скорость реализации

Если между скоростью реализации и качеством есть конфликт — всегда выбирать качество.

---

# Перед выполнением любой задачи

Перед тем как писать код, обязательно:

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

Если в проекте установлен Graphify — использовать его как основной источник информации о проекте.

Если Graphify отсутствует — использовать встроенный анализ проекта Claude Code.

---

# Анализ проекта

Перед созданием нового кода необходимо:

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

Запрещается писать новый код без предварительного анализа проекта.

---

# Graphify

Если Graphify установлен:

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

После крупных изменений архитектуры предложить обновить граф знаний.

---

# MCP

Если доступны MCP-серверы:

использовать их автоматически, если они способны улучшить качество решения.

Не использовать MCP без необходимости.

---

# Архитектура

Не изменять архитектуру проекта без необходимости.

Если найден лучший вариант архитектуры:

1. сообщить пользователю;
2. объяснить преимущества;
3. дождаться подтверждения.

Только после этого выполнять изменения.

---

# Production Ready

Каждая реализация должна соответствовать следующим требованиям:

- production-ready;
- масштабируемость;
- читаемость;
- расширяемость;
- отказоустойчивость;
- безопасность;
- высокая производительность.

---

# Запрещено

Запрещается:

- писать временный код;
- оставлять TODO без согласования;
- создавать костыли;
- писать дублирующий код;
- игнорировать ошибки;
- делать предположения без проверки.

---

# Обработка ошибок

Любой возможный сценарий ошибки должен быть обработан.

Ошибки должны:

- логироваться;
- содержать понятное описание;
- не приводить к падению приложения без необходимости.

---

# Производительность

При написании кода учитывать:

- использование памяти;
- скорость выполнения;
- масштабируемость;
- возможность дальнейшей оптимизации.

---

# Безопасность

Всегда учитывать:

- SQL Injection;
- XSS;
- CSRF;
- Path Traversal;
- Race Conditions;
- утечки памяти;
- утечки ресурсов;
- переполнение буферов;
- безопасность API;
- безопасность файловой системы.

---

# Повторное использование

Перед созданием:

- класса;
- функции;
- сервиса;
- интерфейса;
- модели;

необходимо проверить, существует ли аналогичная реализация.

Если существует — использовать её.

---

# Документация

Если изменения требуют обновления документации:

предложить пользователю обновить:

- README.md
- AGENTS.md
- ARCHITECTURE.md
- ROADMAP.md
- CHANGELOG.md

---

# Код

Код должен быть:

- понятным;
- хорошо структурированным;
- модульным;
- расширяемым;
- документированным;
- легко тестируемым.

---

# Предложения

Если найдено:

- архитектурное улучшение;
- потенциальная ошибка;
- нарушение best practices;
- проблема производительности;
- проблема безопасности;

обязательно сообщить пользователю до выполнения задачи.

---

# Общение

Всегда отвечать на языке пользователя.

Если пользователь пишет на русском — отвечать на русском.

Если пользователь пишет на английском — отвечать на английском.

---

# Проверка

Перед завершением задачи проверить:

- корректность;
- производительность;
- безопасность;
- архитектуру;
- типизацию;
- обработку ошибок;
- соответствие требованиям проекта.

---

# Главный принцип

Перед написанием нового кода:

Сначала анализ.

Потом предложение.

Потом реализация.

Никогда наоборот.