@pcircle/memesh 4.0.1 → 4.0.3

package/README.ko.md

@@ -3,253 +3,108 @@
 <p align="center">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>가장 가벼운 범용 AI 메모리 레이어.</strong><br />
-    SQLite 파일 하나. 어떤 LLM이든. 클라우드 없이.
-  </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>
-    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
-    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square" alt="Node" /></a>
-    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
+    <strong>Claude Code와 MCP coding agents를 위한 로컬 메모리 레이어.</strong><br />
+    SQLite 파일 하나. Docker 불필요. 클라우드 불필요.
   </p>
 </p>
 
----
+> 이 한국어 README는 핵심만 정리한 안내 버전입니다. 최신의 완전한 내용은 [English README](README.md)를 기준으로 보세요.
 
-## 문제의 본질
+## 어떤 문제를 해결하나?
 
-AI는 세션이 끝날 때마다 모든 것을 잊어버립니다. 모든 결정, 모든 버그 수정, 모든 교훈——사라집니다. 같은 맥락을 반복해서 설명하고, Claude는 같은 패턴을 다시 발견하며, 팀의 AI 지식은 매번 제로로 초기화됩니다.
+coding agent는 세션이 바뀌면 맥락을 잃기 쉽습니다. 아키텍처 결정, 버그를 고친 과정, 이미 배운 교훈, 프로젝트 제약을 계속 다시 설명해야 합니다.
 
-**MeMesh는 모든 AI에게 지속적이고, 검색 가능하며, 진화하는 메모리를 제공합니다.**
+**MeMesh는 이런 지식을 로컬에 남기고, 검색 가능하게 유지하며, 나중에 다시 불러올 수 있게 해줍니다.**
 
----
+이 npm package는 MeMesh의 로컬 plugin / package 버전입니다. 클라우드 워크스페이스나 엔터프라이즈 플랫폼 전체를 담은 제품은 아닙니다.
 
-## 60초 만에 시작하기
+## 60초 시작
 
-### 1단계: 설치
+### 1. 설치
 
 ```bash
 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가 세션을 넘나들며 기억하고 떠올리기 시작했습니다.
-
-대시보드를 열어 메모리를 탐색해보세요:
+대시보드 열기:
 
 ```bash
 memesh
 ```
 
-<p align="center">
-  <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%" />
-</p>
-
-<p align="center">
-  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — 타입 필터와 에고 모드가 있는 인터랙티브 지식 그래프" width="100%" />
-</p>
-
----
-
-## 누구를 위한 도구인가?
-
-| 당신이…라면 | MeMesh가 이렇게 도와줍니다 |
-|---------------|---------------------|
-| **Claude Code를 사용하는 개발자** | 결정, 패턴, 교훈을 세션을 넘나들며 자동으로 기억 |
-| **LLM으로 제품을 만드는 팀** | 내보내기/가져오기로 팀 지식을 공유하고 모두의 AI 맥락을 정렬 |
-| **AI 에이전트 개발자** | MCP, HTTP API, Python SDK를 통해 에이전트에 지속 메모리 부여 |
-| **여러 AI 도구를 쓰는 파워 유저** | Claude, GPT, LLaMA, Ollama 또는 모든 MCP 클라이언트와 작동하는 단일 메모리 레이어 |
-
----
-
-## 모든 것과 연동
-
-<table>
-<tr>
-<td width="33%" align="center">
-
-**Claude Code / Desktop**
-```bash
-memesh-mcp
-```
-MCP 프로토콜 (자동 설정)
-
-</td>
-<td width="33%" align="center">
-
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
-```
-`pip install memesh`
-
-</td>
-<td width="33%" align="center">
-
-**모든 LLM (OpenAI 형식)**
-```bash
-memesh export-schema \
-  --format openai
-```
-어떤 API 호출에도 붙여넣기
-
-</td>
-</tr>
-</table>
-
----
-
-## 왜 Mem0 / Zep가 아닌가?
+## 이런 사용자에게 맞습니다
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **설치 시간** | 5초 | 30~60분 | 30분 이상 |
-| **설정 방법** | `npm i -g` — 완료 | Neo4j + VectorDB + API 키 | Neo4j + 설정 |
-| **저장소** | SQLite 파일 하나 | Neo4j + Qdrant | Neo4j |
-| **오프라인 사용** | 항상 가능 | 불가 | 불가 |
-| **대시보드** | 내장 (7개 탭 + 분석) | 없음 | 없음 |
-| **의존성** | 6개 | 20개 이상 | 10개 이상 |
-| **가격** | 영구 무료 | 무료 티어 / 유료 | 무료 티어 / 유료 |
+- Claude Code를 쓰면서 세션 사이에도 프로젝트 맥락을 유지하고 싶은 개발자
+- 같은 로컬 메모리를 여러 MCP coding agents에서 함께 쓰고 싶은 고급 사용자
+- export / import로 팀 지식을 공유하려는 소규모 AI-native 개발팀
+- CLI, HTTP, MCP 흐름에 로컬 메모리를 붙이고 싶은 agent 개발자
 
-**MeMesh의 트레이드오프:** 엔터프라이즈급 멀티테넌트 기능을 포기하는 대신 **즉시 설치, 제로 인프라, 100% 프라이버시**를 얻습니다.
+## 왜 MeMesh인가?
 
----
+- 로컬 우선: 데이터가 내 SQLite 파일에 저장됨
+- 가벼운 설치: `npm install -g` 후 바로 사용 가능
+- 연결 방식이 명확함: CLI, HTTP, MCP 지원
+- Claude Code 친화적: hooks로 작업 중 관련 메모리를 쉽게 불러옴
+- 확인과 정리가 쉬움: dashboard가 있어 블랙박스가 아님
+- import 안전 경계: import한 메모리는 검색되더라도, 검토하거나 다시 저장하기 전에는 Claude hooks에 자동 주입되지 않음
 
-## 자동으로 일어나는 일들
+## Claude Code에서 자동으로 하는 일
 
-모든 것을 직접 기억할 필요가 없습니다. MeMesh에는 **4개의 훅**이 있어 아무것도 하지 않아도 지식을 자동으로 포착합니다:
+MeMesh는 현재 다음 5가지 시점에 도움을 줍니다.
 
-| 언제 | MeMesh가 하는 일 |
-|------|------------------|
-| **모든 세션 시작 시** | 가장 관련성 높은 메모리를 로드 + 과거 교훈으로부터의 사전 경고 |
-| **모든 `git commit` 후** | 변경 내용과 diff 통계를 기록 |
-| **Claude 종료 시** | 편집한 파일, 수정한 오류를 포착하고 실패로부터 구조화된 교훈을 자동 생성 |
-| **컨텍스트 압축 전** | 컨텍스트 한계로 사라지기 전에 지식을 저장 |
+- 세션 시작 시 관련 메모리와 이미 배운 교훈을 불러옴
+- 파일 편집 전에 그 파일이나 프로젝트와 관련된 메모리를 먼저 찾음
+- `git commit` 후 변경 내용을 기록함
+- 세션 종료 시 이번 수정, 오류, lesson learned를 정리함
+- context compact 전에 중요한 내용을 로컬 메모리에 저장함
 
-> **언제든 비활성화:** `export MEMESH_AUTO_CAPTURE=false`
+## Dashboard에는 무엇이 있나?
 
----
+Dashboard는 현재 7개 탭과 11개 언어를 지원합니다.
 
-## 대시보드
+- Search: 메모리 검색
+- Browse: 전체 메모리 보기
+- Analytics: 건강도와 추세 확인
+- Graph: 지식 관계 보기
+- Lessons: 과거 교훈 보기
+- Manage: 아카이브와 복원
+- Settings: LLM provider와 언어 설정
 
-7개 탭, 11개 언어, 외부 의존성 제로. 서버 실행 중 `http://localhost:3737/dashboard`에서 접근.
+## Smart Mode란?
 
-| 탭 | 내용 |
-|----|------|
-| **Search** | 모든 메모리에 대한 전문 검색 + 벡터 유사도 검색 |
-| **Browse** | 모든 엔티티의 페이지네이션 목록 (아카이브/복원 지원) |
-| **Analytics** | 메모리 건강 점수 (0-100), 30일 타임라인, 가치 지표, 지식 커버리지, 정리 제안, 작업 패턴 |
-| **Graph** | 타입 필터, 검색, 에고 모드, 최신성 히트맵이 있는 인터랙티브 포스 그래프 |
-| **Lessons** | 과거 실패로부터 생성된 구조화된 교훈 (오류, 근본 원인, 수정, 예방) |
-| **Manage** | 엔티티 아카이브 및 복원 |
-| **Settings** | LLM 제공자 설정, 언어 선택 |
+MeMesh는 기본적으로 오프라인에서 사용할 수 있습니다. 여기에 LLM API key를 설정하면 다음과 같은 기능을 더 쓸 수 있습니다.
 
----
+- query expansion
+- 더 나은 자동 추출
+- 더 똑똑한 정리와 압축
 
-## 스마트 기능
+API key가 없어도 핵심 기능은 그대로 사용할 수 있습니다.
 
-**🧠 스마트 검색** — "login security"를 검색하면 "OAuth PKCE"에 관한 메모리를 찾아냅니다. 설정한 LLM을 이용해 쿼리를 관련 용어로 확장합니다.
+## 더 알아보기
 
-**📊 점수 기반 순위** — 결과는 관련성(35%) + 최근 사용 시각(25%) + 사용 빈도(20%) + 신뢰도(15%) + 정보 유효성(5%)으로 순위를 매깁니다.
+- 전체 기능, 비교, API, release 정보: [English README](README.md)
+- 플랫폼별 안내: [docs/platforms/README.md](docs/platforms/README.md)
+- API 참고: [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
 
-**🔄 지식 진화** — 결정은 바뀝니다. `forget`은 오래된 메모리를 아카이브합니다(절대 삭제하지 않습니다). `supersedes` 관계가 이전 것과 새 것을 연결합니다. AI는 항상 최신 버전을 참조합니다.
-
-**⚠️ 충돌 감지** — 두 메모리가 서로 모순될 경우 MeMesh가 경고를 보냅니다.
-
-**📦 팀 공유** — `memesh export > team-knowledge.json` → 팀과 공유 → `memesh import team-knowledge.json`
-
----
-
-## 스마트 모드 활성화 (선택 사항)
-
-MeMesh는 기본적으로 완전히 오프라인으로 동작합니다. LLM API 키를 추가하면 더 스마트한 검색을 사용할 수 있습니다:
-
-```bash
-memesh config set llm.provider anthropic
-memesh config set llm.api-key sk-ant-...
-```
-
-또는 대시보드 설정 탭에서 시각적으로 설정:
-
-```bash
-memesh  # 대시보드 열기 → 설정 탭
-```
-
-| | 레벨 0 (기본값) | 레벨 1 (스마트 모드) |
-|---|---|---|
-| **검색** | FTS5 키워드 매칭 | + LLM 쿼리 확장 (~97% 재현율) |
-| **자동 포착** | 규칙 기반 패턴 | + LLM이 결정 & 교훈 추출 |
-| **압축** | 사용 불가 | `consolidate`로 장황한 메모리 압축 |
-| **비용** | 무료, API 키 불필요 | 검색당 ~$0.0001 (Haiku) |
-
----
-
-## 전체 8가지 메모리 도구
-
-| 도구 | 기능 |
-|------|-------------|
-| `remember` | 관찰 기록, 관계, 태그와 함께 지식 저장 |
-| `recall` | 다중 요소 스코어링과 LLM 쿼리 확장을 활용한 스마트 검색 |
-| `forget` | 소프트 아카이브(절대 삭제 없음) 또는 특정 관찰 기록 제거 |
-| `consolidate` | LLM 기반 장황한 메모리 압축 |
-| `export` | 메모리를 JSON으로 프로젝트 또는 팀원과 공유 |
-| `import` | 병합 전략(건너뛰기 / 덮어쓰기 / 추가)을 선택해 메모리 가져오기 |
-| `learn` | 실수로부터 구조화된 교훈 기록 (오류, 근본 원인, 수정, 예방) |
-| `user_patterns` | 작업 패턴 분석 — 일정, 도구, 강점, 학습 영역 |
-
----
-
-## 아키텍처
-
-```
-                    ┌─────────────────┐
-                    │   Core Engine   │
-                    │  (8 operations) │
-                    └────────┬────────┘
-           ┌─────────────────┼─────────────────┐
-           │                 │                 │
-     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
-           │                 │                 │
-           └─────────────────┼─────────────────┘
-                             │
-                    SQLite + FTS5 + sqlite-vec
-                    (~/.memesh/knowledge-graph.db)
-```
-
-코어는 프레임워크 독립적. 터미널, HTTP, MCP 어디서 호출해도 동일한 로직이 실행됩니다.
-
----
-
-## 기여하기
+## 개발과 검증
 
 ```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
+cd memesh-llm-memory
+npm install
+npm run build
+npm test
 ```
-
-대시보드: `cd dashboard && npm install && npm run dev`
-
----
-
-<p align="center">
-  <strong>MIT</strong> — <a href="https://pcircle.ai">PCIRCLE AI</a> 제작
-</p>

package/README.md

@@ -3,8 +3,8 @@
 <p align="center">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>The lightest universal AI memory layer.</strong><br />
-    One SQLite file. Any LLM. Zero cloud.
+    <strong>Local memory for Claude Code and MCP coding agents.</strong><br />
+    One SQLite file. No Docker. No cloud required.
   </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>
@@ -18,9 +18,11 @@
 
 ## The Problem
 
-Your AI forgets everything between sessions. Every decision, every bug fix, every lesson learned — gone. You re-explain the same context, Claude re-discovers the same patterns, and your team's AI knowledge resets to zero.
+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.
 
-**MeMesh gives every AI persistent, searchable, evolving memory.**
+**MeMesh gives coding agents persistent, searchable, evolving local memory.**
+
+This package is the local memory layer of the MeMesh product family. It is intentionally small and open-source: install it with npm, keep your memory in `~/.memesh/knowledge-graph.db`, and connect it to Claude Code or any MCP-compatible client. Hosted workspace and enterprise operating-system products should stay separate from this package's README and roadmap.
 
 ---
 
@@ -32,13 +34,13 @@ Your AI forgets everything between sessions. Every decision, every bug fix, ever
 npm install -g @pcircle/memesh
 ```
 
-### Step 2: Your AI remembers
+### Step 2: Store a decision
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### Step 3: Your AI recalls
+### Step 3: Recall it later
 
 ```bash
 memesh recall "login security"
@@ -71,14 +73,14 @@ memesh
 
 | If you are... | MeMesh helps you... |
 |---------------|---------------------|
-| **A developer using Claude Code** | Remember decisions, patterns, and lessons across sessions automatically |
-| **A team building with LLMs** | Share team knowledge via export/import, keep everyone's AI context aligned |
-| **An AI agent developer** | Give your agents persistent memory via MCP, HTTP API, or Python SDK |
-| **A power user with multiple AI tools** | One memory layer that works with Claude, GPT, LLaMA, Ollama, or any MCP client |
+| **A developer using Claude Code** | Auto-recall project decisions, file-specific lessons, and past failures as you work |
+| **A coding-agent power user** | Share one local memory layer across MCP-compatible tools |
+| **A team experimenting with AI coding workflows** | Export/import project knowledge without introducing hosted infrastructure |
+| **An agent developer** | Add local memory through MCP, HTTP, CLI, or the Python SDK |
 
 ---
 
-## Works With Everything
+## Designed For Coding Agents First
 
 <table>
 <tr>
@@ -88,7 +90,7 @@ memesh
 ```bash
 memesh-mcp
 ```
-MCP protocol (auto-configured)
+MCP tools + Claude Code hooks
 
 </td>
 <td width="33%" align="center">
@@ -96,6 +98,7 @@ MCP protocol (auto-configured)
 **Any HTTP Client**
 ```bash
 curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
   -d '{"query":"auth"}'
 ```
 `memesh serve` (REST API)
@@ -116,29 +119,30 @@ Paste tools into any API call
 
 ---
 
-## Why Not Just Use Mem0 / Zep?
+## Why Not OpenMemory, Cursor Memories, Mem0, Or Zep?
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **Install time** | 5 seconds | 30-60 minutes | 30+ minutes |
-| **Setup** | `npm i -g` — done | Neo4j + VectorDB + API keys | Neo4j + config |
-| **Storage** | Single SQLite file | Neo4j + Qdrant | Neo4j |
-| **Works offline** | Yes, always | No | No |
-| **Dashboard** | Built-in (7 tabs + analytics) | None | None |
-| **Dependencies** | 6 | 20+ | 10+ |
-| **Price** | Free forever | Free tier / Paid | Free tier / Paid |
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **Best fit** | Local memory for coding agents | Local/cross-client MCP memory | Cursor-native project memory | Managed app/agent memory | Temporal knowledge graphs |
+| **Install shape** | `npm install -g @pcircle/memesh` | Local app/server flow | Built into Cursor | Cloud API / SDK / MCP | Service/framework setup |
+| **Storage** | One local SQLite file | Local memory stack | Cursor-managed rules/memories | Hosted or self-hosted stack | Graph database |
+| **Cloud required** | No | No for local mode | Depends on Cursor account/settings | Yes for platform | Usually yes/self-hosted |
+| **Claude Code hooks** | First-class | MCP tools | No | MCP tools | Not Claude Code-specific |
+| **Dashboard** | Built in | Built in | Cursor settings | Platform dashboard | Platform/graph tooling |
+| **Tradeoff** | Simple local wedge, not enterprise scale | Broader local app footprint | Locked to Cursor | Strong managed platform, less local-first | Strong graph model, heavier setup |
 
-**MeMesh trades:** enterprise-scale multi-tenant features for **instant setup, zero infrastructure, and 100% privacy**.
+**MeMesh trades enterprise-scale managed infrastructure for instant local setup, inspectable storage, and coding-agent workflow hooks.**
 
 ---
 
-## What Happens Automatically
+## What Happens Automatically In Claude Code
 
-You don't need to manually remember everything. MeMesh has **4 hooks** that capture knowledge without you doing anything:
+You don't need to manually remember everything. MeMesh has **5 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 |
 | **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 |
@@ -159,7 +163,7 @@ You don't need to manually remember everything. MeMesh has **4 hooks** that capt
 | **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 |
-| **Settings** | LLM provider config, language selector |
+| **Settings** | LLM provider config, instant language selector |
 
 ---
 
@@ -167,17 +171,18 @@ You don't need to manually remember everything. MeMesh has **4 hooks** that capt
 
 **🧠 Smart Search** — Search "login security" and find memories about "OAuth PKCE". MeMesh expands queries with related terms using your configured LLM.
 
-**📊 Scored Ranking** — Results ranked by relevance (35%) + how recently you used it (25%) + how often (20%) + confidence (15%) + whether the info is still current (5%).
+**📊 Scored Ranking** — Results ranked by relevance (30%) + recency (25%) + frequency (15%) + confidence (15%) + recall impact (10%) + temporal validity (5%).
 
 **🔄 Knowledge Evolution** — Decisions change. `forget` archives old memories (never deletes). `supersedes` relations link old → new. Your AI always sees the latest version.
 
 **⚠️ Conflict Detection** — If you have two memories that contradict each other, MeMesh warns you.
 
 **📦 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.
 
 ---
 
-## Real-World Usage
+## Example Usage
 
 > "MeMesh remembered that we chose PKCE over implicit flow three weeks ago. When I asked Claude about auth again, it already knew — no re-explaining needed."
 > — **Solo developer, building a SaaS**
@@ -192,7 +197,7 @@ You don't need to manually remember everything. MeMesh has **4 hooks** that capt
 
 ## Unlock Smart Mode (Optional)
 
-MeMesh works fully offline out of the box. Add an LLM API key to unlock smarter search:
+MeMesh works offline by default. Add an LLM API key only if you want query expansion, smarter extraction, and compression:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -255,7 +260,8 @@ 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 -- --run    # 413 tests
+npm test             # 484 tests
+npm run test:e2e-dashboard
 ```
 
 Dashboard: `cd dashboard && npm install && npm run dev`