@pcircle/memesh 4.0.2 → 4.1.0

package/README.ko.md

@@ -1,10 +1,13 @@
+<!-- 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">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>가장 가벼운 범용 AI 메모리 레이어.</strong><br />
-    SQLite 파일 하나. 어떤 LLM이든. 클라우드 없이.
+    <strong>Claude Code와 MCP 코딩 에이전트를 위한 로컬 메모리.</strong><br />
+    SQLite 파일 하나. Docker 없음. 클라우드 필수 아님.
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
@@ -16,15 +19,17 @@
 
 ---
 
-## 문제의 본질
+## 문제점
+
+코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. 아키텍처 결정, 버그 수정, 실패한 테스트, 힘들게 얻은 교훈 — 매번 다시 설명해야 합니다. Claude Code는 매번 새로 시작하고, 이미 알아야 할 제약 조건을 다시 발견하며, 불필요하게 컨텍스트를 소비합니다.
 
-AI는 세션이 끝날 때마다 모든 것을 잊어버립니다. 모든 결정, 모든 버그 수정, 모든 교훈——사라집니다. 같은 맥락을 반복해서 설명하고, Claude는 같은 패턴을 다시 발견하며, 팀의 AI 지식은 매번 제로로 초기화됩니다.
+**MeMesh는 코딩 에이전트에게 영구적이고 검색 가능하며 진화하는 로컬 메모리를 제공합니다.**
 
-**MeMesh는 모든 AI에게 지속적이고, 검색 가능하며, 진화하는 메모리를 제공합니다.**
+이 패키지는 MeMesh 제품군의 로컬 메모리 레이어입니다. 의도적으로 작고 오픈소스입니다: npm으로 설치하고, 메모리는 `~/.memesh/knowledge-graph.db`에 보관하며, Claude Code 또는 MCP 호환 클라이언트와 연결합니다. 호스팅 워크스페이스와 엔터프라이즈 OS 제품은 이 패키지의 README와 로드맵과 별개로 유지됩니다.
 
 ---
 
-## 60초 만에 시작하기
+## 60초 안에 시작하기
 
 ### 1단계: 설치
 
@@ -32,33 +37,39 @@ AI는 세션이 끝날 때마다 모든 것을 잊어버립니다. 모든 결정
 npm install -g @pcircle/memesh
 ```
 
-### 2단계: AI가 기억하기
+### 2단계: 의사결정 저장
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 3단계: AI가 떠올리기
+### 3단계: 나중에 회상
 
 ```bash
 memesh recall "login security"
-# → 다른 단어로 검색해도 "OAuth 2.0 with PKCE"를 찾아냅니다
+# → 다른 단어를 검색했어도 "OAuth 2.0 with PKCE"를 찾습니다
 ```
 
-**끝입니다.** MeMesh가 세션을 넘나들며 기억하고 떠올리기 시작했습니다.
+**이게 전부입니다.** MeMesh가 이제 세션 간에 기억하고 회상합니다.
 
-대시보드를 열어 메모리를 탐색해보세요:
+설치와 로컬 연결을 확인하려면:
+
+```bash
+memesh doctor
+```
+
+대시보드를 열어서 메모리를 탐색합니다:
 
 ```bash
 memesh
 ```
 
 <p align="center">
-  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — 어떤 메모리도 즉시 검색" width="100%" />
+  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — 모든 메모리를 즉시 찾습니다" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — AI의 지식을 한눈에 파악" width="100%" />
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — 건강 점수, 타임라인, 패턴, 지식 커버리지" width="100%" />
 </p>
 
 <p align="center">
@@ -67,18 +78,18 @@ memesh
 
 ---
 
-## 누구를 위한 도구인가?
+## 누가 사용할까요?
 
-| 당신이…라면 | MeMesh가 이렇게 도와줍니다 |
-|---------------|---------------------|
-| **Claude Code를 사용하는 개발자** | 결정, 패턴, 교훈을 세션을 넘나들며 자동으로 기억 |
-| **LLM으로 제품을 만드는 팀** | 내보내기/가져오기로 팀 지식을 공유하고 모두의 AI 맥락을 정렬 |
-| **AI 에이전트 개발자** | MCP, HTTP API, Python SDK를 통해 에이전트에 지속 메모리 부여 |
-| **여러 AI 도구를 쓰는 파워 유저** | Claude, GPT, LLaMA, Ollama 또는 모든 MCP 클라이언트와 작동하는 단일 메모리 레이어 |
+| 이런 개발자라면 | MeMesh가 도와줍니다 |
+|---|---|
+| **Claude Code를 사용 중** | 프로젝트 결정, 파일별 교훈, 과거 실패를 작업 중에 자동으로 회상 |
+| **코딩 에이전트 파워 유저** | MCP 호환 도구 전체에서 하나의 로컬 메모리 레이어 공유 |
+| **팀이 AI 코딩 워크플로우 실험 중** | 호스팅 인프라 도입 없이 프로젝트 지식 내보내기/가져오기 |
+| **에이전트 개발자** | MCP, HTTP, CLI, Python SDK를 통해 로컬 메모리 추가 |
 
 ---
 
-## 모든 것과 연동
+## 코딩 에이전트를 우선으로 설계
 
 <table>
 <tr>
@@ -88,18 +99,18 @@ memesh
 ```bash
 memesh-mcp
 ```
-MCP 프로토콜 (자동 설정)
+MCP 도구 + Claude Code 훅
 
 </td>
 <td width="33%" align="center">
 
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
+**모든 HTTP 클라이언트**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
 ```
-`pip install memesh`
+`memesh serve` (REST API)
 
 </td>
 <td width="33%" align="center">
@@ -109,7 +120,7 @@ m.recall("auth")
 memesh export-schema \
   --format openai
 ```
-어떤 API 호출에도 붙여넣기
+모든 API 호출에 도구 붙여넣기
 
 </td>
 </tr>
@@ -117,103 +128,120 @@ memesh export-schema \
 
 ---
 
-## 왜 Mem0 / Zep가 아닌가?
+## OpenMemory, Cursor Memories, Mem0, Zep와는 왜 다를까요?
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **설치 시간** | 5초 | 30~60분 | 30분 이상 |
-| **설정 방법** | `npm i -g` — 완료 | Neo4j + VectorDB + API 키 | Neo4j + 설정 |
-| **저장소** | SQLite 파일 하나 | Neo4j + Qdrant | Neo4j |
-| **오프라인 사용** | 항상 가능 | 불가 | 불가 |
-| **대시보드** | 내장 (7개 탭 + 분석) | 없음 | 없음 |
-| **의존성** | 6개 | 20개 이상 | 10개 이상 |
-| **가격** | 영구 무료 | 무료 티어 / 유료 | 무료 티어 / 유료 |
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **최적화 대상** | 코딩 에이전트 로컬 메모리 | 로컬/크로스 클라이언트 MCP 메모리 | Cursor 네이티브 프로젝트 메모리 | 관리형 앱/에이전트 메모리 | 시계열 지식 그래프 |
+| **설치 방식** | `npm install -g @pcircle/memesh` | 로컬 앱/서버 흐름 | Cursor 내장 | 클라우드 API / SDK / MCP | 서비스/프레임워크 구성 |
+| **저장소** | 로컬 SQLite 파일 하나 | 로컬 메모리 스택 | Cursor 관리 규칙/메모리 | 호스팅 또는 셀프 호스팅 스택 | 그래프 데이터베이스 |
+| **클라우드 필수** | 아니오 | 로컬 모드는 아니오 | Cursor 계정/설정에 따라 | 플랫폼을 위해서 필수 | 보통 필수/셀프 호스팅 |
+| **Claude Code 훅** | 1순위 | MCP 도구 | 없음 | MCP 도구 | Claude Code 특화 아님 |
+| **대시보드** | 내장 | 내장 | Cursor 설정 | 플랫폼 대시보드 | 플랫폼/그래프 도구 |
+| **트레이드오프** | 간단한 로컬 솔루션, 엔터프라이즈 규모 아님 | 더 넓은 로컬 앱 풋프린트 | Cursor에 종속 | 강력한 관리형 플랫폼, 로컬 우선 아님 | 강력한 그래프 모델, 복잡한 구성 |
 
-**MeMesh의 트레이드오프:** 엔터프라이즈급 멀티테넌트 기능을 포기하는 대신 **즉시 설치, 제로 인프라, 100% 프라이버시**를 얻습니다.
+**MeMesh는 엔터프라이즈급 관리 인프라를 포기하고 즉각적인 로컬 구성, 검사 가능한 저장소, 코딩 에이전트 워크플로우 훅을 얻습니다.**
 
 ---
 
-## 자동으로 일어나는 일들
+## Claude Code에서 자동으로 일어나는 일
 
-모든 것을 직접 기억할 필요가 없습니다. MeMesh에는 **4개의 훅**이 있어 아무것도 하지 않아도 지식을 자동으로 포착합니다:
+모든 것을 수동으로 기억할 필요는 없습니다. MeMesh는 작업 중에 지식을 캡처하고 주입하는 **6가지 훅**이 있습니다:
 
-| 언제 | MeMesh가 하는 일 |
-|------|------------------|
-| **모든 세션 시작 시** | 가장 관련성 높은 메모리를 로드 + 과거 교훈으로부터의 사전 경고 |
-| **모든 `git commit` 후** | 변경 내용과 diff 통계를 기록 |
-| **Claude 종료 시** | 편집한 파일, 수정한 오류를 포착하고 실패로부터 구조화된 교훈을 자동 생성 |
-| **컨텍스트 압축 전** | 컨텍스트 한계로 사라지기 전에 지식을 저장 |
+| 시점 | MeMesh가 수행하는 작업 |
+|------|---|
+| **매 세션 시작** | 가장 관련 있는 메모리 + 과거 교훈의 사전 경고 + 에이전트 오케스트레이션 배너 로드 |
+| **파일 편집 전** | Claude가 코드를 작성하기 전에 파일 또는 프로젝트와 연결된 메모리 회상 |
+| **Bash 명령 전** | Claude가 높은 검증 가능성의 명령어(테스트, 빌드, 린트, 마이그레이션, 배포, 벤치마크)를 백그라운드 에이전트로 실행하도록 유도 |
+| **모든 `git commit` 후** | 변경 사항을 diff 통계와 함께 기록 |
+| **Claude가 멈출 때** | 편집된 파일, 수정된 에러, 실패로부터 자동 생성된 구조화된 교훈 캡처 |
+| **컨텍스트 압축 전** | 컨텍스트 제한으로 손실되기 전에 지식 저장 |
 
-> **언제든 비활성화:** `export MEMESH_AUTO_CAPTURE=false`
+> **언제든 해제 가능:** `export MEMESH_AUTO_CAPTURE=false`
 
 ---
 
 ## 대시보드
 
-7개 탭, 11개 언어, 외부 의존성 제로. 서버 실행 중 `http://localhost:3737/dashboard`에서 접근.
+7개 탭, 11개 언어, 외부 의존성 없음. 서버 실행 중 `http://localhost:3737/dashboard`에서 접근합니다.
 
 | 탭 | 내용 |
-|----|------|
-| **Search** | 모든 메모리에 대한 전문 검색 + 벡터 유사도 검색 |
-| **Browse** | 모든 엔티티의 페이지네이션 목록 (아카이브/복원 지원) |
-| **Analytics** | 메모리 건강 점수 (0-100), 30일 타임라인, 가치 지표, 지식 커버리지, 정리 제안, 작업 패턴 |
-| **Graph** | 타입 필터, 검색, 에고 모드, 최신성 히트맵이 있는 인터랙티브 포스 그래프 |
-| **Lessons** | 과거 실패로부터 생성된 구조화된 교훈 (오류, 근본 원인, 수정, 예방) |
-| **Manage** | 엔티티 아카이브 및 복원 |
-| **Settings** | LLM 제공자 설정, 언어 선택 |
+|------|---|
+| **Search** | 모든 메모리에 걸친 전체 텍스트 + 벡터 유사성 검색 |
+| **Browse** | 보관 및 복구 옵션이 있는 모든 엔티티 페이지 리스트 |
+| **Analytics** | 메모리 건강 점수(0-100), 30일 타임라인, 가치 지표, 지식 커버리지, 정리 제안, 작업 패턴 |
+| **Graph** | 타입 필터, 검색, 에고 모드, 최근성 히트맵이 있는 인터랙티브 포스 디렉션 지식 그래프 |
+| **Lessons** | 과거 실패로부터 구조화된 교훈(에러, 근본 원인, 수정, 예방) |
+| **Manage** | 엔티티 보관 및 복구 |
+| **Settings** | LLM 프로바이더 설정, 즉시 언어 선택기 |
 
 ---
 
 ## 스마트 기능
 
-**🧠 스마트 검색** — "login security"를 검색하면 "OAuth PKCE"에 관한 메모리를 찾아냅니다. 설정한 LLM을 이용해 쿼리를 관련 용어로 확장합니다.
+**🧠 스마트 검색** — "login security"를 검색하면 "OAuth PKCE"에 관한 메모리를 찾습니다. MeMesh는 설정된 LLM으로 쿼리를 관련 용어로 확장합니다.
 
-**📊 점수 기반 순위** — 결과는 관련성(35%) + 최근 사용 시각(25%) + 사용 빈도(20%) + 신뢰도(15%) + 정보 유효성(5%)으로 순위를 매깁니다.
+**📊 점수 순위 매김** — 결과는 관련성(30%) + 최근성(25%) + 빈도(15%) + 신뢰도(15%) + 회상 영향(10%) + 시계열 유효성(5%)으로 순위 매겨집니다.
 
-**🔄 지식 진화** — 결정은 바뀝니다. `forget`은 오래된 메모리를 아카이브합니다(절대 삭제하지 않습니다). `supersedes` 관계가 이전 것과 새 것을 연결합니다. AI는 항상 최신 버전을 참조합니다.
+**🔄 지식 진화** — 결정은 변합니다. `forget`으로 오래된 메모리 보관(절대 삭제 안 함). `supersedes` 관계가 구 → 신 을 연결합니다. AI는 항상 최신 버전을 봅니다.
 
-**⚠️ 충돌 감지** — 두 메모리가 서로 모순될 경우 MeMesh가 경고를 보냅니다.
+**⚠️ 충돌 감지** — 서로 모순되는 메모리 두 개가 있으면 MeMesh가 경고합니다.
 
 **📦 팀 공유** — `memesh export > team-knowledge.json` → 팀과 공유 → `memesh import team-knowledge.json`
+임포트된 번들은 계속 검색 가능하지만, MeMesh는 검토하거나 로컬에 다시 저장할 때까지 Claude 훅에 임포트된 메모리를 자동 주입하지 않습니다.
+
+---
+
+## 사용 예시
+
+> "MeMesh가 3주 전에 암시적 흐름보다 PKCE를 선택했다는 것을 기억했습니다. 다시 인증에 대해 Claude에게 물었을 때, 이미 알고 있었습니다 — 설명할 필요 없었습니다."
+> — **SaaS를 만드는 개별 개발자**
+
+> "매주 금요일 팀 메모리를 내보내고 월요일에 임포트합니다. 모든 Claude가 주간 시작 시 팀이 지난주에 배운 것을 알고 시작합니다."
+> — **3명 스타트업, 공유 지식베이스**
+
+> "대시보드를 보니 메모리의 90%가 자동 생성된 세션 로그였습니다. `remember`를 의식적으로 사용해서 아키텍처 결정을 저장하기 시작했습니다. 정말 바뀌었습니다."
+> — **Analytics 탭을 발견한 개발자**
 
 ---
 
-## 스마트 모드 활성화 (선택 사항)
+## 스마트 모드 언잠금 (선택)
 
-MeMesh는 기본적으로 완전히 오프라인으로 동작합니다. LLM API 키를 추가하면 더 스마트한 검색을 사용할 수 있습니다:
+MeMesh는 기본적으로 오프라인에서 작동합니다. 쿼리 확장, 더 스마트한 추출, 압축을 원할 때만 LLM API 키를 추가합니다:
 
 ```bash
 memesh config set llm.provider anthropic
 memesh config set llm.api-key sk-ant-...
 ```
 
-또는 대시보드 설정 탭에서 시각적으로 설정:
+또는 대시보드 Settings 탭 사용 (비주얼 설정):
 
 ```bash
-memesh  # 대시보드 열기 → 설정 탭
+memesh  # 대시보드 열기 → Settings 탭
 ```
 
-| | 레벨 0 (기본값) | 레벨 1 (스마트 모드) |
+| | Level 0 (기본) | Level 1 (스마트 모드) |
 |---|---|---|
-| **검색** | FTS5 키워드 매칭 | + LLM 쿼리 확장 (~97% 재현율) |
-| **자동 포착** | 규칙 기반 패턴 | + LLM이 결정 & 교훈 추출 |
+| **검색** | FTS5 키워드 매칭 | + LLM 쿼리 확장 (~97% 회상율) |
+| **자동 캡처** | 규칙 기반 패턴 | + LLM이 결정과 교훈 추출 |
 | **압축** | 사용 불가 | `consolidate`로 장황한 메모리 압축 |
-| **비용** | 무료, API 키 불필요 | 검색당 ~$0.0001 (Haiku) |
+| **비용** | 무료, API 키 불필요 | ~$0.0001 검색당 (Haiku) |
 
 ---
 
-## 전체 8가지 메모리 도구
+## 9가지 메모리 도구 전체
 
-| 도구 | 기능 |
-|------|-------------|
-| `remember` | 관찰 기록, 관계, 태그와 함께 지식 저장 |
-| `recall` | 다중 요소 스코어링과 LLM 쿼리 확장을 활용한 스마트 검색 |
-| `forget` | 소프트 아카이브(절대 삭제 없음) 또는 특정 관찰 기록 제거 |
+| 도구 | 역할 |
+|---|---|
+| `remember` | 관찰, 관계, 태그를 포함한 지식 저장 |
+| `recall` | 다중 요소 점수 매김과 LLM 쿼리 확장이 있는 스마트 검색 |
+| `forget` | 소프트 보관(절대 삭제 안 함) 또는 특정 관찰 제거 |
 | `consolidate` | LLM 기반 장황한 메모리 압축 |
-| `export` | 메모리를 JSON으로 프로젝트 또는 팀원과 공유 |
-| `import` | 병합 전략(건너뛰기 / 덮어쓰기 / 추가)을 선택해 메모리 가져오기 |
-| `learn` | 실수로부터 구조화된 교훈 기록 (오류, 근본 원인, 수정, 예방) |
+| `export` | 프로젝트나 팀 멤버 간 메모리 JSON 공유 |
+| `import` | 병합 전략(스킵/덮어쓰기/추가)이 있는 메모리 임포트 |
+| `learn` | 실수로부터 구조화된 교훈 기록(에러, 근본 원인, 수정, 예방) |
 | `user_patterns` | 작업 패턴 분석 — 일정, 도구, 강점, 학습 영역 |
+| `verify_agent_work` | 백그라운드 에이전트 작업에 대한 검증 보고서 유지; 청구된 파일 변경사항을 `git diff`와 현실 확인 |
 
 ---
 
@@ -234,7 +262,7 @@ memesh  # 대시보드 열기 → 설정 탭
                     (~/.memesh/knowledge-graph.db)
 ```
 
-코어는 프레임워크 독립적. 터미널, HTTP, MCP 어디서 호출해도 동일한 로직이 실행됩니다.
+코어는 프레임워크에 구애받지 않습니다. 같은 로직이 터미널, HTTP, MCP에서 실행됩니다.
 
 ---
 
@@ -243,7 +271,8 @@ memesh  # 대시보드 열기 → 설정 탭
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
 cd memesh-llm-memory && npm install && npm run build
-npm test -- --run    # 413 tests
+npm test             # 489 tests
+npm run test:e2e-dashboard
 ```
 
 대시보드: `cd dashboard && npm install && npm run dev`
@@ -251,5 +280,5 @@ npm test -- --run    # 413 tests
 ---
 
 <p align="center">
-  <strong>MIT</strong> — <a href="https://pcircle.ai">PCIRCLE AI</a> 제작
+  <strong>MIT</strong> — Made by <a href="https://pcircle.ai">PCIRCLE AI</a>
 </p>

package/README.md

@@ -26,6 +26,22 @@ This package is the local memory layer of the MeMesh product family. It is inten
 
 ---
 
+## Proof — 95.40% R@5 on LongMemEval-S
+
+MeMesh's retrieval engine is **FTS5 alone** (no LLM, no embeddings on the hot path), measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+
+| System | R@5 | Source |
+|---|---|---|
+| **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 |
+
+Reproduction commands, dataset SHA256, raw per-question results, and known-failure analysis are all in [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Re-runnable in ~10 seconds.
+
+---
+
 ## Get Started in 60 Seconds
 
 ### Step 1: Install
@@ -34,12 +50,22 @@ This package is the local memory layer of the MeMesh product family. It is inten
 npm install -g @pcircle/memesh
 ```
 
+> **First-install notes (one-time):**
+> - **Native modules** — `better-sqlite3` and `sqlite-vec` install via prebuilt binaries on macOS (arm64/x64), Linux (x64/arm64), and Windows x64. On uncommon platforms or when prebuilds fail, you'll need a working C/C++ toolchain.
+> - **Embedding model** — the first call that triggers a local embedding (e.g. `recall` with semantic mode) downloads `Xenova/all-MiniLM-L6-v2` (~80 MB) into `~/.memesh/models/`. Subsequent calls are instant. The default retrieval path (FTS5) does not require this download.
+
 ### Step 2: Store a decision
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
+Or quick-capture in one line:
+
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
 ### Step 3: Recall it later
 
 ```bash
@@ -49,6 +75,12 @@ memesh recall "login security"
 
 **That's it.** MeMesh is now remembering and recalling across sessions.
 
+If you want to verify the install and local wiring end to end:
+
+```bash
+memesh doctor
+```
+
 Open the dashboard to explore your memory:
 
 ```bash
@@ -137,12 +169,13 @@ Paste tools into any API call
 
 ## What Happens Automatically In Claude Code
 
-You don't need to manually remember everything. MeMesh has **5 hooks** that capture and inject knowledge while you work:
+You don't need to manually remember everything. MeMesh has **6 hooks** that capture and inject knowledge while you work:
 
 | When | What MeMesh does |
 |------|------------------|
 | **Every session start** | Loads your most relevant memories + proactive warnings from past lessons |
 | **Before editing files** | Recalls memories tied to the file or project before Claude writes code |
+| **Before bash commands** | (Opt-in) Nudges Claude to dispatch high-verifiability commands (test, build, lint, migrate, deploy, benchmark) as background agents |
 | **After every `git commit`** | Records what you changed, with diff stats |
 | **When Claude stops** | Captures files edited, errors fixed, and auto-generates structured lessons from failures |
 | **Before context compaction** | Saves knowledge before it's lost to context limits |
@@ -151,6 +184,23 @@ You don't need to manually remember everything. MeMesh has **5 hooks** that capt
 
 ---
 
+## Configuration
+
+All configuration is via environment variables. Defaults are local-only and zero-network — you don't need to set anything to get a working system.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Override the SQLite database location. |
+| `MEMESH_AUTO_CAPTURE` | `true` | Disable the auto-capture hooks (`Stop`, `PreCompact`) entirely. |
+| `MEMESH_AUTO_DETECT_LLM` | unset | Set to `1` to let memesh auto-detect a provider from your shell env (`OPENAI_API_KEY` etc.) and switch to BYOK embeddings. **Default fresh-install is local ONNX (384-dim) only** — opt in if you want cloud embeddings. Without this flag set, an `OPENAI_API_KEY` lying around in your shell is ignored. |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | Set to `1` to enable an experimental working-model protocol (CTO / Orchestrator / Agents framing). Adds a session-start banner, a Bash command nudge, and `verify_agent_work` telemetry. The protocol's effectiveness is being instrumented, not yet proven — opt in if you want to participate. **Default is OFF**: the core memory features work without this flag. |
+| `OPENAI_API_KEY` | unset | Your OpenAI key. Only used when `MEMESH_AUTO_DETECT_LLM=1` or you explicitly configure the provider. |
+| `OLLAMA_HOST` | `http://localhost:11434` | Override the Ollama endpoint when using a local Ollama provider. |
+
+`memesh doctor` prints the resolved configuration so you can see what's active.
+
+---
+
 ## Dashboard
 
 7 tabs, 11 languages, zero external dependencies. Access at `http://localhost:3737/dashboard` when the server is running.
@@ -219,7 +269,7 @@ memesh  # opens dashboard → Settings tab
 
 ---
 
-## All 8 Memory Tools
+## All 9 Memory Tools
 
 | Tool | What it does |
 |------|-------------|
@@ -231,6 +281,7 @@ memesh  # opens dashboard → Settings tab
 | `import` | Import memories with merge strategies (skip / overwrite / append) |
 | `learn` | Record structured lessons from mistakes (error, root cause, fix, prevention) |
 | `user_patterns` | Analyze your work patterns — schedule, tools, strengths, learning areas |
+| `verify_agent_work` | Persist a verification report for background-agent work; reality-checks claimed file changes against `git diff` |
 
 ---
 
@@ -260,7 +311,7 @@ Core is framework-agnostic. Same logic runs from terminal, HTTP, or MCP.
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
 cd memesh-llm-memory && npm install && npm run build
-npm test             # 463 tests
+npm test             # 489 tests
 npm run test:e2e-dashboard
 ```