reefiki 0.2.0

Multi-project markdown wiki and memory control plane for LLM agents.

REEFIKI

AI-агенты быстро помогают, но плохо помнят контекст: решения остаются в чатах, полезные приемы теряются, а следующий агент снова начинает с нуля.

REEFIKI решает эту проблему как локальная вики-память для AI-агентов: она сохраняет не весь шум, а только то, что реально пригодится снова.

English · 中文 · Быстрый старт · Команды

---

Проблема

Работа с AI-агентами часто ломается не из-за кода, а из-за памяти.

После нескольких тредов появляются типичные проблемы:

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

Обычная база заметок тоже не решает это полностью: туда легко складывать все подряд, но трудно отделять reusable knowledge от случайного контекста.

Что Такое REEFIKI

REEFIKI это локальная multi-project distillation wiki для AI-агентов.

Проще:

• у каждого проекта есть своя вики;
• агент сохраняет туда решения, навыки, выводы и источники;
• слабые или временные материалы откладываются, а не засоряют базу;
• все хранится в markdown-файлах и git-истории;
• правила работы описаны в AGENTS.md, поэтому их понимают разные агенты.

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

Типы Проектов

Не все REEFIKI-проекты одинаковые. При создании или подключении проекта можно сразу сказать агенту, какой это профиль:

Профиль	Для чего	Примеры
agent_surface	правила, skills, adapters, diagnostics и recovery для agent/IDE/runtime окружений	Codex, Claude Code, Gemini, Mimo, Hermes
product	продуктовые решения, delivery evidence, UX и release knowledge	Metrica
knowledge_domain	предметная база знаний без основного runtime-слоя	Suno, Instagram, Security Guidance
reefiki_core	правила и governance самого REEFIKI	reefiki

Это ручной onboarding label, а не обязательное поле схемы. Подробно: docs/PROJECT_PROFILES.md.

Зачем Он Нужен

REEFIKI полезен, если ты работаешь с AI-агентами регулярно и хочешь, чтобы они:

• продолжали работу с учетом прошлых решений;
• не повторяли уже пройденные ошибки;
• быстро поднимали проектный контекст;
• сохраняли процедуры как навыки;
• разделяли личную/private память и публичные материалы;
• передавали работу между Codex, Claude Code, Cursor, Windsurf и другими агентами.

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

Как Это Работает

REEFIKI использует простой цикл:

1. Собрать: ссылка, файл, решение или вывод попадает в копилку проекта.
2. Отфильтровать: агент проверяет, можно ли это применить снова.
3. Сохранить: полезное становится страницей вики, навыком, решением или synthesis.
4. Связать: страницы получают связи, индекс и запись в журнале.
5. Поднять позже: следующий агент отвечает уже из накопленной вики, а не из догадок.

Внутри REEFIKI есть несколько типов памяти:

Тип	Что сохраняет
sources	откуда пришла идея или материал
concepts	reusable-понимание
decisions	принятое решение и причина
skills	воспроизводимая процедура
synthesis	выводы из сессии или этапа работы

Рифик

Рифик это маленький reef crab archivist: хранитель рифа-вики, который не тащит в память весь песок, а отбирает только полезные ракушки. В README он работает как метафора: слева шум сессий, в центре дистилляция, справа аккуратная проектная память.

Быстрый Старт

Самый короткий trial без установки:

pipx run reefiki first-run

Постоянная установка:

pipx install reefiki
reefiki first-run

first-run создаёт или переиспользует ~/reefiki-workspace, запускает проверку здоровья и показывает 1-2 следующих шага.

Подробности: QUICKSTART.md и docs/INSTALL.md.

Как Работать После Запуска

После первого запуска можно говорить обычными фразами:

Ты говоришь	Что делает агент
"положи это в копилку"	сохраняет материал на разбор
"разбери копилку"	превращает полезное в wiki-страницы
"запомни это как решение"	сохраняет durable decision
"сохрани как навык"	оформляет повторяемую процедуру
"подключи этот проект к вики"	создаёт отдельную wiki и bridge только после явного подтверждения
"что мы решали про sync?"	отвечает только из накопленной вики
"зафиксируй выводы сессии"	сохраняет synthesis

Что Уже Умеет

• Отдельные wiki-проекты в projects/<name>/.
• Подключение существующего кодового проекта через _wiki.
• Импорт локальных Markdown/Obsidian/Logseq заметок в inbox/ для безопасного cold start.
• Capture -> process -> query -> harvest workflow.
• Agent-agnostic правила через AGENTS.md.
• Ручные project profiles для agent/runtime, product и knowledge-domain проектов.
• Локальные markdown-файлы вместо закрытого облачного storage.
• Журнал изменений и индекс вики.
• Health/lint проверки, чтобы база не превращалась в свалку.
• Handoff context для следующего агента.
• Явные границы между локальной/private памятью и материалами, которые можно публиковать.

Полная карта возможностей: COMMANDS.md.

Что REEFIKI Не Делает

REEFIKI сознательно не является:

• хранилищем всех сообщений чата;
• заменой git, Obsidian или issue tracker;
• автоматическим облачным sync-сервисом;
• векторной базой "на всякий случай";
• системой, которая пишет в любую папку без project boundary.

Если материал нельзя применить снова, его лучше не сохранять в durable wiki.

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

REEFIKI local-first by default:

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

Коротко: REEFIKI делает память полезной, но не размывает границы проекта.

Для Агентов

Агентам не нужно помнить внутренние команды. Они читают AGENTS.md и работают по проектному контракту:

• в корне REEFIKI можно создавать и подключать проекты;
• внутри projects/<name>/ можно сохранять и разбирать знания;
• старые строки wiki/log.md не переписываются;
• raw/ не редактируется;
• все durable writes должны быть объяснимыми и воспроизводимыми.

Это делает REEFIKI переносимым между Codex, Claude Code, Cursor, Windsurf/Cascade, Cline и другими LLM-агентами.

Если проект относится к agent/IDE/runtime окружению вроде Codex, Claude Code, Gemini, Mimo или Hermes, веди его как agent_surface: сохраняй переносимые процедуры, adapters, diagnostics и recovery notes, но не объединяй wikis и не копируй skills автоматически.

Экономия Токенов

REEFIKI снижает расход токенов не магическим сжатием, а тем, что агент читает меньше мусора.

• Вместо всего чата поднимаются короткие страницы decisions, skills, concepts и synthesis.
• Проекты изолированы, поэтому агент не тащит чужой контекст в текущую задачу.
• wiki/index.md и журнал помогают найти нужные страницы без полного перечитывания базы.
• Handoff-пакет собирает ограниченный контекст для следующего агента.
• Слабые материалы остаются в копилке или отказе, а не попадают в постоянную память.

Ориентир, не гарантия: одна короткая decision или skill-страница обычно занимает примерно 500-2 000 токенов и часто заменяет 5 000-30 000 токенов старой переписки. Handoff-пакет обычно разумно держать в районе 2 000-8 000 токенов вместо десятков тысяч токенов истории.

На повторных задачах это часто даёт примерно 50-90% меньше токенов на чтение контекста; для точечного возврата к одному решению или навыку выигрыш может быть 70-95%.

Подробно: docs/TOKEN_ECONOMY.md#русский.

Куда Дальше

• QUICKSTART.md: первый запуск без знания CLI.
• COMMANDS.md: все операции REEFIKI.
• docs/TOKEN_ECONOMY.md: как REEFIKI экономит токены.
• docs/INSTALL.md: установка и smoke-проверка CLI.
• docs/obsidian-setup.md: безопасная настройка Obsidian.
• docs/PUBLIC_DEMO.md: публичное демо и границы.
• docs/RECOVERY.md: восстановление после сбоев.

Публичный roadmap: docs/PUBLIC_ROADMAP.md. Публичный backlog: docs/PUBLIC_BACKLOG.md.

Карта статуса документации: docs/STATUS.md.

License

Код REEFIKI: Apache License 2.0. См. LICENSE.

Контент wiki-проектов принадлежит пользователю, который его создал или добавил.

Благодарности и источники идей

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

• Karpathy LLM Wiki gist: идея компактной, читаемой агентом wiki вместо бесконечного пересказа чатов; фокус на distillation, а не на сыром архивировании.
• REEF protocol: цикл capture -> distillation -> telemetry; разделение дешёвого сохранения, осмысленной переработки и последующего использования.
• Vannevar Bush, "As We May Think": Memex, ассоциативные тропы, личная долговременная память и связанная база знаний вместо одиночных заметок.
• Markdown wiki и Obsidian-подход: локальные markdown-файлы, wikilinks, graph/viewer-мышление и возможность читать знания без облачного сервиса. REEFIKI не является клоном Obsidian: source of truth остаётся в репозитории и agent-aware правилах.
• Git worktree workflow: идея изолированной работы над задачами, reviewable изменений и аккуратного разделения локального/private контента от публичного snapshot.
• memoir: короткая рабочая память и preferences как отдельный слой. В REEFIKI это optional short-memory provider; durable truth остаётся в markdown wiki.
• Graphify и graph-based retrieval: граф структуры кода, файлов и документов как слой навигации и candidate selection. REEFIKI не становится graph database, а использует graph-подход для поиска связей и компактного контекста.
• CodeGraph-style navigation: одноразовые impact/callgraph/relationship-запросы по коду как помощник разработчика, не как долговременная память.
• Agent/IDE runtimes: Codex, Claude Code, Cursor, Windsurf/Cascade, Cline, Gemini, Mimo и Hermes повлияли на vendor-neutral AGENTS.md, project profiles, portable rules и переносимые runbooks.
• Local-first security practice: явные project boundaries, проверка публичных материалов, append-only logs, immutable raw/ и отказ от широкого сохранения всего подряд как REEFIKI-specific safety layer.

Итоговая идея REEFIKI: соединить wiki, agent workflow, short memory, graph navigation и Git discipline в один local-first процесс, где знания можно проверить, перенести и безопасно опубликовать.