@pcircle/memesh 4.1.7 → 4.2.1

package/README.ja.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,17 +26,52 @@
 
 ---
 
+## エビデンス — LongMemEval-S で 95.40% R@5
+
+MeMesh の検索エンジンは **FTS5 のみ**(LLM もホットパスのエンベディングも使用しない)で、公開されている [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) ベンチマーク(500 問、MIT ライセンス)で測定された結果です:
+
+| システム | R@5 | ソース |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | ベンダー自社申告 |
+| Supermemory | ~82% | ベンダー推定値 |
+| Zep | 63.8% | LongMemEval 論文 |
+| Mem0 | 49.0% | LongMemEval 論文 |
+
+再現コマンド、データセット SHA256、問題ごとの生結果、既知失敗の分析はすべて [`benchmarks/longmemeval/`](benchmarks/longmemeval/) にあります。約 10 秒で再実行可能です。
+
+---
+
 ## 60 秒で始める
 
-### ステップ 1: インストール
+### オプション A — Claude Code プラグイン(ワンライナーインストール)
+
+Claude Code を使っている場合、CLI 内から MeMesh をプラグインとしてインストールできます:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code がフック、スキル、MCP サーバーを自動的にワイヤリングします。セッション内自動キャプチャ、プロアクティブリコール、Claude Code 会話内の `/memesh` スキル(remember / recall / learn / forget)、エージェント向け MCP ツールとしての `remember` / `recall` / `forget` / `learn` がすべて使えるようになります。CLI とローカルダッシュボードもグローバルインストールなしで完全にアクセス可能です — `npx @pcircle/memesh <command>` であらゆる CLI コマンドが実行でき、`npx @pcircle/memesh` で `localhost:3737` のダッシュボードが起動します。MCP サーバーは Anthropic の公式プラグイン(例: `context7`)と同じ `npx` ベースの起動パターンを使用するため、どの機能にも `npm install -g` は不要です。
+
+### オプション B — npm グローバル(オプションの最適化)
+
+シェルの `PATH` にバイナリを直接配置したい場合(`memesh`、`memesh-mcp` 等が任意のターミナルで `npx` ルックアップなしに動作)、または `memesh-mcp` を **Claude Code 以外の MCP クライアント**(Cursor、Cline、ターミナル専用フロー)に固定パスの stdio コマンドとして公開したい場合:
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### ステップ 1.5: MeMesh を Claude Code に接続(推奨、一度きり)
+> **初回インストールに関する注意(一度きり):**
+> - **ネイティブモジュール** — `better-sqlite3` と `sqlite-vec` は macOS (arm64/x64)、Linux (x64/arm64)、Windows x64 でビルド済みバイナリ経由でインストールされます。珍しいプラットフォームやビルド済みバイナリが失敗した場合は、動作する C/C++ ツールチェインが必要です。
+> - **エンベディングモデル** — ローカルエンベディングをトリガーする最初の呼び出し(例: セマンティックモードでの `recall`)で `Xenova/all-MiniLM-L6-v2`(~80 MB)が `~/.memesh/models/` にダウンロードされます。以降の呼び出しは即時です。デフォルトの検索パス(FTS5)はこのダウンロードを必要としません。
+
+### ステップ 1.5: MeMesh を Claude Code に接続(npm パスのみ)
 
-`npm install -g` は CLI を PATH に配置し MCP サーバーを登録しますが、MeMesh の Claude Code セッションフックは自動的にはワイヤリング**されません**。フックがないと `memesh remember` / `recall` は手動で使えますが、**自動キャプチャループ**(セッション → レッスン → 次のセッションで自発的にリコール)はサイレントになります。
+**オプション A**(`/plugin install memesh@pcircle-memesh`)でインストールした場合はこのステップをスキップしてください — Claude Code がプラグインフックを自動的にワイヤリングします。
+
+**オプション B**(`npm install -g`)でインストールした場合、CLI は PATH に配置され MCP サーバーは登録されますが、Claude Code セッションフックは自動的にはワイヤリングされません。フックがないと `memesh remember` / `recall` は手動で使えますが、**自動キャプチャループ**(セッション → レッスン → 次のセッションで自発的にリコール)はサイレントになります。
 
 ```bash
 memesh install-hooks         # ~/.claude/settings.json に memesh フックを追加
@@ -50,6 +82,14 @@ memesh doctor                # "Hooks wired into Claude Code" が PASS になる
 
 ### ステップ 2: 決定を記録
 
+> 以下の bash 例は `memesh` が `PATH` 上にあること(オプション B)を前提にしています。オプション A(プラグイン専用)のユーザーには等価な 2 つのパスがあります: Claude Code 会話内で尋ねる(`/memesh` スキル + MCP ツールが同じフローをカバー)か、任意のシェルで `memesh` を `npx @pcircle/memesh` に置き換える — フラグは同じで、グローバルインストール不要です。
+
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+または、後でフィルタリングしたい場合に安定した名前と型を付ける明示形式:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -157,13 +197,14 @@ memesh export-schema \
 
 ## Claude Code での自動動作
 
-すべてを手動で記録する必要はありません。MeMesh に **6 つのフック** があり、作業中に知識を自動キャプチャ・注入します:
+すべてを手動で記録する必要はありません。MeMesh に **7 つのフック** があり、作業中に知識を自動キャプチャ・注入します:
 
 | タイミング | MeMesh の動作 |
 |---------|-----------|
-| **セッション開始時** | 最も関連の高いメモリ + 過去の教訓から得た予防警告 + エージェント編成バナーをロード |
+| **セッション開始時** | 最も関連の高いメモリ + 過去の教訓から得た予防警告をロード |
 | **ファイル編集前** | ファイルまたはプロジェクト関連のメモリをリコール (Claude がコード執筆前) |
-| **bash コマンド実行前** | 高い検証性を持つコマンド (テスト、ビルド、lint、マイグレーション、デプロイ、ベンチマーク) をバックグラウンドエージェントとして実行するよう促す |
+| **bash コマンド実行前** | (オプトイン)高い検証性を持つコマンド(テスト、ビルド、lint、マイグレーション、デプロイ、ベンチマーク)をバックグラウンドエージェントとして実行するよう Claude を促す |
+| **記憶を依頼したとき** | "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" の意図(5 言語)を検出し、Claude に memesh 使用をリマインド |
 | **`git commit` 後** | 変更内容と diff 統計を記録 |
 | **Claude 停止時** | 編集ファイル、修正エラー、失敗から自動生成した構造化教訓をキャプチャ |
 | **コンテキスト圧縮前** | コンテキスト限界で失われる前に知識を保存 |
@@ -172,15 +213,36 @@ memesh export-schema \
 
 ---
 
+## 設定
+
+すべての設定は環境変数経由です。デフォルトはローカル専用・ネットワークなしで、何も設定せずに動作するシステムが手に入ります。
+
+| 変数 | デフォルト | 動作 |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | SQLite データベースの保存場所を上書き。 |
+| `MEMESH_AUTO_CAPTURE` | `true` | 自動キャプチャフック(`Stop`、`PreCompact`)を完全に無効化。 |
+| `MEMESH_AUTO_DETECT_LLM` | 未設定 | `1` に設定すると、memesh がシェル環境変数(`OPENAI_API_KEY` 等)からプロバイダを自動検出し BYOK エンベディングに切り替えます。**新規インストールのデフォルトはローカル ONNX(384 次元)のみ** — クラウドエンベディングを使いたい場合のみオプトインしてください。このフラグが未設定なら、シェルに `OPENAI_API_KEY` があっても無視されます。 |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | 未設定 | `1` に設定すると、実験的なワーキングモデルプロトコル(CTO / Orchestrator / Agents のフレーミング)が有効になります。セッション開始バナー、Bash コマンドの促し、`verify_agent_work` テレメトリが追加されます。プロトコルの有効性は計測中であり、まだ証明されていません — 参加したい場合のみオプトイン。**デフォルトは OFF**: コアメモリ機能はこのフラグなしで動作します。 |
+| `MEMESH_AUTO_UPDATE` | `off` | 自動更新ポリシー。`off`(デフォルト)は自動更新を行いません。`patch` は `X.Y.Z → X.Y.Z+N` を許可、`minor` は `X.Y.Z → X.Y+1.0` を追加、`major` は任意のバンプを許可。許可されている場合、デタッチ実行された `npm install -g` がセッション終了時(Stop フック)に発火するため作業をブロックしません — 結果は `~/.memesh/auto-update.log` に記録されます。`~/.memesh/config.json` の `autoUpdate` でも設定可能(env が優先)。インストール済みバージョンがメンテナーによって非推奨化された場合(セキュリティアドバイザリ)、`off` でも `patch` は強制的に許可されます — minor / major バンプはサイレントな挙動変化を避けるため手動のままです。 |
+| `OPENAI_API_KEY` | 未設定 | OpenAI のキー。`MEMESH_AUTO_DETECT_LLM=1` のとき、または明示的にプロバイダを設定したときのみ使用。 |
+| `OLLAMA_HOST` | `http://localhost:11434` | ローカル Ollama プロバイダ使用時の Ollama エンドポイントを上書き。 |
+
+`memesh doctor` は解決された設定を表示するため、何が有効かを確認できます。
+
+npm がインストール済みバージョンを非推奨としてフラグした場合(典型的にはセキュリティアドバイザリ)、次のセッション開始時に強い `⚠️ MeMesh <ver> is DEPRECATED` バナーが先頭に表示され、`memesh update-status` がアップグレードまで同じ行を表示し続けます。チェックは `~/.memesh/update-check.<version>.json` にキャッシュされ、一時的なネットワーク障害で警告が薄まらないようになっています。
+
+---
+
 ## ダッシュボード
 
-7 つのタブ、11 言語対応、外部依存なし。サーバー実行中は `http://localhost:3737/dashboard` でアクセス可能。
+8 つのタブ、11 言語対応、外部依存なし。サーバー実行中は `http://localhost:3737/dashboard` でアクセス可能。
 
 | タブ | 表示内容 |
 |-----|--------|
+| **Insights** | メモリインサイト — dreamer エンジンによる週次サマリーとパターン提案。ワンクリックで承認・拒否 |
 | **Search** | 全メモリ対象の全文検索 + ベクトル類似度検索 |
 | **Browse** | ページネーション表示された全エンティティ、アーカイブ・復元機能 |
-| **Analytics** | メモリ健全性スコア (0-100)、30 日間タイムライン、価値指標、知識カバレッジ、クリーンアップ提案、あなたの作業パターン |
+| **Analytics** | メモリ健全性スコア、30 日間タイムライン、PM ベロシティ + KG 接続性指標、作業パターン、クリーンアップ提案 |
 | **Graph** | インタラクティブ力指向知識グラフ、型フィルタ、検索、エゴモード、再度ヒートマップ |
 | **Lessons** | 過去の失敗から構造化された教訓 (エラー、根本原因、修正、予防) |
 | **Manage** | エンティティのアーカイブ・復元 |
@@ -190,7 +252,7 @@ memesh export-schema \
 
 ## スマート機能
 
-**🧠 スマート検索** — 「login security」で検索すると「OAuth PKCE」についてのメモリが見つかります。設定した LLM を使いクエリを関連用語で拡張します。
+**🧠 スマート検索** — 「login security」で検索すると「OAuth PKCE」についてのメモリが見つかります。MeMesh は設定された LLM を使い、クエリを関連用語で拡張します。
 
 **📊 スコア付きランキング** — 関連性 (30%) + 新しさ (25%) + 頻度 (15%) + 信頼度 (15%) + リコール影響度 (10%) + 時間的有効性 (5%) でランク付け。
 
@@ -198,6 +260,8 @@ memesh export-schema \
 
 **⚠️ 矛盾検出** — 互いに矛盾するメモリが 2 つある場合、MeMesh が警告します。
 
+**🕸️ ナレッジグラフ接続性** — `memesh kg backfill-relations --all-rules` はタグの共起・プロジェクトクラスタリング・セッションコンテキスト・名前類似度を使って孤立エンティティをリンク — LLM 不要。代表的なナレッジベースで孤立率を 89% から 12% 未満に削減。
+
 **📦 チーム共有** — `memesh export > team-knowledge.json` → チームと共有 → `memesh import team-knowledge.json`。
 インポートされたバンドルは検索可能ですが、MeMesh はレビュー・ローカル再保存まで Claude フックへの自動注入はしません。
 
@@ -218,7 +282,7 @@ memesh export-schema \
 
 ## スマートモードをアンロック (オプション)
 
-MeMesh はデフォルトでオフライン動作します。クエリ拡張、より賢い抽出、圧縮が必要な場合のみ LLM API キーを追加:
+MeMesh はデフォルトでオフライン動作します — リコールは厳密に LLM フリーのまま(箱出し状態で LongMemEval-S 95.40% R@5)。LLM API キーを追加するのは、その上に LLM 拡張の分析フローを重ねたい場合のみです: より賢いセッション抽出、新規メモリの自動タグ付け、失敗からのレッスン生成、`consolidate` / `dream` 圧縮:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -233,10 +297,12 @@ memesh  # ダッシュボード → Settings タブを開く
 
 | | レベル 0 (デフォルト) | レベル 1 (スマートモード) |
 |---|---|---|
-| **検索** | FTS5 キーワードマッチング | + LLM クエリ拡張 (~97% リコール率) |
+| **検索** | FTS5 + sqlite-vec、95.40% R@5(~18ms/クエリ) | 変更なし — リコールはどのレベルでも LLM フリー |
 | **自動キャプチャ** | ルールベースパターン | + LLM が判断・教訓を抽出 |
-| **圧縮** | 利用不可 | `consolidate` で冗長メモリを圧縮 |
-| **コスト** | 無料、API キー不要 | 検索あたり ~$0.0001 (Haiku) |
+| **自動タグ付け** | 手動タグのみ | + LLM が新規メモリにタグを生成 |
+| **失敗分析** | 利用不可 | + LLM がセッションエラーを構造化教訓に変換 |
+| **圧縮** | 利用不可 | `consolidate` + `dream` が冗長メモリを圧縮 |
+| **コスト** | 無料、API キー不要 | 分析呼び出しあたり ~$0.0001(Haiku) |
 
 ---
 
@@ -245,7 +311,7 @@ memesh  # ダッシュボード → Settings タブを開く
 | ツール | 機能 |
 |------|------|
 | `remember` | 観察、関係、タグ付きで知識を保存 |
-| `recall` | 多要素スコアリングと LLM クエリ拡張のスマート検索 |
+| `recall` | FTS5 + sqlite-vec 検索、多要素スコアリング(関連性、新しさ、頻度、信頼度、時間的有効性) — ホットパスに LLM なし |
 | `forget` | ソフトアーカイブ (削除されない) または特定の観察を削除 |
 | `consolidate` | LLM が冗長メモリを圧縮 |
 | `export` | メモリを JSON でシェア (プロジェクト・チーム間) |

package/README.ko.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,17 +26,52 @@
 
 ---
 
+## 검증 — LongMemEval-S에서 R@5 95.40%
+
+MeMesh의 검색 엔진은 **FTS5 단독**(핫 패스에 LLM 없음, 임베딩 없음)이며, 공개 [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) 벤치마크(500개 질문, MIT 라이선스)로 측정되었습니다:
+
+| 시스템 | R@5 | 출처 |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | 벤더 자체 보고 |
+| Supermemory | ~82% | 벤더 추정치 |
+| Zep | 63.8% | LongMemEval 논문 |
+| Mem0 | 49.0% | LongMemEval 논문 |
+
+재현 명령어, 데이터셋 SHA256, 질문별 원시 결과, 알려진 실패 분석이 모두 [`benchmarks/longmemeval/`](benchmarks/longmemeval/)에 있습니다. 약 10초 내에 재실행 가능합니다.
+
+---
+
 ## 60초 안에 시작하기
 
-### 1단계: 설치
+### 옵션 A — Claude Code 플러그인 (한 줄 설치)
+
+Claude Code를 사용한다면 CLI 안에서 MeMesh를 플러그인으로 설치합니다:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code가 훅, 스킬, MCP 서버를 자동으로 연결합니다. 세션 내 자동 캡처, 능동적 회상, Claude Code 대화 내 `/memesh` 스킬(remember / recall / learn / forget), 그리고 에이전트가 사용할 수 있는 MCP 도구 `remember` / `recall` / `forget` / `learn`을 모두 얻을 수 있습니다. CLI와 로컬 대시보드도 추가 글로벌 설치 없이 완전히 접근 가능합니다 — `npx @pcircle/memesh <command>`로 모든 CLI 명령을 실행하고, `npx @pcircle/memesh`로 `localhost:3737`의 대시보드를 시작합니다. MCP 서버는 Anthropic 공식 플러그인(예: `context7`)과 동일한 `npx` 기반 실행 패턴을 사용하므로, 어떤 기능도 `npm install -g`가 필요하지 않습니다.
+
+### 옵션 B — npm 글로벌 (선택적 최적화)
+
+바이너리를 셸 `PATH`에 직접 두고 싶거나(매 호출마다 `npx` 조회 없이 모든 터미널에서 단순 `memesh`, `memesh-mcp` 등이 작동), `memesh-mcp`를 **Claude Code 이외의 MCP 클라이언트**(Cursor, Cline, 터미널 전용 워크플로우)에 고정 경로 stdio 명령으로 노출하고 싶다면:
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 1.5단계: MeMesh를 Claude Code에 연결(권장, 일회성)
+> **첫 설치 안내(일회성):**
+> - **네이티브 모듈** — `better-sqlite3`와 `sqlite-vec`는 macOS(arm64/x64), Linux(x64/arm64), Windows x64에서 사전 빌드 바이너리로 설치됩니다. 흔치 않은 플랫폼이거나 사전 빌드가 실패하는 경우 작동하는 C/C++ 툴체인이 필요합니다.
+> - **임베딩 모델** — 로컬 임베딩을 트리거하는 첫 호출(예: 시맨틱 모드의 `recall`)이 `Xenova/all-MiniLM-L6-v2`(~80 MB)를 `~/.memesh/models/`에 다운로드합니다. 이후 호출은 즉시 실행됩니다. 기본 검색 경로(FTS5)는 이 다운로드가 필요하지 않습니다.
+
+### 1.5단계: MeMesh를 Claude Code에 연결 (npm 경로만)
 
-`npm install -g`는 CLI를 PATH에 추가하고 MCP 서버를 등록하지만, MeMesh의 Claude Code 세션 훅을 자동으로 연결하지는 **않습니다**. 훅이 없으면 `memesh remember` / `recall`을 수동으로 사용할 수 있지만, **자동 캡처 루프**(세션 → 교훈 → 다음 세션에서 능동적 회상)는 작동하지 않습니다.
+**옵션 A**(`/plugin install memesh@pcircle-memesh`)로 설치했다면, 이 단계를 건너뜁니다 — Claude Code가 플러그인 훅을 자동으로 연결합니다.
+
+**옵션 B**(`npm install -g`)로 설치했다면, CLI는 PATH에 있고 MCP 서버는 등록되지만, Claude Code 세션 훅은 자동으로 연결되지 않습니다. 훅이 없으면 `memesh remember` / `recall`을 수동으로 사용할 수 있지만, **자동 캡처 루프**(세션 → 교훈 → 다음 세션에서 회상)는 작동하지 않습니다.
 
 ```bash
 memesh install-hooks         # ~/.claude/settings.json에 memesh 훅 추가
@@ -50,6 +82,14 @@ memesh doctor                # "Hooks wired into Claude Code" PASS 확인
 
 ### 2단계: 의사결정 저장
 
+> 아래 bash 예제는 `memesh`가 `PATH`에 있다고 가정합니다(옵션 B). 옵션 A(플러그인 전용) 사용자는 두 가지 동등한 경로가 있습니다: Claude Code 대화에서 직접 요청하거나(`/memesh` 스킬 + MCP 도구가 동일한 흐름을 커버), 셸에서 `memesh`를 `npx @pcircle/memesh`로 대체합니다 — 동일한 플래그, 글로벌 설치 불필요.
+
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+또는 나중에 필터링할 수 있도록 안정적인 이름과 타입을 원하면 명시적 형식을 사용합니다:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -63,7 +103,7 @@ memesh recall "login security"
 
 **이게 전부입니다.** MeMesh가 이제 세션 간에 기억하고 회상합니다.
 
-설치와 로컬 연결을 확인하려면:
+설치와 로컬 연결을 엔드 투 엔드로 확인하려면:
 
 ```bash
 memesh doctor
@@ -157,13 +197,14 @@ memesh export-schema \
 
 ## Claude Code에서 자동으로 일어나는 일
 
-모든 것을 수동으로 기억할 필요는 없습니다. MeMesh는 작업 중에 지식을 캡처하고 주입하는 **6가지 훅**이 있습니다:
+모든 것을 수동으로 기억할 필요는 없습니다. MeMesh는 작업 중에 지식을 캡처하고 주입하는 **7가지 훅**이 있습니다:
 
 | 시점 | MeMesh가 수행하는 작업 |
 |------|---|
-| **매 세션 시작** | 가장 관련 있는 메모리 + 과거 교훈의 사전 경고 + 에이전트 오케스트레이션 배너 로드 |
+| **매 세션 시작** | 가장 관련 있는 메모리 + 과거 교훈의 사전 경고 로드 |
 | **파일 편집 전** | Claude가 코드를 작성하기 전에 파일 또는 프로젝트와 연결된 메모리 회상 |
-| **Bash 명령 전** | Claude가 높은 검증 가능성의 명령어(테스트, 빌드, 린트, 마이그레이션, 배포, 벤치마크)를 백그라운드 에이전트로 실행하도록 유도 |
+| **Bash 명령 전** | (옵트인) Claude가 높은 검증 가능성의 명령어(테스트, 빌드, 린트, 마이그레이션, 배포, 벤치마크)를 백그라운드 에이전트로 실행하도록 유도 |
+| **기억 요청 시** | "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" 의도(5개 언어)를 감지하고 Claude가 memesh를 사용하도록 알림 |
 | **모든 `git commit` 후** | 변경 사항을 diff 통계와 함께 기록 |
 | **Claude가 멈출 때** | 편집된 파일, 수정된 에러, 실패로부터 자동 생성된 구조화된 교훈 캡처 |
 | **컨텍스트 압축 전** | 컨텍스트 제한으로 손실되기 전에 지식 저장 |
@@ -172,15 +213,36 @@ memesh export-schema \
 
 ---
 
+## 구성
+
+모든 구성은 환경 변수를 통해 이루어집니다. 기본값은 로컬 전용이고 네트워크 사용이 없습니다 — 작동하는 시스템을 얻기 위해 아무것도 설정할 필요가 없습니다.
+
+| 변수 | 기본값 | 역할 |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | SQLite 데이터베이스 위치를 재정의합니다. |
+| `MEMESH_AUTO_CAPTURE` | `true` | 자동 캡처 훅(`Stop`, `PreCompact`)을 완전히 비활성화합니다. |
+| `MEMESH_AUTO_DETECT_LLM` | unset | `1`로 설정하면 memesh가 셸 환경 변수(`OPENAI_API_KEY` 등)에서 프로바이더를 자동 감지하고 BYOK 임베딩으로 전환합니다. **새 설치의 기본값은 로컬 ONNX(384-dim) 전용** — 클라우드 임베딩을 원하면 옵트인하세요. 이 플래그가 설정되지 않으면, 셸에 남아있는 `OPENAI_API_KEY`는 무시됩니다. |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | `1`로 설정하면 실험적 작업 모델 프로토콜(CTO / Orchestrator / Agents 프레이밍)을 활성화합니다. 세션 시작 배너, Bash 명령 nudge, `verify_agent_work` 텔레메트리를 추가합니다. 이 프로토콜의 효과는 측정 중이며 아직 입증되지 않았습니다 — 참여하려면 옵트인하세요. **기본값은 OFF**: 코어 메모리 기능은 이 플래그 없이도 작동합니다. |
+| `MEMESH_AUTO_UPDATE` | `off` | 자동 업데이트 정책. `off`(기본값)는 자동 업데이트하지 않습니다; `patch`는 `X.Y.Z → X.Y.Z+N`을 허용합니다; `minor`는 `X.Y.Z → X.Y+1.0`을 추가합니다; `major`는 모든 bump를 허용합니다. 허용된 경우, 분리된 `npm install -g`가 세션 종료 시(Stop 훅) 실행되어 작업을 차단하지 않습니다 — 결과는 `~/.memesh/auto-update.log`에 기록됩니다. `~/.memesh/config.json`에서도 `autoUpdate`로 설정 가능합니다(env가 우선). 설치된 버전이 메인테이너에 의해 deprecated된 경우(보안 권고), `off`에서도 `patch`가 강제 허용됩니다 — minor / major bump는 조용한 동작 변화를 피하기 위해 수동으로 유지됩니다. |
+| `OPENAI_API_KEY` | unset | OpenAI 키. `MEMESH_AUTO_DETECT_LLM=1`이거나 명시적으로 프로바이더를 구성한 경우에만 사용됩니다. |
+| `OLLAMA_HOST` | `http://localhost:11434` | 로컬 Ollama 프로바이더를 사용할 때 Ollama 엔드포인트를 재정의합니다. |
+
+`memesh doctor`는 활성화된 항목을 볼 수 있도록 해결된 구성을 출력합니다.
+
+npm이 설치된 버전을 deprecated로 플래그하면(일반적으로 보안 권고), 다음 세션 시작 시 강력한 `⚠️ MeMesh <ver> is DEPRECATED` 배너가 앞에 추가되고, 업그레이드할 때까지 `memesh update-status`가 동일한 라인을 표시합니다. 일시적인 네트워크 실패가 경고를 흐리지 않도록 검사가 `~/.memesh/update-check.<version>.json`에 캐시됩니다.
+
+---
+
 ## 대시보드
 
-7개 탭, 11개 언어, 외부 의존성 없음. 서버 실행 중 `http://localhost:3737/dashboard`에서 접근합니다.
+8개 탭, 11개 언어, 외부 의존성 없음. 서버 실행 중 `http://localhost:3737/dashboard`에서 접근합니다.
 
 | 탭 | 내용 |
 |------|---|
+| **Insights** | 메모리 인사이트 — dreamer 엔진의 주간 요약 및 패턴 제안; 원클릭 수락/거절 |
 | **Search** | 모든 메모리에 걸친 전체 텍스트 + 벡터 유사성 검색 |
 | **Browse** | 보관 및 복구 옵션이 있는 모든 엔티티 페이지 리스트 |
-| **Analytics** | 메모리 건강 점수(0-100), 30일 타임라인, 가치 지표, 지식 커버리지, 정리 제안, 작업 패턴 |
+| **Analytics** | 메모리 건강 점수, 30일 타임라인, PM 속도 + KG 연결성 지표, 작업 패턴, 정리 제안 |
 | **Graph** | 타입 필터, 검색, 에고 모드, 최근성 히트맵이 있는 인터랙티브 포스 디렉션 지식 그래프 |
 | **Lessons** | 과거 실패로부터 구조화된 교훈(에러, 근본 원인, 수정, 예방) |
 | **Manage** | 엔티티 보관 및 복구 |
@@ -190,14 +252,16 @@ memesh export-schema \
 
 ## 스마트 기능
 
-**🧠 스마트 검색** — "login security"를 검색하면 "OAuth PKCE"에 관한 메모리를 찾습니다. MeMesh는 설정된 LLM으로 쿼리를 관련 용어로 확장합니다.
+**🧠 스마트 검색** — FTS5 + sqlite-vec를 사용해 모든 메모리에서 즉시 검색. 핫 패스에 LLM이 없어 LongMemEval-S에서 R@5 95.40% 달성.
 
 **📊 점수 순위 매김** — 결과는 관련성(30%) + 최근성(25%) + 빈도(15%) + 신뢰도(15%) + 회상 영향(10%) + 시계열 유효성(5%)으로 순위 매겨집니다.
 
-**🔄 지식 진화** — 결정은 변합니다. `forget`으로 오래된 메모리 보관(절대 삭제 안 함). `supersedes` 관계가 구 → 신 을 연결합니다. AI는 항상 최신 버전을 봅니다.
+**🔄 지식 진화** — 결정은 변합니다. `forget`으로 오래된 메모리 보관(절대 삭제 안 함). `supersedes` 관계가 구 → 신을 연결합니다. AI는 항상 최신 버전을 봅니다.
 
 **⚠️ 충돌 감지** — 서로 모순되는 메모리 두 개가 있으면 MeMesh가 경고합니다.
 
+**🕸️ 지식 그래프 연결성** — `memesh kg backfill-relations --all-rules`는 태그 공동 발생, 프로젝트 클러스터링, 세션 컨텍스트, 이름 유사성을 사용해 고아 엔티티를 연결 — LLM 불필요. 대표적인 지식 베이스에서 고아 비율을 89%에서 12% 미만으로 감소.
+
 **📦 팀 공유** — `memesh export > team-knowledge.json` → 팀과 공유 → `memesh import team-knowledge.json`
 임포트된 번들은 계속 검색 가능하지만, MeMesh는 검토하거나 로컬에 다시 저장할 때까지 Claude 훅에 임포트된 메모리를 자동 주입하지 않습니다.
 
@@ -216,9 +280,9 @@ memesh export-schema \
 
 ---
 
-## 스마트 모드 언잠금 (선택)
+## 스마트 모드 언락 (선택)
 
-MeMesh는 기본적으로 오프라인에서 작동합니다. 쿼리 확장, 더 스마트한 추출, 압축을 원할 때만 LLM API 키를 추가합니다:
+MeMesh는 기본적으로 오프라인에서 작동합니다 — 회상은 엄격히 LLM-free로 유지됩니다(기본 설치만으로 LongMemEval-S에서 R@5 95.40%). LLM API 키는 그 위에 LLM 증강 분석 흐름을 원할 때만 추가합니다: 더 스마트한 세션 추출, 새 메모리의 자동 태그 부여, 실패로부터의 교훈 생성, `consolidate` / `dream` 압축:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -233,10 +297,12 @@ memesh  # 대시보드 열기 → Settings 탭
 
 | | Level 0 (기본) | Level 1 (스마트 모드) |
 |---|---|---|
-| **검색** | FTS5 키워드 매칭 | + LLM 쿼리 확장 (~97% 회상율) |
+| **검색** | FTS5 + sqlite-vec, R@5 95.40% (~18ms/쿼리) | 변경 없음 — 회상은 모든 레벨에서 LLM-free |
 | **자동 캡처** | 규칙 기반 패턴 | + LLM이 결정과 교훈 추출 |
-| **압축** | 사용 불가 | `consolidate`로 장황한 메모리 압축 |
-| **비용** | 무료, API 키 불필요 | ~$0.0001 검색당 (Haiku) |
+| **자동 태그 부여** | 수동 태그만 | + LLM이 새 메모리에 태그 생성 |
+| **실패 분석** | 사용 불가 | + LLM이 세션 에러를 구조화된 교훈으로 변환 |
+| **압축** | 사용 불가 | `consolidate` + `dream`이 장황한 메모리 압축 |
+| **비용** | 무료, API 키 불필요 | ~$0.0001 분석 호출당 (Haiku) |
 
 ---
 
@@ -245,7 +311,7 @@ memesh  # 대시보드 열기 → Settings 탭
 | 도구 | 역할 |
 |---|---|
 | `remember` | 관찰, 관계, 태그를 포함한 지식 저장 |
-| `recall` | 다중 요소 점수 매김과 LLM 쿼리 확장이 있는 스마트 검색 |
+| `recall` | 다중 요소 점수 매김(관련성, 최근성, 빈도, 신뢰도, 시계열 유효성)이 있는 FTS5 + sqlite-vec 검색 — 핫 패스에 LLM 없음 |
 | `forget` | 소프트 보관(절대 삭제 안 함) 또는 특정 관찰 제거 |
 | `consolidate` | LLM 기반 장황한 메모리 압축 |
 | `export` | 프로젝트나 팀 멤버 간 메모리 JSON 공유 |

package/README.md

@@ -235,13 +235,14 @@ When npm flags an installed version as deprecated (typically a security advisory
 
 ## Dashboard
 
-7 tabs, 11 languages, zero external dependencies. Access at `http://localhost:3737/dashboard` when the server is running.
+8 tabs, 11 languages, zero external dependencies. Access at `http://localhost:3737/dashboard` when the server is running.
 
 | Tab | What you see |
 |-----|-------------|
+| **Insights** | Memory insights — weekly recaps and pattern proposals from the dreamer engine; one-click accept/reject |
 | **Search** | Full-text + vector similarity search across all memories |
 | **Browse** | Paginated list of all entities with archive/restore |
-| **Analytics** | Memory Health Score (0-100), 30-day timeline, value metrics, knowledge coverage, cleanup suggestions, your work patterns |
+| **Analytics** | Memory Health Score, 30-day timeline, PM velocity + KG connectivity metrics, work patterns, cleanup suggestions |
 | **Graph** | Interactive force-directed knowledge graph with type filters, search, ego mode, recency heatmap |
 | **Lessons** | Structured lessons from past failures (error, root cause, fix, prevention) |
 | **Manage** | Archive and restore entities |
@@ -259,6 +260,8 @@ When npm flags an installed version as deprecated (typically a security advisory
 
 **⚠️ Conflict Detection** — If you have two memories that contradict each other, MeMesh warns you.
 
+**🕸️ Knowledge Graph Connectivity** — `memesh kg backfill-relations --all-rules` links orphan entities using tag co-occurrence, project clustering, session context, and name similarity — no LLM required. Reduces orphan rate from 89% to under 12% on a representative knowledge base.
+
 **📦 Team Sharing** — `memesh export > team-knowledge.json` → share with your team → `memesh import team-knowledge.json`
 Imported bundles stay searchable, but MeMesh does not auto-inject imported memories into Claude hooks until you review or re-store them locally.
 
@@ -279,7 +282,7 @@ Imported bundles stay searchable, but MeMesh does not auto-inject imported memor
 
 ## Unlock Smart Mode (Optional)
 
-MeMesh works offline by default. Add an LLM API key only if you want query expansion, smarter extraction, and compression:
+MeMesh works offline by default — recall stays strictly LLM-free (95.40% R@5 on LongMemEval-S out of the box). Add an LLM API key only if you want LLM-augmented analysis flows on top: smarter session extraction, auto-tagging of new memories, lesson generation from failures, and `consolidate` / `dream` compression:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -294,10 +297,12 @@ memesh  # opens dashboard → Settings tab
 
 | | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5 keyword matching | + LLM query expansion (~97% recall) |
+| **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/query) | unchanged — recall is LLM-free at every level |
 | **Auto-capture** | Rule-based patterns | + LLM extracts decisions & lessons |
-| **Compression** | Not available | `consolidate` compresses verbose memories |
-| **Cost** | Free, no API key | ~$0.0001 per search (Haiku) |
+| **Auto-tagging** | Manual tags only | + LLM generates tags for new memories |
+| **Failure analysis** | Not available | + LLM converts session errors into structured lessons |
+| **Compression** | Not available | `consolidate` + `dream` compress verbose memories |
+| **Cost** | Free, no API key | ~$0.0001 per analysis call (Haiku) |
 
 ---
 
@@ -306,7 +311,7 @@ memesh  # opens dashboard → Settings tab
 | Tool | What it does |
 |------|-------------|
 | `remember` | Store knowledge with observations, relations, and tags |
-| `recall` | Smart search with multi-factor scoring and LLM query expansion |
+| `recall` | FTS5 + sqlite-vec search with multi-factor scoring (relevance, recency, frequency, confidence, temporal validity) — no LLM in the hot path |
 | `forget` | Soft-archive (never deletes) or remove specific observations |
 | `consolidate` | LLM-powered compression of verbose memories |
 | `export` | Share memories as JSON between projects or team members |

package/README.pt.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,6 +26,22 @@ Este pacote é a camada de memória local da família de produtos MeMesh. É pro
 
 ---
 
+## Prova — 95,40% R@5 no LongMemEval-S
+
+O motor de recuperação do MeMesh é **apenas FTS5** (sem LLM, sem embeddings no hot path), medido contra o benchmark público [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 perguntas, licença MIT):
+
+| Sistema | R@5 | Fonte |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95,40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96,6% | Auto-relato do fornecedor |
+| Supermemory | ~82% | Estimativa do fornecedor |
+| Zep | 63,8% | Paper LongMemEval |
+| Mem0 | 49,0% | Paper LongMemEval |
+
+Comandos de reprodução, SHA256 do dataset, resultados brutos por pergunta e análise de falhas conhecidas estão todos em [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Reexecutável em ~10 segundos.
+
+---
+
 ## Comece em 60 Segundos
 
 ### Passo 1: Instale
@@ -173,15 +186,36 @@ Você não precisa lembrar tudo manualmente. MeMesh tem **7 hooks** que capturam
 
 ---
 
+## Configuração
+
+Toda a configuração é feita por variáveis de ambiente. Os padrões são local-only e zero-network — você não precisa configurar nada para ter um sistema funcional.
+
+| Variável | Padrão | O que faz |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Sobrescreve a localização do banco SQLite. |
+| `MEMESH_AUTO_CAPTURE` | `true` | Desativa completamente os hooks de auto-captura (`Stop`, `PreCompact`). |
+| `MEMESH_AUTO_DETECT_LLM` | unset | Defina como `1` para que o memesh detecte automaticamente um provedor a partir do seu env de shell (`OPENAI_API_KEY` etc.) e mude para embeddings BYOK. **A instalação fresca por padrão é apenas ONNX local (384-dim)** — opte se quiser embeddings na nuvem. Sem essa flag, uma `OPENAI_API_KEY` esquecida no seu shell é ignorada. |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | Defina como `1` para habilitar um protocolo experimental de modelo de trabalho (enquadramento CTO / Orchestrator / Agents). Adiciona um banner de início de sessão, um nudge para comandos Bash e telemetria `verify_agent_work`. A eficácia do protocolo está sendo instrumentada, ainda não comprovada — opte se quiser participar. **Padrão é OFF**: as funcionalidades de memória core funcionam sem essa flag. |
+| `MEMESH_AUTO_UPDATE` | `off` | Política de auto-update. `off` (padrão) nunca faz auto-update; `patch` permite `X.Y.Z → X.Y.Z+N`; `minor` adiciona `X.Y.Z → X.Y+1.0`; `major` permite qualquer bump. Quando permitido, um `npm install -g` desanexado dispara no fim da sessão (hook Stop) para nunca bloquear seu trabalho — os resultados aparecem em `~/.memesh/auto-update.log`. Também configurável como `autoUpdate` em `~/.memesh/config.json` (env vence). Quando a versão instalada é depreciada pelos mantenedores (advisory de segurança), `patch` é forçado mesmo em `off` — bumps minor / major continuam manuais para evitar drift silencioso de comportamento. |
+| `OPENAI_API_KEY` | unset | Sua chave OpenAI. Usada apenas quando `MEMESH_AUTO_DETECT_LLM=1` ou você configura o provedor explicitamente. |
+| `OLLAMA_HOST` | `http://localhost:11434` | Sobrescreve o endpoint do Ollama ao usar um provedor Ollama local. |
+
+`memesh doctor` imprime a configuração resolvida para você ver o que está ativo.
+
+Quando o npm sinaliza uma versão instalada como depreciada (tipicamente um advisory de segurança), o próximo início de sessão antepõe um banner forte `⚠️ MeMesh <ver> is DEPRECATED` e `memesh update-status` mostra a mesma linha até você atualizar. A verificação fica em cache em `~/.memesh/update-check.<version>.json` para que uma falha de rede transitória não atenue o aviso.
+
+---
+
 ## Dashboard
 
-7 abas, 11 idiomas, zero dependências externas. Acesse em `http://localhost:3737/dashboard` quando o servidor estiver rodando.
+8 abas, 11 idiomas, zero dependências externas. Acesse em `http://localhost:3737/dashboard` quando o servidor estiver rodando.
 
 | Aba | O que você vê |
 |-----|-------------|
+| **Insights** | Insights de memória — resumos semanais e propostas de padrões do motor dreamer; aceitar/rejeitar com um clique |
 | **Search** | Busca full-text + similaridade vetorial em todas as memórias |
 | **Browse** | Lista paginada de todas as entidades com archive/restore |
-| **Analytics** | Memory Health Score (0-100), timeline de 30 dias, métricas de valor, cobertura de conhecimento, sugestões de limpeza, seus padrões de trabalho |
+| **Analytics** | Memory Health Score, timeline de 30 dias, velocidade PM + métricas de conectividade KG, padrões de trabalho, sugestões de limpeza |
 | **Graph** | Grafo de conhecimento interativo force-directed com filtros por tipo, busca, modo ego, heatmap de recência |
 | **Lessons** | Lições estruturadas de falhas passadas (erro, causa raiz, fix, prevenção) |
 | **Manage** | Archive e restore de entidades |
@@ -199,6 +233,8 @@ Você não precisa lembrar tudo manualmente. MeMesh tem **7 hooks** que capturam
 
 **⚠️ Detecção de Conflitos** — Se você tem duas memórias que se contradizem, MeMesh te avisa.
 
+**🕸️ Conectividade do grafo de conhecimento** — `memesh kg backfill-relations --all-rules` liga entidades órfãs usando co-ocorrência de tags, agrupamento de projetos, contexto de sessão e similaridade de nomes — sem LLM. Reduz a taxa de órfãos de 89% para menos de 12% numa base de conhecimento representativa.
+
 **📦 Compartilhamento em Equipe** — `memesh export > team-knowledge.json` → compartilhe com sua equipe → `memesh import team-knowledge.json`
 Bundles importados permanecem pesquisáveis, mas MeMesh não injeta automaticamente memórias importadas nos hooks do Claude até você revisar ou re-armazená-las localmente.
 
@@ -219,7 +255,7 @@ Bundles importados permanecem pesquisáveis, mas MeMesh não injeta automaticame
 
 ## Desbloqueie Smart Mode (Opcional)
 
-MeMesh funciona offline por padrão. Adicione uma chave de API de LLM apenas se quiser query expansion, extração mais inteligente e compressão:
+MeMesh funciona offline por padrão — o recall permanece estritamente LLM-free (95,40% R@5 no LongMemEval-S, sem LLM). Adicione uma chave de API de LLM apenas se quiser fluxos de análise LLM-augmented adicionais: extração de sessão mais inteligente, auto-tagging de novas memórias, geração de lessons a partir de falhas, e compressão `consolidate` / `dream`:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -234,10 +270,12 @@ memesh  # abre dashboard → aba Settings
 
 | | Level 0 (padrão) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Busca** | Correspondência de keywords FTS5 | + query expansion de LLM (~97% recall) |
+| **Busca** | FTS5 + sqlite-vec, 95,40% R@5 (~18ms/query) | inalterado — recall é LLM-free em todos os níveis |
 | **Auto-capture** | Padrões baseados em regras | + LLM extrai decisões & lições |
-| **Compressão** | Não disponível | `consolidate` comprime memórias verbosas |
-| **Custo** | Grátis, sem chave de API | ~$0.0001 por busca (Haiku) |
+| **Auto-tagging** | Apenas tags manuais | + LLM gera tags para novas memórias |
+| **Análise de falhas** | Não disponível | + LLM converte erros de sessão em structured lessons |
+| **Compressão** | Não disponível | `consolidate` + `dream` comprimem memórias verbosas |
+| **Custo** | Grátis, sem chave de API | ~$0.0001 por analysis call (Haiku) |
 
 ---
 
@@ -246,7 +284,7 @@ memesh  # abre dashboard → aba Settings
 | Ferramenta | O que faz |
 |------|-------------|
 | `remember` | Armazena conhecimento com observações, relações e tags |
-| `recall` | Busca inteligente com scoring multi-fator e query expansion com LLM |
+| `recall` | Busca FTS5 + sqlite-vec com scoring multi-fator (relevância, recência, frequência, confiança, validade temporal) — sem LLM no hot path |
 | `forget` | Soft-archive (nunca deleta) ou remove observações específicas |
 | `consolidate` | Compressão com LLM de memórias verbosas |
 | `export` | Compartilha memórias como JSON entre projetos ou membros da equipe |