@pcircle/memesh 4.1.7 → 4.2.0

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)는 이 다운로드가 필요하지 않습니다.
 
-`npm install -g`는 CLI를 PATH에 추가하고 MCP 서버를 등록하지만, MeMesh의 Claude Code 세션 훅을 자동으로 연결하지는 **않습니다**. 훅이 없으면 `memesh remember` / `recall`을 수동으로 사용할 수 있지만, **자동 캡처 루프**(세션 → 교훈 → 다음 세션에서 능동적 회상)는 작동하지 않습니다.
+### 1.5단계: MeMesh를 Claude Code에 연결 (npm 경로만)
+
+**옵션 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,6 +213,26 @@ 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`에서 접근합니다.
@@ -190,11 +251,11 @@ 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가 경고합니다.
 
@@ -216,9 +277,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 +294,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 +308,7 @@ memesh  # 대시보드 열기 → Settings 탭
 | 도구 | 역할 |
 |---|---|
 | `remember` | 관찰, 관계, 태그를 포함한 지식 저장 |
-| `recall` | 다중 요소 점수 매김과 LLM 쿼리 확장이 있는 스마트 검색 |
+| `recall` | 다중 요소 점수 매김(관련성, 최근성, 빈도, 신뢰도, 시계열 유효성)이 있는 FTS5 + sqlite-vec 검색 — 핫 패스에 LLM 없음 |
 | `forget` | 소프트 보관(절대 삭제 안 함) 또는 특정 관찰 제거 |
 | `consolidate` | LLM 기반 장황한 메모리 압축 |
 | `export` | 프로젝트나 팀 멤버 간 메모리 JSON 공유 |

package/README.md

@@ -279,7 +279,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 +294,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 +308,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,6 +186,26 @@ 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.
@@ -219,7 +252,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 +267,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 +281,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 |

package/README.th.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 @@
 
 ---
 
+## หลักฐาน — 95.40% R@5 บน LongMemEval-S
+
+เครื่องมือเรียกคืนของ MeMesh ใช้ **FTS5 เพียงอย่างเดียว** (ไม่มี LLM ไม่มี embedding บนเส้นทางหลัก) วัดผลด้วยเบนช์มาร์กสาธารณะ [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: ติดตั้ง
@@ -173,6 +186,26 @@ memesh export-schema \
 
 ---
 
+## การตั้งค่า
+
+การตั้งค่าทั้งหมดทำผ่านตัวแปรสภาพแวดล้อม ค่าเริ่มต้นทำงานภายในเครื่องล้วน ๆ และไม่มีเครือข่าย — ไม่ต้องตั้งค่าอะไรเพื่อให้ระบบใช้งานได้
+
+| ตัวแปร | ค่าเริ่มต้น | ทำอะไร |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | เปลี่ยนตำแหน่งฐานข้อมูล SQLite |
+| `MEMESH_AUTO_CAPTURE` | `true` | ปิดการใช้ hook จับข้อมูลอัตโนมัติทั้งหมด (`Stop`, `PreCompact`) |
+| `MEMESH_AUTO_DETECT_LLM` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อให้ memesh ตรวจหาผู้ให้บริการจาก shell env (`OPENAI_API_KEY` ฯลฯ) โดยอัตโนมัติและสลับไปใช้ BYOK embeddings **ค่าเริ่มต้นของการติดตั้งใหม่คือ ONNX ภายในเครื่อง (384 มิติ) เท่านั้น** — opt-in ถ้าต้องการ embedding บนคลาวด์ ถ้าไม่ตั้งค่าธงนี้ `OPENAI_API_KEY` ที่อยู่ใน shell จะถูกเพิกเฉย |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อเปิดใช้โปรโตคอล working-model เชิงทดลอง (กรอบ CTO / Orchestrator / Agents) เพิ่มแบนเนอร์ตอนเริ่มเซสชัน การเตือนคำสั่ง Bash และเทเลเมตรี `verify_agent_work` ประสิทธิผลของโปรโตคอลกำลังถูกเก็บข้อมูล ยังไม่ได้พิสูจน์ — opt-in ถ้าต้องการเข้าร่วม **ค่าเริ่มต้นปิด**: ฟีเจอร์หน่วยความจำหลักทำงานได้โดยไม่ต้องเปิดธงนี้ |
+| `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` แบบ detached จะทำงานเมื่อจบเซสชัน (Stop hook) เพื่อไม่บล็อกงานของคุณ — ผลลัพธ์ลงใน `~/.memesh/auto-update.log` ตั้งใน `~/.memesh/config.json` ผ่านคีย์ `autoUpdate` ก็ได้ (env ชนะ) เมื่อเวอร์ชันที่ติดตั้งถูก deprecate (security advisory) `patch` จะถูกบังคับเปิดแม้ตั้งเป็น `off` — minor / major ยังต้องทำมือเพื่อหลีกเลี่ยงการเปลี่ยนพฤติกรรมเงียบ ๆ |
+| `OPENAI_API_KEY` | ไม่ตั้ง | คีย์ OpenAI ของคุณ ใช้เฉพาะเมื่อ `MEMESH_AUTO_DETECT_LLM=1` หรือคุณตั้งค่าผู้ให้บริการอย่างชัดเจน |
+| `OLLAMA_HOST` | `http://localhost:11434` | เปลี่ยนปลายทาง Ollama เมื่อใช้ผู้ให้บริการ Ollama ภายในเครื่อง |
+
+`memesh doctor` พิมพ์การตั้งค่าที่ resolve แล้วเพื่อให้คุณเห็นว่าอะไรทำงานอยู่
+
+เมื่อ npm ระบุว่าเวอร์ชันที่ติดตั้งถูก deprecate (โดยทั่วไปคือ security advisory) เซสชันถัดไปจะแสดงแบนเนอร์ `⚠️ MeMesh <ver> is DEPRECATED` แบบหนักนำหน้า และ `memesh update-status` จะแสดงบรรทัดเดียวกันจนกว่าคุณจะอัปเกรด การตรวจสอบถูก cache ที่ `~/.memesh/update-check.<version>.json` เพื่อไม่ให้ความล้มเหลวเครือข่ายชั่วคราวลดความสว่างของคำเตือน
+
+---
+
 ## แดชบอร์ด
 
 7 แท็บ 11 ภาษา ไม่มีการพึ่งพิ่นภายนอก เข้าถึงได้ที่ `http://localhost:3737/dashboard` เมื่อเซิร์ฟเวอร์ทำงาน
@@ -234,10 +267,12 @@ memesh  # opens dashboard → Settings tab
 
 | | ระดับ 0 (ค่าเริ่มต้น) | ระดับ 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5 keyword matching | + LLM query expansion (~97% recall) |
+| **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms ต่อ query) | คงเดิม — recall ไม่ใช้ LLM ในทุก level |
 | **Auto-capture** | รูปแบบตามกฎ | + LLM สกัดการตัดสินใจ & บทเรียน |
-| **Compression** | ไม่พร้อมใช้ | `consolidate` บีบอัดหน่วยความจำที่มีเนื้อหามาก |
-| **Cost** | ฟรี ไม่ต้องคีย์ API | ~$0.0001 ต่อการค้นหา (Haiku) |
+| **Auto-tagging** | แท็กด้วยตนเองเท่านั้น | + LLM สร้างแท็กให้ entity ใหม่ |
+| **วิเคราะห์ความล้มเหลว** | ไม่พร้อมใช้ | + LLM แปลง session errors เป็น structured lessons |
+| **Compression** | ไม่พร้อมใช้ | `consolidate` + `dream` บีบอัดหน่วยความจำ |
+| **Cost** | ฟรี ไม่ต้องคีย์ API | ~$0.0001 ต่อ analysis call (Haiku) |
 
 ---
 

package/README.vi.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 @@ Package này là tầng bộ nhớ cục bộ của dòng sản phẩm MeMesh. N
 
 ---
 
+## Proof — 95.40% R@5 trên LongMemEval-S
+
+Engine truy hồi của MeMesh là **chỉ FTS5** (không LLM, không embeddings trên hot path), được đo trên benchmark công khai [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 câu hỏi, giấy phép MIT):
+
+| Hệ thống | R@5 | Nguồn |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Vendor self-report |
+| Supermemory | ~82% | Vendor estimate |
+| Zep | 63.8% | LongMemEval paper |
+| Mem0 | 49.0% | LongMemEval paper |
+
+Lệnh tái hiện, SHA256 của dataset, kết quả thô theo từng câu hỏi, và phân tích các lỗi đã biết đều có trong [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Có thể chạy lại trong ~10 giây.
+
+---
+
 ## Bắt đầu trong 60 giây
 
 ### Bước 1: Cài đặt
@@ -173,6 +186,26 @@ Bạn không cần phải manually nhớ mọi thứ. MeMesh có **7 hooks** đ
 
 ---
 
+## Cấu hình
+
+Toàn bộ cấu hình thông qua biến môi trường. Các giá trị mặc định là local-only và zero-network — bạn không cần thiết lập gì để có một hệ thống hoạt động.
+
+| Biến | Mặc định | Tác dụng |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Ghi đè vị trí của database SQLite. |
+| `MEMESH_AUTO_CAPTURE` | `true` | Tắt hoàn toàn các hooks auto-capture (`Stop`, `PreCompact`). |
+| `MEMESH_AUTO_DETECT_LLM` | chưa đặt | Đặt thành `1` để memesh tự động phát hiện provider từ shell env (`OPENAI_API_KEY` v.v.) và chuyển sang BYOK embeddings. **Cài đặt mới mặc định chỉ dùng ONNX cục bộ (384-dim)** — opt in nếu bạn muốn cloud embeddings. Khi flag này không được đặt, một `OPENAI_API_KEY` còn sót trong shell sẽ bị bỏ qua. |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | chưa đặt | Đặt thành `1` để bật một giao thức working-model thử nghiệm (CTO / Orchestrator / Agents framing). Thêm session-start banner, một Bash command nudge, và telemetry `verify_agent_work`. Hiệu quả của giao thức đang được instrument, chưa được chứng minh — opt in nếu bạn muốn tham gia. **Mặc định là OFF**: các tính năng bộ nhớ cốt lõi vẫn hoạt động mà không cần flag này. |
+| `MEMESH_AUTO_UPDATE` | `off` | Chính sách auto-update. `off` (mặc định) không bao giờ tự cập nhật; `patch` cho phép `X.Y.Z → X.Y.Z+N`; `minor` thêm `X.Y.Z → X.Y+1.0`; `major` cho phép mọi bump. Khi được phép, một `npm install -g` detached chạy ở cuối session (Stop hook) để không bao giờ chặn công việc của bạn — kết quả lưu vào `~/.memesh/auto-update.log`. Cũng có thể đặt là `autoUpdate` trong `~/.memesh/config.json` (env thắng). Khi phiên bản đã cài bị maintainers đánh dấu deprecated (security advisory), `patch` sẽ được force-allowed ngay cả khi `off` — minor / major bumps vẫn manual để tránh behaviour drift im lặng. |
+| `OPENAI_API_KEY` | chưa đặt | Khóa OpenAI của bạn. Chỉ được dùng khi `MEMESH_AUTO_DETECT_LLM=1` hoặc bạn cấu hình provider tường minh. |
+| `OLLAMA_HOST` | `http://localhost:11434` | Ghi đè endpoint Ollama khi dùng local Ollama provider. |
+
+`memesh doctor` in ra cấu hình đã resolve để bạn thấy cái gì đang active.
+
+Khi npm gắn cờ phiên bản đã cài là deprecated (thường là security advisory), session-start kế tiếp sẽ thêm banner mạnh `⚠️ MeMesh <ver> is DEPRECATED` ở đầu và `memesh update-status` hiển thị cùng dòng đó cho đến khi bạn nâng cấp. Kết quả check được cache tại `~/.memesh/update-check.<version>.json` để một lỗi mạng tạm thời không làm mờ cảnh báo.
+
+---
+
 ## Dashboard
 
 7 tabs, 11 ngôn ngữ, không phụ thuộc bên ngoài. Truy cập tại `http://localhost:3737/dashboard` khi server đang chạy.
@@ -219,7 +252,7 @@ Các imported bundles vẫn có thể tìm kiếm được, nhưng MeMesh không
 
 ## Mở khóa Smart Mode (Tuỳ chọn)
 
-MeMesh hoạt động offline theo mặc định. Thêm LLM API key chỉ nếu bạn muốn query expansion, smarter extraction, và compression:
+MeMesh hoạt động offline theo mặc định — recall luôn LLM-free (95.40% R@5 trên LongMemEval-S, không cần LLM). Thêm LLM API key chỉ nếu bạn muốn các luồng phân tích LLM-augmented bổ sung: trích xuất session thông minh hơn, auto-tagging cho memories mới, phân tích lỗi thành lessons có cấu trúc, và compression `consolidate` / `dream`:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -234,10 +267,12 @@ memesh  # mở 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) | giữ nguyên — recall luôn LLM-free ở mọi level |
 | **Auto-capture** | Rule-based patterns | + LLM extracts decisions & lessons |
-| **Compression** | Không có sẵn | `consolidate` compresses verbose memories |
-| **Chi phí** | Free, no API key | ~$0.0001 per search (Haiku) |
+| **Auto-tagging** | Chỉ thẻ thủ công | + LLM tự động gắn nhãn entity mới |
+| **Phân tích lỗi** | Không có sẵn | + LLM chuyển session errors thành structured lessons |
+| **Compression** | Không có sẵn | `consolidate` + `dream` nén verbose memories |
+| **Chi phí** | Free, no API key | ~$0.0001 mỗi analysis call (Haiku) |
 
 ---
 
@@ -246,7 +281,7 @@ memesh  # mở dashboard → Settings tab
 | Tool | Nó làm gì |
 |------|-------------|
 | `remember` | Lưu trữ kiến thức với observations, relations, và tags |
-| `recall` | Smart search với multi-factor scoring và LLM query expansion |
+| `recall` | Tìm kiếm FTS5 + sqlite-vec với multi-factor scoring (relevance, recency, frequency, confidence, temporal validity) — không có LLM trong hot path |
 | `forget` | Soft-archive (không bao giờ xóa) hoặc xóa observations cụ thể |
 | `consolidate` | LLM-powered compression của verbose memories |
 | `export` | Chia sẻ memories dưới dạng JSON giữa các dự án hoặc thành viên team |