PCIRCLE-AI · kevintseng · May 13, 2026 · May 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to MeMesh are documented here.
 
+## [Unreleased]
+
+### Docs
+- **All 11 README locales now have an `## Upgrading` section** (`README.md`, `README.zh-TW.md`, `README.zh-CN.md`, `README.ja.md`, `README.ko.md`, `README.de.md`, `README.fr.md`, `README.es.md`, `README.pt.md`, `README.vi.md`, `README.th.md`) — v4.2.5–v4.2.7 release notes added the upgrade flow + pre-v4.2.5 fallback to English + Thai only, so 9 locales were missing the section entirely. Now every locale has the three upgrade paths and the npm-global fallback note.
+- **"Actively developed" callout at the top of every README** — adds a `> [!IMPORTANT]` block immediately after the hero divider linking to the GitHub Issues tracker. Sets expectations that features evolve between releases and routes bug reports / feature requests to the correct channel from the first glance.
+
+### Fixed
+- **Test flake: `tests/transports/http.test.ts > returns array (possibly empty) for no-match query`** — assertion was `toHaveLength(0)`, but `recallEnhanced` may supplement FTS5 results with sqlite-vec near-neighbours when ONNX embeddings are loaded, so a query that misses FTS5 can still legitimately return a small set. The API contract is "always return a valid JSON array of entities, never a 500"; assertion now mirrors that contract (length bounded, all rows shaped like entities).
+- **Test flake: `tests/tools.test.ts > auto-archives entity when superseded by new remember`** — same root cause; the `recall('JWT')` after archiving `auth-v2` asserted exactly `[]`, but vector supplement could surface the related `auth-v3`. The behavioural guarantee is "archived rows stay hidden from default recall", so the assertion now checks `not.toContain('auth-v2')` instead of empty-array.
+- **Test isolation: `tests/hooks/pre-bash-orchestration-nudge.test.ts` no longer reads the developer's real `~/.memesh/config.json`** — `isAgenticOrchestrationEnabled()` falls back to `readHookConfig()` when the env var is unset, and `readHookConfig()` reads `<memeshDir>/config.json`. The "default off" test deleted the env var but didn't pin `MEMESH_DIR`, so a developer with `enableAgenticOrchestration: true` in their personal config saw the test fail even though hook code was correct. Both the test helper and the gate-off case now point `MEMESH_DIR` at the per-test tmpdir.
+
 ## [4.2.7] — 2026-05-13
 
 ### Added

diff --git a/README.de.md b/README.de.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Das Problem
 
 Ihr Coding-Agent vergisst, was zwischen Sessions passiert ist. Jede Architekturentscheidung, jede Bugfix, jeder fehlgeschlagene Test und jede hart erarbeitete Erkenntnis muss erneut erklärt werden. Claude Code startet von vorne, entdeckt alte Constraints neu und verschwendet Context auf Dinge, die es längst wissen sollte.
@@ -376,6 +379,35 @@ Der Kern ist Framework-agnostisch. Dieselbe Logik läuft vom Terminal, HTTP oder
 
 ---
 
+## Aktualisieren
+
+Der Plugin-Marketplace von Claude Code fixiert Versionen zum Installationszeitpunkt und aktualisiert **nicht** automatisch. So holst du dir ein neues Release:
+
+**Option A — `/plugin` UI**: `memesh@pcircle-memesh` deinstallieren, dann neu installieren. Claude Code holt die neueste Marketplace-Version.
+
+**Option B — Einzeiler-Skript** (kein UI-Klicken, idempotent):
+
+```bash
+# Wenn deine Plugin-Installation v4.2.5 oder neuer ist, ist das Skript enthalten:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Bei Installationen vor v4.2.5 (also v4.2.4 oder v4.2.3)
+# ist das Skript noch nicht im Plugin. Nutze stattdessen die npm-global-Kopie:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Das setzt voraus, dass du auch `npm install -g @pcircle/memesh` ausgeführt hast.
+# Falls nicht, ist jetzt ein guter Moment dafür — siehe oben „Installationspfade auf
+# einen Blick" für die Gründe, warum die meisten Nutzer beide Pfade wollen.)
+```
+
+Das Skript fast-forwarded den Marketplace-Cache, legt die neue Version unter `~/.claude/plugins/cache/` ab, installiert Runtime-Dependencies und zeigt `installed_plugins.json` neu. Starte danach Claude Code neu, damit der MCP-Server sich neu verbindet.
+
+**npm-global-Installationen** (`npm install -g @pcircle/memesh`) können sich via `memesh update` selbst aktualisieren. Source-Checkouts: `git pull && npm install && npm run build`.
+
+Beim Session-Start erscheint ein einzeiliges Banner (pro Version alle 24h gedrosselt), wenn ein neueres Release verfügbar ist, und `memesh doctor` meldet das Upgrade-Ziel mit kanalspezifischem Befehl.
+
+---
+
 ## Beitragen
 
 ```bash

diff --git a/README.es.md b/README.es.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Proyecto en desarrollo activo** — las funcionalidades evolucionan continuamente y pueden cambiar entre versiones. Si encuentras un bug o tienes una solicitud de funcionalidad, por favor [abre un issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## El Problema
 
 Tu agente de codificación olvida lo que sucedió en sesiones anteriores. Cada decisión arquitectónica, corrección de bugs, prueba fallida y lección aprendida con esfuerzo debe explicarse de nuevo. Claude Code comienza desde cero, redescubre restricciones antiguas y gasta contexto en cosas que ya debería saber.
@@ -404,6 +407,35 @@ El core es agnóstico de framework. La misma lógica se ejecuta desde terminal,
 
 ---
 
+## Actualizar
+
+El plugin marketplace de Claude Code fija las versiones en el momento de la instalación y **no** se actualiza automáticamente. Para obtener una nueva versión:
+
+**Opción A — Interfaz `/plugin`**: desinstala `memesh@pcircle-memesh`, luego reinstala. Claude Code obtiene la versión más reciente del marketplace.
+
+**Opción B — Script en una línea** (sin hacer clic en la UI, idempotente):
+
+```bash
+# Si tu plugin instalado es v4.2.5 o posterior, el script viene incluido:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si instalaste antes de v4.2.5 (es decir, v4.2.4 o v4.2.3),
+# el script aún no está en tu plugin. Usa la copia npm-global en su lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Esto asume que también ejecutaste `npm install -g @pcircle/memesh`. Si no lo has hecho,
+# este es un buen momento para hacerlo — consulta la sección "Vista rápida de las rutas
+# de instalación" arriba para entender por qué la mayoría de los usuarios quieren ambas.)
+```
+
+El script fast-forwarded el caché del marketplace, prepara la nueva versión en `~/.claude/plugins/cache/`, instala las runtime deps y repunta `installed_plugins.json`. Reinicia Claude Code después para que el MCP server se reconecte.
+
+**Las instalaciones npm-global** (`npm install -g @pcircle/memesh`) pueden auto-actualizarse mediante `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+Al inicio de sesión aparece un banner de una línea (limitado a una vez cada 24h por versión) cuando hay una nueva versión disponible, y `memesh doctor` reporta el objetivo de actualización con el comando específico del canal.
+
+---
+
 ## Contribuir
 
 ```bash

diff --git a/README.fr.md b/README.fr.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projet en développement actif** — les fonctionnalités évoluent continuellement et peuvent changer entre les versions. En cas de bug ou de demande de fonctionnalité, merci d'[ouvrir une issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Le Problème
 
 Votre agent de codage oublie ce qui s'est passé d'une session à l'autre. Chaque décision architecturale, correction de bug, test échoué et leçon apprise difficilement doit être réexpliquée. Claude Code redémarre à zéro, redécouvre les anciennes contraintes et gaspille du contexte sur des éléments qu'il devrait déjà connaître.
@@ -377,6 +380,35 @@ Le cœur est agnostique du framework. La même logique s'exécute depuis le term
 
 ---
 
+## Mise à Jour
+
+Le plugin marketplace de Claude Code fige les versions à l'installation et **ne** se met **pas** à jour automatiquement. Pour récupérer une nouvelle version :
+
+**Option A — Interface `/plugin`** : désinstaller `memesh@pcircle-memesh`, puis réinstaller. Claude Code récupère la dernière version du marketplace.
+
+**Option B — Script en une ligne** (sans cliquer dans l'UI, idempotent) :
+
+```bash
+# Si votre plugin est en v4.2.5 ou plus récent, le script est embarqué :
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si vous avez installé avant v4.2.5 (c.-à-d. v4.2.4 ou v4.2.3),
+# le script n'est pas encore dans votre plugin. Utilisez la copie npm-global :
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Cela suppose que vous avez aussi exécuté `npm install -g @pcircle/memesh`. Sinon,
+# c'est le bon moment — voir la section « Aperçu des chemins d'installation »
+# ci-dessus pour comprendre pourquoi la plupart des utilisateurs veulent les deux.)
+```
+
+Le script fast-forward le cache marketplace, place la nouvelle version dans `~/.claude/plugins/cache/`, installe les runtime deps, et repointe `installed_plugins.json`. Redémarrez Claude Code ensuite pour que le serveur MCP se reconnecte.
+
+**Les installations npm-global** (`npm install -g @pcircle/memesh`) peuvent s'auto-mettre à jour via `memesh update`. Source checkouts : `git pull && npm install && npm run build`.
+
+Au démarrage de session, une bannière sur une ligne s'affiche (limitée à une fois par 24h par version) quand une nouvelle version est disponible, et `memesh doctor` indique la cible de mise à jour avec la commande adaptée au canal.
+
+---
+
 ## Contribuer
 
 ```bash

diff --git a/README.ja.md b/README.ja.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **活発に開発中のプロジェクト** — 機能は継続的に更新され、リリース間で変更される可能性があります。バグや機能要望がある場合は[issue を開いてください](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 課題
 
 コーディングエージェントはセッション間で記憶を失います。アーキテクチャの決定、バグ修正、テスト失敗、苦労して得た教訓 — すべてを毎回説明し直さなければなりません。Claude Code はいつも初期状態から始まり、既に知っているはずの制約を再発見し、貴重なコンテキストを無駄にします。
@@ -404,6 +407,35 @@ memesh  # ダッシュボード → Settings タブを開く
 
 ---
 
+## アップグレード
+
+Claude Code の plugin marketplace はインストール時にバージョンを固定し、**自動更新しません**。新しいリリースを取得するには：
+
+**オプション A — `/plugin` UI**：`memesh@pcircle-memesh` をアンインストールして再インストール。Claude Code が marketplace の最新バージョンを取得します。
+
+**オプション B — ワンラインスクリプト**（UI クリック不要、冪等）：
+
+```bash
+# plugin が v4.2.5 以降なら、スクリプトは同梱済み：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# v4.2.5 より前（つまり v4.2.4 または v4.2.3）のインストールの場合、
+# スクリプトはまだ plugin に入っていません。npm-global の副本を使用：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （`npm install -g @pcircle/memesh` も実行済みであることを前提とします。
+# まだなら、ちょうど良い機会です — 上の「インストールパス早見表」セクションで、
+# 多くのユーザーが両方のパスを必要とする理由を確認してください。）
+```
+
+スクリプトは marketplace cache を fast-forward し、新バージョンを `~/.claude/plugins/cache/` に展開し、runtime deps をインストールし、`installed_plugins.json` を新バージョンに向け直します。完了後、MCP server が再接続するように Claude Code を再起動してください。
+
+**npm-global インストール**（`npm install -g @pcircle/memesh`）は `memesh update` で自動更新できます。Source checkouts：`git pull && npm install && npm run build`。
+
+セッション開始時、新しいリリースがあると 1 行のバナーが表示されます（バージョンごとに 24 時間スロットル）。`memesh doctor` はアップグレードターゲットとチャンネル固有のコマンドを報告します。
+
+---
+
 ## コントリビュート
 
 ```bash

diff --git a/README.ko.md b/README.ko.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **활발히 개발 중인 프로젝트** — 기능이 지속적으로 업데이트되며 릴리스 간에 변경될 수 있습니다. 버그나 기능 요청이 있으면 [issue를 열어주세요](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## 문제점
 
 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. 아키텍처 결정, 버그 수정, 실패한 테스트, 힘들게 얻은 교훈 — 매번 다시 설명해야 합니다. Claude Code는 매번 새로 시작하고, 이미 알아야 할 제약 조건을 다시 발견하며, 불필요하게 컨텍스트를 소비합니다.
@@ -404,6 +407,35 @@ memesh  # 대시보드 열기 → Settings 탭
 
 ---
 
+## 업그레이드
+
+Claude Code의 plugin marketplace는 설치 시 버전을 고정하며 **자동으로 업데이트되지 않습니다**. 새 릴리스를 가져오려면:
+
+**옵션 A — `/plugin` UI**: `memesh@pcircle-memesh`를 제거한 후 다시 설치합니다. Claude Code가 marketplace의 최신 버전을 가져옵니다.
+
+**옵션 B — 한 줄 스크립트** (UI 클릭 불필요, 멱등):
+
+```bash
+# plugin이 v4.2.5 이상이면 스크립트가 함께 제공됩니다:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# v4.2.5 이전 버전(즉 v4.2.4 또는 v4.2.3)을 설치한 경우,
+# 스크립트가 plugin에 아직 없습니다. npm-global 사본을 사용하세요:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (이는 `npm install -g @pcircle/memesh`도 실행했다고 가정합니다. 아직 안 했다면
+# 지금이 적기입니다 — 위의 "설치 경로 한눈에 보기" 섹션에서 대부분의 사용자가
+# 두 경로를 모두 원하는 이유를 확인하세요.)
+```
+
+스크립트는 marketplace cache를 fast-forward하고, 새 버전을 `~/.claude/plugins/cache/`에 스테이징하고, runtime deps를 설치하고, `installed_plugins.json`을 새 버전으로 다시 가리킵니다. 완료 후 MCP server가 다시 연결되도록 Claude Code를 재시작하세요.
+
+**npm-global 설치**(`npm install -g @pcircle/memesh`)는 `memesh update`로 자체 업데이트할 수 있습니다. Source checkouts: `git pull && npm install && npm run build`.
+
+세션 시작 시 새 릴리스가 있으면 한 줄 배너가 표시됩니다(버전당 24시간 스로틀). `memesh doctor`는 업그레이드 대상과 채널별 명령을 보고합니다.
+
+---
+
 ## 기여하기
 
 ```bash

diff --git a/README.md b/README.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Actively developed project** — features evolve and may change between releases. If you hit a bug or have a feature request, please [open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## The Problem
 
 Your coding agent forgets what happened between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.

diff --git a/README.pt.md b/README.pt.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projeto em desenvolvimento ativo** — funcionalidades evoluem continuamente e podem mudar entre releases. Em caso de bug ou pedido de funcionalidade, por favor [abra uma issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## O Problema
 
 Seu agente de código esquece tudo entre sessões. Toda decisão arquitetônica, correção de bug, teste que falhou e lição conquistada na marra precisa ser re-explicada. Claude Code sempre começa do zero, redescobre restrições antigas e queima contexto em coisas que já deveria saber.
@@ -377,6 +380,35 @@ Core é agnóstico a framework. A mesma lógica roda de terminal, HTTP ou MCP.
 
 ---
 
+## Atualizando
+
+O plugin marketplace do Claude Code fixa versões no momento da instalação e **não** atualiza automaticamente. Para obter uma nova versão:
+
+**Opção A — UI `/plugin`**: desinstale `memesh@pcircle-memesh`, depois reinstale. O Claude Code busca a versão mais recente do marketplace.
+
+**Opção B — Script de uma linha** (sem cliques na UI, idempotente):
+
+```bash
+# Se o seu plugin instalado for v4.2.5 ou mais recente, o script já está incluído:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Se você instalou antes de v4.2.5 (ou seja, v4.2.4 ou v4.2.3),
+# o script ainda não está no seu plugin. Use a cópia npm-global no lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Isso assume que você também executou `npm install -g @pcircle/memesh`. Se não,
+# este é um bom momento para fazê-lo — veja a seção "Caminhos de instalação resumidos"
+# acima para entender por que a maioria dos usuários quer ambos os caminhos.)
+```
+
+O script fast-forwarded o cache do marketplace, prepara a nova versão em `~/.claude/plugins/cache/`, instala runtime deps e repõe o ponteiro de `installed_plugins.json`. Reinicie o Claude Code depois para o MCP server reconectar.
+
+**Instalações npm-global** (`npm install -g @pcircle/memesh`) podem se auto-atualizar via `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+No início da sessão aparece um banner de uma linha (limitado a uma vez por 24h por versão) quando há uma nova versão disponível, e `memesh doctor` reporta o alvo de upgrade com o comando específico do canal.
+
+---
+
 ## Contribuindo
 
 ```bash

diff --git a/README.th.md b/README.th.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **โปรเจกต์อยู่ระหว่างพัฒนาอย่างต่อเนื่อง** — ฟีเจอร์มีการอัปเดตอย่างต่อเนื่องและอาจเปลี่ยนแปลงระหว่างเวอร์ชัน หากพบบักหรือมีคำขอฟีเจอร์ กรุณา[เปิด issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)
+
 ## ปัญหา
 
 เอเจนต์คิดโค้ดลืมสิ่งที่เกิดขึ้นระหว่างเซสชัน ทุกการตัดสินใจด้านสถาปัตยกรรม การแก้บั๊ก การทดสอบที่ล้มเหลว และบทเรียนที่ยากที่สุดต้องอธิบายซ้ำ Claude Code เริ่มต้นใหม่ ค้นพบข้อจำกัดเดิม และใช้ context ไปกับสิ่งที่น่าจะรู้อยู่แล้ว