@bloodyeagle/megamemory 0.0.0-stage → 1.6.3-fork.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xk3vin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+<p align="center">
+  <h1 align="center">MegaMemory <sub><sup>fork</sup></sub></h1>
+</p>
+<p align="center">Persistent project knowledge graph for coding agents — multilingual, token-economical, visible in the UI.</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" />
+  <img alt="version" src="https://img.shields.io/badge/version-1.6.3--fork.1-orange?style=flat-square" />
+</p>
+
+<p align="center">
+  <img src="./assets/preview.png" alt="MegaMemory web explorer" width="800" />
+</p>
+
+> **Fork of [0xK3vin/MegaMemory](https://github.com/0xK3vin/MegaMemory) v1.6.2 (MIT).**
+> Upstream keeps the concept, this fork fixes multilingual IDs, adds hybrid search,
+> a context budget, fact freshness, digests, export and token accounting.
+> Русская версия: [README.ru.md](./README.ru.md).
+
+An [MCP](https://modelcontextprotocol.io/) server that lets your coding agent build and query a
+graph of concepts, architecture, and decisions — so it **remembers across sessions**.
+
+The LLM is the indexer. No AST parsing, no static analysis: the agent reads code, writes concepts
+in its own words, and queries them before future tasks. The graph stores **concepts** — features,
+modules, patterns, decisions — not code symbols. Everything persists in a per-project SQLite
+database at `.megamemory/knowledge.db`.
+
+---
+
+## What this fork changes
+
+| Area | Upstream 1.6.2 | This fork |
+|---|---|---|
+| Node IDs | slug strips everything outside `[a-z0-9-]`; Cyrillic, CJK, Greek, emoji names collapse to `""` and the second such node is lost | Unicode-safe slug: letters of any script, diacritics stripped only after Latin/Cyrillic/Greek/Hebrew bases (katakana dakuten and Hangul jamo are preserved), `/` becomes `-`, NFC output, hash fallback for emoji-only names, `-<hash8>` on collisions |
+| Embeddings | `all-MiniLM-L6-v2`, English-only, dimension hardcoded | `Xenova/multilingual-e5-small` by default (`MEGAMEMORY_EMBED_MODEL`), e5 `passage:`/`query:` prefixes, dimension read from the model, vector search disabled on model mismatch until `megamemory reembed` |
+| Search | cosine similarity only | hybrid: FTS5 + vector fused with RRF, per-hit `via: vector \| fts \| both`, query sanitization for `MATCH`, short-CJK routing, optional trigram index, `name_norm` LIKE fallback |
+| Context | `understand` returns everything it found | `mode: "compact"` by default, bounded by `max_tokens` (1500), summaries trimmed to 240 chars, edges between returned nodes only, `meta.returned / dropped / tokens_estimated` |
+| Freshness | delete or nothing | node `status` (`active`/`superseded`/`deprecated`), `supersedes` and `contradicts` edges, outdated nodes hidden from answers but visible in the graph |
+| Duplicates | manual merge | `megamemory consolidate` finds embedding-similar pairs (≥ 0.95) and merges them with edge transfer |
+| Long modules | every child read separately | `digest` nodes: one per module, rebuilt after the 5th child, lower search weight |
+| Portability | DB only | `megamemory export --md <dir>` writes one markdown file per node (frontmatter + wiki-links), `--check` for CI |
+| Cost visibility | none | every `understand` / `list_roots` / `get_concept` is measured; 7-day aggregates in `megamemory stats`, `/api/stats` and the explorer's **Tokens** panel |
+| Migration | — | `megamemory migrate --dry-run/--apply` upgrades an upstream database in place, additively, with backups and a downgrade-safe schema |
+
+---
+
+## The loop
+
+`understand → work → update`
+
+1. **Session start** — the agent calls `list_roots` (budgeted) to orient itself.
+2. **Before a task** — `understand` with a natural-language query, or `get_concept` for an exact ID.
+3. **After a task** — `create_concept` / `update_concept`, then `link` for relationships.
+
+---
+
+## Install
+
+Requires Node.js >= 18. For Russian-only projects a much smaller model (`cointegrated/rubert-tiny2`, 312-dim) works after an ONNX conversion; the model unloads after 5 minutes idle (`MEGAMEMORY_EMBED_IDLE_MS=0` disables that), and `MEGAMEMORY_SEARCH=fts` avoids loading it at all. The embedding model (~120 MB, multilingual) downloads on first use and is
+cached in `~/.cache/huggingface`.
+
+The fork is not published to npm — install from a tarball or a checkout:
+
+```bash
+git clone https://github.com/BloodyEagle/MegaMemoryAgent.git
+cd MegaMemoryAgent
+npm ci
+npm run build
+npm pack                      # megamemory-1.6.3-fork.1.tgz
+npm install -g ./megamemory-1.6.3-fork.1.tgz
+```
+
+Then either run the installer or register the MCP server by hand:
+
+```bash
+megamemory install            # interactive: opencode / [CC] / Codex / Antigravity
+```
+
+```json
+{
+  "megamemory": {
+    "type": "local",
+    "command": ["megamemory"],
+    "enabled": true
+  }
+}
+```
+
+The server reads `.megamemory/knowledge.db` relative to the working directory; override with
+`MEGAMEMORY_DB_PATH`.
+
+### Upgrading an existing upstream database
+
+```bash
+megamemory migrate --dry-run    # prints the plan, changes nothing
+megamemory migrate --apply      # backs up knowledge.db.bak-<ts>, applies the additive schema
+megamemory reembed              # only needed if the embedding model changed
+megamemory doctor               # health check, exit code 1 on problems
+```
+
+The migration never drops or renames a column, so upstream v1.6.2 still opens a migrated database.
+Nodes lost upstream to the empty-ID bug cannot be recovered; `--dry-run` reports them explicitly.
+
+---
+
+## MCP tools
+
+| Tool | Description |
+|---|---|
+| `understand` | Hybrid search over the graph. `top_k`, `max_tokens`, `mode: "compact" \| "full"`, `include_inactive`. |
+| `get_concept` | Exact-ID lookup with children, edges, incoming edges, parent. |
+| `create_concept` | Add a concept with edges, file refs and `supersedes`. |
+| `update_concept` | Update fields; embeddings are regenerated. |
+| `link` | Typed relationship between concepts. |
+| `remove_concept` | Soft-delete with a reason; history kept, status set to `deprecated`. |
+| `list_roots` | Top-level concepts with direct children (budgeted). |
+| `list_conflicts` | Unresolved merge conflicts, plus `contradicts` pairs. |
+| `resolve_conflict` | Resolve a conflict with verified content. |
+
+**Kinds:** `feature` · `module` · `pattern` · `config` · `decision` · `component` · `digest`
+
+**Relations:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by` · `supersedes` · `contradicts`
+
+---
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `megamemory install` | Configure an MCP client |
+| `megamemory serve [--port N]` | Web explorer (graph, search, node cards, Tokens panel, consolidate tab) |
+| `megamemory migrate [--dry-run\|--apply]` | Upgrade an upstream database |
+| `megamemory repair-ids [--apply]` | Rebuild empty / trailing-slash IDs from names |
+| `megamemory reembed` | Recompute embeddings (resumable, batched) |
+| `megamemory doctor` | Health check: schema, model, FTS, IDs, vectors, orphans, digests |
+| `megamemory stats` | Graph and token statistics |
+| `megamemory eval` | recall@10 over `fixtures/eval.jsonl` |
+| `megamemory consolidate [--dry-run\|--apply]` | Find and merge near-duplicate nodes |
+| `megamemory digest [--apply]` | Build or rebuild digest nodes |
+| `megamemory export --md <dir> [--check]` | Markdown export, CI-friendly drift check |
+| `megamemory merge`, `conflicts`, `resolve` | Two-way merge of graphs across branches |
+
+---
+
+## Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MEGAMEMORY_DB_PATH` | `./.megamemory/knowledge.db` | Database location |
+| `MEGAMEMORY_EMBED_MODEL` | `Xenova/multilingual-e5-small` | Embedding model (any transformers.js ONNX model) |
+| `MEGAMEMORY_SEARCH` | `hybrid` | `hybrid` / `fts` / `vector` |
+| `MEGAMEMORY_FTS_TOKENIZER` | — | `trigram` adds a second index for CJK |
+| `MEGAMEMORY_AUTO_DIGEST` | on | `0` disables auto-digest after the 5th child |
+
+---
+
+## Web explorer
+
+```bash
+megamemory serve --port 8080
+```
+
+- nodes colored by kind, sized by edge count; `digest` nodes and outdated (`superseded`) nodes are visually distinct
+- `supersedes` edges drawn dashed, status badges in the node card, "show outdated" toggle
+- search hits carry a `via` badge (vector / fts / both) and a budget line: `N nodes, ~X tokens, dropped M`
+- **Tokens** panel: average answer size and saved tokens over 7 days
+- **Consolidate** tab: duplicate candidates with apply
+
+---
+
+## Tests
+
+```bash
+npm run build
+npx vitest run src/__tests__/id-generation.test.ts --reporter=dot     # targeted
+npx vitest run                                                       # full suite (slow: model download)
+```
+
+`fixtures/demo.db` is a ready-made graph (ru/en/zh/emoji, one `superseded`, one `digest`, one
+duplicate pair) for manual checks in the explorer.
+
+---
+
+## Compatibility and limits
+
+- Upstream v1.6.2 keeps working against a migrated database: new columns have defaults, FTS
+  triggers maintain the index for upstream inserts. Backups `knowledge.db.bak-<ts>`, last 3 kept.
+- FTS5 requires libsql's local file mode — MegaMemory is local-only; remote Turso forbids virtual tables.
+- After any `VACUUM`, run `megamemory migrate --apply` to rebuild the FTS index (rowids are not stable).
+- Russian text is not stemmed by FTS5's `unicode61`; the vector channel compensates, prefix queries help.
+
+---
+
+## Credits and license
+
+Based on [MegaMemory](https://github.com/0xK3vin/MegaMemory) by 0xK3vin (MIT).
+Fork maintained by [BloodyEagle](https://github.com/BloodyEagle). MIT, see [LICENSE](./LICENSE).
+Differences and sync instructions: [docs/FORK.md](./docs/FORK.md).

package/README.ru.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <h1 align="center">MegaMemory <sub><sup>форк</sup></sub></h1>
+</p>
+<p align="center">Граф знаний проекта для кодинг-агентов — мультиязычный, экономный по токенам, видимый в интерфейсе.</p>
+
+<p align="center">
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" />
+  <img alt="version" src="https://img.shields.io/badge/version-1.6.3--fork.1-orange?style=flat-square" />
+</p>
+
+<p align="center">
+  <img src="./assets/preview.png" alt="Веб-обозреватель MegaMemory" width="800" />
+</p>
+
+> **Форк [0xK3vin/MegaMemory](https://github.com/0xK3vin/MegaMemory) v1.6.2 (MIT).**
+> Идея и база — upstream. В форке: исправлены идентификаторы для любых языков, добавлены
+> гибридный поиск, бюджет контекста, актуальность фактов, digest-узлы, экспорт и учёт токенов.
+> English version: [README.md](./README.md).
+
+[MCP](https://modelcontextprotocol.io/)-сервер, который даёт кодинг-агенту строить граф концепций,
+архитектуры и решений — и **помнить проект между сессиями**.
+
+Индексатор — сам LLM. Никакого AST-парсинга и статического анализа: агент читает код, записывает
+концепции своими словами и запрашивает их перед следующими задачами. В графе хранятся **концепции** —
+фичи, модули, паттерны, решения, — а не символы кода. Всё лежит в SQLite проекта:
+`.megamemory/knowledge.db`.
+
+---
+
+## Что изменилось в форке
+
+| Область | Upstream 1.6.2 | Этот форк |
+|---|---|---|
+| Идентификаторы | slug вырезает всё вне `[a-z0-9-]`: кириллица, CJK, греческий, эмодзи схлопываются в `""`, второй такой узел теряется | Unicode-слаг: буквы любого алфавита, диакритика снимается только после латиницы/кириллицы/греческого/иврита (дакутэн катаканы и хангыль сохраняются), `/` → `-`, вывод в NFC, hash-фолбэк для имён из эмодзи, суффикс `-<hash8>` при коллизии |
+| Эмбеддинги | `all-MiniLM-L6-v2`, только английский, размерность зашита | по умолчанию `Xenova/multilingual-e5-small` (`MEGAMEMORY_EMBED_MODEL`), префиксы e5 `passage:`/`query:`, размерность берётся из модели, при смене модели векторный поиск отключается до `megamemory reembed` |
+| Поиск | только косинус | гибрид: FTS5 + вектор через RRF, у каждого попадания `via: vector \| fts \| both`, санитизация запросов для `MATCH`, маршрутизация коротких CJK-запросов, опциональный trigram-индекс, LIKE-фолбэк по `name_norm` |
+| Контекст | `understand` отдаёт всё найденное | по умолчанию `mode: "compact"` с лимитом `max_tokens` (1500), summary обрезается до 240 символов, рёбра — только между возвращёнными узлами, `meta.returned / dropped / tokens_estimated` |
+| Актуальность | либо удалить, либо никак | `status` (`active`/`superseded`/`deprecated`), рёбра `supersedes` и `contradicts`, устаревшее скрыто из ответов, но видно в графе |
+| Дубли | только ручной merge | `megamemory consolidate` находит пары с близостью эмбеддингов ≥ 0.95 и сливает их с переносом рёбер |
+| Большие модули | каждый ребёнок читается отдельно | `digest`-узлы: один на модуль, пересобирается после 5-го ребёнка, пониженный вес в поиске |
+| Переносимость | только БД | `megamemory export --md <dir>` — по файлу на узел (frontmatter + wiki-ссылки), `--check` для CI |
+| Видимость цены | нет | каждый `understand` / `list_roots` / `get_concept` измеряется; агрегаты за 7 дней в `megamemory stats`, `/api/stats` и панели **Tokens** в explorer |
+| Миграция | — | `megamemory migrate --dry-run/--apply` обновляет базу upstream на месте, аддитивно, с бэкапами и совместимостью вниз |
+
+---
+
+## Цикл работы
+
+`understand → работа → update`
+
+1. **Начало сессии** — агент вызывает `list_roots` (с бюджетом), чтобы сориентироваться.
+2. **Перед задачей** — `understand` с запросом на естественном языке или `get_concept` по точному id.
+3. **После задачи** — `create_concept` / `update_concept`, затем `link` для связей.
+
+---
+
+## Установка
+
+Нужен Node.js >= 18. Для чисто русских проектов подойдёт значительно меньшая модель (`cointegrated/rubert-tiny2`, 312-мерная) после конвертации в ONNX; модель выгружается после 5 минут простоя (`MEGAMEMORY_EMBED_IDLE_MS=0` отключает выгрузку), а `MEGAMEMORY_SEARCH=fts` не загружает её вовсе. Модель эмбеддингов (~120 МБ, мультиязычная) скачивается при первом
+запуске и кешируется в `~/.cache/huggingface`.
+
+Форк не публикуется в npm — ставится из tarball или из чекаута:
+
+```bash
+git clone https://github.com/BloodyEagle/MegaMemoryAgent.git
+cd MegaMemoryAgent
+npm ci
+npm run build
+npm pack                      # megamemory-1.6.3-fork.1.tgz
+npm install -g ./megamemory-1.6.3-fork.1.tgz
+```
+
+Дальше — либо установщик, либо регистрация MCP-сервера руками:
+
+```bash
+megamemory install            # интерактивно: opencode / [CC] / Codex / Antigravity
+```
+
+```json
+{
+  "megamemory": {
+    "type": "local",
+    "command": ["megamemory"],
+    "enabled": true
+  }
+}
+```
+
+Сервер читает `.megamemory/knowledge.db` относительно рабочей директории; путь переопределяется
+через `MEGAMEMORY_DB_PATH`.
+
+### Обновление существующей базы upstream
+
+```bash
+megamemory migrate --dry-run    # печатает план, ничего не меняет
+megamemory migrate --apply      # бэкап knowledge.db.bak-<ts>, аддитивная миграция схемы
+megamemory reembed              # нужен только если сменилась модель эмбеддингов
+megamemory doctor               # проверка здоровья, код выхода 1 при проблемах
+```
+
+Миграция не удаляет и не переименовывает столбцы, поэтому upstream v1.6.2 открывает
+мигрированную базу. Узлы, потерянные в upstream из-за пустых id, восстановить нельзя —
+`--dry-run` честно их показывает.
+
+---
+
+## MCP-инструменты
+
+| Инструмент | Что делает |
+|---|---|
+| `understand` | Гибридный поиск по графу. `top_k`, `max_tokens`, `mode: "compact" \| "full"`, `include_inactive`. |
+| `get_concept` | Точный поиск по id: дети, рёбра, входящие рёбра, родитель. |
+| `create_concept` | Новая концепция с рёбрами, ссылками на файлы и `supersedes`. |
+| `update_concept` | Обновление полей; эмбеддинг пересчитывается. |
+| `link` | Типизированная связь между концепциями. |
+| `remove_concept` | Мягкое удаление с причиной; история сохраняется, статус `deprecated`. |
+| `list_roots` | Корневые концепции с детьми (с бюджетом). |
+| `list_conflicts` | Неразрешённые конфликты merge и пары `contradicts`. |
+| `resolve_conflict` | Разрешение конфликта проверенным содержимым. |
+
+**Типы узлов:** `feature` · `module` · `pattern` · `config` · `decision` · `component` · `digest`
+
+**Типы связей:** `connects_to` · `depends_on` · `implements` · `calls` · `configured_by` · `supersedes` · `contradicts`
+
+---
+
+## CLI
+
+| Команда | Назначение |
+|---|---|
+| `megamemory install` | Настроить MCP-клиент |
+| `megamemory serve [--port N]` | Веб-обозреватель: граф, поиск, карточки узлов, панель Tokens, вкладка consolidate |
+| `megamemory migrate [--dry-run\|--apply]` | Обновить базу upstream |
+| `megamemory repair-ids [--apply]` | Пересобрать пустые id и id с хвостовым `/` |
+| `megamemory reembed` | Пересчитать эмбеддинги (прерываемо, пакетами) |
+| `megamemory doctor` | Проверка: схема, модель, FTS, id, векторы, осиротевшие рёбра, digest |
+| `megamemory stats` | Статистика графа и токенов |
+| `megamemory eval` | recall@10 по `fixtures/eval.jsonl` |
+| `megamemory consolidate [--dry-run\|--apply]` | Поиск и слияние почти одинаковых узлов |
+| `megamemory digest [--apply]` | Сборка и пересборка digest-узлов |
+| `megamemory export --md <dir> [--check]` | Markdown-экспорт и проверка расхождений для CI |
+| `megamemory merge`, `conflicts`, `resolve` | Двусторонний merge графов между ветками |
+
+---
+
+## Переменные окружения
+
+| Переменная | По умолчанию | Значение |
+|---|---|---|
+| `MEGAMEMORY_DB_PATH` | `./.megamemory/knowledge.db` | Путь к базе |
+| `MEGAMEMORY_EMBED_MODEL` | `Xenova/multilingual-e5-small` | Модель эмбеддингов (любая ONNX-модель transformers.js) |
+| `MEGAMEMORY_SEARCH` | `hybrid` | `hybrid` / `fts` / `vector` |
+| `MEGAMEMORY_FTS_TOKENIZER` | — | `trigram` добавляет второй индекс для CJK |
+| `MEGAMEMORY_AUTO_DIGEST` | включено | `0` отключает автосборку digest после 5-го ребёнка |
+
+---
+
+## Веб-обозреватель
+
+```bash
+megamemory serve --port 8080
+```
+
+- узлы раскрашены по типу, размер — по числу рёбер; `digest` и устаревшие (`superseded`) визуально отличаются
+- рёбра `supersedes` — пунктиром, бейдж статуса в карточке узла, тумблер «показывать устаревшие»
+- у результатов поиска бейдж `via` (vector / fts / both) и строка бюджета: `N nodes, ~X tokens, dropped M`
+- панель **Tokens**: средний размер ответа и сэкономленные токены за 7 дней
+- вкладка **Consolidate**: кандидаты-дубликаты с кнопкой применения
+
+---
+
+## Тесты
+
+```bash
+npm run build
+npx vitest run src/__tests__/id-generation.test.ts --reporter=dot     # целевой прогон
+npx vitest run                                                       # всё (долго: скачивание модели)
+```
+
+`fixtures/demo.db` — готовый граф (ru/en/zh/эмодзи, один `superseded`, один `digest`, пара дублей)
+для ручной проверки в обозревателе.
+
+---
+
+## Совместимость и ограничения
+
+- Upstream v1.6.2 работает с мигрированной базой: у новых столбцов есть `DEFAULT`, FTS-триггеры
+  поддерживают индекс при вставках upstream. Бэкапы `knowledge.db.bak-<ts>`, хранятся 3 последних.
+- FTS5 требует локального файлового режима libsql — MegaMemory локальная; удалённый Turso
+  виртуальные таблицы запрещает.
+- После любого `VACUUM` нужен `megamemory migrate --apply` — пересборка FTS (rowid не гарантированы).
+- Русский текст FTS5 `unicode61` не стеммит; компенсирует векторный канал, помогают префикс-запросы.
+
+---
+
+## Авторы и лицензия
+
+Основа — [MegaMemory](https://github.com/0xK3vin/MegaMemory), автор 0xK3vin (MIT).
+Форк поддерживает [BloodyEagle](https://github.com/BloodyEagle). MIT, см. [LICENSE](./LICENSE).
+Отличия и порядок синхронизации с upstream: [docs/FORK.md](./docs/FORK.md).

package/commands/bootstrap-memory.md

@@ -0,0 +1,51 @@
+<!-- MegaMemory-managed file. Safe for megamemory install to update. -->
+# Bootstrap Project Knowledge Graph
+
+RUN { git ls-files; git ls-files --others --exclude-standard; } 2>/dev/null | sort -u | xargs wc -l 2>/dev/null | sort -rn | head -150
+READ README.md
+
+You are bootstrapping the megamemory knowledge graph for this project.
+
+Your job is to understand the codebase and record its core concepts, architecture,
+and patterns as knowledge graph nodes. The file listing above is sorted by line
+count — the biggest files are where the core logic lives.
+
+## Step 1: Check existing graph
+
+Call `megamemory:list_roots` to see what's already recorded. If the graph has
+good coverage, report what's there and ask if I want to fill in specific areas.
+
+## Step 2: Identify major modules
+
+From the file listing and README, identify the top-level systems in this project.
+Think in terms of:
+- What does this project DO? (features)
+- What are the distinct subsystems? (modules)
+- How is it structured? (patterns, decisions)
+
+## Step 3: Read and create root concepts
+
+For each major module, read its key files to understand what it does. Then call
+`megamemory:create_concept` with a specific, detailed summary. Include parameter
+names, defaults, file paths, and behavior details — not vague descriptions.
+
+## Step 4: Create children for important sub-components
+
+For substantial modules, create child concepts for key pieces. Stay max 2 levels
+deep. Focus on things a developer would need to know when working in that area.
+
+## Step 5: Link related concepts
+
+Connect concepts that interact across boundaries using `megamemory:link`.
+Focus on meaningful relationships: depends_on, calls, connects_to, implements,
+configured_by.
+
+## Guidelines
+
+- Be specific. "Handles auth" is useless. "JWT auth with RS256, tokens from
+  /auth/login, validated in middleware, refresh tokens in Redis with 7d TTL" is useful.
+- Focus on the top 10-15 most important concepts first. The graph grows over time.
+- Don't document trivial things. If it's obvious from the file name, skip it.
+
+- When a concept replaces an earlier decision, pass `supersedes: [old_id]` instead of deleting.
+- Do not create digest nodes manually — they are built from children automatically.

package/commands/save-memory.md

@@ -0,0 +1,84 @@
+<!-- MegaMemory-managed file. Safe for megamemory install to update. -->
+# Save Session Knowledge
+
+You are saving what you learned this session into the megamemory knowledge graph.
+This is YOUR memory — record anything valuable for future sessions: what you
+understood about the project, what you built, decisions that were made, patterns
+you noticed, or intent the user shared.
+
+## Step 1: Load existing graph
+
+Call `megamemory:list_roots` to see what's already recorded. Understanding the
+current state prevents duplicates and helps you decide what to update vs create.
+
+## Step 2: Reflect on this session
+
+Think about what happened this session. Consider:
+- What did you learn about the project's purpose or intent?
+- What features, modules, or components did you build or change?
+- What design decisions were made and why?
+- What patterns or conventions did you discover?
+- What architectural understanding do you have now that isn't in the graph?
+- Did anything get removed, replaced, or deprecated?
+
+## Step 3: Search for overlap
+
+Before creating anything new, call `megamemory:understand` with queries based on
+what you worked on this session. For each area you touched, search to see if
+concepts already exist that should be updated rather than duplicated.
+
+For example, if you worked on authentication, call:
+  megamemory:understand — query="authentication"
+
+Do this for each distinct area. Existing concepts that are stale or incomplete
+should be updated — don't create a new node when an update will do.
+
+## Step 4: Write to the knowledge graph
+
+For each thing worth remembering:
+
+**New understanding** → `megamemory:create_concept`
+  - name: human-readable name
+  - kind: use `decision` for intent/rationale, `feature` for capabilities,
+    `module` for subsystems, `pattern` for conventions, `config` for setup,
+    `component` for distinct pieces of a system
+  - summary: be specific — include parameter names, defaults, file paths,
+    behavior details, and the WHY behind things
+  - why: the rationale — this is often the most valuable part
+  - file_refs: relevant files if applicable
+  - edges: connect to existing concepts where relationships exist
+    [{to: "concept-id", relation: "depends_on|implements|calls|connects_to|configured_by", description: "why"}]
+  - created_by_task: brief description of what you were doing this session
+
+**Updated understanding** → `megamemory:update_concept`
+  - id: the concept slug
+  - changes: {summary?, why?, file_refs?, name?, kind?}
+  If an existing concept is now stale or incomplete based on what you learned,
+  update it. This is often more valuable than creating new nodes.
+
+**New connections** → `megamemory:link`
+  - from, to: concept IDs
+  - relation: depends_on | implements | calls | connects_to | configured_by
+  - description: why this relationship exists
+  If you discovered how existing concepts relate to each other.
+
+**Removed/replaced things** → `megamemory:remove_concept`
+  - id: concept to remove
+  - reason: why it was removed
+  If something in the graph is no longer true.
+
+## Step 5: Verify
+
+Call `megamemory:list_roots` again. Confirm the graph reflects your current
+understanding. Report what you saved.
+
+## Guidelines
+
+- Record what a future you (with no memory of this session) would need to know.
+- Intent and rationale ("why") are more valuable than implementation details.
+- Update existing concepts before creating new ones — keep the graph lean.
+- Don't record trivial things. If it's obvious from the code, skip it.
+- Max 2 levels of nesting. Flat is better than deep.
+- Connect concepts — isolated nodes are less useful than a connected graph.
+- Be specific. "Handles auth" is useless. "JWT auth with RS256, validated in
+  middleware at src/middleware/auth.ts, refresh tokens in Redis with 7d TTL" is useful.

package/dist/cli-utils.d.ts

@@ -0,0 +1,23 @@
+export declare function error(msg: string): void;
+export declare function errorBold(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function success(msg: string): void;
+export declare function skip(msg: string): void;
+export declare function info(msg: string): void;
+export declare function heading(msg: string): void;
+export declare function ask(question: string): Promise<string>;
+export declare function multiSelect(prompt: string, options: Array<{
+    label: string;
+    value: string;
+    description?: string;
+}>): Promise<string[]>;
+/**
+ * Prompt the user for a port when the current one is in use.
+ * Returns the chosen port number, or null if the user wants to cancel.
+ */
+export declare function askPort(currentPort: number): Promise<number | null>;
+/**
+ * Validate a port number. Returns an error message or null if valid.
+ */
+export declare function validatePort(value: unknown, rawInput?: string): string | null;
+//# sourceMappingURL=cli-utils.d.ts.map

package/dist/cli-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-utils.d.ts","sourceRoot":"","sources":["../src/cli-utils.ts"],"names":[],"mappings":"AAKA,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEvC;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzC;AAID,wBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWrD;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACrE,OAAO,CAAC,MAAM,EAAE,CAAC,CAmHnB;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmBzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7E"}