diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml
deleted file mode 100644
index e885e2a9..00000000
--- a/.github/workflows/auto-release.yml
+++ /dev/null
@@ -1,154 +0,0 @@
-name: Auto Release
-
-# Automatically create git tag and GitHub release when package.json version changes on main branch
-# This prevents version/tag discrepancies and ensures every version bump gets a proper release
-#
-# Workflow: PR merged → Version changed → Create tag → Create release → Trigger npm publish
-# Duration: ~1-2 minutes
-#
-# Requirements:
-# - GITHUB_TOKEN is automatically available
-# - Requires write permissions for contents
-#
-# For manual release creation, see docs/RELEASE_PROCESS.md
-
-on:
- push:
- branches:
- - main
- paths:
- - 'package.json'
-
-permissions:
- contents: write # Required to create tags and releases
-
-jobs:
- check-version:
- runs-on: ubuntu-latest
- outputs:
- version-changed: ${{ steps.check.outputs.changed }}
- new-version: ${{ steps.check.outputs.version }}
-
- steps:
- - name: Checkout code
- uses: actions/checkout@v6
- with:
- fetch-depth: 2 # Need previous commit to compare
-
- - name: Check if version changed
- id: check
- run: |
- # Get current version from package.json
- CURRENT_VERSION=$(node -p "require('./package.json').version")
- echo "Current version: $CURRENT_VERSION"
-
- # Get previous version from parent commit
- git checkout HEAD~1 package.json 2>/dev/null || echo "First commit"
- PREVIOUS_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "none")
- echo "Previous version: $PREVIOUS_VERSION"
-
- # Restore package.json
- git checkout HEAD package.json
-
- # Check if version changed
- if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
- echo "✅ Version changed: $PREVIOUS_VERSION → $CURRENT_VERSION"
- echo "changed=true" >> $GITHUB_OUTPUT
- echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
- else
- echo "⏭️ Version unchanged: $CURRENT_VERSION"
- echo "changed=false" >> $GITHUB_OUTPUT
- fi
-
- create-release:
- needs: check-version
- if: needs.check-version.outputs.version-changed == 'true'
- runs-on: ubuntu-latest
-
- steps:
- - name: Checkout code
- uses: actions/checkout@v6
-
- - name: Extract changelog for version
- id: changelog
- env:
- VERSION: ${{ needs.check-version.outputs.new-version }}
- run: |
- echo "📝 Extracting changelog for v$VERSION"
-
- # Extract changelog section for this version
- # This is a simple extraction - can be enhanced with a proper parser
- if [ -f "CHANGELOG.md" ]; then
- # Extract content between [VERSION] and next [VERSION] or end
- CHANGELOG=$(awk "/## \[$VERSION\]/,/## \[/" CHANGELOG.md | sed '$d' | tail -n +2)
-
- if [ -n "$CHANGELOG" ]; then
- echo "✅ Found changelog for v$VERSION"
- # Save to file for multi-line content
- echo "$CHANGELOG" > changelog.txt
- else
- echo "⚠️ No changelog found for v$VERSION, using default"
- echo "Release v$VERSION" > changelog.txt
- echo "" >> changelog.txt
- echo "See [CHANGELOG.md](CHANGELOG.md) for details." >> changelog.txt
- fi
- else
- echo "⚠️ CHANGELOG.md not found, using default release notes"
- echo "Release v$VERSION" > changelog.txt
- fi
-
- - name: Create git tag
- env:
- VERSION: ${{ needs.check-version.outputs.new-version }}
- run: |
- git config user.name "github-actions[bot]"
- git config user.email "github-actions[bot]@users.noreply.github.com"
-
- # Check if tag already exists (idempotent)
- if git ls-remote --tags origin | grep -q "refs/tags/v$VERSION$"; then
- echo "⏭️ Tag v$VERSION already exists, skipping tag creation"
- else
- # Create annotated tag with changelog
- git tag -a "v$VERSION" -F changelog.txt
- git push origin "v$VERSION"
- echo "✅ Created and pushed tag v$VERSION"
- fi
-
- - name: Create GitHub Release
- id: create_release
- uses: softprops/action-gh-release@v2
- with:
- tag_name: v${{ needs.check-version.outputs.new-version }}
- name: v${{ needs.check-version.outputs.new-version }}
- body_path: changelog.txt
- draft: false
- prerelease: false
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- continue-on-error: true
-
- - name: Verify release exists
- env:
- VERSION: ${{ needs.check-version.outputs.new-version }}
- REPO: ${{ github.repository }}
- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- # Check if release exists (either created now or previously)
- if gh release view "v$VERSION" &>/dev/null; then
- echo "✅ Release v$VERSION exists"
- echo "📦 Tag: v$VERSION"
- echo "🔗 Release URL: https://github.com/$REPO/releases/tag/v$VERSION"
- else
- echo "❌ Release v$VERSION not found"
- echo "This should not happen - check previous steps"
- exit 1
- fi
-
- - name: Log success
- env:
- VERSION: ${{ needs.check-version.outputs.new-version }}
- REPO: ${{ github.repository }}
- run: |
- echo "🎉 Successfully ensured release v$VERSION exists"
- echo ""
- echo "⏭️ Next: The publish-npm.yml workflow will automatically publish to npm"
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
deleted file mode 100644
index 279a0c30..00000000
--- a/.github/workflows/e2e.yml
+++ /dev/null
@@ -1,66 +0,0 @@
-name: E2E Tests
-
-on:
- push:
- branches: [main]
- pull_request:
- branches: [main]
- paths:
- - 'src/mcp/**'
- - 'tests/e2e/**'
- - 'tests/integration/**'
- workflow_dispatch:
- inputs:
- debug:
- description: 'Enable debug mode'
- required: false
- type: boolean
- default: false
-
-concurrency:
- group: e2e-${{ github.ref }}
- cancel-in-progress: true
-
-jobs:
- e2e:
- name: E2E Tests
- runs-on: ubuntu-latest
- timeout-minutes: 20
-
- steps:
- - name: Checkout
- uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: '20'
- cache: 'npm'
-
- - name: Install dependencies
- run: npm ci
-
- - name: Build
- run: npm run build
-
- # E2E tests run sequentially with no retries
- # - singleThread: true prevents resource exhaustion
- # - retry: 0 because failures are config issues, not flakes
- # - 60s timeout per test
- - name: Run E2E tests
- run: npm run test:e2e:safe
- env:
- NODE_OPTIONS: --max-old-space-size=4096
- CI: true
-
- - name: Run integration tests
- run: npm run test:integration -- --run
- env:
- NODE_OPTIONS: --max-old-space-size=4096
-
- - name: Cleanup processes
- if: always()
- run: |
- # Kill any orphaned node processes from tests
- pkill -f "server-bootstrap" || true
- pkill -f "vitest" || true
diff --git a/.github/workflows/installation-test.yml b/.github/workflows/installation-test.yml
deleted file mode 100644
index ebfdc5dd..00000000
--- a/.github/workflows/installation-test.yml
+++ /dev/null
@@ -1,164 +0,0 @@
-name: Installation Testing (All Methods)
-
-on:
- push:
- branches: [main, develop]
- paths:
- - 'package.json'
- - 'plugin.json'
- - 'mcp.json'
- - 'scripts/**'
- - 'src/**'
- - '.github/workflows/installation-test.yml'
- pull_request:
- branches: [main, develop]
- workflow_dispatch:
-
-jobs:
- # Job 1: 基礎檢查
- basic-checks:
- name: Basic Checks
- runs-on: ubuntu-latest
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: '20'
- cache: 'npm'
-
- - name: Validate JSON Files
- run: |
- echo "Validating package.json..."
- node -e "require('./package.json')"
-
- echo "Validating plugin.json..."
- node -e "const p = require('./plugin.json'); if (p.mcpServers) throw new Error('plugin.json should not contain mcpServers');"
-
- echo "Validating mcp.json..."
- node -e "const m = require('./mcp.json'); if (!m.memesh || !m.memesh.command) throw new Error('Invalid mcp.json');"
-
- echo "✅ All JSON files are valid"
-
- - name: Check File Structure
- run: |
- test -f package.json || exit 1
- test -f plugin.json || exit 1
- test -f mcp.json || exit 1
- test -f README.md || exit 1
- test -d src || exit 1
- test -d scripts || exit 1
- echo "✅ File structure is correct"
-
- # Job 2: 方式 1 - npm 全域安裝測試
- npm-install-test:
- name: Method 1 - npm Global Install
- runs-on: ubuntu-latest
- needs: basic-checks
-
- strategy:
- matrix:
- node-version: ['20', '22']
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: ${{ matrix.node-version }}
-
- - name: Install dependencies
- run: npm ci
-
- - name: Run tests
- run: npm test
-
- - name: Build project
- run: npm run build
-
- - name: Test npm pack
- run: |
- npm pack
- TARBALL=$(ls -t pcircle-memesh-*.tgz | head -1)
- tar -tzf "$TARBALL" | grep -q "package/mcp.json" || exit 1
- tar -tzf "$TARBALL" | grep -q "package/plugin.json" || exit 1
- echo "✅ npm pack successful"
-
- # Job 3: 方式 2 - Plugin Build 測試
- plugin-build-test:
- name: Method 2 - Plugin Build
- runs-on: ubuntu-latest
- needs: basic-checks
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: '20'
- cache: 'npm'
-
- - name: Install dependencies
- run: npm ci
-
- - name: Build project
- run: npm run build
-
- - name: Build plugin
- run: npm run build:plugin
-
- - name: Verify plugin structure
- run: |
- test -f .claude-plugin/memesh/.claude-plugin/plugin.json || exit 1
- test -f .claude-plugin/memesh/.mcp.json || exit 1
- test -f .claude-plugin/memesh/dist/mcp/server-bootstrap.js || exit 1
- test -d .claude-plugin/memesh/node_modules || exit 1
- echo "✅ Plugin structure verified"
-
- - name: Test MCP Server standalone
- run: |
- chmod +x ./scripts/test-mcp-server-standalone.sh
- ./scripts/test-mcp-server-standalone.sh
-
- # Job 4: Docker 測試
- docker-test:
- name: Method 3 - Docker Clean Install
- runs-on: ubuntu-latest
- needs: basic-checks
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Build test Docker image
- run: docker build -f Dockerfile.test -t memesh-test:latest .
-
- - name: Run tests in Docker
- run: docker run --rm memesh-test:latest
-
- # Job 5: 安全性檢查
- security-check:
- name: Security Checks
- runs-on: ubuntu-latest
- needs: basic-checks
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: '20'
-
- - name: Install dependencies
- run: npm ci
-
- - name: Run npm audit
- run: npm audit --audit-level=high || echo "Audit warnings"
-
- - name: Check for secrets
- run: |
- echo "✅ No leaked secrets found"
diff --git a/.github/workflows/plugin-deployment-check.yml b/.github/workflows/plugin-deployment-check.yml
deleted file mode 100644
index a0ab4320..00000000
--- a/.github/workflows/plugin-deployment-check.yml
+++ /dev/null
@@ -1,27 +0,0 @@
-name: Plugin Deployment Pre-Check
-
-on:
- workflow_dispatch:
- push:
- tags:
- - 'v*'
-
-jobs:
- deployment-check:
- runs-on: ubuntu-latest
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Setup Node.js
- uses: actions/setup-node@v6
- with:
- node-version: '20'
-
- - name: Install dependencies
- run: npm ci
-
- - name: Run comprehensive pre-deployment check
- run: |
- chmod +x scripts/pre-deployment-check.sh
- ./scripts/pre-deployment-check.sh
diff --git a/.mcp.json b/.mcp.json
index 6243d15d..28c9741d 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -2,11 +2,8 @@
"mcpServers": {
"memesh": {
"command": "node",
- "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server-bootstrap.js"],
- "env": {
- "NODE_ENV": "production",
- "MEMESH_DISABLE_DAEMON": "1"
- }
+ "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+ "env": { "NODE_ENV": "production" }
}
}
}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3d4159ab..aa936eff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **`memesh-view` CLI command** — generates self-contained HTML dashboard with D3.js force-directed knowledge graph, searchable entity table, and statistics
+- Fixed vitest pool from `threads` to `forks` to prevent SIGSEGV with better-sqlite3 native module
+
+## [3.0.0-alpha.1] - 2026-03-09
+
+### Breaking Changes
+
+- **Minimal core rewrite** — stripped from 50+ source files to 5, 26 dependencies to 3
+- **3 MCP tools only**: `remember`, `recall`, `forget` (removed buddy-do, buddy-help, memesh-hook-tool-use, memesh-generate-tests, memesh-metrics)
+- **2 hooks only**: session-start, post-commit (removed pre-tool-use, post-tool-use, stop, subagent-stop)
+
+### Removed
+
+- Vector search (ONNX embeddings, sqlite-vec, EmbeddingService)
+- Daemon/proxy server modes (standalone only)
+- CLI features (commander, inquirer, interactive prompts)
+- HTTP server (express)
+- All UI formatting (chalk, boxen, ora, cli-spinners, cli-table3, asciichart)
+- Logging framework (winston)
+- 23 production dependencies
+
+### Architecture
+
+- **Database**: Direct better-sqlite3 with FTS5 full-text search
+- **Server**: Standalone MCP via StdioServerTransport
+- **Validation**: Zod schemas for all tool inputs
+- **Backward compatible**: Existing DB data (entities, observations, relations, tags) preserved and queryable
+
+## [2.10.2] - 2026-03-09
+
+### Changed
+
+- Clean up changelog entries
+
## [2.10.1] - 2026-03-09
### Fixed
@@ -15,7 +51,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
-- Untrack local-only files from git (CLAUDE.md, .claude/, media/demo-video/, Dockerfile.test)
+- Streamline repository for professional open source standards
+- Simplify documentation and build configuration
## [2.10.0] - 2026-03-08
diff --git a/README.de.md b/README.de.md
deleted file mode 100644
index 495ebf7d..00000000
--- a/README.de.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### Deine KI-Coding-Sitzungen verdienen ein Gedächtnis.
-
-MeMesh Plugin gibt Claude Code ein persistentes, durchsuchbares Gedächtnis — damit jede Sitzung auf der vorherigen aufbaut.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Loslegen](#loslegen) · [So funktioniert es](#so-funktioniert-es) · [Befehle](#befehle) · [Dokumentation](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · **Deutsch** · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### Vor MeMesh
-```
-Sitzung 1: "Verwende JWT für Auth"
-Sitzung 2: "Warum haben wir JWT gewählt?"
-Sitzung 3: "Moment, welche Auth-Bibliothek nutzen wir?"
-```
-Du wiederholst Entscheidungen. Claude vergisst den Kontext. Der Fortschritt stockt.
-
- |
-
-
-### Nach MeMesh
-```
-Sitzung 1: "Verwende JWT für Auth" → gespeichert
-Sitzung 2: buddy-remember "auth" → sofortiger Abruf
-Sitzung 3: Kontext wird beim Start automatisch geladen
-```
-Jede Sitzung knüpft dort an, wo du aufgehört hast.
-
- |
-
-
-
----
-
-## Was du bekommst
-
-**Durchsuchbares Projektgedächtnis** — Frage „Was haben wir über Auth entschieden?" und erhalte sofort eine semantisch abgeglichene Antwort. Keine Stichwortsuche — *Bedeutungssuche*, angetrieben durch lokale ONNX-Embeddings.
-
-**Intelligente Aufgabenanalyse** — `buddy-do "Benutzer-Auth hinzufügen"` führt nicht einfach aus. Es zieht relevanten Kontext aus vergangenen Sitzungen, prüft welche Muster du etabliert hast und erstellt einen angereicherten Plan, bevor eine einzige Zeile geschrieben wird.
-
-**Proaktiver Abruf** — MeMesh ruft automatisch relevante Erinnerungen ab, wenn du eine Sitzung startest, ein Test fehlschlägt oder ein Fehler auftritt. Kein manuelles Suchen nötig.
-
-**Workflow-Automatisierung** — Sitzungszusammenfassungen beim Start. Verfolgung von Dateiänderungen. Code-Review-Erinnerungen vor Commits. Alles läuft leise im Hintergrund.
-
-**Aus Fehlern lernen** — Fehler und Korrekturen aufzeichnen, um eine Wissensbasis aufzubauen. Derselbe Fehler passiert nicht zweimal.
-
----
-
-## Loslegen
-
-**Voraussetzungen**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Claude Code neu starten. Das war's.
-
-**Überprüfen** — tippe in Claude Code:
-
-```
-buddy-help
-```
-
-Du solltest eine Liste der verfügbaren Befehle sehen.
-
-
-Aus dem Quellcode installieren (für Mitwirkende)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## Befehle
-
-| Befehl | Was er tut |
-|--------|-----------|
-| `buddy-do "Aufgabe"` | Aufgabe mit vollem Gedächtniskontext ausführen |
-| `buddy-remember "Thema"` | Vergangene Entscheidungen und Kontext durchsuchen |
-| `buddy-help` | Verfügbare Befehle anzeigen |
-
-**Praxisbeispiele:**
-
-```bash
-# Sich in einer neuen Codebase orientieren
-buddy-do "explain this codebase"
-
-# Features mit Kontext aus vergangener Arbeit bauen
-buddy-do "add user authentication"
-
-# Nachvollziehen, warum Entscheidungen getroffen wurden
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-Alle Daten bleiben auf deinem Rechner mit automatischer 90-Tage-Aufbewahrung.
-
----
-
-## Wie unterscheidet sich das von CLAUDE.md?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **Zweck** | Statische Anweisungen für Claude | Lebendiges Gedächtnis, das mit deinem Projekt wächst |
-| **Suche** | Manuelle Textsuche | Semantische Suche nach Bedeutung |
-| **Aktualisierung** | Du bearbeitest manuell | Erfasst Entscheidungen automatisch während der Arbeit |
-| **Abruf** | Wird immer geladen (kann lang werden) | Zeigt relevanten Kontext bei Bedarf |
-| **Umfang** | Allgemeine Präferenzen | Projektspezifischer Wissensgraph |
-
-**Sie ergänzen sich.** CLAUDE.md sagt Claude, *wie* er arbeiten soll. MeMesh erinnert sich daran, *was* ihr gebaut habt.
-
----
-
-## Plattformunterstützung
-
-| Plattform | Status |
-|-----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 empfohlen) |
-
-**Funktioniert mit:** Claude Code CLI · VS Code Extension · Cursor (via MCP) · Jeder MCP-kompatible Editor
-
----
-
-## Architektur
-
-MeMesh läuft als Claude Code Plugin lokal mit integrierter MCP-Komponente:
-
-- **Knowledge Graph** — SQLite-basierter Entity-Speicher mit FTS5-Volltextsuche
-- **Vector Embeddings** — ONNX Runtime für semantische Ähnlichkeit (läuft 100% lokal)
-- **Content Dedup** — SHA-256-Hashing überspringt redundante Embedding-Berechnungen
-- **Batch Processing** — Effiziente Massenoperationen für große Wissensbasen
-- **Hook System** — Proaktiver Abruf bei Sitzungsstart, Testfehlern und Fehlern
-
-Alles läuft lokal. Keine Cloud. Keine API-Aufrufe. Deine Daten verlassen nie deinen Rechner.
-
----
-
-## Dokumentation
-
-| Dokument | Beschreibung |
-|----------|-------------|
-| [Erste Schritte](docs/GETTING_STARTED.md) | Schritt-für-Schritt-Einrichtungsanleitung |
-| [Benutzerhandbuch](docs/USER_GUIDE.md) | Vollständige Anleitung mit Beispielen |
-| [Befehle](docs/COMMANDS.md) | Komplette Befehlsreferenz |
-| [Architektur](docs/ARCHITECTURE.md) | Technischer Tiefgang |
-| [Mitwirken](CONTRIBUTING.md) | Richtlinien für Beiträge |
-| [Entwicklung](docs/DEVELOPMENT.md) | Entwicklungsumgebung für Mitwirkende |
-
----
-
-## Mitwirken
-
-Beiträge sind willkommen! Siehe [CONTRIBUTING.md](CONTRIBUTING.md) für den Einstieg.
-
----
-
-## Lizenz
-
-MIT — Siehe [LICENSE](LICENSE)
-
----
-
-
-
-**Gebaut mit Claude Code, für Claude Code.**
-
-[Bug melden](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Feature anfragen](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Hilfe erhalten](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.es.md b/README.es.md
deleted file mode 100644
index 19e55a4b..00000000
--- a/README.es.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### Tus sesiones de programación con IA merecen memoria.
-
-MeMesh Plugin le da a Claude Code una memoria persistente y consultable — para que cada sesión se base en la anterior.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Comenzar](#comenzar) · [Cómo funciona](#cómo-funciona) · [Comandos](#comandos) · [Docs](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · **Español** · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### Antes de MeMesh
-```
-Session 1: "Use JWT for auth"
-Session 2: "Why did we pick JWT again?"
-Session 3: "Wait, what auth library are we using?"
-```
-Repites decisiones. Claude olvida el contexto. El progreso se detiene.
-
- |
-
-
-### Después de MeMesh
-```
-Session 1: "Use JWT for auth" → saved
-Session 2: buddy-remember "auth" → instant recall
-Session 3: Context auto-loaded on start
-```
-Cada sesión continúa donde lo dejaste.
-
- |
-
-
-
----
-
-## Lo que obtienes
-
-**Memoria de proyecto consultable** — Pregunta "¿qué decidimos sobre la auth?" y obtén una respuesta instantánea con coincidencia semántica. No es búsqueda por palabras clave — es búsqueda por *significado*, impulsada por embeddings ONNX locales.
-
-**Análisis inteligente de tareas** — `buddy-do "add user auth"` no solo ejecuta. Extrae contexto relevante de sesiones anteriores, verifica qué patrones has establecido y construye un plan enriquecido antes de escribir una sola línea.
-
-**Recuperación proactiva** — MeMesh muestra automáticamente memorias relevantes cuando inicias una sesión, cuando falla un test o cuando encuentras un error. Sin búsqueda manual necesaria.
-
-**Automatización del flujo de trabajo** — Resúmenes de sesión al iniciar. Seguimiento de cambios en archivos. Recordatorios de revisión de código antes de commits. Todo ejecutándose silenciosamente en segundo plano.
-
-**Aprendizaje de errores** — Registra errores y correcciones para construir una base de conocimiento. El mismo error no ocurre dos veces.
-
----
-
-## Comenzar
-
-**Requisitos previos**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Reinicia Claude Code. Eso es todo.
-
-**Verificar** — escribe en Claude Code:
-
-```
-buddy-help
-```
-
-Deberías ver una lista de comandos disponibles.
-
-
-Instalar desde el código fuente (contribuidores)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## Comandos
-
-| Comando | Qué hace |
-|---------|----------|
-| `buddy-do "tarea"` | Ejecutar una tarea con contexto de memoria completo |
-| `buddy-remember "tema"` | Buscar decisiones y contexto anteriores |
-| `buddy-help` | Mostrar comandos disponibles |
-
-**Ejemplos reales:**
-
-```bash
-# Orientarte en un codebase nuevo para ti
-buddy-do "explain this codebase"
-
-# Construir funcionalidades con contexto de trabajo anterior
-buddy-do "add user authentication"
-
-# Recordar por qué se tomaron decisiones
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-Todos los datos permanecen en tu máquina con retención automática de 90 días.
-
----
-
-## ¿En qué se diferencia de CLAUDE.md?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **Propósito** | Instrucciones estáticas para Claude | Memoria viva que crece con tu proyecto |
-| **Búsqueda** | Búsqueda manual de texto | Búsqueda semántica por significado |
-| **Actualizaciones** | Las editas manualmente | Captura decisiones automáticamente mientras trabajas |
-| **Recuperación** | Siempre cargado (puede volverse extenso) | Muestra contexto relevante bajo demanda |
-| **Alcance** | Preferencias generales | Grafo de conocimiento específico del proyecto |
-
-**Funcionan juntos.** CLAUDE.md le dice a Claude *cómo* trabajar. MeMesh recuerda *qué* has construido.
-
----
-
-## Plataformas soportadas
-
-| Plataforma | Estado |
-|------------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 recomendado) |
-
-**Compatible con:** Claude Code CLI · VS Code Extension · Cursor (vía MCP) · Cualquier editor compatible con MCP
-
----
-
-## Arquitectura
-
-MeMesh funciona como un plugin de Claude Code en local, con un componente MCP integrado:
-
-- **Grafo de conocimiento** — Almacén de entidades respaldado por SQLite con búsqueda de texto completo FTS5
-- **Embeddings vectoriales** — Runtime ONNX para similitud semántica (se ejecuta 100% localmente)
-- **Deduplicación de contenido** — Hashing SHA-256 omite cálculos de embedding redundantes
-- **Procesamiento por lotes** — Operaciones masivas eficientes para grandes bases de conocimiento
-- **Sistema de hooks** — Recuperación proactiva al iniciar sesión, fallos de tests y errores
-
-Todo se ejecuta localmente. Sin nube. Sin llamadas API. Tus datos nunca salen de tu máquina.
-
----
-
-## Documentación
-
-| Documento | Descripción |
-|-----------|-------------|
-| [Primeros pasos](docs/GETTING_STARTED.md) | Guía de configuración paso a paso |
-| [Guía de usuario](docs/USER_GUIDE.md) | Guía completa de uso con ejemplos |
-| [Comandos](docs/COMMANDS.md) | Referencia completa de comandos |
-| [Arquitectura](docs/ARCHITECTURE.md) | Análisis técnico en profundidad |
-| [Contribuir](CONTRIBUTING.md) | Directrices para contribuir |
-| [Desarrollo](docs/DEVELOPMENT.md) | Configuración de desarrollo para contribuidores |
-
----
-
-## Contribuir
-
-¡Las contribuciones son bienvenidas! Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para comenzar.
-
----
-
-## Licencia
-
-MIT — Ver [LICENSE](LICENSE)
-
----
-
-
-
-**Construido con Claude Code, para Claude Code.**
-
-[Reportar bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Solicitar función](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Obtener ayuda](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.fr.md b/README.fr.md
deleted file mode 100644
index 0e2e3808..00000000
--- a/README.fr.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### Vos sessions de code avec l'IA méritent une mémoire.
-
-MeMesh Plugin offre à Claude Code une mémoire persistante et consultable — chaque session s'appuie sur la précédente.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Démarrage](#démarrage) · [Fonctionnement](#fonctionnement) · [Commandes](#commandes) · [Documentation](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Français** · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### Avant MeMesh
-```
-Session 1 : "Utiliser JWT pour l'auth"
-Session 2 : "Pourquoi on avait choisi JWT déjà ?"
-Session 3 : "Attends, on utilise quelle bibliothèque d'auth ?"
-```
-Vous répétez vos décisions. Claude oublie le contexte. La progression stagne.
-
- |
-
-
-### Après MeMesh
-```
-Session 1 : "Utiliser JWT pour l'auth" → sauvegardé
-Session 2 : buddy-remember "auth" → rappel instantané
-Session 3 : Contexte chargé automatiquement au démarrage
-```
-Chaque session reprend là où vous vous étiez arrêté.
-
- |
-
-
-
----
-
-## Ce que vous obtenez
-
-**Mémoire de projet consultable** — Demandez "qu'est-ce qu'on avait décidé pour l'auth ?" et obtenez une réponse instantanée par correspondance sémantique. Pas une recherche par mots-clés — une recherche par *sens*, propulsée par des embeddings ONNX locaux.
-
-**Analyse intelligente des tâches** — `buddy-do "ajouter l'auth utilisateur"` ne se contente pas d'exécuter. Il récupère le contexte pertinent des sessions passées, vérifie les patterns que vous avez établis, et construit un plan enrichi avant d'écrire la moindre ligne.
-
-**Rappel proactif** — MeMesh fait remonter automatiquement les souvenirs pertinents au démarrage d'une session, lors d'un échec de test ou d'une erreur. Aucune recherche manuelle nécessaire.
-
-**Automatisation du workflow** — Récapitulatifs de session au démarrage. Suivi des modifications de fichiers. Rappels de revue de code avant les commits. Le tout fonctionne silencieusement en arrière-plan.
-
-**Apprentissage des erreurs** — Enregistrez les erreurs et leurs corrections pour construire une base de connaissances. La même erreur ne se reproduit pas deux fois.
-
----
-
-## Démarrage
-
-**Prérequis** : [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Redémarrez Claude Code. C'est tout.
-
-**Vérification** — tapez dans Claude Code :
-
-```
-buddy-help
-```
-
-Vous devriez voir une liste des commandes disponibles.
-
-
-Installation depuis les sources (contributeurs)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## Commandes
-
-| Commande | Ce qu'elle fait |
-|----------|----------------|
-| `buddy-do "tâche"` | Exécuter une tâche avec le contexte mémoire complet |
-| `buddy-remember "sujet"` | Rechercher les décisions et le contexte passés |
-| `buddy-help` | Afficher les commandes disponibles |
-
-**Exemples concrets :**
-
-```bash
-# Se repérer dans un nouveau codebase
-buddy-do "explain this codebase"
-
-# Développer des fonctionnalités avec le contexte du travail passé
-buddy-do "add user authentication"
-
-# Retrouver pourquoi des décisions ont été prises
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-Toutes les données restent sur votre machine avec une rétention automatique de 90 jours.
-
----
-
-## En quoi est-ce différent de CLAUDE.md ?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **Objectif** | Instructions statiques pour Claude | Mémoire vivante qui grandit avec votre projet |
-| **Recherche** | Recherche textuelle manuelle | Recherche sémantique par sens |
-| **Mises à jour** | Vous éditez manuellement | Capture automatique des décisions en cours de travail |
-| **Rappel** | Toujours chargé (peut devenir long) | Fait remonter le contexte pertinent à la demande |
-| **Portée** | Préférences générales | Graphe de connaissances spécifique au projet |
-
-**Ils fonctionnent ensemble.** CLAUDE.md indique à Claude *comment* travailler. MeMesh se souvient de *ce que* vous avez construit.
-
----
-
-## Plateformes supportées
-
-| Plateforme | Statut |
-|-----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 recommandé) |
-
-**Compatible avec :** Claude Code CLI · VS Code Extension · Cursor (via MCP) · Tout éditeur compatible MCP
-
----
-
-## Architecture
-
-MeMesh fonctionne comme un plugin Claude Code en local, avec un composant MCP intégré :
-
-- **Graphe de connaissances** — Stockage d'entités basé sur SQLite avec recherche plein texte FTS5
-- **Embeddings vectoriels** — Runtime ONNX pour la similarité sémantique (100 % local)
-- **Déduplication de contenu** — Hachage SHA-256 pour éviter les calculs d'embeddings redondants
-- **Traitement par lots** — Opérations en masse efficaces pour les grandes bases de connaissances
-- **Système de hooks** — Rappel proactif au démarrage de session, en cas d'échec de tests et d'erreurs
-
-Tout fonctionne localement. Pas de cloud. Pas d'appels API. Vos données ne quittent jamais votre machine.
-
----
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Démarrage](docs/GETTING_STARTED.md) | Guide d'installation pas à pas |
-| [Guide utilisateur](docs/USER_GUIDE.md) | Guide complet avec exemples |
-| [Commandes](docs/COMMANDS.md) | Référence complète des commandes |
-| [Architecture](docs/ARCHITECTURE.md) | Plongée technique approfondie |
-| [Contribuer](CONTRIBUTING.md) | Guide de contribution |
-| [Développement](docs/DEVELOPMENT.md) | Configuration pour les contributeurs |
-
----
-
-## Contribuer
-
-Les contributions sont les bienvenues ! Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour commencer.
-
----
-
-## Licence
-
-MIT — Voir [LICENSE](LICENSE)
-
----
-
-
-
-**Construit avec Claude Code, pour Claude Code.**
-
-[Signaler un bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Demander une fonctionnalité](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Obtenir de l'aide](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.id.md b/README.id.md
deleted file mode 100644
index 3d0d74bb..00000000
--- a/README.id.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### Sesi coding AI Anda layak memiliki memori.
-
-MeMesh Plugin memberikan Claude Code memori yang persisten dan dapat dicari — sehingga setiap sesi melanjutkan dari yang terakhir.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Mulai Sekarang](#mulai-sekarang) · [Cara Kerja](#cara-kerja) · [Perintah](#perintah) · [Dokumentasi](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · **Bahasa Indonesia**
-
-
-
-|
-
-### Sebelum MeMesh
-```
-Sesi 1: "Gunakan JWT untuk auth"
-Sesi 2: "Kenapa kita pilih JWT tadi?"
-Sesi 3: "Tunggu, pustaka auth apa yang kita pakai?"
-```
-Anda mengulang keputusan. Claude lupa konteks. Progres terhenti.
-
- |
-
-
-### Setelah MeMesh
-```
-Sesi 1: "Gunakan JWT untuk auth" → tersimpan
-Sesi 2: buddy-remember "auth" → langsung teringat
-Sesi 3: Konteks dimuat otomatis saat mulai
-```
-Setiap sesi melanjutkan dari yang terakhir.
-
- |
-
-
-
----
-
-## Yang Anda Dapatkan
-
-**Memori Proyek yang Dapat Dicari** — Tanya "apa yang kita putuskan tentang auth?" dan dapatkan jawaban instan yang dicocokkan secara semantik. Bukan pencarian kata kunci — pencarian berdasarkan *makna*, didukung oleh embedding ONNX lokal.
-
-**Analisis Tugas Cerdas** — `buddy-do "tambahkan auth pengguna"` tidak langsung mengeksekusi. Ia mengambil konteks relevan dari sesi sebelumnya, memeriksa pola yang sudah Anda tetapkan, dan menyusun rencana yang diperkaya sebelum menulis satu baris kode pun.
-
-**Pemanggilan Proaktif** — MeMesh secara otomatis memunculkan memori yang relevan saat Anda memulai sesi, menghadapi kegagalan pengujian, atau menemui error. Tidak perlu pencarian manual.
-
-**Otomasi Alur Kerja** — Ringkasan sesi saat startup. Pelacakan perubahan file. Pengingat code review sebelum commit. Semuanya berjalan diam-diam di latar belakang.
-
-**Belajar dari Kesalahan** — Catat error dan perbaikannya untuk membangun basis pengetahuan. Kesalahan yang sama tidak terjadi dua kali.
-
----
-
-## Mulai Sekarang
-
-**Prasyarat**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Restart Claude Code. Selesai.
-
-**Verifikasi** — ketik di Claude Code:
-
-```
-buddy-help
-```
-
-Anda akan melihat daftar perintah yang tersedia.
-
-
-Instalasi dari source (kontributor)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## Perintah
-
-| Perintah | Fungsi |
-|----------|--------|
-| `buddy-do "tugas"` | Jalankan tugas dengan konteks memori penuh |
-| `buddy-remember "topik"` | Cari keputusan dan konteks sebelumnya |
-| `buddy-help` | Tampilkan perintah yang tersedia |
-
-**Contoh nyata:**
-
-```bash
-# Pahami codebase yang baru Anda temui
-buddy-do "explain this codebase"
-
-# Bangun fitur dengan konteks dari pekerjaan sebelumnya
-buddy-do "add user authentication"
-
-# Ingat kembali mengapa keputusan dibuat
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-Semua data tetap di mesin Anda dengan retensi otomatis 90 hari.
-
----
-
-## Apa Bedanya dengan CLAUDE.md?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **Tujuan** | Instruksi statis untuk Claude | Memori hidup yang berkembang bersama proyek |
-| **Pencarian** | Pencarian teks manual | Pencarian semantik berdasarkan makna |
-| **Pembaruan** | Anda edit secara manual | Otomatis menangkap keputusan saat Anda bekerja |
-| **Pemanggilan** | Selalu dimuat (bisa jadi panjang) | Memunculkan konteks relevan sesuai kebutuhan |
-| **Cakupan** | Preferensi umum | Grafik pengetahuan khusus proyek |
-
-**Keduanya bekerja bersama.** CLAUDE.md memberi tahu Claude *cara* bekerja. MeMesh mengingat *apa* yang telah Anda bangun.
-
----
-
-## Dukungan Platform
-
-| Platform | Status |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 direkomendasikan) |
-
-**Kompatibel dengan:** Claude Code CLI · VS Code Extension · Cursor (via MCP) · Editor mana pun yang kompatibel MCP
-
----
-
-## Arsitektur
-
-MeMesh berjalan sebagai plugin Claude Code secara lokal, dengan komponen MCP terintegrasi:
-
-- **Knowledge Graph** — Penyimpanan entitas berbasis SQLite dengan pencarian teks lengkap FTS5
-- **Vector Embeddings** — Runtime ONNX untuk kesamaan semantik (berjalan 100% lokal)
-- **Content Dedup** — Hashing SHA-256 melewati komputasi embedding yang redundan
-- **Batch Processing** — Operasi massal yang efisien untuk basis pengetahuan besar
-- **Hook System** — Pemanggilan proaktif saat memulai sesi, kegagalan pengujian, dan error
-
-Semuanya berjalan secara lokal. Tanpa cloud. Tanpa panggilan API. Data Anda tidak pernah meninggalkan mesin Anda.
-
----
-
-## Dokumentasi
-
-| Dokumen | Deskripsi |
-|---------|-----------|
-| [Memulai](docs/GETTING_STARTED.md) | Panduan setup langkah demi langkah |
-| [Panduan Pengguna](docs/USER_GUIDE.md) | Panduan penggunaan lengkap dengan contoh |
-| [Perintah](docs/COMMANDS.md) | Referensi perintah lengkap |
-| [Arsitektur](docs/ARCHITECTURE.md) | Penjelasan teknis mendalam |
-| [Kontribusi](CONTRIBUTING.md) | Panduan kontribusi |
-| [Pengembangan](docs/DEVELOPMENT.md) | Setup pengembangan untuk kontributor |
-
----
-
-## Kontribusi
-
-Kami menyambut kontribusi! Lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk memulai.
-
----
-
-## Lisensi
-
-MIT — Lihat [LICENSE](LICENSE)
-
----
-
-
-
-**Dibangun dengan Claude Code, untuk Claude Code.**
-
-[Laporkan Bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Minta Fitur](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Dapatkan Bantuan](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.ja.md b/README.ja.md
deleted file mode 100644
index c9b175f9..00000000
--- a/README.ja.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### あなたの AI コーディングセッションにはメモリが必要です。
-
-MeMesh Plugin は Claude Code に永続的で検索可能なメモリを提供し、すべてのセッションが前回の続きから始まります。
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[はじめに](#はじめに) · [仕組み](#仕組み) · [コマンド](#コマンド) · [ドキュメント](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### MeMesh 導入前
-```
-セッション 1: 「認証には JWT を使おう」
-セッション 2: 「なぜ JWT にしたんだっけ？」
-セッション 3: 「え、どの認証ライブラリ使ってるの？」
-```
-決定を繰り返す。Claude はコンテキストを忘れる。進捗が止まる。
-
- |
-
-
-### MeMesh 導入後
-```
-セッション 1: 「認証には JWT を使おう」→ 保存済み
-セッション 2: buddy-remember "auth" → 即座に呼び出し
-セッション 3: 開始時にコンテキスト自動読み込み
-```
-すべてのセッションが前回の続きから始まります。
-
- |
-
-
-
----
-
-## できること
-
-**検索可能なプロジェクトメモリ** — 「認証についてどう決めた？」と聞けば、意味に基づいて即座にマッチした回答が返ります。キーワード検索ではなく、ローカル ONNX 埋め込みによる*意味*検索です。
-
-**スマートタスク分析** — `buddy-do "ユーザー認証を追加"` はただ実行するだけではありません。過去のセッションから関連コンテキストを引き出し、確立されたパターンを確認し、一行のコードを書く前に充実したプランを構築します。
-
-**プロアクティブな呼び出し** — MeMesh はセッション開始時、テスト失敗時、エラー発生時に関連するメモリを自動的に表示します。手動検索は不要です。
-
-**ワークフロー自動化** — 起動時のセッション要約。ファイル変更の追跡。コミット前のコードレビューリマインダー。すべてバックグラウンドで静かに動作します。
-
-**ミスから学ぶ** — エラーと修正を記録してナレッジベースを構築。同じミスを二度と繰り返しません。
-
----
-
-## はじめに
-
-**必要なもの**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Claude Code を再起動すれば完了です。
-
-**動作確認** — Claude Code で以下を入力：
-
-```
-buddy-help
-```
-
-利用可能なコマンドの一覧が表示されます。
-
-
-ソースからインストール（コントリビューター向け）
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## コマンド
-
-| コマンド | 機能 |
-|---------|------|
-| `buddy-do "タスク"` | メモリコンテキスト付きでタスクを実行 |
-| `buddy-remember "トピック"` | 過去の決定やコンテキストを検索 |
-| `buddy-help` | 利用可能なコマンドを表示 |
-
-**実際の例：**
-
-```bash
-# 初めてのコードベースを理解する
-buddy-do "explain this codebase"
-
-# 過去の作業のコンテキストを活用して機能を構築
-buddy-do "add user authentication"
-
-# なぜその決定をしたか思い出す
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-すべてのデータはローカルマシンに保存され、自動的に 90 日間保持されます。
-
----
-
-## CLAUDE.md との違いは？
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **目的** | Claude への静的な指示 | プロジェクトと共に成長する生きたメモリ |
-| **検索** | 手動テキスト検索 | 意味に基づくセマンティック検索 |
-| **更新** | 手動で編集 | 作業中に決定事項を自動キャプチャ |
-| **呼び出し** | 常に読み込み（長くなりがち） | 必要に応じて関連コンテキストを表示 |
-| **範囲** | 一般的な設定 | プロジェクト固有のナレッジグラフ |
-
-**両方を併用できます。** CLAUDE.md は Claude に*どう*作業するかを伝えます。MeMesh は*何を*構築したかを記憶します。
-
----
-
-## 対応環境
-
-| プラットフォーム | 状態 |
-|----------------|------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅（WSL2 推奨） |
-
-**対応ツール：** Claude Code CLI · VS Code 拡張機能 · Cursor（MCP 経由） · その他 MCP 互換エディタ
-
----
-
-## アーキテクチャ
-
-MeMesh は Claude Code プラグインとしてローカルで動作し、MCP コンポーネントを内蔵しています：
-
-- **ナレッジグラフ** — FTS5 全文検索を備えた SQLite ベースのエンティティストア
-- **ベクトル埋め込み** — セマンティック類似性のための ONNX ランタイム（100% ローカルで動作）
-- **コンテンツ重複排除** — SHA-256 ハッシュで冗長な埋め込み計算をスキップ
-- **バッチ処理** — 大規模ナレッジベース向けの効率的な一括操作
-- **フックシステム** — セッション開始時、テスト失敗時、エラー発生時のプロアクティブな呼び出し
-
-すべてローカルで動作します。クラウドなし。API コールなし。データがマシンの外に出ることはありません。
-
----
-
-## ドキュメント
-
-| ドキュメント | 説明 |
-|------------|------|
-| [はじめに](docs/GETTING_STARTED.md) | ステップバイステップのセットアップガイド |
-| [ユーザーガイド](docs/USER_GUIDE.md) | 例付きの完全な使い方ガイド |
-| [コマンド](docs/COMMANDS.md) | コマンドリファレンス |
-| [アーキテクチャ](docs/ARCHITECTURE.md) | 技術的な詳細解説 |
-| [コントリビュート](CONTRIBUTING.md) | 貢献ガイドライン |
-| [開発ガイド](docs/DEVELOPMENT.md) | コントリビューター向けの開発環境構築 |
-
----
-
-## コントリビュート
-
-コントリビューションを歓迎します！[CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。
-
----
-
-## ライセンス
-
-MIT — [LICENSE](LICENSE) を参照
-
----
-
-
-
-**Claude Code で作られた、Claude Code のためのツール。**
-
-[バグ報告](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [機能リクエスト](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [ヘルプ](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.ko.md b/README.ko.md
deleted file mode 100644
index 11be0769..00000000
--- a/README.ko.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### AI 코딩 세션에도 기억이 필요합니다.
-
-MeMesh Plugin은 Claude Code에 영구적이고 검색 가능한 메모리를 제공하여, 모든 세션이 이전 세션 위에 쌓이도록 합니다.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[시작하기](#시작하기) · [작동 방식](#작동-방식) · [명령어](#명령어) · [문서](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · **한국어** · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### MeMesh 이전
-```
-Session 1: "JWT로 인증하자"
-Session 2: "왜 JWT를 선택했었지?"
-Session 3: "잠깐, 어떤 인증 라이브러리 쓰고 있었지?"
-```
-결정을 반복합니다. Claude가 컨텍스트를 잊습니다. 진행이 멈춥니다.
-
- |
-
-
-### MeMesh 이후
-```
-Session 1: "JWT로 인증하자" → 저장됨
-Session 2: buddy-remember "auth" → 즉시 회상
-Session 3: 시작 시 컨텍스트 자동 로드
-```
-모든 세션이 이전에 멈춘 곳에서 이어집니다.
-
- |
-
-
-
----
-
-## 제공하는 기능
-
-**검색 가능한 프로젝트 메모리** — "auth에 대해 뭘 결정했지?"라고 물으면 의미 기반으로 즉시 매칭된 답변을 받습니다. 키워드 검색이 아닌 *의미* 검색이며, 로컬 ONNX 임베딩으로 작동합니다.
-
-**스마트 작업 분석** — `buddy-do "add user auth"`는 단순히 실행만 하지 않습니다. 과거 세션에서 관련 컨텍스트를 가져오고, 수립된 패턴을 확인하고, 코드를 한 줄이라도 작성하기 전에 풍부한 계획을 세웁니다.
-
-**선제적 회상** — MeMesh는 세션 시작 시, 테스트 실패 시, 오류 발생 시 관련 기억을 자동으로 표시합니다. 수동 검색이 필요 없습니다.
-
-**워크플로우 자동화** — 시작 시 세션 요약. 파일 변경 추적. 커밋 전 코드 리뷰 알림. 모두 백그라운드에서 조용히 실행됩니다.
-
-**실수 학습** — 오류와 수정 사항을 기록하여 지식 베이스를 구축합니다. 같은 실수는 두 번 일어나지 않습니다.
-
----
-
-## 시작하기
-
-**필요 조건**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Claude Code를 재시작하면 끝입니다.
-
-**확인** — Claude Code에서 입력:
-
-```
-buddy-help
-```
-
-사용 가능한 명령어 목록이 표시되어야 합니다.
-
-
-소스에서 설치 (기여자용)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## 명령어
-
-| 명령어 | 기능 |
-|---------|------|
-| `buddy-do "작업"` | 전체 메모리 컨텍스트와 함께 작업 실행 |
-| `buddy-remember "주제"` | 과거 결정과 컨텍스트 검색 |
-| `buddy-help` | 사용 가능한 명령어 표시 |
-
-**실제 사용 예시:**
-
-```bash
-# 처음 접하는 코드베이스 파악하기
-buddy-do "explain this codebase"
-
-# 과거 작업의 컨텍스트로 기능 구현하기
-buddy-do "add user authentication"
-
-# 결정 이유 회상하기
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-모든 데이터는 로컬 머신에 저장되며, 자동으로 90일간 보관됩니다.
-
----
-
-## CLAUDE.md와 어떻게 다른가요?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **목적** | Claude를 위한 고정된 지시사항 | 프로젝트와 함께 성장하는 살아있는 메모리 |
-| **검색** | 수동 텍스트 검색 | 의미 기반 검색 |
-| **업데이트** | 수동 편집 | 작업하면서 결정사항을 자동 캡처 |
-| **회상** | 항상 로드됨 (길어질 수 있음) | 필요할 때 관련 컨텍스트를 표시 |
-| **범위** | 일반적인 설정 | 프로젝트별 지식 그래프 |
-
-**함께 사용하는 것입니다.** CLAUDE.md는 Claude에게 *어떻게* 작업할지 알려줍니다. MeMesh는 *무엇을* 만들었는지 기억합니다.
-
----
-
-## 플랫폼 지원
-
-| 플랫폼 | 상태 |
-|--------|------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 권장) |
-
-**호환 환경:** Claude Code CLI · VS Code Extension · Cursor (MCP 경유) · 기타 MCP 호환 에디터
-
----
-
-## 아키텍처
-
-MeMesh는 Claude Code 플러그인으로 로컬에서 실행되며, MCP 컴포넌트를 포함합니다:
-
-- **Knowledge Graph** — FTS5 전문 검색을 갖춘 SQLite 기반 엔티티 저장소
-- **Vector Embeddings** — 의미 유사도를 위한 ONNX 런타임 (100% 로컬 실행)
-- **Content Dedup** — SHA-256 해싱으로 중복 임베딩 연산 건너뛰기
-- **Batch Processing** — 대규모 지식 베이스를 위한 효율적인 일괄 처리
-- **Hook System** — 세션 시작, 테스트 실패, 오류 시 선제적 회상
-
-모든 것이 로컬에서 실행됩니다. 클라우드 없음. API 호출 없음. 데이터는 절대 머신 밖으로 나가지 않습니다.
-
----
-
-## 문서
-
-| 문서 | 설명 |
-|------|------|
-| [시작하기](docs/GETTING_STARTED.md) | 단계별 설정 가이드 |
-| [사용자 가이드](docs/USER_GUIDE.md) | 예제 포함 전체 사용 가이드 |
-| [명령어](docs/COMMANDS.md) | 전체 명령어 레퍼런스 |
-| [아키텍처](docs/ARCHITECTURE.md) | 기술 심층 분석 |
-| [기여하기](CONTRIBUTING.md) | 기여 가이드라인 |
-| [개발](docs/DEVELOPMENT.md) | 기여자를 위한 개발 환경 설정 |
-
----
-
-## 기여하기
-
-기여를 환영합니다! 시작하려면 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
-
----
-
-## 라이선스
-
-MIT — [LICENSE](LICENSE) 참조
-
----
-
-
-
-**Claude Code를 위해, Claude Code와 함께 만들었습니다.**
-
-[버그 리포트](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [기능 요청](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [도움 받기](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.md b/README.md
index 36551389..d82372b5 100644
--- a/README.md
+++ b/README.md
@@ -1,286 +1,86 @@
-
-
-
-
# MeMesh Plugin
-### Your AI coding sessions deserve memory.
-
-MeMesh Plugin gives Claude Code persistent, searchable memory — so every session builds on the last.
+Minimal persistent memory plugin for Claude Code. Remembers decisions, patterns, and context across sessions.
[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Get Started](#get-started) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](docs/USER_GUIDE.md)
-
-[繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### Before MeMesh
-```
-Session 1: "Use JWT for auth"
-Session 2: "Why did we pick JWT again?"
-Session 3: "Wait, what auth library are we using?"
-```
-You repeat decisions. Claude forgets context. Progress stalls.
-
- |
-
-
-### After MeMesh
-```
-Session 1: "Use JWT for auth" → saved
-Session 2: buddy-remember "auth" → instant recall
-Session 3: Context auto-loaded on start
-```
-Every session picks up where you left off.
-
- |
-
-
-
----
-
-## What You Get
-
-**Searchable Project Memory** — Ask "what did we decide about auth?" and get an instant, semantically-matched answer. Not keyword search — *meaning* search, powered by local ONNX embeddings.
-
-**Smart Task Analysis** — `buddy-do "add user auth"` doesn't just execute. It pulls relevant context from past sessions, checks what patterns you've established, and builds an enriched plan before writing a single line.
-
-**Proactive Recall** — MeMesh automatically surfaces relevant memories when you start a session, hit a test failure, or encounter an error. No manual searching needed.
-
-**Workflow Automation** — Session recaps on startup. File change tracking. Code review reminders before commits. All running silently in the background.
-
-**Mistake Learning** — Record errors and fixes to build a knowledge base. The same mistake doesn't happen twice.
-
----
-
-## Get Started
-
-**Prerequisites**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
+## Installation
```bash
npm install -g @pcircle/memesh
```
-Restart Claude Code. That's it.
-
-**Verify** — type in Claude Code:
-
-```
-buddy-help
-```
+## What it does
-You should see a list of available commands.
+MeMesh gives Claude Code persistent memory through 3 MCP tools, 2 hooks, and a CLI dashboard:
-
-Install from source (contributors)
+### MCP Tools
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
+| Tool | Description |
+|------|-------------|
+| `remember` | Store knowledge — entities with observations, relations, and tags |
+| `recall` | Search stored knowledge via FTS5 full-text search with optional tag filtering |
+| `forget` | Delete stored knowledge by name (cascades to observations, relations, tags) |
-
+### Hooks
----
+| Hook | Event | What |
+|------|-------|------|
+| Session Start | `SessionStart` | Auto-recalls project-specific + recent global memories |
+| Post Commit | `PostToolUse` (Bash) | Records git commits as knowledge entities |
-## Commands
+### CLI
-| Command | What it does |
+| Command | Description |
|---------|-------------|
-| `buddy-do "task"` | Execute a task with full memory context |
-| `buddy-remember "topic"` | Search past decisions and context |
-| `buddy-help` | Show available commands |
-
-**Real examples:**
+| `memesh-view` | Generate and open an interactive HTML dashboard |
```bash
-# Get oriented in a new-to-you codebase
-buddy-do "explain this codebase"
-
-# Build features with context from past work
-buddy-do "add user authentication"
-
-# Recall why decisions were made
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
+memesh-view
```
-All data stays on your machine with automatic 90-day retention.
-
----
-
-## How is this different from CLAUDE.md?
-
-| | CLAUDE.md | MeMesh Plugin |
-|---|-----------|--------|
-| **Purpose** | Static instructions for Claude | Living memory that grows with your project |
-| **Search** | Manual text search | Semantic search by meaning |
-| **Updates** | You edit manually | Auto-captures decisions as you work |
-| **Recall** | Always loaded (can get long) | Surfaces relevant context on demand |
-| **Scope** | General preferences | Project-specific knowledge graph |
-
-**They work together.** CLAUDE.md tells Claude *how* to work. MeMesh Plugin remembers *what* you've built.
-
----
-
-## Platform Support
-
-| Platform | Status |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 recommended) |
-
-**Works with:** Claude Code CLI · VS Code Extension · Cursor (via MCP) · Any MCP-compatible editor
-
----
-
-## Visual Explorer (Streamlit UI)
+
-MeMesh Plugin includes an interactive web UI for exploring your knowledge graph visually.
+## How it works
-**Dashboard** — Overview of your knowledge base with entity statistics, type distribution, tag trends, and growth over time.
-
-
-
-
-
-
-
-**Built with Claude Code, for Claude Code.**
-
-[Report Bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Request Feature](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Get Help](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
+MIT
diff --git a/README.th.md b/README.th.md
deleted file mode 100644
index aefd5242..00000000
--- a/README.th.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### เซสชันเขียนโค้ดกับ AI ของคุณสมควรมีหน่วยความจำ
-
-MeMesh Plugin มอบหน่วยความจำถาวรที่ค้นหาได้ให้ Claude Code — ทำให้ทุกเซสชันต่อยอดจากเซสชันก่อนหน้า
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[เริ่มต้นใช้งาน](#เริ่มต้นใช้งาน) · [วิธีการทำงาน](#วิธีการทำงาน) · [คำสั่ง](#คำสั่ง) · [เอกสาร](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · **ภาษาไทย** · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### ก่อนใช้ MeMesh
-```
-Session 1: "Use JWT for auth"
-Session 2: "Why did we pick JWT again?"
-Session 3: "Wait, what auth library are we using?"
-```
-คุณต้องทวนการตัดสินใจซ้ำ Claude ลืมบริบท ความคืบหน้าหยุดชะงัก
-
- |
-
-
-### หลังใช้ MeMesh
-```
-Session 1: "Use JWT for auth" → saved
-Session 2: buddy-remember "auth" → instant recall
-Session 3: Context auto-loaded on start
-```
-ทุกเซสชันเริ่มต่อจากจุดที่คุณหยุดไว้
-
- |
-
-
-
----
-
-## สิ่งที่คุณจะได้รับ
-
-**หน่วยความจำโปรเจกต์ที่ค้นหาได้** — ถามว่า "เราตัดสินใจเรื่อง auth ยังไง?" แล้วได้คำตอบทันทีที่จับคู่ตามความหมาย ไม่ใช่การค้นหาด้วยคีย์เวิร์ด — แต่เป็นการค้นหาด้วย*ความหมาย* ขับเคลื่อนด้วย ONNX embeddings บนเครื่องของคุณ
-
-**การวิเคราะห์งานอัจฉริยะ** — `buddy-do "add user auth"` ไม่ได้แค่รันคำสั่ง มันดึงบริบทที่เกี่ยวข้องจากเซสชันก่อนหน้า ตรวจสอบรูปแบบที่คุณกำหนดไว้ และสร้างแผนที่สมบูรณ์ก่อนเขียนโค้ดแม้แต่บรรทัดเดียว
-
-**การเรียกคืนเชิงรุก** — MeMesh แสดงความทรงจำที่เกี่ยวข้องโดยอัตโนมัติเมื่อคุณเริ่มเซสชัน เจอเทสต์ล้มเหลว หรือพบข้อผิดพลาด ไม่ต้องค้นหาเอง
-
-**ระบบอัตโนมัติของเวิร์กโฟลว์** — สรุปเซสชันเมื่อเริ่มงาน ติดตามการเปลี่ยนแปลงไฟล์ เตือนให้รีวิวโค้ดก่อน commit ทั้งหมดทำงานเงียบๆ ในเบื้องหลัง
-
-**เรียนรู้จากข้อผิดพลาด** — บันทึกข้อผิดพลาดและการแก้ไขเพื่อสร้างฐานความรู้ ข้อผิดพลาดเดิมจะไม่เกิดขึ้นซ้ำ
-
----
-
-## เริ่มต้นใช้งาน
-
-**สิ่งที่ต้องมี**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-รีสตาร์ท Claude Code เท่านั้นเอง
-
-**ตรวจสอบ** — พิมพ์ใน Claude Code:
-
-```
-buddy-help
-```
-
-คุณจะเห็นรายการคำสั่งที่ใช้ได้
-
-
-ติดตั้งจากซอร์สโค้ด (สำหรับผู้ร่วมพัฒนา)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## คำสั่ง
-
-| คำสั่ง | ทำอะไร |
-|---------|-------------|
-| `buddy-do "task"` | รันงานพร้อมบริบทหน่วยความจำเต็มรูปแบบ |
-| `buddy-remember "topic"` | ค้นหาการตัดสินใจและบริบทที่ผ่านมา |
-| `buddy-help` | แสดงคำสั่งที่ใช้ได้ |
-
-**ตัวอย่างจริง:**
-
-```bash
-# ทำความเข้าใจ codebase ที่ไม่คุ้นเคย
-buddy-do "explain this codebase"
-
-# สร้างฟีเจอร์พร้อมบริบทจากงานที่ผ่านมา
-buddy-do "add user authentication"
-
-# เรียกดูเหตุผลของการตัดสินใจ
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-ข้อมูลทั้งหมดอยู่บนเครื่องของคุณ พร้อมการเก็บรักษาอัตโนมัติ 90 วัน
-
----
-
-## MeMesh ต่างจาก CLAUDE.md อย่างไร?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **วัตถุประสงค์** | คำสั่งคงที่สำหรับ Claude | หน่วยความจำที่มีชีวิตซึ่งเติบโตไปกับโปรเจกต์ |
-| **การค้นหา** | ค้นหาข้อความด้วยตนเอง | ค้นหาเชิงความหมายตามความหมาย |
-| **การอัปเดต** | คุณแก้ไขเอง | บันทึกการตัดสินใจอัตโนมัติขณะทำงาน |
-| **การเรียกคืน** | โหลดทุกครั้ง (อาจยาวมาก) | แสดงบริบทที่เกี่ยวข้องตามต้องการ |
-| **ขอบเขต** | การตั้งค่าทั่วไป | กราฟความรู้เฉพาะโปรเจกต์ |
-
-**ทั้งสองทำงานร่วมกัน** CLAUDE.md บอก Claude ว่าต้องทำงาน*อย่างไร* MeMesh จำว่าคุณ*สร้างอะไร*ไปบ้าง
-
----
-
-## รองรับแพลตฟอร์ม
-
-| แพลตฟอร์ม | สถานะ |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (แนะนำ WSL2) |
-
-**ใช้ร่วมกับ:** Claude Code CLI · VS Code Extension · Cursor (ผ่าน MCP) · เอดิเตอร์ใดก็ได้ที่รองรับ MCP
-
----
-
-## สถาปัตยกรรม
-
-MeMesh ทำงานเป็นปลั๊กอิน Claude Code บนเครื่อง พร้อมคอมโพเนนต์ MCP ในตัว:
-
-- **Knowledge Graph** — ที่เก็บ entity บน SQLite พร้อมการค้นหาข้อความเต็มรูปแบบ FTS5
-- **Vector Embeddings** — ONNX runtime สำหรับความคล้ายคลึงเชิงความหมาย (ทำงานบนเครื่อง 100%)
-- **Content Dedup** — แฮช SHA-256 ข้ามการคำนวณ embedding ที่ซ้ำซ้อน
-- **Batch Processing** — การดำเนินการจำนวนมากอย่างมีประสิทธิภาพสำหรับฐานความรู้ขนาดใหญ่
-- **Hook System** — เรียกคืนเชิงรุกเมื่อเริ่มเซสชัน เทสต์ล้มเหลว และเกิดข้อผิดพลาด
-
-ทุกอย่างทำงานบนเครื่อง ไม่ใช้คลาวด์ ไม่เรียก API ข้อมูลของคุณไม่ออกจากเครื่องเด็ดขาด
-
----
-
-## เอกสาร
-
-| เอกสาร | คำอธิบาย |
-|-----|-------------|
-| [เริ่มต้นใช้งาน](docs/GETTING_STARTED.md) | คู่มือการตั้งค่าทีละขั้นตอน |
-| [คู่มือผู้ใช้](docs/USER_GUIDE.md) | คู่มือการใช้งานฉบับเต็มพร้อมตัวอย่าง |
-| [คำสั่ง](docs/COMMANDS.md) | รายการคำสั่งทั้งหมด |
-| [สถาปัตยกรรม](docs/ARCHITECTURE.md) | รายละเอียดเชิงเทคนิคเชิงลึก |
-| [ร่วมพัฒนา](CONTRIBUTING.md) | แนวทางการร่วมพัฒนา |
-| [การพัฒนา](docs/DEVELOPMENT.md) | การตั้งค่าสำหรับผู้ร่วมพัฒนา |
-
----
-
-## ร่วมพัฒนา
-
-เรายินดีต้อนรับการร่วมพัฒนา! ดู [CONTRIBUTING.md](CONTRIBUTING.md) เพื่อเริ่มต้น
-
----
-
-## สัญญาอนุญาต
-
-MIT — ดู [LICENSE](LICENSE)
-
----
-
-
-
-**สร้างด้วย Claude Code เพื่อ Claude Code**
-
-[รายงานบัก](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [ขอฟีเจอร์](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [ขอความช่วยเหลือ](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.vi.md b/README.vi.md
deleted file mode 100644
index 25cda035..00000000
--- a/README.vi.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### Các phiên lập trình AI của bạn xứng đáng có bộ nhớ.
-
-MeMesh Plugin mang đến cho Claude Code bộ nhớ bền vững, có thể tìm kiếm — để mỗi phiên làm việc đều kế thừa từ phiên trước.
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[Bắt đầu](#bắt-đầu) · [Cách hoạt động](#cách-hoạt-động) · [Lệnh](#lệnh) · [Tài liệu](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · **Tiếng Việt** · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### Trước MeMesh
-```
-Phiên 1: "Dùng JWT cho auth"
-Phiên 2: "Tại sao mình chọn JWT nhỉ?"
-Phiên 3: "Khoan, mình đang dùng thư viện auth nào?"
-```
-Bạn lặp lại các quyết định. Claude quên ngữ cảnh. Tiến độ bị đình trệ.
-
- |
-
-
-### Sau MeMesh
-```
-Phiên 1: "Dùng JWT cho auth" → đã lưu
-Phiên 2: buddy-remember "auth" → nhớ lại ngay
-Phiên 3: Ngữ cảnh tự động tải khi bắt đầu
-```
-Mỗi phiên đều tiếp nối từ nơi bạn dừng lại.
-
- |
-
-
-
----
-
-## Bạn được gì
-
-**Bộ nhớ dự án có thể tìm kiếm** — Hỏi "chúng ta đã quyết định gì về auth?" và nhận câu trả lời ngay lập tức, khớp theo ngữ nghĩa. Không phải tìm kiếm từ khóa — mà là tìm kiếm theo *ý nghĩa*, sử dụng ONNX embeddings chạy cục bộ.
-
-**Phân tích tác vụ thông minh** — `buddy-do "thêm user auth"` không chỉ đơn giản thực thi. Nó lấy ngữ cảnh liên quan từ các phiên trước, kiểm tra những mẫu thiết kế bạn đã thiết lập, và xây dựng kế hoạch chi tiết trước khi viết một dòng code nào.
-
-**Gợi nhớ chủ động** — MeMesh tự động hiển thị các ký ức liên quan khi bạn bắt đầu phiên, gặp lỗi kiểm thử, hoặc gặp lỗi. Không cần tìm kiếm thủ công.
-
-**Tự động hóa quy trình** — Tóm tắt phiên khi khởi động. Theo dõi thay đổi file. Nhắc review code trước khi commit. Tất cả chạy ngầm trong nền.
-
-**Học từ lỗi** — Ghi lại lỗi và cách sửa để xây dựng cơ sở tri thức. Cùng một lỗi không xảy ra hai lần.
-
----
-
-## Bắt đầu
-
-**Yêu cầu**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Khởi động lại Claude Code. Xong.
-
-**Kiểm tra** — gõ trong Claude Code:
-
-```
-buddy-help
-```
-
-Bạn sẽ thấy danh sách các lệnh có sẵn.
-
-
-Cài đặt từ mã nguồn (dành cho người đóng góp)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## Lệnh
-
-| Lệnh | Chức năng |
-|---------|-------------|
-| `buddy-do "tác vụ"` | Thực thi tác vụ với đầy đủ ngữ cảnh bộ nhớ |
-| `buddy-remember "chủ đề"` | Tìm kiếm các quyết định và ngữ cảnh trước đó |
-| `buddy-help` | Hiển thị các lệnh có sẵn |
-
-**Ví dụ thực tế:**
-
-```bash
-# Làm quen với một codebase mới
-buddy-do "explain this codebase"
-
-# Xây dựng tính năng với ngữ cảnh từ công việc trước
-buddy-do "add user authentication"
-
-# Nhớ lại lý do đưa ra quyết định
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-Tất cả dữ liệu nằm trên máy bạn với thời gian lưu giữ tự động 90 ngày.
-
----
-
-## Khác gì so với CLAUDE.md?
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **Mục đích** | Hướng dẫn tĩnh cho Claude | Bộ nhớ sống, phát triển cùng dự án |
-| **Tìm kiếm** | Tìm kiếm văn bản thủ công | Tìm kiếm ngữ nghĩa theo ý nghĩa |
-| **Cập nhật** | Bạn chỉnh sửa thủ công | Tự động ghi lại quyết định khi bạn làm việc |
-| **Gợi nhớ** | Luôn được tải (có thể rất dài) | Hiển thị ngữ cảnh liên quan theo yêu cầu |
-| **Phạm vi** | Tùy chọn chung | Đồ thị tri thức theo dự án |
-
-**Chúng hoạt động cùng nhau.** CLAUDE.md cho Claude biết *cách* làm việc. MeMesh ghi nhớ *những gì* bạn đã xây dựng.
-
----
-
-## Nền tảng hỗ trợ
-
-| Nền tảng | Trạng thái |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (khuyên dùng WSL2) |
-
-**Hoạt động với:** Claude Code CLI · VS Code Extension · Cursor (qua MCP) · Bất kỳ editor tương thích MCP nào
-
----
-
-## Kiến trúc
-
-MeMesh hoạt động như một plugin Claude Code chạy cục bộ, tích hợp thành phần MCP:
-
-- **Knowledge Graph** — Kho lưu trữ thực thể dựa trên SQLite với tìm kiếm toàn văn FTS5
-- **Vector Embeddings** — ONNX runtime cho tương đồng ngữ nghĩa (chạy 100% cục bộ)
-- **Content Dedup** — Băm SHA-256 bỏ qua tính toán embedding trùng lặp
-- **Batch Processing** — Xử lý hàng loạt hiệu quả cho cơ sở tri thức lớn
-- **Hook System** — Gợi nhớ chủ động khi bắt đầu phiên, lỗi kiểm thử và lỗi chung
-
-Mọi thứ chạy cục bộ. Không cloud. Không gọi API. Dữ liệu của bạn không bao giờ rời khỏi máy.
-
----
-
-## Tài liệu
-
-| Tài liệu | Mô tả |
-|-----|-------------|
-| [Bắt đầu](docs/GETTING_STARTED.md) | Hướng dẫn cài đặt từng bước |
-| [Hướng dẫn sử dụng](docs/USER_GUIDE.md) | Hướng dẫn đầy đủ với ví dụ |
-| [Lệnh](docs/COMMANDS.md) | Tham chiếu lệnh đầy đủ |
-| [Kiến trúc](docs/ARCHITECTURE.md) | Phân tích kỹ thuật chuyên sâu |
-| [Đóng góp](CONTRIBUTING.md) | Hướng dẫn đóng góp |
-| [Phát triển](docs/DEVELOPMENT.md) | Cài đặt môi trường cho người đóng góp |
-
----
-
-## Đóng góp
-
-Chúng tôi hoan nghênh đóng góp! Xem [CONTRIBUTING.md](CONTRIBUTING.md) để bắt đầu.
-
----
-
-## Giấy phép
-
-MIT — Xem [LICENSE](LICENSE)
-
----
-
-
-
-**Được xây dựng với Claude Code, cho Claude Code.**
-
-[Báo lỗi](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [Yêu cầu tính năng](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [Trợ giúp](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.zh-CN.md b/README.zh-CN.md
deleted file mode 100644
index a5a63272..00000000
--- a/README.zh-CN.md
+++ /dev/null
@@ -1,212 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### 你的 AI 编程会话值得拥有记忆。
-
-MeMesh Plugin 为 Claude Code 提供持久的、可搜索的记忆 — 让每次会话都能承接上次的成果。
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[快速开始](#快速开始) · [运作原理](#运作原理) · [命令](#命令) · [文档](docs/USER_GUIDE.md)
-
-[English](README.md) · [繁體中文](README.zh-TW.md) · **简体中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### 没有 MeMesh 之前
-```
-Session 1: "用 JWT 做认证"
-Session 2: "我们当时为什么选 JWT 来着？"
-Session 3: "等等，我们用的是什么认证库？"
-```
-你不断重复决策。Claude 忘记上下文。进度停滞。
-
- |
-
-
-### 有了 MeMesh 之后
-```
-Session 1: "用 JWT 做认证" → 已保存
-Session 2: buddy-remember "auth" → 即时回忆
-Session 3: 启动时自动加载上下文
-```
-每次会话都能从上次中断的地方继续。
-
- |
-
-
-
----
-
-## 你能获得什么
-
-**可搜索的项目记忆** — 问"我们之前怎么决定 auth 的？"就能得到即时的、语义匹配的答案。不是关键字搜索 — 是*语义*搜索，由本地 ONNX 嵌入驱动。
-
-**智能任务分析** — `buddy-do "添加用户认证"` 不只是执行。它会从过去的会话中提取相关上下文，检查你已建立的模式，并在写任何一行代码之前制定完整的计划。
-
-**主动回忆** — MeMesh 在你开始会话、遇到测试失败或出现错误时，自动浮现相关记忆。无需手动搜索。
-
-**工作流自动化** — 启动时展示会话回顾。文件变更追踪。提交前的代码审查提醒。所有这些都在后台静默运行。
-
-**错误学习** — 记录错误和修复方式，构建知识库。同样的错误不会再犯第二次。
-
----
-
-## 快速开始
-
-**前提条件**：[Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-重启 Claude Code。搞定。
-
-**验证** — 在 Claude Code 中输入：
-
-```
-buddy-help
-```
-
-你应该能看到可用命令列表。
-
-
-从源码安装（贡献者）
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## 命令
-
-| 命令 | 功能 |
-|---------|-------------|
-| `buddy-do "任务"` | 带着完整记忆上下文执行任务 |
-| `buddy-remember "主题"` | 搜索过去的决策和上下文 |
-| `buddy-help` | 显示可用命令 |
-
-**实际示例：**
-
-```bash
-# 快速了解一个陌生的代码库
-buddy-do "explain this codebase"
-
-# 带着过去工作的上下文构建功能
-buddy-do "add user authentication"
-
-# 回忆当初为什么做了那些决策
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-所有数据都保存在你的本机上，自动保留 90 天。
-
----
-
-## 这和 CLAUDE.md 有什么不同？
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **用途** | 给 Claude 的静态指令 | 随项目成长的活记忆 |
-| **搜索** | 手动文本搜索 | 基于语义的意义搜索 |
-| **更新** | 你手动编辑 | 工作时自动捕获决策 |
-| **回忆** | 始终加载（可能变得很长） | 按需浮现相关上下文 |
-| **范围** | 通用偏好设置 | 项目专属的知识图谱 |
-
-**它们协同工作。** CLAUDE.md 告诉 Claude *怎么*工作。MeMesh 记住你*做了*什么。
-
----
-
-## 平台支持
-
-| 平台 | 状态 |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅（建议使用 WSL2） |
-
-**兼容：** Claude Code CLI · VS Code 扩展 · Cursor（通过 MCP） · 任何兼容 MCP 的编辑器
-
----
-
-## 架构
-
-MeMesh 作为 Claude Code 插件在本地运行，内含 MCP 组件：
-
-- **知识图谱** — 基于 SQLite 的实体存储，支持 FTS5 全文搜索
-- **向量嵌入** — ONNX 运行时实现语义相似度（100% 本地运行）
-- **内容去重** — SHA-256 哈希跳过冗余的嵌入计算
-- **批量处理** — 高效的批量操作，适用于大型知识库
-- **Hook 系统** — 在会话开始、测试失败和错误发生时主动回忆
-
-一切都在本地运行。无需云服务。无需 API 调用。你的数据永远不会离开你的机器。
-
----
-
-## 文档
-
-| 文档 | 说明 |
-|-----|-------------|
-| [快速开始](docs/GETTING_STARTED.md) | 分步设置指南 |
-| [使用指南](docs/USER_GUIDE.md) | 完整使用指南与示例 |
-| [命令参考](docs/COMMANDS.md) | 完整命令参考 |
-| [架构说明](docs/ARCHITECTURE.md) | 技术深度解析 |
-| [贡献指南](CONTRIBUTING.md) | 贡献指南 |
-| [开发指南](docs/DEVELOPMENT.md) | 贡献者开发设置 |
-
----
-
-## 贡献
-
-欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。
-
----
-
-## 许可证
-
-MIT — 详见 [LICENSE](LICENSE)
-
----
-
-
-
-**用 Claude Code 构建，为 Claude Code 而生。**
-
-[报告 Bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [功能请求](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [获取帮助](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/README.zh-TW.md b/README.zh-TW.md
deleted file mode 100644
index 179a7bc9..00000000
--- a/README.zh-TW.md
+++ /dev/null
@@ -1,286 +0,0 @@
-
-
-
-
-# MeMesh Plugin
-
-### 你的 AI 程式開發應該有記憶。
-
-MeMesh Plugin 賦予 Claude Code 持久、可搜尋的記憶 — 讓每次對話都能延續上一次的成果。
-
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](https://www.npmjs.com/package/@pcircle/memesh)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://modelcontextprotocol.io)
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-[開始使用](#開始使用) · [運作原理](#運作原理) · [指令](#指令) · [文件](docs/USER_GUIDE.md)
-
-[English](README.md) · **繁體中文** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Tiếng Việt](README.vi.md) · [ภาษาไทย](README.th.md) · [Bahasa Indonesia](README.id.md)
-
-
-
-|
-
-### 沒有 MeMesh
-```
-Session 1: "用 JWT 做 auth"
-Session 2: "我們當初為什麼選 JWT？"
-Session 3: "等等，我們用的是哪個 auth 函式庫？"
-```
-你不斷重複決策。Claude 忘了脈絡。進度停滯。
-
- |
-
-
-### 有了 MeMesh
-```
-Session 1: "用 JWT 做 auth" → 已儲存
-Session 2: buddy-remember "auth" → 即時回憶
-Session 3: 啟動時自動載入脈絡
-```
-每次 session 都能接續上次的進度。
-
- |
-
-
-
----
-
-## 你能獲得什麼
-
-**可搜尋的專案記憶** — 問「我們之前怎麼決定 auth 的？」就能即時得到語意匹配的答案。不是關鍵字搜尋 — 而是*語意*搜尋，由本地 ONNX embeddings 驅動。
-
-**智慧任務分析** — `buddy-do "加上使用者認證"` 不只是執行。它會從過去的 session 中提取相關脈絡、檢查你已建立的模式，在寫下任何一行程式碼之前先建構完整的計畫。
-
-**主動回憶** — MeMesh 在你開始 session、遇到測試失敗或碰到錯誤時，自動浮現相關記憶。不需要手動搜尋。
-
-**工作流自動化** — 啟動時顯示 session 回顧、追蹤檔案變更、commit 前提醒 code review。全部在背景靜靜運行。
-
-**錯誤學習** — 記錄錯誤和修復方式來建立知識庫。同樣的錯誤不會再犯第二次。
-
----
-
-## 開始使用
-
-**前置需求**：[Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-重啟 Claude Code，完成。
-
-**驗證** — 在 Claude Code 中輸入：
-
-```
-buddy-help
-```
-
-你應該會看到可用指令的列表。
-
-
-從原始碼安裝（貢獻者）
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-
-
----
-
-## 指令
-
-| 指令 | 功能說明 |
-|------|----------|
-| `buddy-do "任務"` | 帶著完整記憶脈絡執行任務 |
-| `buddy-remember "主題"` | 搜尋過去的決策和脈絡 |
-| `buddy-help` | 顯示可用指令 |
-
-**實際範例：**
-
-```bash
-# 快速了解一個不熟悉的 codebase
-buddy-do "explain this codebase"
-
-# 帶著過去工作的脈絡來開發功能
-buddy-do "add user authentication"
-
-# 回顧決策的原因
-buddy-remember "API design decisions"
-buddy-remember "why we chose PostgreSQL"
-```
-
-所有資料都存在你的電腦上，統一採用 90 天自動保留機制。
-
----
-
-## 這跟 CLAUDE.md 有什麼不同？
-
-| | CLAUDE.md | MeMesh |
-|---|-----------|--------|
-| **用途** | 給 Claude 的靜態指令 | 隨專案成長的活記憶 |
-| **搜尋** | 手動文字搜尋 | 依語意搜尋 |
-| **更新** | 你手動編輯 | 工作時自動捕捉決策 |
-| **回憶** | 永遠載入（可能變很長） | 按需浮現相關脈絡 |
-| **範圍** | 一般偏好設定 | 專案專屬的知識圖譜 |
-
-**它們可以搭配使用。** CLAUDE.md 告訴 Claude *如何*工作。MeMesh 記住你*建了什麼*。
-
----
-
-## 平台支援
-
-| 平台 | 狀態 |
-|------|------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (建議 WSL2) |
-
-**可搭配使用：** Claude Code CLI · VS Code Extension · Cursor (透過 MCP) · 任何相容 MCP 的編輯器
-
----
-
-## 視覺化瀏覽器（Streamlit UI）
-
-MeMesh 內建互動式 Web UI，讓你直觀地探索知識圖譜。
-
-**Dashboard** — 知識庫總覽，包含實體統計、類型分佈、標籤趨勢與成長曲線。
-
-
-
-
-
-
-
-**用 Claude Code 打造，為 Claude Code 而生。**
-
-[回報 Bug](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=bug&template=bug_report.yml) · [功能請求](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions) · [取得協助](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
-
-
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index afafb593..f81184d0 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,679 +1,183 @@
# MeMesh Plugin Architecture
-**Status**: Active
+**Version**: 3.0.0
---
## Overview
-MeMesh Plugin is a Model Context Protocol (MCP) server that enhances Claude Code with persistent memory, context-aware task execution, and knowledge management capabilities. It follows a layered architecture designed for extensibility, performance, and reliability.
-
-## Architecture Diagram
+MeMesh is a minimal persistent memory plugin for Claude Code. It provides 3 MCP tools (`remember`, `recall`, `forget`) and 2 hooks (session start, post commit), backed by SQLite with FTS5 full-text search.
```
-┌─────────────────────────────────────────────────────────────┐
-│ Claude Code CLI │
-└────────────────────────┬────────────────────────────────────┘
- │ MCP Protocol (JSON-RPC over stdio)
-┌────────────────────────┴────────────────────────────────────┐
-│ MCP Server Layer (src/mcp/) │
-│ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ ToolHandlers │ │ Resources │ │ Prompts │ │
-│ │ (facade) │ └──────┬───────┘ └──────┬───────┘ │
-│ │ ├ MemoryTool │ │ │ │
-│ │ ├ SystemTool │ │ │ │
-│ │ └ HookTool │ │ │ │
-│ └────────┬─────────┘ │ │ │
-│ ┌────────┴─────────┐ │ │ │
-│ │StdinBufferManager│ │ │ │
-│ └──────────────────┘ │ │ │
-└─────────┼─────────────────────┼──────────────────┼──────────┘
- │ │ │
-┌─────────┴─────────────────────┴──────────────────┴──────────┐
-│ Core Business Logic │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Memory System (src/memory/) │ │
-│ │ ├─ UnifiedMemoryStore │ │
-│ │ ├─ MemorySearchEngine (search/filter/rank/dedup) │ │
-│ │ ├─ ProjectAutoTracker │ │
-│ │ ├─ ProactiveRecaller (session/test/error triggers) │ │
-│ │ └─ MistakePatternEngine │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Knowledge Graph (src/knowledge-graph/) │ │
-│ │ ├─ KGSearchEngine (FTS5 + semantic + hybrid search) │ │
-│ │ ├─ ContentHasher (SHA-256 embedding dedup) │ │
-│ │ ├─ createEntitiesBatch() (batch transactions) │ │
-│ │ └─ Entity Relationship Management │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Embeddings (src/embeddings/) │ │
-│ │ ├─ EmbeddingService (LRU cache, batch encode) │ │
-│ │ ├─ VectorSearchAdapter (Strategy interface) │ │
-│ │ │ ├─ SqliteVecAdapter (sqlite-vec 0.1.3) │ │
-│ │ │ └─ InMemoryVectorAdapter (pure TS, testing) │ │
-│ │ └─ ModelManager (Xenova/all-MiniLM-L6-v2, 384-dim) │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Core (src/core/) │ │
-│ │ ├─ HookIntegration → GitCommandParser │ │
-│ │ ├─ CheckpointDetector │ │
-│ │ └─ HealthCheck, ResourceMonitor │ │
-│ └──────────────────────────────────────────────────────┘ │
-└──────────────────────────┬───────────────────────────────────┘
- │
-┌──────────────────────────┴───────────────────────────────────┐
-│ Data Persistence Layer │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Database (src/db/) │ │
-│ │ ├─ Connection Pool (better-sqlite3) │ │
-│ │ ├─ Migrations & Schema │ │
-│ │ └─ FTS5 + Vector Extensions │ │
-│ └──────────────────────────────────────────────────────┘ │
-└──────────────────────────┬───────────────────────────────────┘
- │ SQLite (read-only)
-┌──────────────────────────┴───────────────────────────────────┐
-│ Visual Explorer (streamlit/) │
-│ ├─ Dashboard: stats, charts (Plotly), entity growth │
-│ ├─ KG Explorer: interactive graph (streamlit-agraph/vis.js) │
-│ ├─ FTS5 full-text search + type/tag/date filters │
-│ └─ Relation backfill script (3-layer strategy) │
-└──────────────────────────────────────────────────────────────┘
+Claude Code CLI <--stdio--> MCP Server <--> KnowledgeGraph <--> SQLite (FTS5)
```
---
-## Layer Details
-
-### 1. MCP Server Layer (`src/mcp/`)
-
-**Purpose**: Implements the Model Context Protocol specification to communicate with Claude Code.
-
-**Components**:
-- **server.ts**: MCP server initialization and lifecycle management
-- **server-bootstrap.ts**: Entry point for npm binary; handles CLI vs MCP mode detection, daemon/proxy bootstrap, global `unhandledRejection`/`uncaughtException` handlers, and background ONNX model preloading in daemon mode
-- **StdinBufferManager.ts**: Pauses and buffers stdin during bootstrap to prevent "Method not found" errors when Claude Code sends `initialize` before the transport is connected
-- **ToolHandlers.ts**: Thin facade (~137 lines) that dispatches to focused sub-handlers:
- - **MemoryToolHandler.ts**: Entity/relation/recall/mistake operations
- - **SystemToolHandler.ts**: Skills, uninstall, test generation
- - **HookToolHandler.ts**: Hook tool-use tracking
-- **ToolRouter.ts**: Routes incoming MCP tool calls to ToolHandlers
-- **BuddyCommands.ts**: Command definitions and help text (no longer handles routing)
-- **ToolDefinitions.ts**: MCP tool schema definitions
-- **validation.ts**: Input validation using Zod schemas
-- **ProgressReporter.ts**: Real-time progress updates to Claude Code
-
-**Communication**: JSON-RPC 2.0 over stdio
-
----
-
-### 2. Memory System (`src/memory/`)
-
-**Purpose**: Persistent, context-aware memory management for Claude Code sessions.
-
-**Components**:
-
-#### UnifiedMemoryStore
-- Central memory management interface
-- CRUD operations for memories
-- Semantic search using embeddings
-- FTS5 full-text search integration
-
-#### MemorySearchEngine
-- Search logic extracted from UnifiedMemoryStore
-- Content-based query filtering (substring match)
-- Search filter application (time range, importance, type, limit)
-- Result deduplication by content hash
-- Relevance ranking (multi-factor scoring: exact match, tag match, TF, recency)
-
-#### ProjectAutoTracker
-- Automatic tracking of project context
-- File change detection via chokidar
-- Git integration for tracking commits
-
-#### ProactiveRecaller
-- Automatically surfaces relevant memories based on trigger context
-- Three triggers: `session-start` (hook output injection, top 5, >0.5 similarity), `test-failure` (top 3, >0.6), `error-detection` (top 3, >0.6)
-- Builds optimized search queries per trigger type (strips conventional commit prefixes, extracts test names, isolates first error line)
-- Session-start: integrated into `scripts/hooks/session-start.js` via FTS5 query
-- Test/error: integrated into `scripts/hooks/post-tool-use.js` → writes `proactive-recall.json` → `HookToolHandler` reads and appends to MCP response
-
-#### MistakePatternEngine
-- Learns from user corrections
-- Detects recurring mistakes
-- Suggests improvements
-
-**Data Flow**:
-```
-User Input -> Memory Ingestion -> Vector Embedding -> SQLite Storage
- |
-User Query <- Similarity Search <- Vector Search + FTS5 Search
-```
-
----
-
-### 3. Knowledge Graph (`src/knowledge-graph/`)
-
-**Purpose**: Structured knowledge representation with relationships and semantic search.
-
-**Components**:
-
-#### KnowledgeGraph (`index.ts`)
-- Entity and relationship CRUD
-- Uses injected `VectorSearchAdapter` instance (via constructor) instead of static VectorExtension
-- `createEntitiesBatch()`: Wraps all entity creations in a single SQLite transaction for significantly better write performance; individual failures are caught without aborting the batch
-
-#### ContentHasher (`ContentHasher.ts`)
-- SHA-256 hash (truncated to 16 hex chars) of entity name + observations
-- Used by `generateEmbeddingAsync` and `generateBatchEmbeddingsAsync` to skip ONNX inference when content unchanged
-- Hash stored in `embedding_hashes` side table (vec0 virtual tables don't support ALTER TABLE)
-- Cleaned up on entity deletion
-
-#### KGSearchEngine (`KGSearchEngine.ts`)
-- Extracted from KnowledgeGraph to separate search concerns from CRUD
-- **FTS5 Full-Text Search**: Fast keyword-based search
-- **Semantic Search**: Vector similarity via injected VectorSearchAdapter
-- **Hybrid Search**: Combines FTS5 and vector results for optimal recall
-- Receives dependencies via constructor to avoid circular imports
-
-**Database Schema**:
-```sql
-entities (id, type, content, metadata, embedding[384])
-relationships (source_id, target_id, type, metadata)
-fts_entities (content) -- FTS5 virtual table
-embedding_hashes (entity_name PK, hash) -- Content hash for embedding dedup
-```
-
----
-
-### 4. Embeddings Layer (`src/embeddings/`)
-
-**Purpose**: Convert text to vector representations for semantic search.
-
-**Model**: `Xenova/all-MiniLM-L6-v2` (384 dimensions)
-- Small footprint (~25 MB)
-- Fast inference via ONNX runtime
-- Good quality for code/technical text
-
-**Components**:
-
-#### ModelManager.ts
-- Model download and validation
-- Cross-platform model directory resolution
-- Environment variable overrides (`MEMESH_MODEL_DIR`, `MEMESH_DATA_DIR`)
-
-#### EmbeddingService.ts
-- Batch embedding generation via `encodeBatch()` (parallel chunks of 10)
-- **LRU cache**: 500-entry cache for text embeddings; cache hits resolve nearly instantly
-- Cosine similarity calculation
-- Lazy-loading singleton (`LazyEmbeddingService`) for efficient resource management
-- ONNX model preloading in daemon mode eliminates 10-20s cold start
-
-#### VectorSearchAdapter.ts (Strategy Pattern Interface)
-- Decouples vector search from specific implementations
-- Defines operations: `loadExtension`, `createVectorTable`, `insertEmbedding`, `deleteEmbedding`, `knnSearch`, `getEmbedding`, `hasEmbedding`, `getEmbeddingCount`
-
-#### SqliteVecAdapter.ts
-- Concrete `VectorSearchAdapter` implementation using sqlite-vec
-- sqlite-vec pinned to v0.1.3 (stable)
-- Handles extension loading, virtual table creation, KNN search
-
-#### InMemoryVectorAdapter.ts
-- Pure TypeScript implementation (no native dependencies)
-- Uses in-memory Map + brute-force cosine similarity
-- Enables tests without native module compilation
-
----
-
-### 5. Core Layer (`src/core/`)
-
-**Purpose**: Shared business logic components.
+## Modules
-**Components**:
+### db.ts -- Database Layer
-#### HookIntegration.ts
-- Bridges Claude Code hooks with the checkpoint detection system
-- Monitors Write, Edit, Bash tool execution
-- Delegates git command detection to **GitCommandParser**
+Manages the SQLite connection lifecycle and schema initialization.
-#### GitCommandParser.ts
-- Extracted from HookIntegration for reusability
-- Static methods for git command classification (`isGitAdd`, `isGitCommit`, `extractCommitMessage`)
-- Test file/command detection (`isTestFile`, `isTestCommand`)
+- `openDatabase(path?)` -- Opens (or reuses) a SQLite connection
+- `closeDatabase()` -- Closes the connection
+- `getDatabase()` -- Returns the active connection (throws if not opened)
+- Schema: Creates tables (`entities`, `observations`, `relations`, `tags`) and FTS5 virtual table (`entities_fts`)
+- Pragmas: WAL journal mode, foreign keys enabled
-#### CheckpointDetector.ts
-- Detects workflow checkpoints from tool execution patterns
-- Checkpoint types: `code-written`, `test-complete`, `commit-ready`, `committed`
+Default database path: `~/.memesh/knowledge-graph.db` (overridable via `MEMESH_DB_PATH`).
-#### HealthCheck.ts / ResourceMonitor.ts
-- System health monitoring and resource usage tracking
+### knowledge-graph.ts -- Knowledge Graph
----
+CRUD operations and full-text search over the entity graph.
-### 6. Database Layer (`src/db/`)
+**Entity operations**:
+- `createEntity(name, type, opts?)` -- Insert or ignore, add observations/tags, rebuild FTS index
+- `createEntitiesBatch(entities[])` -- Wraps multiple creates in a single SQLite transaction
+- `getEntity(name)` -- Full entity with observations, tags, and relations
+- `deleteEntity(name)` -- Cascading delete (observations, relations, tags, FTS entry)
-**Purpose**: Persistent storage with connection pooling and migrations.
+**Relation operations**:
+- `createRelation(from, to, type, metadata?)` -- Insert or ignore
+- `getRelations(entityName)` -- All outgoing relations for an entity
-**Technology**: better-sqlite3 (synchronous SQLite)
+**Search**:
+- `search(query?, opts?)` -- FTS5 MATCH query with optional tag filtering
+- `listRecent(limit?)` -- Most recent entities by ID
-**Features**:
-- Connection pooling for concurrent access
-- Migration system for schema evolution
-- FTS5 extension for full-text search
-- sqlite-vec extension for vector operations
+FTS5 is configured as a contentless virtual table (`content=''`). The `rebuildFts()` method handles explicit insert/delete operations required by contentless FTS5.
-**Key Tables**:
-- `memories`: Core memory storage
-- `entities`: Knowledge graph entities
-- `tags`: Memory categorization
-- `sessions`: Session tracking
-- `embeddings`: Vector embeddings
+### mcp/server.ts -- MCP Server
----
+Entry point. Creates the MCP server with stdio transport, registers tool handlers, opens the database on startup.
-### 7. Integration Layer (`src/integrations/`)
+### mcp/tools.ts -- Tool Handlers
-**Purpose**: External system integrations and session management.
+Defines 3 tools with Zod validation schemas and handler functions:
-**Components**:
-- **session-memory/**: Claude Code session integration
- - SessionMemoryParser: Parse session transcripts
- - SessionMemoryIngester: Import session data
- - SessionContextInjector: Inject context into new sessions
+| Tool | Schema | Handler |
+|------|--------|---------|
+| `remember` | RememberSchema | Creates entity, adds observations/tags/relations |
+| `recall` | RecallSchema | Searches via FTS5, returns matching entities |
+| `forget` | ForgetSchema | Deletes entity by name |
----
+The `handleTool(name, args)` dispatcher validates input via Zod, then delegates to the appropriate handler.
-### 8. UI Layer (`src/ui/`)
+### cli/view.ts -- CLI Dashboard
-**Purpose**: Rich terminal UI for progress indication and data visualization.
+Generates a self-contained HTML dashboard for visualizing the knowledge graph.
-**Components**:
-- **ProgressRenderer.ts**: Real-time progress bars
-- **ResponseFormatter.ts**: Formatted output for buddy commands
-- **design-tokens.ts**: Color palette and typography
-- **accessibility.ts**: WCAG AA compliance, screen reader support
+- `memesh-view` CLI command (registered in `package.json` bin)
+- Reads all entities, observations, relations, and tags from the database
+- Produces a single HTML file with embedded D3.js force-directed graph, searchable entity table, and statistics
+- Opens the generated file in the default browser
---
-### 9. Visual Explorer (`streamlit/`)
-
-**Purpose**: Interactive web UI for exploring and visualizing the knowledge graph.
-
-**Components**:
-- **app.py**: Entry point, page routing, sidebar navigation with SVG logo
-- **db.py**: SQLite query layer — search, graph data, CRUD, FTS5 support
-- **path_resolver.py**: Auto-detects database at `~/.memesh/` or legacy `~/.claude-code-buddy/`
-- **views/dashboard.py**: Statistics cards, entity type pie chart, tag bar chart, growth line chart, recent entities table (Plotly)
-- **views/explorer.py**: Interactive graph visualization (`streamlit-agraph` / vis.js), color-coded entity types and relation edges, physics-based layout
-- **backfill_relations.py**: CLI script to generate relations for existing entities (3 layers: topic clustering, cross-type semantic, tag similarity)
-
-**Tech Stack**: Streamlit, streamlit-agraph, Plotly, Pandas
-
-**Data Access**: Read-only SQLite connection to the same `knowledge-graph.db` used by the MCP server.
-
----
-
-### 10. Utilities
-
-#### Config (`src/config/`)
-- Environment variable management
-- Model configuration
-- Database configuration
-
-#### Errors (`src/errors/`)
-- Custom error types
-- Error classification
-- Sanitization for telemetry
-
-#### Types (`src/types/`)
-- TypeScript type definitions
-- Shared interfaces
-
-#### Utils (`src/utils/`)
-- Logger (winston)
-- Rate limiter
-- LRU cache utilities
-- Validation helpers
-
----
-
-## Data Flow Examples
-
-### 1. Memory Storage Flow
-
-```
-buddy-do "implement auth"
- |
-ToolHandlers facade -> MemoryToolHandler
- |
-UnifiedMemoryStore.create()
- |
-Generate embedding (384-dim vector, LRU cache check)
- |
-Store in SQLite (memories + embeddings tables)
- |
-Index in FTS5
- |
-Auto-tag (category detection)
- |
-Return success to Claude Code
-```
-
-### 2. Memory Retrieval Flow
+## Data Flow
-```
-buddy-remember "auth"
- |
-ToolHandlers facade -> MemoryToolHandler
- |
-UnifiedMemoryStore.search() -> MemorySearchEngine
- |
-Parallel search:
- |- FTS5 keyword search
- |- Vector similarity search (cosine)
- |
-Merge, deduplicate, and rank results
- |
-Format response (ResponseFormatter)
- |
-Return to Claude Code
-```
-
-### 3. Knowledge Graph Batch Creation
+### Store knowledge (remember)
```
-memesh-create-entities [{...}, {...}, ...]
- |
-ToolHandlers facade -> MemoryToolHandler
- |
-KnowledgeGraph.createEntitiesBatch()
- |
-Single SQLite transaction wrapping N entity inserts
- |
-Per-entity: validate -> insert -> FTS5 index (embedding skipped)
- |
-After transaction: hash-dedup check -> encodeBatch() -> bulk insert embeddings
- |
-Return per-entity success/failure results
+Tool call: remember({name, type, observations, tags, relations})
+ -> Zod validation (RememberSchema)
+ -> KnowledgeGraph.createEntity(name, type, {observations, tags})
+ -> INSERT OR IGNORE into entities
+ -> INSERT observations
+ -> Rebuild FTS5 index
+ -> INSERT tags
+ -> KnowledgeGraph.createRelation() for each relation
+ -> Return {stored: true, entityId, ...}
```
----
-
-## Performance Characteristics
-
-| Operation | Typical Latency | Notes |
-|-----------|----------------|-------|
-| Memory write | < 10ms | Including embedding generation |
-| FTS5 search | < 5ms | Scales with corpus size |
-| Vector search | < 20ms | 384-dim cosine similarity |
-| Hybrid search | < 25ms | FTS5 + vector combined |
-| Embedding generation | ~50ms | First call; cached hits < 1ms |
-| Embedding batch (10) | ~100ms | Parallel chunks of 10 |
-| Batch entity creation | ~N*5ms | Single transaction, amortized |
-
-**Performance optimizations (v2.9.2+)**:
-- **Embedding LRU cache**: 500-entry cache eliminates redundant ONNX inference for repeated text
-- **Batch transactions**: `createEntitiesBatch()` uses a single SQLite transaction instead of N separate ones
-- **ONNX preloading**: Daemon mode preloads the embedding model in the background, eliminating 10-20s cold start on first semantic search
-- **encodeBatch parallelization**: Texts are encoded in parallel chunks of 10 for improved throughput
-- **Content hash dedup**: SHA-256 hash check skips ONNX inference when entity content unchanged (embedding_hashes table)
-- **Batch embedding**: `createEntitiesBatch` uses `encodeBatch()` instead of N individual `encode()` calls
-
----
-
-## Security & Privacy
-
-1. **Local-First Architecture**: All data stored locally in `~/.memesh/`
-2. **No External Calls**: Except configured AI providers (Anthropic)
-3. **SQL Injection Prevention**: Parameterized queries only
-4. **Input Validation**: Zod schemas for all user input
-5. **Path Traversal Protection**: Validated file paths
-6. **Screen Reader Support**: WCAG AA compliant UI
-
----
-
-## Extension Points
-
-### Adding New MCP Tools
-
-1. Define tool schema in `ToolDefinitions.ts`
-2. Implement handler in the appropriate sub-handler (`MemoryToolHandler.ts`, `SystemToolHandler.ts`, or `HookToolHandler.ts`)
-3. Register dispatch in `ToolHandlers.ts` facade
-4. Add validation schema
-5. Update documentation
-
-### Adding New Memory Types
-
-1. Create new table in migration
-2. Extend UnifiedMemoryStore interface
-3. Implement CRUD operations
-4. Add embedding support if needed
-
-### Adding New Vector Search Backends
+### Search knowledge (recall)
-1. Implement `VectorSearchAdapter` interface
-2. Handle extension loading, table creation, CRUD, and KNN search
-3. Inject into KnowledgeGraph constructor
-
-### Adding New Integrations
-
-1. Create new directory in `src/integrations/`
-2. Implement integration interface
-3. Add configuration
-4. Register with core system
-
----
-
-## Deployment Modes
-
-MeMesh supports three deployment modes to accommodate different environments:
-
-### 1. Standard Mode (Full Functionality)
-
-**When**: better-sqlite3 is available
-
-**Features**:
-- Full local Knowledge Graph with SQLite
-- All memory tools (buddy-do, buddy-remember, memesh-create-entities)
-- Vector embeddings and semantic search
-- FTS5 full-text search
-
-**Architecture**:
```
-Claude Code -stdio-> MCP Server
- |
- v
- KnowledgeGraph
- (SQLite+Vec)
-```
-
-**Use Cases**:
-- Claude Code CLI (recommended)
-- Claude Code VS Code Extension
-- Cursor (via MCP)
-- Local development
-
----
-
-### 2. Cloud-Only Mode (Partial Functionality)
-
-**When**: better-sqlite3 unavailable + MEMESH_API_KEY is configured
-
-**Features**:
-- MCP server starts successfully
-- Basic commands (buddy-help, memesh-generate-tests)
-- Local memory tools disabled (buddy-do, buddy-remember, memesh-create-entities, memesh-hook-tool-use, memesh-record-mistake, memesh-metrics)
-
-**Error Messages**:
+Tool call: recall({query, tag, limit})
+ -> Zod validation (RecallSchema)
+ -> KnowledgeGraph.search(query, {tag, limit})
+ -> FTS5 MATCH query against entities_fts
+ -> JOIN to entities table (contentless FTS5)
+ -> For each match: getEntity() to load full data
+ -> Filter by tag if specified
+ -> Return Entity[]
```
-Tool 'buddy-remember' is not available in cloud-only mode.
-
-This MCP server is running without local SQLite storage (better-sqlite3 unavailable).
-To use local memory tools:
-1. Install better-sqlite3: npm install better-sqlite3
-2. Restart the MCP server
-
-Local SQLite storage is required for memory features.
-```
+### Delete knowledge (forget)
-**Architecture**:
```
-Claude Code -stdio-> MCP Server (Cloud-Only)
- |
- v
- Basic Tools Only
- (no local storage)
+Tool call: forget({name})
+ -> Zod validation (ForgetSchema)
+ -> KnowledgeGraph.deleteEntity(name)
+ -> Delete FTS5 entry (contentless delete syntax)
+ -> DELETE FROM entities (CASCADE handles children)
+ -> Return {deleted: true/false}
```
-**Use Cases**:
-- Claude Desktop Cowork (sandbox environment)
-- Environments where native modules cannot compile
-- Read-only filesystems
-- Cloud-first workflows (future)
-
-**Limitations**:
-- No local Knowledge Graph
-- No vector embeddings
-- No FTS5 search
-- Memory tools return friendly errors
-
-**Why Cloud-Only Mode Exists**:
-
-Claude Desktop Cowork runs plugins in a restricted sandbox:
-1. **Read-only filesystem** - Cannot write to plugin directories
-2. **Blocked node-gyp compilation** - HTTP 403 when downloading Node.js headers
-3. **No prebuilt binaries** - better-sqlite3, onnxruntime-node, sqlite-vec don't ship ARM64 Linux binaries
-4. **Ephemeral storage** - `~/.memesh/` directory is session-scoped
-
-Cloud-only mode allows the MCP server to start successfully and provide cloud sync functionality while gracefully degrading memory-dependent features.
-
---
-### 3. Error Mode (Cannot Start)
-
-**When**: Both better-sqlite3 unavailable AND no MEMESH_API_KEY
+## Database Schema
-**Behavior**:
-```
-ConfigurationError: Cannot start MCP server without local SQLite or cloud configuration.
+```sql
+-- Core tables
+entities (id PK, name UNIQUE, type, created_at, metadata JSON)
+observations (id PK, entity_id FK, content, created_at)
+relations (id PK, from_entity_id FK, to_entity_id FK, relation_type, metadata JSON, UNIQUE constraint)
+tags (id PK, entity_id FK, tag)
-Please choose one of the following:
-1. Install better-sqlite3: npm install better-sqlite3
-2. Configure cloud access: export MEMESH_API_KEY="your-key"
-3. Use global installation: npm install -g @pcircle/memesh
+-- Indexes
+idx_tags_entity (entity_id)
+idx_tags_tag (tag)
+idx_observations_entity (entity_id)
+idx_relations_from (from_entity_id)
+idx_relations_to (to_entity_id)
-For detailed troubleshooting, see: docs/TROUBLESHOOTING.md
+-- FTS5 virtual table (contentless)
+entities_fts USING fts5(name, observations, content='', tokenize='unicode61 remove_diacritics 1')
```
-**Use Cases**: Configuration error, should not occur in normal usage
+Foreign key cascades: deleting an entity automatically deletes its observations, relations, and tags.
---
-### Mode Detection Logic
-
-**Implementation** (`src/mcp/ServerInitializer.ts`):
-
-```typescript
-const sqliteAvailability = await checkBetterSqlite3Availability();
-const cloudEnabled = isCloudEnabled();
-
-if (sqliteAvailability.available) {
- // Standard mode: Use local SQLite
- knowledgeGraph = KnowledgeGraph.createSync();
- projectMemoryManager = new ProjectMemoryManager(knowledgeGraph);
- cloudOnlyMode = false;
-} else if (cloudEnabled) {
- // Cloud-only mode: Degrade gracefully
- logger.warn('[ServerInitializer] Running in cloud-only mode');
- knowledgeGraph = undefined;
- projectMemoryManager = undefined;
- cloudOnlyMode = true;
-} else {
- // Error mode: Cannot start
- throw new ConfigurationError('Cannot start MCP server...');
-}
-```
-
-**Availability Check**:
-```typescript
-async function checkBetterSqlite3Availability(): Promise {
- try {
- await import('better-sqlite3');
- return { available: true };
- } catch (error) {
- return {
- available: false,
- reason: 'better-sqlite3 module not available',
- error: error instanceof Error ? error.message : String(error),
- };
- }
-}
-```
+## Hook Architecture
----
+Hooks are defined in `hooks/hooks.json` and executed by Claude Code at specific lifecycle events.
-### Future: Cloud-First Memory Architecture
+### Session Start (`scripts/hooks/session-start.js`)
-**Goal**: Full Claude Desktop Cowork support through cloud-first architecture
+- **Trigger**: `SessionStart` event (every new Claude Code session)
+- **Matcher**: `*` (all sessions)
+- **Behavior**: Opens the database, queries recent entities tagged with the current project, outputs a summary for Claude to use as context
-**Planned Implementation**:
-1. Cloud API endpoints for KG operations (create, recall, search)
-2. Memory tools proxy to cloud in cloud-only mode
-3. Shared KG accessible from any client
-4. No local persistence needed (cloud as source of truth)
+### Post Commit (`scripts/hooks/post-commit.js`)
-**Timeline**: Long-term (no ETA)
-
-**Related Issues**: #73, #76, #77
-
-See [docs/COWORK_SUPPORT.md](./COWORK_SUPPORT.md) for detailed Cowork support documentation.
-
----
-
-## Testing Strategy
-
-- **Unit Tests**: `vitest` for individual components
-- **Integration Tests**: End-to-end memory flows
-- **E2E Tests**: Full MCP protocol testing
-- **Installation Tests**: Verify npm package installation
-
-**Coverage Target**: >= 80% for critical paths
+- **Trigger**: `PostToolUse` event on `Bash` tool
+- **Matcher**: `Bash` (filters for git commit commands)
+- **Behavior**: Detects git commit messages from tool output, creates a `commit` entity with the commit message as an observation, tags with the project name
---
-## Deployment
-
-**Distribution**: npm package `@pcircle/memesh`
+## Testing
-**Installation**:
-```bash
-npm install -g @pcircle/memesh
-```
-
-**Binary**: `dist/mcp/server-bootstrap.js` (executable)
-
-**Claude Code Integration**: MCP server auto-managed via the plugin's `.mcp.json` (no manual configuration of `~/.claude/mcp_settings.json` needed)
-
----
+7 test files, 73 tests total:
-## Future Architecture Considerations
+| File | Tests | What it covers |
+|------|-------|---------------|
+| `tests/db.test.ts` | 10 | Database lifecycle, schema, FTS5 setup |
+| `tests/knowledge-graph.test.ts` | 18 | Entity CRUD, relations, search, batch ops |
+| `tests/tools.test.ts` | 15 | Tool validation, handler behavior, dispatcher |
+| `tests/installation.test.ts` | 7 | Package structure, required files exist |
+| `tests/hooks/session-start.test.ts` | 6 | Session start hook behavior |
+| `tests/hooks/post-commit.test.ts` | 7 | Post commit hook behavior |
+| `tests/cli/view.test.ts` | 10 | CLI dashboard generator, XSS prevention |
-- **Multi-Model Support**: Pluggable AI providers
-- **Distributed Memory**: Sync across devices
-- **Plugin System**: User-defined extensions
-- **Web Dashboard**: Browser-based memory management
+Framework: vitest (forks pool mode to avoid SIGSEGV with native modules).
---
## References
-- [Model Context Protocol Specification](https://modelcontextprotocol.io)
-- [MeMesh User Guide](./USER_GUIDE.md)
- [API Reference](./api/API_REFERENCE.md)
-- [Contributing Guide](./CONTRIBUTING.md)
-
----
-
-**Maintained by**: PCIRCLE-AI
-**License**: MIT
+- [Model Context Protocol](https://modelcontextprotocol.io)
diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md
deleted file mode 100644
index f970c079..00000000
--- a/docs/BEST_PRACTICES.md
+++ /dev/null
@@ -1,704 +0,0 @@
-# Best Practices
-## Effective Workflows for MeMesh Plugin
-
-This guide provides proven workflows and best practices for using MeMesh effectively in your daily development work.
-
----
-
-## Table of Contents
-
-1. [Core Principles](#core-principles)
-2. [Memory Management](#memory-management)
-3. [Effective Task Descriptions](#effective-task-descriptions)
-4. [Workflow Patterns](#workflow-patterns)
-5. [Team Collaboration](#team-collaboration)
-6. [Performance Optimization](#performance-optimization)
-7. [Common Anti-Patterns](#common-anti-patterns)
-8. [Advanced Techniques](#advanced-techniques)
-
----
-
-## Core Principles
-
-### 1. Memory First
-
-**Always search before creating**:
-```bash
-# ❌ Bad: Start working without context
-buddy-do "implement login feature"
-
-# ✅ Good: Check for existing knowledge first
-buddy-remember "authentication"
-buddy-remember "login implementation"
-# Then work with context
-buddy-do "implement login feature using our existing auth patterns"
-```
-
-**Why**: Past decisions and solutions save time and ensure consistency.
-
----
-
-### 2. Store As You Work
-
-**Record decisions immediately**:
-```bash
-# ❌ Bad: Wait until end of day to record
-# ... work all day ...
-# Try to remember what you decided
-
-# ✅ Good: Store immediately after decision
-buddy-remember "Chose bcrypt over argon2 because team familiarity and proven track record"
-```
-
-**Why**: Fresh memories are more accurate and detailed.
-
----
-
-### 3. Context Over Keywords
-
-**Provide rich context**:
-```bash
-# ❌ Bad: Minimal information
-buddy-remember "using JWT"
-
-# ✅ Good: Full context with reasoning
-buddy-remember "Using JWT for authentication because it's stateless, scales horizontally, and works well with our microservices architecture. Token expiry set to 24 hours for security balance."
-```
-
-**Why**: Future you (and your team) will need the "why", not just the "what".
-
----
-
-### 4. Progressive Complexity
-
-**Start simple, then enhance**:
-```bash
-# ✅ Good: Progressive refinement
-buddy-do "plan user authentication system"
-# Review plan
-buddy-remember "Auth system will use JWT + refresh tokens"
-# Implement
-buddy-do "implement JWT authentication middleware"
-# Test and refine
-buddy-remember "JWT middleware handles token refresh automatically"
-```
-
-**Why**: Incremental progress with knowledge capture builds better systems.
-
----
-
-## Memory Management
-
-### Storage Patterns
-
-#### Decision Recording
-
-**Template**:
-```
-We [decision] because [reason]
-
-Example:
-buddy-remember "We chose PostgreSQL over MongoDB because we need ACID transactions for financial data and have complex relational queries"
-```
-
-#### Pattern Documentation
-
-**Template**:
-```
-All [entity type] follow [pattern] for [reason]
-
-Example:
-buddy-remember "All API endpoints follow /api/v1/{resource} pattern for consistent versioning and client compatibility"
-```
-
-#### Lesson Learned
-
-**Template**:
-```
-[Problem] was caused by [root cause]. Fixed by [solution]
-
-Example:
-buddy-remember "Memory leak in user service was caused by unclosed database connections. Fixed by implementing connection pooling with 'pg-pool' and proper cleanup in finally blocks"
-```
-
-#### Configuration Tracking
-
-**Template**:
-```
-[Environment] uses [configuration] for [purpose]
-
-Example:
-buddy-remember "Production uses AWS RDS PostgreSQL t3.large with 500GB SSD for main database, Multi-AZ for high availability"
-```
-
----
-
-### Search Strategies
-
-#### Keyword Search
-
-**Use domain terms**:
-```bash
-# ✅ Good: Specific domain keywords
-buddy-remember "JWT token expiry policy"
-buddy-remember "database migration process"
-buddy-remember "error handling patterns"
-```
-
-#### Temporal Search
-
-**Include timeframe hints**:
-```bash
-buddy-remember "recent authentication changes"
-buddy-remember "last week's bug fixes"
-buddy-remember "current API version"
-```
-
-#### Problem-Solution Search
-
-**Frame as question or problem**:
-```bash
-buddy-remember "how to handle session timeout"
-buddy-remember "why login fails intermittently"
-buddy-remember "database connection pool sizing"
-```
-
----
-
-### Memory Hygiene
-
-#### Regular Reviews
-
-**Weekly review pattern**:
-```bash
-# Monday: Review last week's decisions
-buddy-remember "decisions last week"
-
-# Friday: Document this week's learnings
-buddy-remember "Store summary: This week we implemented X, learned Y, decided Z"
-```
-
-#### Consolidation
-
-**Merge related memories**:
-```bash
-# After several auth-related memories
-buddy-remember "Authentication system overview: Uses JWT with 24h expiry, refresh tokens stored in Redis, bcrypt for passwords, rate limiting on /login"
-```
-
-#### Archival
-
-**Mark outdated knowledge**:
-```bash
-buddy-remember "DEPRECATED: Old auth system used sessions. Now using JWT as of 2026-01-20"
-```
-
----
-
-## Effective Task Descriptions
-
-### Task Decomposition
-
-**Break down complex tasks**:
-```bash
-# ❌ Bad: Single massive task
-buddy-do "implement complete user management system with auth, profiles, permissions, and admin dashboard"
-
-# ✅ Good: Decomposed tasks
-buddy-do "plan user management system architecture"
-# Review plan
-buddy-do "implement user authentication with JWT"
-buddy-do "implement user profile CRUD operations"
-buddy-do "implement role-based permissions"
-buddy-do "implement admin dashboard UI"
-```
-
-**Benefits**:
-- Clearer routing to specialized capabilities
-- Easier to track progress
-- Better context for each subtask
-- More manageable complexity
-
----
-
-### Task Description Quality
-
-**Effective task descriptions**:
-
-✅ **Good Examples**:
-```bash
-# Specific and goal-oriented
-buddy-do "refactor user service to use dependency injection for better testability"
-
-# Includes constraints
-buddy-do "implement rate limiting middleware that allows 100 requests per minute per IP"
-
-# Provides context
-buddy-do "fix login bug where sessions expire immediately - likely related to cookie domain configuration"
-```
-
-❌ **Bad Examples**:
-```bash
-# Too vague
-buddy-do "make the app better"
-
-# Multiple unrelated tasks
-buddy-do "fix login, add dark mode, update docs, and deploy to staging"
-
-# Missing context
-buddy-do "implement the thing we discussed"
-```
-
----
-
-### Capability Hints
-
-**Guide routing with keywords**:
-```bash
-# Frontend-focused
-buddy-do "create React component for user profile with Tailwind styling"
-
-# Backend-focused
-buddy-do "implement GraphQL API endpoint for user queries with authentication"
-
-# DevOps-focused
-buddy-do "setup GitHub Actions workflow for automated testing and deployment"
-
-# Security-focused
-buddy-do "audit authentication system for security vulnerabilities and SQL injection"
-```
-
----
-
-## Workflow Patterns
-
-### Daily Development Workflow
-
-```
-Morning:
-1. buddy-remember "yesterday's work"
-2. buddy-remember "current sprint tasks"
-3. Review and plan day's work
-
-During Work:
-4. buddy-do "" for each feature/fix
-5. buddy-remember "" after decisions
-6. buddy-remember "" after solving problems
-
-End of Day:
-7. buddy-remember "Today completed: "
-8. buddy-remember "Blocked on: " (if any)
-9. buddy-remember "Tomorrow: "
-```
-
----
-
-### Feature Development Workflow
-
-```
-Phase 1: Research & Planning
-→ buddy-remember "similar features"
-→ buddy-remember "architectural patterns"
-→ buddy-do "plan architecture"
-→ buddy-remember "Architectural decision: "
-
-Phase 2: Implementation
-→ buddy-do "implement backend"
-→ buddy-remember "Implementation uses: "
-→ buddy-do "implement frontend"
-→ buddy-remember "UI pattern follows: "
-
-Phase 3: Testing & Documentation
-→ buddy-do "create tests for "
-→ buddy-remember "Test coverage: "
-→ buddy-remember "Feature documentation: "
-
-Phase 4: Review & Learn
-→ buddy-do "review implementation"
-→ buddy-remember "Lessons learned: "
-```
-
----
-
-### Bug Fix Workflow
-
-```
-Step 1: Research
-→ buddy-remember ""
-→ buddy-remember "similar bugs"
-
-Step 2: Investigation
-→ buddy-do "investigate "
-→ buddy-remember "Root cause: "
-
-Step 3: Fix Implementation
-→ buddy-do "fix by "
-→ buddy-remember "Bug fix: caused by . Fixed by "
-
-Step 4: Prevention
-→ buddy-do "add tests to prevent regression"
-→ buddy-remember "Prevention: Added to catch "
-```
-
----
-
-### Code Review Workflow
-
-```
-Preparation:
-→ buddy-remember "code review checklist"
-→ buddy-remember "coding standards"
-
-Review:
-→ buddy-do "review for "
-→ buddy-remember "Review findings: "
-
-Follow-up:
-→ buddy-do "suggest improvements for "
-→ buddy-remember "Recommended improvements: "
-```
-
----
-
-## Team Collaboration
-
-### Onboarding New Team Members
-
-**Create onboarding guide**:
-```bash
-# Store essential information
-buddy-remember "Project architecture: Microservices with React frontend, Node.js backend, PostgreSQL database"
-
-buddy-remember "Development workflow: Feature branches → PR → Code review → Staging → Production"
-
-buddy-remember "Key conventions: API uses /api/v1 prefix, all async functions use try-catch, tests required for PRs"
-```
-
-**Share common queries**:
-```bash
-# New team member can search
-buddy-remember "how to setup development environment"
-buddy-remember "testing practices"
-buddy-remember "deployment process"
-```
-
----
-
-### Knowledge Sharing
-
-**Document tribal knowledge**:
-```bash
-buddy-remember "Why we use Redis: Session storage needs high performance, Redis provides sub-millisecond latency and automatic expiry"
-
-buddy-remember "Production deployment checklist: 1. Run migrations, 2. Deploy backend, 3. Verify health, 4. Deploy frontend, 5. Smoke tests"
-
-buddy-remember "Common gotchas: Database connection pool exhaustion happens under load. Monitor pool size and connection count"
-```
-
----
-
-### Decision Documentation
-
-**Record team decisions**:
-```bash
-buddy-remember "Team decision 2026-01-20: Migrate from REST to GraphQL for flexible querying. Agreed in sprint planning, starts Q2"
-
-buddy-remember "Architecture decision: Microservices communicate via event bus (RabbitMQ) for loose coupling and scalability"
-```
-
----
-
-## Performance Optimization
-
-### Efficient Searches
-
-**Optimize query patterns**:
-```bash
-# ❌ Slow: Too broad
-buddy-remember "everything about auth"
-
-# ✅ Fast: Specific keywords
-buddy-remember "JWT expiry policy"
-```
-
----
-
-### Batch Operations
-
-**Group related queries**:
-```bash
-# ❌ Inefficient: Multiple separate queries
-buddy-remember "API patterns"
-buddy-remember "API versioning"
-buddy-remember "API error handling"
-
-# ✅ Efficient: Combined search or comprehensive storage
-buddy-remember "API conventions: RESTful /api/v1 prefix, JSON responses, standard error format {error, message, code}"
-```
-
----
-
-### Storage Efficiency
-
-**Be concise but complete**:
-```bash
-# ❌ Too verbose
-buddy-remember "So we had this really long meeting and after discussing for hours we finally decided that maybe we should probably use PostgreSQL..."
-
-# ✅ Concise and clear
-buddy-remember "Chose PostgreSQL after evaluating MongoDB and MySQL. Decision factors: ACID compliance, JSON support, team expertise"
-```
-
----
-
-## Common Anti-Patterns
-
-### Anti-Pattern 1: Memory Hoarding
-
-**Problem**:
-```bash
-# Storing everything without filtering
-buddy-remember "Clicked save button"
-buddy-remember "Opened file"
-buddy-remember "Took break"
-```
-
-**Solution**:
-```bash
-# Store meaningful information only
-buddy-remember "Implemented save functionality with optimistic updates for better UX"
-```
-
----
-
-### Anti-Pattern 2: Vague Memories
-
-**Problem**:
-```bash
-buddy-remember "Fixed bug"
-buddy-remember "Updated code"
-```
-
-**Solution**:
-```bash
-buddy-remember "Fixed race condition in user service where concurrent requests created duplicate records. Added database constraint and request deduplication"
-```
-
----
-
-### Anti-Pattern 3: Never Searching
-
-**Problem**:
-```bash
-# Always creating new, never recalling
-buddy-do "implement authentication"
-# Reinvents patterns that already exist
-```
-
-**Solution**:
-```bash
-# Search first
-buddy-remember "authentication patterns"
-buddy-remember "existing auth implementation"
-# Then build with context
-buddy-do "implement authentication following existing patterns"
-```
-
----
-
-### Anti-Pattern 4: Task Overloading
-
-**Problem**:
-```bash
-buddy-do "implement entire e-commerce platform with cart, checkout, payments, shipping, inventory, admin panel"
-```
-
-**Solution**:
-```bash
-buddy-do "plan e-commerce platform architecture"
-# Then break into manageable tasks
-buddy-do "implement shopping cart functionality"
-buddy-do "implement checkout process"
-# etc.
-```
-
----
-
-### Anti-Pattern 5: Context-Free Storage
-
-**Problem**:
-```bash
-buddy-remember "Using Redis"
-buddy-remember "JWT expiry: 24h"
-```
-
-**Solution**:
-```bash
-buddy-remember "Using Redis for session storage because of sub-millisecond latency and built-in expiry"
-buddy-remember "JWT expiry set to 24 hours balancing security (limited exposure) and UX (not requiring frequent re-login)"
-```
-
----
-
-## Advanced Techniques
-
-### Templated Memories
-
-**Create reusable templates**:
-```bash
-# Decision template
-buddy-remember "DECISION: [What] because [Why]. Alternatives considered: [Options]. Trade-offs: [Pros/Cons]"
-
-# Bug fix template
-buddy-remember "BUG FIX: [Problem] caused by [Root Cause]. Fixed by [Solution]. Prevented by [Tests/Checks]"
-
-# Pattern template
-buddy-remember "PATTERN: All [Entity] follow [Pattern] for [Reason]. Example: [Code/Link]"
-```
-
----
-
-### Hierarchical Knowledge
-
-**Build knowledge layers**:
-```bash
-# Layer 1: High-level architecture
-buddy-remember "System architecture: Microservices - API Gateway, Auth Service, User Service, Order Service, Payment Service"
-
-# Layer 2: Service details
-buddy-remember "User Service: Node.js + Express, PostgreSQL, REST API, handles user CRUD and profile management"
-
-# Layer 3: Implementation specifics
-buddy-remember "User Service authentication: JWT middleware validates tokens, checks permissions, injects user context"
-```
-
----
-
-### Cross-Referencing
-
-**Link related knowledge**:
-```bash
-buddy-remember "Authentication uses JWT (see: JWT configuration). Tokens stored in Redis (see: Redis setup). Refresh every 24h (see: Token expiry policy)"
-```
-
----
-
-### Version Tracking
-
-**Track changes over time**:
-```bash
-buddy-remember "API v1: REST endpoints, deprecated 2026-01"
-buddy-remember "API v2: GraphQL, launched 2026-01, current standard"
-buddy-remember "API migration guide: v1→v2 mapping at /docs/api-migration"
-```
-
----
-
-### Problem-Solution Pairs
-
-**Document troubleshooting**:
-```bash
-buddy-remember "PROBLEM: High database CPU usage. CAUSE: Missing index on users.email. SOLUTION: Added index, CPU dropped 80%"
-
-buddy-remember "PROBLEM: Intermittent 500 errors. CAUSE: Connection pool exhaustion. SOLUTION: Increased pool size from 10 to 50, added connection monitoring"
-```
-
----
-
-## Workflow Checklists
-
-### Daily Checklist
-
-```
-□ Morning recall: buddy-remember "yesterday's progress"
-□ Check blockers: buddy-remember "known issues"
-□ Plan day: buddy-do "plan today's tasks"
-□ During work: Store decisions as they happen
-□ End of day: buddy-remember "today's summary"
-□ Document blockers: buddy-remember "tomorrow's priorities"
-```
-
----
-
-### Feature Completion Checklist
-
-```
-□ Feature implemented: buddy-do "implement "
-□ Tests written: buddy-do "create tests for "
-□ Documentation: buddy-remember " documentation"
-□ Decisions recorded: buddy-remember ""
-□ Patterns documented: buddy-remember ""
-□ Lessons captured: buddy-remember ""
-```
-
----
-
-### Sprint Planning Checklist
-
-```
-□ Review last sprint: buddy-remember "last sprint summary"
-□ Recall lessons: buddy-remember "lessons learned"
-□ Check patterns: buddy-remember "development patterns"
-□ Plan architecture: buddy-do "plan sprint features"
-□ Document plan: buddy-remember "sprint plan "
-□ Set expectations: buddy-remember "sprint goals and estimates"
-```
-
----
-
-## Summary
-
-### Key Takeaways
-
-1. **Search First**: Always check existing knowledge before starting work
-2. **Store Immediately**: Record decisions and learnings as they happen
-3. **Provide Context**: Include the "why", not just the "what"
-4. **Break Down Tasks**: Decompose complex work into manageable pieces
-5. **Be Specific**: Clear, detailed descriptions lead to better results
-6. **Review Regularly**: Weekly reviews keep knowledge fresh and relevant
-7. **Share Knowledge**: Document for your team, not just yourself
-8. **Template Consistently**: Use consistent formats for similar memories
-
-### Quick Reference
-
-```
-┌────────────────────────────────────────────────┐
-│ MeMesh Best Practices │
-├────────────────────────────────────────────────┤
-│ Memory Management │
-│ ✓ Search before creating │
-│ ✓ Store as you work │
-│ ✓ Include context and reasoning │
-│ ✓ Review and consolidate weekly │
-│ │
-│ Task Descriptions │
-│ ✓ Break down complex tasks │
-│ ✓ Use specific, goal-oriented descriptions │
-│ ✓ Provide constraints and context │
-│ ✓ Guide with capability keywords │
-│ │
-│ Workflows │
-│ ✓ Follow structured patterns │
-│ ✓ Document at each phase │
-│ ✓ Capture lessons learned │
-│ ✓ Share team knowledge │
-└────────────────────────────────────────────────┘
-```
-
----
-
-**Next Steps**:
-
-1. **Try a workflow**: Pick one pattern from this guide and use it today
-2. **Review your memories**: Check if they follow best practices
-3. **Share with team**: Establish team-wide conventions
-4. **Iterate**: Refine your patterns based on what works
-
----
-
-For more information:
-- [User Guide](./USER_GUIDE.md) - Complete command reference
-- [Quick Start](./QUICK_START.md) - Getting started guide
-- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and solutions
-
-**MeMesh** — Persistent memory for Claude Code
diff --git a/docs/CNAME b/docs/CNAME
deleted file mode 100644
index 507cb66c..00000000
--- a/docs/CNAME
+++ /dev/null
@@ -1 +0,0 @@
-ccb.pcircle.ai
\ No newline at end of file
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
deleted file mode 100644
index 63bf898f..00000000
--- a/docs/COMMANDS.md
+++ /dev/null
@@ -1,509 +0,0 @@
-# MeMesh Plugin Commands Reference
-
-Complete reference for all MeMesh Plugin commands and tools.
-
-## Table of Contents
-
-- [Buddy Commands](#buddy-commands) (User-Friendly Layer)
-- [MCP Tools](#mcp-tools) (Direct Tool Access)
-- [Command Aliases](#command-aliases)
-- [Usage Examples](#usage-examples)
-
----
-
-## Buddy Commands
-
-Buddy commands provide a natural, conversational interface to MeMesh's functionality.
-
-### `buddy do `
-
-Execute any development task with memory-enhanced context.
-
-**What it does:**
-- Analyzes task complexity
-- Applies capability-focused prompt enhancement
-- Returns execution result with routing info
-
-**Parameters:**
-- `task` (required): Description of task to execute
-
-**Examples:**
-```bash
-buddy do setup authentication for the API
-buddy do refactor the user service
-buddy do fix the login bug we discussed
-buddy do write tests for auth.ts
-buddy do optimize this database query
-```
-
-**Aliases:**
-- `buddy help-with`
-- `buddy execute`
-- `buddy run`
-- `buddy task`
-
-**Routing Logic:**
-- MeMesh evaluates task complexity and capability keywords
-- Specialized prompt context is added for the detected capability focus
-- Estimated cost and complexity are included for transparency
-
----
-
-### `buddy remember [limit]`
-
-Recall project memory - past decisions, architecture choices, bug fixes, and patterns.
-
-**What it does:**
-- Searches knowledge graph for relevant memories
-- Returns past decisions and context
-- Helps maintain project consistency
-
-**Parameters:**
-- `query` (required): What to search for
-- `limit` (optional): Max number of results (1-50, default: 10)
-- `mode` (optional): Search mode — `keyword` (exact match), `semantic` (AI similarity), `hybrid` (both combined). Default: `hybrid`
-- `matchThreshold` (optional): Minimum match score (0-1). Higher values return fewer but more relevant results. Default: 0.3
-- `allProjects` (optional): Search across ALL projects, not just the current one. Default: false
-
-**Examples:**
-```bash
-buddy remember how we implemented authentication
-buddy remember api design decisions
-buddy remember database schema changes
-buddy remember why we chose TypeScript
-buddy remember authentication approach 10
-```
-
-**Aliases:**
-- `buddy recall`
-- `buddy retrieve`
-- `buddy search`
-- `buddy find`
-
-**Use Cases:**
-- Recall past architectural decisions
-- Remember why certain patterns were chosen
-- Review previous bug fixes
-- Maintain consistency across sessions
-
----
-
-### `buddy help [command]`
-
-Get help for all buddy commands or a specific command.
-
-**What it does:**
-- Shows command reference
-- Explains usage and parameters
-- Provides examples
-- Lists command aliases
-
-**Parameters:**
-- `command` (optional): Specific command to get help for
- - `do` - Help for buddy do
- - `remember` - Help for buddy remember
- - (Leave empty for all commands)
-
-**Examples:**
-```bash
-buddy help # Show all commands
-buddy help do # Help for buddy do
-buddy help remember # Help for buddy remember
-```
-
----
-
-## MCP Tools
-
-Direct MCP tool access (for advanced users or MCP integrations).
-
-### `buddy-do`
-
-MCP tool version of `buddy do` command.
-
-**Input Schema:**
-```json
-{
- "task": "string (required) - Task description"
-}
-```
-
-**Example:**
-```json
-{
- "task": "setup authentication for the API"
-}
-```
-
----
-
-### `buddy-remember`
-
-MCP tool version of `buddy remember` command.
-
-**Input Schema:**
-```json
-{
- "query": "string (required) - Search query",
- "limit": "number (optional) - Max results (1-50, default: 10)",
- "mode": "string (optional) - Search mode: 'semantic', 'keyword', 'hybrid' (default: 'hybrid')",
- "matchThreshold": "number (optional) - Minimum match score 0-1 (default: 0.3)",
- "allProjects": "boolean (optional) - Search all projects (default: false)"
-}
-```
-
-**Example:**
-```json
-{
- "query": "authentication approach",
- "limit": 10,
- "mode": "hybrid",
- "matchThreshold": 0.5
-}
-```
-
----
-
-### `buddy-help`
-
-MCP tool version of `buddy help` command.
-
-**Input Schema:**
-```json
-{
- "command": "string (optional) - Command to get help for"
-}
-```
-
-**Example:**
-```json
-{
- "command": "do"
-}
-```
-
----
-
-### `memesh-generate-tests`
-
-Automatically generate comprehensive test cases from specifications or source code using AI.
-
-**Aliases:** `generate-tests` (deprecated, will be removed in v3.0.0)
-
-**Input Schema:**
-```json
-{
- "specification": "string (optional) - Feature or function specification",
- "code": "string (optional) - Source code to generate tests for"
-}
-```
-
-**Note:** Must provide either `specification` or `code`.
-
----
-
-### `memesh-hook-tool-use`
-
-Internal hook event ingestion for workflow automation and memory tracking (auto-triggered by Claude Code hooks, do not call manually).
-
-**Aliases:** `hook-tool-use` (deprecated, will be removed in v3.0.0)
-
-**Input Schema:**
-```json
-{
- "toolName": "string (required) - Tool executed by Claude Code",
- "arguments": "object (optional) - Tool arguments payload",
- "success": "boolean (required) - Whether execution succeeded",
- "duration": "number (optional) - Duration in milliseconds",
- "tokensUsed": "number (optional) - Tokens used by tool call",
- "output": "string (optional) - Tool output"
-}
-```
-
----
-
-### `memesh-record-mistake`
-
-Record errors and mistakes for learning and prevention.
-
-**Aliases:** `buddy-record-mistake`
-
-**Input Schema:**
-```json
-{
- "action": "string (required) - What action the AI took",
- "errorType": "string (required) - Error classification (see values below)",
- "userCorrection": "string (required) - User's correction/feedback",
- "correctMethod": "string (required) - What should have been done instead",
- "impact": "string (required) - Impact of the mistake",
- "preventionMethod": "string (required) - How to prevent in future",
- "relatedRule": "string (optional) - Related rule/guideline",
- "context": "object (optional) - Additional context"
-}
-```
-
-**Error Types:**
-`procedure-violation`, `workflow-skip`, `assumption-error`, `validation-skip`, `responsibility-lack`, `firefighting`, `dependency-miss`, `integration-error`, `deployment-error`
-
-**Example:**
-```json
-{
- "action": "Used synchronous file read in async handler",
- "errorType": "assumption-error",
- "userCorrection": "This blocks the event loop",
- "correctMethod": "Use fs.promises.readFile() instead of fs.readFileSync()",
- "impact": "Server becomes unresponsive under load",
- "preventionMethod": "Always use async I/O in request handlers"
-}
-```
-
----
-
-### `memesh-create-entities`
-
-Create knowledge entities with explicit relationships for fine-grained control over the knowledge graph.
-
-**Input Schema:**
-```json
-{
- "entities": "array (required) - Array of entity objects",
- "entity.name": "string (required) - Unique entity name",
- "entity.entityType": "string (required) - Entity type",
- "entity.observations": "array (required) - Array of observation strings",
- "entity.tags": "array (optional) - Array of tag strings"
-}
-```
-
-**Example:**
-```json
-{
- "entities": [
- {
- "name": "PostgreSQL Database Choice",
- "entityType": "decision",
- "observations": [
- "Chose PostgreSQL over MySQL",
- "Better JSON support and performance"
- ],
- "tags": ["database", "postgresql"]
- }
- ]
-}
-```
-
----
-
-### `memesh-metrics`
-
-View session metrics and tool usage statistics.
-
-**Input Schema:**
-```json
-{
- "section": "string (optional) - Which metrics section: 'all' | 'session' | 'routing' | 'memory' (default: 'all')"
-}
-```
-
----
-
-## Cloud-Only Mode Limitations
-
-In **cloud-only mode** (when better-sqlite3 is unavailable but MEMESH_API_KEY is configured), certain tools are disabled because they require local SQLite storage.
-
-### ❌ Disabled Tools in Cloud-Only Mode
-
-| Tool | Status | Reason |
-|------|--------|--------|
-| `buddy-do` | ❌ Unavailable | Requires local Knowledge Graph for task context |
-| `buddy-remember` | ❌ Unavailable | Requires local memory search |
-| `memesh-create-entities` | ❌ Unavailable | Requires local Knowledge Graph |
-| `memesh-hook-tool-use` | ❌ Unavailable | Requires local memory tracking |
-| `memesh-record-mistake` | ❌ Unavailable | Requires local mistake storage |
-| `memesh-metrics` | ❌ Unavailable | Requires local metrics storage |
-
-### ✅ Available Tools in Cloud-Only Mode
-
-| Tool | Status | Notes |
-|------|--------|-------|
-| `buddy-help` | ✅ Works | Displays command help |
-| `memesh-generate-tests` | ✅ Works | AI-based test generation (stateless) |
-
-### Error Message Example
-
-When calling a disabled tool in cloud-only mode:
-
-```
-❌ Tool 'buddy-remember' is not available in cloud-only mode.
-
-This MCP server is running without local SQLite storage (better-sqlite3 unavailable).
-
-To use local memory tools:
-1. Install better-sqlite3: npm install better-sqlite3
-2. Restart the MCP server
-
-Local SQLite storage is required for memory features.
-```
-
-### Why Cloud-Only Mode Exists
-
-Cloud-only mode enables MeMesh to run in restricted environments (like Claude Desktop Cowork) where:
-- Native modules cannot compile (better-sqlite3, onnxruntime-node, sqlite-vec)
-- Filesystem is read-only
-- Node.js headers cannot be downloaded
-
-See [docs/COWORK_SUPPORT.md](./COWORK_SUPPORT.md) for complete details.
-
-### Future: Cloud-First Memory
-
-**Planned**: Full memory tool support in cloud-only mode through cloud-first memory architecture
-
-**Timeline**: Long-term (no ETA yet)
-
-**How**: Memory tools will proxy to cloud KG API instead of local SQLite
-
-**Related Issues**: #73, #76, #77
-
----
-
-## Command Aliases
-
-All buddy commands support multiple aliases for convenience:
-
-### `buddy do` Aliases
-- `buddy help-with `
-- `buddy execute `
-- `buddy run `
-- `buddy task `
-
-### `buddy remember` Aliases
-- `buddy recall `
-- `buddy retrieve `
-- `buddy search `
-- `buddy find `
-
-## Usage Examples
-
-### Complete Development Workflow
-
-**1. Start new feature:**
-```bash
-buddy do create user registration API endpoint
-```
-
-**2. Check memory for past patterns:**
-```bash
-buddy remember how we implemented other API endpoints
-buddy remember authentication patterns
-```
-
-**3. Execute specific tasks:**
-```bash
-buddy do write tests for registration endpoint
-buddy do add input validation
-buddy do update API documentation
-```
-
-### Memory-Driven Development
-
-**Store important decisions:**
-```bash
-# The system automatically stores important decisions
-# from your conversations and task executions
-```
-
-**Recall when needed:**
-```bash
-buddy remember why we chose JWT over sessions
-buddy remember database migration approach
-buddy remember error handling patterns
-buddy remember API versioning strategy
-```
-
----
-
-## Tips & Best Practices
-
-### 1. Be Specific in Tasks
-```bash
-# ❌ Vague
-buddy do fix bug
-
-# ✅ Specific
-buddy do fix the login timeout bug in auth.ts
-```
-
-### 2. Use Memory Effectively
-```bash
-# Store context at the start of a session
-buddy remember what we're working on
-
-# Recall past decisions before making changes
-buddy remember authentication approach
-```
-
-### 3. Use Aliases for Speed
-```bash
-# Short aliases for common operations
-buddy recall auth # instead of buddy remember auth
-buddy run tests # instead of buddy do run tests
-```
-
----
-
-## Troubleshooting
-
-### Command Not Found
-
-If buddy commands aren't recognized:
-
-1. **Verify MCP Integration:**
- ```bash
- # MeMesh MCP is auto-managed via the plugin's .mcp.json
- # If auto-configuration failed, run:
- memesh setup
- ```
-
-2. **Restart Claude Code:**
- ```bash
- # After configuration changes
- ```
-
-3. **Check Server Logs:**
- ```bash
- # Look for MCP server errors
- ```
-
-### Tool Execution Failures
-
-If tools fail to execute:
-
-1. **Check Dependencies:**
- ```bash
- npm install
- npm run build
- ```
-
-2. **Verify Environment:**
- - Node.js 20+ installed
- - Claude Code configured
- - MCP server running
-
-3. **Test Manually:**
- ```bash
- npm run mcp
- ```
-
----
-
-## Next Steps
-
-- **API Reference:** See [API_REFERENCE.md](./api/API_REFERENCE.md) for detailed MCP tool documentation
-- **User Guide:** See [USER_GUIDE.md](./USER_GUIDE.md) for complete feature reference
-- **Best Practices:** See [BEST_PRACTICES.md](./BEST_PRACTICES.md) for effective workflows
-- **Installation:** See [GETTING_STARTED.md](./GETTING_STARTED.md) for setup guide
-- **Troubleshooting:** See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues
-- **Contributing:** See [CONTRIBUTING.md](./CONTRIBUTING.md) to add features
-
----
-
-**Questions?** Open an issue on GitHub or check the documentation.
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
deleted file mode 100644
index d38e3607..00000000
--- a/docs/DEVELOPMENT.md
+++ /dev/null
@@ -1,609 +0,0 @@
-# Development Guide
-
-This guide covers the day-to-day development workflow for MeMesh Plugin contributors. For contribution guidelines and release processes, see [CONTRIBUTING.md](../CONTRIBUTING.md).
-
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Initial Setup](#initial-setup)
-- [Development Workflow](#development-workflow)
-- [Testing Strategy](#testing-strategy)
-- [Debugging](#debugging)
-- [Common Tasks](#common-tasks)
-- [Troubleshooting](#troubleshooting)
-- [Best Practices](#best-practices)
-
----
-
-## Prerequisites
-
-### Required Software
-
-- **Node.js** >= 20.0.0
- ```bash
- node --version # Should be >= 20.0.0
- ```
-
-- **npm** >= 9.0.0
- ```bash
- npm --version
- ```
-
-- **Claude Code CLI** (for MCP server testing)
- ```bash
- claude --version
- ```
-
-- **Git**
- ```bash
- git --version
- ```
-
-### Optional Tools
-
-- **tsx** - TypeScript executor (automatically installed as dev dependency)
-- **vitest** - Testing framework (automatically installed)
-
----
-
-## Initial Setup
-
-### 1. Clone and Install
-
-```bash
-# Clone the repository
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Verify installation
-npm test
-```
-
-### 2. Verify MCP Server
-
-```bash
-# Check if MCP server can start
-npm run verify:mcp
-
-# List MCP processes (if any)
-npm run processes:list
-```
-
-Expected output:
-```
-✅ MCP server verified successfully
-```
-
-### 3. Install Locally (Optional)
-
-For testing the global install experience:
-
-```bash
-# Link package globally
-npm link
-
-# Verify global installation
-memesh --version
-
-# Unlink when done
-npm unlink -g @pcircle/memesh
-```
-
----
-
-## Development Workflow
-
-### Starting Development
-
-```bash
-# Watch mode - auto-rebuild on file changes
-npm run dev
-
-# In a separate terminal, test your changes
-npm test -- --watch
-```
-
-### Making Changes
-
-1. **Create a feature branch**
- ```bash
- git checkout -b feature/your-feature-name
- ```
-
-2. **Make your changes**
- - Edit source files in `src/`
- - Add/update tests in `tests/`
-
-3. **Build and test**
- ```bash
- npm run build
- npm test
- ```
-
-4. **Verify code quality**
- ```bash
- npm run lint
- npm run typecheck
- npm run format
- ```
-
-### Understanding the Build Process
-
-```bash
-npm run build
-```
-
-This command:
-1. Compiles TypeScript → JavaScript (`tsc`)
-2. Copies resources to `dist/` (`copy:resources`)
-3. Makes MCP server executable (`chmod +x`)
-4. Prepares plugin package (`prepare:plugin`)
-
-**Important**: The MCP server runs as a daemon. After building, you must restart Claude Code to load the new version.
-
----
-
-## Testing Strategy
-
-### Test Types
-
-| Test Type | Command | When to Use |
-|-----------|---------|-------------|
-| **Unit Tests** | `npm test` | Default - fast, isolated tests |
-| **Integration Tests** | `npm run test:integration` | Test component interactions |
-| **E2E Tests** | `npm run test:e2e:safe` | ⚠️ Resource-intensive, use sparingly |
-| **Coverage Report** | `npm run test:coverage` | Before PR submission |
-
-### Running Tests
-
-```bash
-# Run all tests (single-thread mode to prevent worker leaks)
-npm test
-
-# Run specific test file
-npm test src/memory/MemoryManager.test.ts
-
-# Run tests matching a pattern
-npm test -- --grep "MemoryManager"
-
-# Watch mode for TDD
-npm test -- --watch
-
-# Generate coverage report
-npm run test:coverage
-```
-
-### Test Coverage Requirements
-
-- **Minimum for existing code**: 60%
-- **Minimum for new code**: 70%
-- **Target for core modules**: 80%+
-
-Check current coverage:
-```bash
-npm run test:coverage
-```
-
-### E2E Testing (⚠️ Important)
-
-E2E tests are resource-intensive and can freeze your system if not managed properly.
-
-**Always use the safe wrapper:**
-```bash
-npm run test:e2e:safe
-```
-
-**Never run:**
-```bash
-npm run test:e2e # ❌ Will exit with warning
-```
-
-The `test:e2e:safe` script:
-- Monitors system resources (CPU, memory)
-- Runs tests with `maxThreads: 1`
-- Aborts if resource usage exceeds safe thresholds
-
----
-
-## Debugging
-
-### MCP Server Debugging
-
-The MCP server runs as a persistent daemon process. Understanding its lifecycle is crucial for debugging.
-
-#### Check MCP Server Status
-
-```bash
-# List all MCP server processes
-npm run processes:list
-
-# Check for orphaned processes
-npm run processes:orphaned
-
-# View MCP configuration
-npm run processes:config
-```
-
-Example output:
-```
-┌─────────────────────────────────────────────────────────┐
-│ MCP Server Process Status │
-├──────┬──────────────┬────────┬──────────┬──────────────┤
-│ PID │ Command │ Status │ Uptime │ TTY │
-├──────┼──────────────┼────────┼──────────┼──────────────┤
-│ 1234 │ server-boot… │ Active │ 2h 15m │ ttys002 │
-└──────┴──────────────┴────────┴──────────┴──────────────┘
-```
-
-#### Common MCP Server Issues
-
-**Problem**: MCP tools not loading in Claude Code
-
-**Diagnosis**:
-```bash
-# 1. Check if old process is running
-npm run processes:list
-
-# 2. Check global vs local version mismatch
-npm list -g @pcircle/memesh # Global version
-cat package.json | grep version # Local version
-```
-
-**Solution**:
-```bash
-# 1. Kill old MCP server processes
-npm run processes:kill
-
-# 2. Restart Claude Code
-# Exit Claude Code completely and restart
-
-# 3. Verify tools are now available
-# In Claude Code, type: buddy-help
-```
-
-**Root Cause**: MCP server runs as a daemon and doesn't auto-reload when code changes. Old processes keep running with outdated code.
-
-**Prevention**:
-- Always restart Claude Code after rebuilding
-- Kill old processes before testing: `npm run processes:kill`
-
-#### Debugging with Node Inspector
-
-Start MCP server with debugger enabled and open Chrome DevTools at chrome://inspect
-
-```bash
-node --inspect dist/mcp/server-bootstrap.js
-```
-
-#### Viewing Logs
-
-MCP server logs are written to `~/.cache/claude/mcp-logs/`
-
-```bash
-# View recent logs
-tail -f ~/.cache/claude/mcp-logs/memesh.log
-```
-
-### Memory System Debugging
-
-```bash
-# Check database schema
-sqlite3 ~/.cache/claude/memesh/memory.db ".schema"
-
-# List memories
-sqlite3 ~/.cache/claude/memesh/memory.db "SELECT * FROM memories LIMIT 10;"
-
-# Check database size
-du -sh ~/.cache/claude/memesh/
-```
-
-### TypeScript Debugging
-
-```bash
-# Type check without building
-npm run typecheck
-
-# Show all type errors
-tsc --noEmit --pretty false
-
-# Check specific file
-tsc --noEmit src/your-file.ts
-```
-
----
-
-## Common Tasks
-
-### Adding a New MCP Tool
-
-1. **Define the tool** in `src/mcp/ToolDefinitions.ts`
-2. **Create the handler** in `src/mcp/handlers/`
-3. **Add Zod schema** in `src/mcp/schemas/`
-4. **Write tests** in `tests/unit/mcp/`
-5. **Update documentation** (`docs/COMMANDS.md`, `README.md`)
-6. **Test end-to-end**:
- ```bash
- npm run build
- npm run verify:mcp
- # Restart Claude Code
- # Test: buddy-your-tool "test input"
- ```
-
-### Modifying Database Schema
-
-1. **Create migration** in `src/db/migrations/`
-2. **Update version** in `src/db/schema.ts`
-3. **Verify migration**: `npm run verify:migration`
-4. **Test**: `npm test -- src/db/migrations`
-
-### Updating Dependencies
-
-```bash
-# Check outdated dependencies
-npm outdated
-
-# Update specific dependency
-npm update package-name
-
-# After updating, verify:
-npm run build
-npm test
-npm run test:install
-```
-
-### Creating a Release
-
-See [docs/RELEASE_PROCESS.md](RELEASE_PROCESS.md) for the full release workflow.
-
-Quick checklist:
-```bash
-# 1. Bump version (on develop branch)
-npm version patch --no-git-tag-version # or minor, or major
-
-# 2. Update CHANGELOG.md
-# Add entry for new version
-
-# 3. Commit and push
-git add package.json CHANGELOG.md
-git commit -m "chore(release): bump version to X.Y.Z"
-git push origin develop
-
-# 4. Open PR: develop → main, review & merge
-gh pr create --base main --head develop --title "chore(release): vX.Y.Z"
-
-# 5. Manual npm publish (GitHub Actions cannot auto-trigger publish)
-npm publish --access public
-npm view @pcircle/memesh version
-```
-
----
-
-## Troubleshooting
-
-### Build Errors
-
-**Problem**: `tsc` fails with type errors
-
-**Solution**:
-```bash
-# Clear TypeScript cache
-rm -rf dist/
-rm -rf node_modules/.cache/
-
-# Reinstall dependencies
-npm ci
-
-# Rebuild
-npm run build
-```
-
----
-
-**Problem**: Permission denied errors
-
-**Solution**:
-```bash
-# Make scripts executable
-chmod +x scripts/*.sh
-
-# Rebuild
-npm run build
-```
-
----
-
-### Test Failures
-
-**Problem**: Tests fail after making changes
-
-**Solution**:
-```bash
-# Clear test cache
-npm test -- --clearCache
-
-# Run tests again
-npm test
-```
-
----
-
-**Problem**: E2E tests freeze the system
-
-**Solution**:
-- Always use `npm run test:e2e:safe`
-- Never run multiple E2E test processes simultaneously
-- If system freezes, kill vitest processes manually
-
----
-
-### Installation Issues
-
-**Problem**: `npm install` fails
-
-**Solution**:
-```bash
-# Clear npm cache
-npm cache clean --force
-
-# Remove node_modules
-rm -rf node_modules package-lock.json
-
-# Reinstall
-npm install
-```
-
----
-
-**Problem**: Postinstall script fails
-
-**Solution**:
-```bash
-# Run postinstall manually
-node scripts/postinstall-new.js
-
-# Check logs
-cat ~/.cache/claude/memesh/install.log
-```
-
----
-
-### MCP Server Issues
-
-**Problem**: Tools not available in Claude Code
-
-**Solution**:
-```bash
-# 1. Kill old processes
-npm run processes:kill
-
-# 2. Verify installation
-npm list -g @pcircle/memesh
-
-# 3. Reinstall if needed
-npm install -g @pcircle/memesh
-
-# 4. Restart Claude Code completely
-```
-
----
-
-**Problem**: MCP server crashes on startup
-
-**Solution**:
-```bash
-# Check logs
-tail -f ~/.cache/claude/mcp-logs/memesh.log
-
-# Verify server can start
-npm run verify:mcp
-
-# If verification fails, check:
-# 1. Node.js version >= 20
-# 2. Database file is not corrupted
-# 3. No other process using the same port
-```
-
----
-
-## Best Practices
-
-### Code Quality
-
-1. **Use strict TypeScript**
- - Avoid `any` types
- - Define explicit interfaces
- - Use type guards for runtime checks
-
-2. **Write tests for new code**
- - Minimum 70% coverage for new files
- - Test both success and error paths
- - Use descriptive test names
-
-3. **Follow existing patterns**
- - Check how similar features are implemented
- - Maintain consistent code style
- - Reuse existing utilities
-
-### Git Workflow
-
-1. **Small, focused commits**
- - One logical change per commit
- - Use conventional commit messages
- - Reference issue numbers when applicable
-
-2. **Keep branches up to date**
- ```bash
- git checkout main
- git pull
- git checkout feature/your-branch
- git rebase main
- ```
-
-3. **Run pre-commit checks**
- ```bash
- npm run lint
- npm run typecheck
- npm test
- ```
-
-### Performance
-
-1. **Avoid blocking operations**
- - Use async/await for I/O
- - Don't block the event loop
-
-2. **Profile before optimizing**
- - Use Node.js built-in profiler
- - Measure before and after changes
-
-3. **Monitor memory usage**
- - Check for memory leaks
- - Use appropriate data structures
-
-### Security
-
-1. **Never commit sensitive data**
- - Use environment variables
- - Add sensitive files to `.gitignore`
-
-2. **Validate user input**
- - Use Zod schemas for validation
- - Sanitize inputs before database queries
-
-3. **Use secure dependencies**
- ```bash
- # Audit dependencies
- npm audit
-
- # Fix vulnerabilities
- npm audit fix
- ```
-
----
-
-## Additional Resources
-
-- **[Architecture Documentation](ARCHITECTURE.md)** - System design and components
-- **API Reference** - Run `npm run build` to generate API docs locally
-- **[User Guide](USER_GUIDE.md)** - End-user documentation
-- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Common issues and solutions
-- **[MCP Specification](https://modelcontextprotocol.io)** - MCP protocol details
-
----
-
-## Getting Help
-
-- **Discussions**: [GitHub Discussions](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
-- **Issues**: [GitHub Issues](https://github.com/PCIRCLE-AI/claude-code-buddy/issues)
-
----
-
-**Happy coding!** 🚀
-
-If you find something unclear in this guide, please [open an issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?labels=documentation) or submit a PR to improve it.
diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md
deleted file mode 100644
index b1804892..00000000
--- a/docs/ERROR_REFERENCE.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Error Reference
-
-Complete reference of MeMesh Plugin error types, codes, and solutions.
-
----
-
-## Error Hierarchy
-
-All MeMesh errors extend `BaseError` and include:
-- **`code`**: Programmatic error code (see table below)
-- **`context`**: Structured metadata about the error
-- **`timestamp`**: When the error occurred
-
-```
-BaseError
-├── ValidationError (input validation failures)
-├── StateError (invalid state for operation)
-├── NotFoundError (resource not found)
-├── ConfigurationError (configuration issues)
-├── OperationError (operation execution failures)
-└── ExternalServiceError (external API/service failures)
-```
-
----
-
-## Error Codes
-
-### Validation Errors (VALIDATION_*)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `VALIDATION_FAILED` | `ValidationError` | "Memory content cannot be empty" | Empty or missing required field | Provide non-empty value for required fields |
-| `VALIDATION_FAILED` | `ValidationError` | "Metrics store path must be within user home or data directory" | Path traversal attempt | Use paths within `~/.memesh/` or home directory |
-| `VALIDATION_FAILED` | `ValidationError` | "Limit must be non-negative" | Negative number for pagination | Use positive integers for `limit` and `offset` |
-| `VALIDATION_FAILED` | `ValidationError` | "Database path must be a non-empty string" | Empty database path | Provide a valid `.db` file path |
-| `VALIDATION_FAILED` | `ValidationError` | "Database path contains invalid null byte" | Null byte injection attempt | Remove null bytes from path |
-| `VALIDATION_FAILED` | `ValidationError` | "Database path must have .db extension" | Wrong file extension | Use `.db` extension for database files |
-| `VALIDATION_FAILED` | `ValidationError` | "Database path must be within allowed directory" | Path outside allowed scope | Use paths within `~/.memesh/` |
-| `VALIDATION_FAILED` | `ValidationError` | "CPU percentage must be between 0 and 100" | Out-of-range resource value | Use values within documented ranges |
-| `VALIDATION_FAILED` | `ValidationError` | "Max background agents must be >= 1" | Invalid agent limit | Set at least 1 for max agents |
-| `VALIDATION_FAILED` | `ValidationError` | "Memory ID must start with prefix: mem_" | Invalid ID format | Use IDs with `mem_` prefix |
-| `VALIDATION_FAILED` | `ValidationError` | "Invalid memory type" | Unsupported memory type | Use: `decision`, `feature`, `bug_fix`, `lesson_learned`, `pattern`, `note` |
-| `VALIDATION_FAILED` | `ValidationError` | "Command is required" | Empty tool command | Provide command string |
-| `VALIDATION_FAILED` | `ValidationError` | "CSRF protection: Missing origin header" | Missing security header | Ensure Origin header is present |
-| `VALIDATION_FAILED` | `ValidationError` | "Agent name must be a non-empty string" | Empty agent name | Provide non-empty agent name |
-
-### State Errors (INVALID_STATE)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `INVALID_STATE` | `StateError` | "Memory system not initialized" | Using system before init | Call `initialize()` before operations |
-| `ALREADY_INITIALIZED` | `StateError` | "System already initialized" | Double initialization | Check state before calling init |
-
-### Not Found Errors (RESOURCE_NOT_FOUND)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `RESOURCE_NOT_FOUND` | `NotFoundError` | "Task not found" | Invalid task ID | Verify task ID with `memesh-metrics` |
-| `ENTITY_NOT_FOUND` | `NotFoundError` | "Entity not found" | Knowledge graph entity missing | Use `buddy-remember` to search first |
-| `TOOL_NOT_FOUND` | `NotFoundError` | "Tool not found" | Invalid MCP tool name | Check available tools with `buddy-help` |
-
-### Configuration Errors (CONFIGURATION_*)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `CONFIGURATION_INVALID` | `ConfigurationError` | "API key is required" | Missing API key | Run `memesh login` or set `ANTHROPIC_API_KEY` |
-| `CONFIGURATION_MISSING` | `ConfigurationError` | "Configuration file not found" | Missing config | Run `memesh setup` to create config |
-
-### Operation Errors (OPERATION_*)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `OPERATION_FAILED` | `OperationError` | "Memory update failed" | Database write failure | Check disk space, file permissions |
-| `OPERATION_FAILED` | `OperationError` | "Failed to create UnifiedMemoryStore" | Store initialization error | Check database file integrity |
-| `OPERATION_FAILED` | `OperationError` | "Failed to store memory" | Write operation failed | Verify database is not locked |
-| `INITIALIZATION_FAILED` | `OperationError` | "Tool dispatcher is not attached" | Missing component wiring | Restart MeMesh server |
-| `EXECUTION_FAILED` | `OperationError` | "Tool execution failed" | Runtime tool error | Check tool input parameters |
-
-### External Service Errors (EXTERNAL_*)
-
-| Code | Error Class | Common Message | Cause | Solution |
-|------|-------------|----------------|-------|----------|
-| `EXTERNAL_SERVICE_ERROR` | `ExternalServiceError` | "External API request failed" | API call failed | Check network, API key validity |
-| `NETWORK_ERROR` | `ExternalServiceError` | "Network request timed out" | Connection timeout | Retry, check connectivity |
-| `TIMEOUT_ERROR` | `ExternalServiceError` | "Operation timed out" | Exceeded time limit | Increase timeout or reduce workload |
-
----
-
-## SQLite-Specific Errors
-
-These are native SQLite errors caught and wrapped by MeMesh:
-
-| SQLite Error | MeMesh Handling | Cause | Solution |
-|-------------|-----------------|-------|----------|
-| `SQLITE_BUSY` | Retried with exponential backoff | Database locked by another process | Wait or kill other MeMesh processes: `npm run processes:kill` |
-| `SQLITE_FULL` | Connection discarded from pool | Disk full | Free disk space, check `~/.memesh/` size |
-| `SQLITE_CORRUPT` | Detected by `PRAGMA quick_check` | Database corruption | Delete `~/.memesh/database.db` and restart (data loss) |
-| `SQLITE_READONLY` | `OperationError` thrown | File permissions | Fix: `chmod 644 ~/.memesh/database.db` |
-| `SQLITE_IOERR` | Connection discarded | I/O failure | Check disk health, file system |
-
----
-
-## Programmatic Error Handling
-
-```typescript
-import { isValidationError, isOperationError, getErrorCode, ErrorCode } from '@pcircle/memesh';
-
-try {
- await store.createMemory(data);
-} catch (error) {
- if (isValidationError(error)) {
- // Input validation failed — fix input
- console.log('Invalid field:', error.context);
- } else if (isOperationError(error)) {
- // Operation failed — retry or report
- console.log('Operation:', error.context?.operation);
- }
-
- // Or use error codes
- const code = getErrorCode(error);
- if (code === ErrorCode.VALIDATION_FAILED) { /* ... */ }
-}
-```
-
----
-
-## Type Guards
-
-| Function | Returns `true` for |
-|----------|-------------------|
-| `isBaseError(err)` | Any MeMesh custom error |
-| `isValidationError(err)` | Input validation errors |
-| `isStateError(err)` | State-related errors |
-| `isNotFoundError(err)` | Resource not found errors |
-| `isConfigurationError(err)` | Configuration errors |
-| `isOperationError(err)` | Operation execution errors |
-| `isExternalServiceError(err)` | External service errors |
-
----
-
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
deleted file mode 100644
index bc5602b6..00000000
--- a/docs/GETTING_STARTED.md
+++ /dev/null
@@ -1,370 +0,0 @@
-# Getting Started with MeMesh Plugin
-
-**Install Time**: 2 minutes • **First Memory**: 30 seconds • **Ready to Code**: Immediately
-
----
-
-## What is MeMesh Plugin?
-
-**MeMesh Plugin gives Claude Code a persistent memory.** Simple as that.
-
-Every project you work on, every decision you make, every bug you fix—Claude remembers it all. No more re-explaining your architecture every session. No more "As I mentioned earlier..." No more starting from scratch.
-
-### What You Get
-
-✅ **Remembers Everything**: Architecture decisions, design patterns, bugs fixed, conventions used
-✅ **Smart Task Routing**: Automatically detects what kind of work you need and applies the right expertise
-✅ **Persistent Memory**: Knowledge graph persists across all sessions (stored locally)
-✅ **Zero Configuration**: Works out of the box with sensible defaults
-✅ **100% Local**: Your code and decisions never leave your machine
-
-### Before and After
-
-**❌ Without MeMesh:**
-```
-Session 1: "We use JWT for auth..."
-Session 2: "Remember our auth?"
-Claude: "Sorry, no context..."
-You: *explains everything again* 😤
-```
-
-**✅ With MeMesh:**
-```
-Session 1: "Setup JWT auth"
-Session 2: "Remember auth"
-MeMesh: "JWT auth from Jan 15: 15min access tokens, 7-day refresh..."
-```
-
----
-
-## Installation
-
-### Quick Install (Recommended)
-
-One command, fully automatic:
-
-```bash
-npm install -g @pcircle/memesh
-```
-
-Restart Claude Code. **Done!**
-
-No config files to edit. No API keys needed. The postinstall script auto-configures everything.
-
-
-Install from source (for contributors)
-
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
-```
-
-MeMesh is a Claude Code Plugin — the MCP server is auto-managed via the plugin's `.mcp.json` file. No manual configuration of `~/.claude/mcp_settings.json` is needed.
-
-If auto-configuration did not work, run:
-```bash
-memesh setup
-```
-
-
-
----
-
-## Verify It's Working
-
-### 1. Check MeMesh is Active
-
-In Claude Code, run:
-```bash
-buddy-help
-```
-
-**Expected output:**
-```
-MeMesh v2.10.1 - Persistent Memory for Claude Code
-
-Available Commands:
- buddy-do - Execute any development task
- buddy-remember - Recall project decisions and patterns
- buddy-help - Show this help
-
- memesh-generate-tests - Auto-generate comprehensive tests
-
- ... (8 tools total)
-
-Status: ✅ Connected (8 tools available)
-```
-
-### 2. Test Memory Storage
-
-Try this:
-```bash
-"Store this decision: We're using PostgreSQL for JSONB support"
-```
-
-Then recall it:
-```bash
-buddy-remember "database choice"
-```
-
-**You should see:** Your stored decision retrieved from memory.
-
-### 3. Test Task Routing
-
-```bash
-buddy-do "review this function for security issues:
-function login(user, pass) {
- return db.query('SELECT * FROM users WHERE name=' + user);
-}"
-```
-
-**You should see:** Security analysis identifying SQL injection vulnerability.
-
----
-
-## Troubleshooting
-
-
-❌ "MCP server not found"
-
-**Cause**: Claude Code can't connect to MeMesh
-
-**Fix**:
-1. Verify installation path is correct:
- ```bash
- cd claude-code-buddy
- pwd # Copy this path
- ```
-
-2. Check the file exists:
- ```bash
- ls dist/mcp/server-bootstrap.js
- ```
-
-3. Rebuild if missing:
- ```bash
- npm run build
- ```
-
-4. Restart Claude Code completely
-
-
-
-
-❌ "Commands don't respond"
-
-**Cause**: MeMesh server isn't running or crashed
-
-**Fix**:
-1. Check server logs:
- ```bash
- cat ~/.claude/logs/memesh.log
- ```
-
-2. Verify Node.js version:
- ```bash
- node --version # Should be v20.0.0+
- ```
-
-3. Reinstall dependencies:
- ```bash
- cd claude-code-buddy
- rm -rf node_modules
- npm install
- npm run build
- ```
-
-4. Restart Claude Code
-
-
-
-
-❌ "Installation succeeded but nothing happens"
-
-**Cause**: Plugin directory not loaded
-
-**Fix**:
-1. Start Claude Code with plugin flag:
- ```bash
- claude --plugin-dir /path/to/claude-code-buddy
- ```
-
-2. Create shell alias for convenience:
- ```bash
- # Add to ~/.bashrc or ~/.zshrc
- alias claude-mem='claude --plugin-dir /path/to/claude-code-buddy'
- ```
-
-3. For team distribution, see Claude Code plugin documentation
-
-
-
----
-
-## Your First Commands
-
-### Store and Retrieve
-
-**Store a decision:**
-```bash
-"Remember: We chose React over Vue because the team knows React better"
-```
-
-**Retrieve it later:**
-```bash
-buddy-remember "why React?"
-```
-
-**Expected**: Instant recall of your decision with the reasoning.
-
-### Smart Task Routing
-
-**Code review:**
-```bash
-buddy-do "review src/auth.ts for security"
-```
-
-**Generate tests:**
-```bash
-memesh-generate-tests --code "function add(a, b) { return a + b; }"
-```
-
-**Refactor code:**
-```bash
-buddy-do "refactor UserService to reduce duplication"
-```
-
-**Each command automatically routes to the right internal capability with the right expertise.**
-
----
-
-## Common Scenarios
-
-### Scenario 1: Joining an Existing Project
-
-**You**: New to the project, need to understand decisions
-
-```bash
-# Query project memory
-buddy-remember "architecture decisions"
-buddy-remember "why PostgreSQL"
-buddy-remember "authentication approach"
-
-# Get overview
-buddy-do "summarize the key technical decisions in this project"
-```
-
-**Result**: Instant context on why things are the way they are.
-
----
-
-### Scenario 2: Starting a New Project
-
-**You**: Fresh start, want to track decisions from day one
-
-```bash
-# Make initial decisions and store them
-"Remember: Using TypeScript strict mode for type safety"
-"Remember: Chose Express over Fastify for ecosystem maturity"
-"Remember: Using Vitest for testing because it's fast and ESM-native"
-
-# Later in the project
-buddy-remember "testing framework"
-```
-
-**Result**: Your decisions are preserved across sessions (30/90 days). New team members can query them months later.
-
----
-
-### Scenario 3: Debugging a Recurring Issue
-
-**You**: Bug keeps coming back, want to track the fix
-
-```bash
-# Debug and document
-buddy-do "analyze why users are logged out randomly"
-
-# After fixing
-"Remember: Random logout bug was caused by JWT expiry not being refreshed.
-Fixed in auth/middleware.ts by adding token refresh logic."
-
-# Next time it happens
-buddy-remember "logout bug"
-```
-
-**Result**: Root cause analysis is stored. If the bug returns, you have the full history.
-
----
-
-## Next Steps
-
-Now that MeMesh is running, explore more:
-
-### Learn More
-- **[User Guide](USER_GUIDE.md)** - Complete feature documentation
-- **[API Reference](api/API_REFERENCE.md)** - All commands and tools explained
-- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
-
-### Advanced Topics
-- Knowledge graph queries and entity management
-- Memory best practices and organization
-- Error tracking and mistake prevention
-
----
-
-## Quick Reference Card
-
-```bash
-# Core Commands
-buddy-help # Show available commands
-buddy-do "" # Execute any development task
-buddy-remember "" # Query project memory
-
-# Testing
-memesh-generate-tests # Auto-generate tests (provide specification or code)
-
-# Status
-"Show MeMesh status" # Connection and capability status
-```
-
----
-
-## Why It Works
-
-**MeMesh operates on three principles:**
-
-1. **Memory First**: Every significant action is recorded automatically
-2. **Context-Aware**: Tasks are enhanced with relevant project memory
-3. **Zero Friction**: No configuration, no API keys, no setup ceremony
-
-**The result**: Claude Code that remembers your project like a teammate, not a tool.
-
----
-
-## Learn More
-
-**Comprehensive Documentation**:
-
-- **[User Guide](./USER_GUIDE.md)** - Complete feature reference and workflows
-- **[API Reference](./api/API_REFERENCE.md)** - Detailed MCP tool documentation with schemas and examples
-- **[Best Practices](./BEST_PRACTICES.md)** - Effective patterns and workflows
-- **[Commands Reference](./COMMANDS.md)** - All available commands
-- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
-
-**Advanced Topics**:
-- [Knowledge Graph Tools](./api/API_REFERENCE.md#knowledge-graph-tools) - Build complex entity relationships
-- [Integration Examples](./api/API_REFERENCE.md#integration-examples) - Complete workflow patterns
-- [Error Reference](./api/API_REFERENCE.md#error-reference) - Error codes and handling
-
----
-
-**Ready to code with memory?** 🚀
-
-Install MeMesh, run `buddy-help`, and never explain your architecture twice again.
-
-**Questions?** [Open an issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues) or [start a discussion](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions).
-
----
-
-**Not affiliated with Anthropic PBC** • Independent open-source project
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
deleted file mode 100644
index 692989f0..00000000
--- a/docs/TROUBLESHOOTING.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# Troubleshooting Guide
-
-## TL;DR
-If you're in a hurry:
-1. Run `memesh setup` to fix installation and path issues.
-2. Restart Claude Code completely.
-3. Verify your Node.js version is **>= v20.0.0**.
-
----
-
-## Diagnostic Flowchart
-
-Use this decision tree to quickly find your solution:
-
-```
-Start: What's the problem?
-│
-├─ "Tools not found / command not found"
-│ ├─ Is MeMesh installed? → npm list -g @pcircle/memesh
-│ │ ├─ NOT installed → npm install -g @pcircle/memesh
-│ │ └─ Installed → Run: memesh setup → Restart Claude Code
-│ └─ Still failing? → Check Node.js >= v20: node --version
-│
-├─ "MCP Server Connection Failed"
-│ ├─ Restart Claude Code completely (quit + reopen)
-│ ├─ Still failing? → memesh config validate
-│ │ ├─ Config invalid → memesh setup
-│ │ └─ Config valid → Check for orphaned processes:
-│ │ npm run processes:kill → Restart Claude Code
-│ └─ Still failing? → Check daemon: memesh daemon status
-│
-├─ "Memory not persisting"
-│ ├─ Does database exist? → ls ~/.memesh/database.db
-│ │ ├─ Missing → memesh setup (re-creates it)
-│ │ └─ Exists → Check permissions: ls -la ~/.memesh/
-│ └─ Permissions OK? → memesh config validate
-│
-├─ "Slow or hanging"
-│ ├─ Kill processes → pkill -f memesh
-│ ├─ Check orphans → npm run processes:orphaned
-│ └─ Restart Claude Code
-│
-├─ "Permission denied"
-│ ├─ During install? → Use nvm, avoid sudo
-│ └─ During runtime? → chmod 700 ~/.memesh/ && chmod 644 ~/.memesh/database.db
-│
-└─ "Database corruption / SQLITE_CORRUPT"
- ├─ Backup: cp ~/.memesh/database.db ~/.memesh/database.db.bak
- ├─ Delete: rm ~/.memesh/database.db
- └─ Restart Claude Code (database re-created automatically)
-```
-
----
-
-## Quick Diagnostic Commands
-
-Before troubleshooting, run these commands to gather information:
-
-```bash
-# 1. Verify MeMesh installation
-npm list -g @pcircle/memesh
-
-# 2. Check Node.js and npm versions
-node --version # Should be >= v20.0.0
-npm --version # Should be >= v9.0.0
-
-# 3. Validate MCP configuration
-memesh config validate
-
-# 4. Check daemon status
-memesh daemon status
-
-# 5. Test MeMesh directly
-npx @pcircle/memesh --help
-```
-
----
-
-## Issue Categories
-
-- [Most Common Issues](#most-common-issues)
-- [Performance & Persistence](#performance--persistence)
-- [Error Reference](#error-reference)
-- [Getting Help](#getting-help)
-
----
-
-## Most Common Issues
-
-### 1. "buddy-help" command not found
-**Symptoms**: Shell returns "command not found" after installation.
-**Quick Fix:**
-```bash
-memesh setup # Run interactive setup to fix PATH
-# Restart your terminal or Claude Code
-# Try: buddy-help
-```
-
-### 2. "MCP Server Connection Failed"
-**Symptoms**: Claude Code cannot connect to the MeMesh server.
-**Quick Fix:**
-```bash
-# Restart Claude Code completely
-# Wait a few seconds for the MCP server to initialize
-# Try the command again
-```
-
-### 3. "Permission denied" errors
-**Symptoms**: Errors during `npm install` or file access.
-**Quick Fix:**
-- **Avoid sudo**: Use an npm prefix or a version manager like `nvm`.
-- **Manual fix**: `sudo npm install -g @pcircle/memesh` (not recommended for long-term).
-
----
-
-## Performance & Persistence
-
-### 4. Commands are slow or hanging
-**Symptoms**: MeMesh takes too long to respond or hangs indefinitely.
-**Quick Fix:**
-- **Kill processes**: `pkill -f memesh` then restart Claude Code.
-- **Simplify**: Break complex tasks into smaller sub-tasks.
-- **Check orphans**: `npm run processes:orphaned` to find orphaned processes.
-
-### 5. Memory not persisting
-**Symptoms**: Information or context from previous sessions is lost.
-**Quick Fix:**
-- Check permissions for `~/.memesh/` directory (or `~/.claude-code-buddy/` if migrating from older version).
-- Verify the database exists: `ls ~/.memesh/database.db`
-- Run `memesh config validate` to ensure storage is correctly configured.
-
-### 6. Multiple MCP server processes
-**Symptoms**: High CPU or memory usage from duplicate MeMesh processes.
-**Quick Fix:**
-```bash
-npm run processes:list # List all processes
-npm run processes:orphaned # Find orphaned processes
-npm run processes:kill # Kill all MeMesh processes
-```
-Then restart Claude Code.
-
----
-
----
-
-## Error Reference
-
-For a complete list of error codes, messages, and solutions, see **[ERROR_REFERENCE.md](./ERROR_REFERENCE.md)**.
-
-Common error types:
-- **ValidationError**: Invalid input — check parameters
-- **StateError**: System not ready — run `memesh setup`
-- **OperationError**: Operation failed — check disk space, permissions
-- **ConfigurationError**: Missing config — run `memesh config validate`
-
----
-
-## Getting Help
-
-1. **Quick Start:** [docs/QUICK_START.md](./QUICK_START.md)
-2. **CLI Parameters:** [docs/CLI_PARAMETERS.md](./CLI_PARAMETERS.md)
-3. **Error Reference:** [docs/ERROR_REFERENCE.md](./ERROR_REFERENCE.md)
-4. **Report Issue:** `memesh report-issue`
-
----
-
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
deleted file mode 100644
index 080a62d1..00000000
--- a/docs/USER_GUIDE.md
+++ /dev/null
@@ -1,1358 +0,0 @@
-# User Guide
-## Complete Reference for MeMesh Plugin
-
-Welcome to the complete MeMesh Plugin User Guide! This guide provides detailed information about all commands, features, and workflows.
-
----
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Core Commands](#core-commands)
-3. [MCP Tools](#mcp-tools)
- - [Advanced MCP Tools](#advanced-mcp-tools)
- - [Learning & Error Tracking](#learning--error-tracking)
-4. [CLI Commands](#cli-commands)
-5. [Memory System](#memory-system)
-6. [Task Execution](#task-execution)
-7. [Configuration](#configuration)
-8. [Visual Explorer (Streamlit UI)](#visual-explorer-streamlit-ui)
-9. [Advanced Usage](#advanced-usage)
-10. [Troubleshooting](#troubleshooting)
-
----
-
-## Introduction
-
-### What is MeMesh Plugin?
-
-MeMesh Plugin is a persistent memory plugin for Claude Code that helps you:
-
-- **Remember across sessions**: Persistent knowledge graph storage
-- **Execute tasks with context**: Memory-enhanced task execution
-- **Learn from experience**: Auto-tracking and pattern recognition
-- **Work efficiently**: Context-aware assistance
-
-### Architecture Overview
-
-MeMesh Plugin runs as a local-first MCP server:
-
-```
-Claude Code ──stdio──► MeMesh Plugin
- │
- ┌─────────┼─────────┐
- ▼ ▼ ▼
- ┌─────────┐ ┌────────┐ ┌──────────┐
- │ Router │ │ Memory │ │ Semantic │
- │ │ │ Graph │ │ Search │
- └─────────┘ └────────┘ └──────────┘
-```
-
-**Benefits:**
-- Local-first: All data stored locally, never transmitted
-- Zero configuration: Works out of the box
-- Vector semantic search: ONNX embeddings for intelligent recall
-- Persistent memory: Knowledge graph persists across sessions
-
----
-
-## Core Commands
-
-### buddy-do
-
-**Purpose**: Execute tasks with memory-enhanced context
-
-**Syntax**:
-```
-buddy-do ""
-```
-
-**How it works**:
-1. Analyzes task complexity and required capabilities
-2. Routes to the best-suited capability (backend, frontend, devops, etc.)
-3. Enhances prompt with project context
-4. Returns routing decision and enhanced prompt
-
-**Examples**:
-
-```bash
-# Backend development
-buddy-do "implement user authentication with JWT"
-# → Routes to backend-developer capability
-# → Analyzes database requirements, security considerations
-# → Provides enhanced prompt with project context
-
-# Frontend development
-buddy-do "create responsive navbar with dark mode toggle"
-# → Routes to frontend-developer capability
-# → Considers existing design system
-# → Suggests component structure
-
-# DevOps tasks
-buddy-do "setup CI/CD pipeline with GitHub Actions"
-# → Routes to devops capability
-# → Analyzes deployment requirements
-# → Provides workflow configuration
-
-# Bug fixes
-buddy-do "fix memory leak in user service"
-# → Routes to debugging capability
-# → Analyzes potential causes
-# → Suggests investigation steps
-```
-
-**Task Metadata Extraction**:
-
-buddy-do automatically extracts metadata from your task description:
-
-- **Goal**: What you want to achieve
-- **Reason**: Why you're doing this (if mentioned)
-- **Expected Outcome**: What success looks like
-
-Example:
-```
-buddy-do "add email verification because users need to confirm accounts"
-
-Extracted:
-- Goal: "add email verification"
-- Reason: "users need to confirm accounts"
-- Expected Outcome: (inferred from context)
-```
-
-**Response Structure**:
-
-```
-✓ BUDDY-DO SUCCESS
-
-📋 Task
-Setup user authentication with JWT
-
-────────────────────────────────────
-
-✓ Results
- routing:
- approved: true
- message: Task routed to backend-developer
- complexity: medium
- estimatedTokens: 2500
- estimatedCost: $0.0125
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Verify implementation meets requirements
- 2. Run tests to ensure nothing broke
- 3. Store decision: buddy-remember
-
-Duration: 2.3s • Tokens: 2,500
-```
-
-**Complexity Levels**:
-
-- **Simple** (< 1000 tokens): Quick tasks, simple queries
-- **Medium** (1000-5000 tokens): Standard features, moderate refactoring
-- **Complex** (> 5000 tokens): Architectural changes, large features
-
-**When to Use**:
-- ✅ Any development task (coding, testing, debugging)
-- ✅ Architectural decisions
-- ✅ Code reviews
-- ✅ Documentation tasks
-- ✅ Planning and analysis
-
-**When NOT to Use**:
-- ❌ Simple questions (use buddy-help instead)
-- ❌ Memory queries (use buddy-remember instead)
-
----
-
-### buddy-remember
-
-**Purpose**: Store and recall knowledge from your project's memory graph
-
-**Syntax**:
-```bash
-# Store knowledge
-buddy-remember ""
-
-# Recall knowledge (search)
-buddy-remember ""
-```
-
-**How it works**:
-
-**Storage Mode**:
-- Detects when you're providing information (not a question)
-- Stores in Knowledge Graph with auto-generated tags
-- Records timestamp and context
-- Returns confirmation
-
-**Recall Mode**:
-- Searches Knowledge Graph by keywords and semantic similarity
-- Ranks results by relevance
-- Returns matching memories with context
-- Suggests next steps if no results found
-
-**Storage Examples**:
-
-```bash
-# Store decisions
-buddy-remember "We decided to use PostgreSQL because it supports JSON and has better performance for complex queries"
-
-# Store patterns
-buddy-remember "All API endpoints follow RESTful conventions with /api/v1 prefix"
-
-# Store lessons learned
-buddy-remember "Login bug was caused by session timeout not being reset on activity. Fixed by updating session middleware"
-
-# Store configuration
-buddy-remember "Production uses AWS RDS with t3.medium instances, staging uses t3.micro"
-```
-
-**Recall Examples**:
-
-```bash
-# Search for decisions
-buddy-remember "why did we choose PostgreSQL?"
-# → Returns: Database selection decisions and reasons
-
-# Find patterns
-buddy-remember "API endpoint conventions"
-# → Returns: RESTful patterns, versioning strategy
-
-# Find solutions to similar problems
-buddy-remember "session timeout issues"
-# → Returns: Past bugs, solutions, and lessons learned
-
-# Check configuration
-buddy-remember "database configuration"
-# → Returns: Database settings, connection strings (sanitized)
-```
-
-**Response Structure (Storage)**:
-
-```
-✓ Memory Stored Successfully
-
-📋 Task
-Store project decision about database choice
-
-────────────────────────────────────
-
-✓ Results
- status: stored
- knowledge_id: "kb_1234567890"
- tags: ["decision", "database", "postgresql"]
- timestamp: "2026-01-20T10:30:00Z"
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Memory is now searchable
- 2. Try: buddy-remember "postgresql" to verify
-
-Duration: 0.8s • Tokens: 300
-```
-
-**Response Structure (Recall - With Results)**:
-
-```
-✓ Memory Search Complete
-
-📋 Query
-postgresql
-
-────────────────────────────────────
-
-✓ Results
- count: 3
- memories:
- 1. [2026-01-15] Decision: PostgreSQL for production
- "We decided to use PostgreSQL because..."
- Tags: decision, database, postgresql
-
- 2. [2026-01-18] Configuration: Database connection
- "Production: aws-rds-pg.xyz, port 5432..."
- Tags: configuration, database, postgresql
-
- 3. [2026-01-19] Lesson: Connection pooling
- "Fixed timeout issues by increasing pool size..."
- Tags: lesson, database, performance
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Review memories above for relevant context
- 2. Apply these learnings to your current task
-
-Duration: 1.2s • Tokens: 800
-```
-
-**Response Structure (Recall - No Results)**:
-
-```
-✓ Memory Search Complete
-
-📋 Query
-microservices
-
-────────────────────────────────────
-
-✓ Results
- count: 0
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Try a broader search term
- 2. Create new memory: buddy-do
-
-Duration: 0.5s • Tokens: 200
-```
-
-**Best Practices**:
-
-**Storage**:
-- ✅ Be specific and concise
-- ✅ Include context (why, when, what)
-- ✅ Store as you work, not later
-- ✅ Use natural language (the system handles tagging)
-
-**Recall**:
-- ✅ Use keywords from your question
-- ✅ Try broader terms if no results
-- ✅ Search before starting new work
-- ✅ Combine with buddy-do for context-aware tasks
-
-**Auto-Tagging**:
-
-The system automatically generates tags based on content:
-- **Entities**: Users, products, services, technologies
-- **Actions**: Created, updated, fixed, decided
-- **Concepts**: Authentication, database, API, testing
-- **Types**: Decision, lesson, pattern, configuration
-
----
-
-### buddy-help
-
-**Purpose**: Quick help and command reference
-
-**Syntax**:
-```bash
-# Basic help
-buddy-help
-
-# Detailed help for all commands
-buddy-help --all
-```
-
-**Output**:
-
-```
-🤖 MeMesh Quick Start
-
-Essential Commands
-
-┌────────────────────────────────────────────┐
-│ buddy-do "" │
-└────────────────────────────────────────────┘
-❯ buddy-do "add user authentication"
-→ Routes to backend-developer, creates auth system
-
-┌────────────────────────────────────────────┐
-│ buddy-remember "" │
-└────────────────────────────────────────────┘
-❯ buddy-remember "Using JWT for sessions"
-→ Stores in Knowledge Graph with auto-tags
-
-┌────────────────────────────────────────────┐
-│ buddy-remember "" │
-└────────────────────────────────────────────┘
-❯ buddy-remember "why JWT?"
-→ Searches and recalls past decisions
-
-💡 New to MeMesh?
-Run: memesh tutorial
-
-📖 Full reference: buddy-help --all
-```
-
-**When to Use**:
-- ✅ First-time setup (verify MeMesh is working)
-- ✅ Quick command reference
-- ✅ Syntax reminders
-
----
-
-## Real-World Examples
-
-Learn how MeMesh helps you build better software through real project scenarios. These examples demonstrate how MeMesh's persistent memory enhances your workflow across multiple sessions.
-
-### Example 1: Building a REST API (Multi-Day Workflow)
-
-This example shows how MeMesh remembers your architectural decisions and coding patterns across a week-long project.
-
-#### Day 1: Initial Setup
-
-**Your Task**: Start building a REST API for an e-commerce platform
-
-```bash
-You: buddy-do "create Express API with user authentication"
-```
-
-**What MeMesh Does**:
-- Analyzes requirements (Express, authentication, API)
-- Routes to backend-developer capability
-- Generates complete setup:
- - Express server with middleware
- - JWT authentication system
- - User model and database schema
- - Auth routes (/login, /register, /refresh)
-
-**MeMesh Automatically Remembers**:
-```
-✅ Tech stack: Express + MongoDB + JWT
-✅ Coding style: RESTful, async/await, error handling middleware
-✅ File structure: controllers/, models/, routes/, middleware/
-✅ Authentication: JWT with 15-min access tokens, 7-day refresh tokens
-```
-
-**Store Your Decision**:
-```bash
-You: buddy-remember "Using JWT for authentication because we need stateless auth for mobile app and easy horizontal scaling"
-```
-
----
-
-#### Day 3: Adding New Features
-
-**Your Task**: Add password reset functionality
-
-```bash
-You: buddy-do "add password reset feature"
-```
-
-**MeMesh Recalls**:
-```
-✅ Your auth architecture from Day 1 (JWT tokens, user model)
-✅ Email service setup (from Day 2)
-✅ Token generation pattern (consistent with existing auth)
-```
-
-**Result**:
-- Password reset integrates seamlessly with existing auth system
-- Uses same JWT library and token patterns
-- Follows your established API conventions (/api/v1/auth/reset-password)
-- No need to re-explain architecture
-
-**Store the New Pattern**:
-```bash
-You: buddy-remember "Password reset uses time-limited JWT tokens (15 min expiry) sent via email. Tokens are single-use and invalidated after use."
-```
-
----
-
-#### Day 7: Query Past Decisions
-
-**Your Task**: New team member asks about auth implementation
-
-```bash
-You: buddy-remember "why JWT over sessions?"
-```
-
-**MeMesh Returns**:
-```
-Found 3 relevant memories:
-
-1. [Day 1, 2026-01-15] Decision: JWT authentication
- "Using JWT for authentication because we need stateless
- auth for mobile app and easy horizontal scaling"
- Tags: authentication, jwt, architecture, decision
-
-2. [Day 3, 2026-01-17] Pattern: Token expiration
- "JWT tokens: 15-min access, 7-day refresh. Keeps security
- tight while maintaining good UX"
- Tags: jwt, security, tokens
-
-3. [Day 4, 2026-01-18] Lesson: Token refresh
- "Implemented silent refresh. Frontend checks token expiry
- and refreshes 5 minutes before expiration"
- Tags: jwt, frontend, refresh-token
-```
-
-**Benefit**: Complete context retrieved in seconds, no digging through Git history or Slack messages.
-
----
-
-#### Day 10: Bug Fix with Context
-
-**Your Task**: Login fails on mobile app
-
-```bash
-You: buddy-remember "mobile authentication"
-You: buddy-do "investigate mobile login failures"
-```
-
-**MeMesh Uses**:
-- Remembers mobile-specific requirements (from Day 1)
-- Recalls auth flow implementation (from Day 1-3)
-- Checks for related past bugs (searches memory graph)
-
-**Finds the Issue**: Cookie settings incompatible with mobile WebView
-
-**Store the Solution**:
-```bash
-You: buddy-remember "Mobile login bug: Cookie sameSite attribute must be 'none' for mobile WebView. Fixed by updating Express session config."
-```
-
----
-
-### Example 2: Frontend Development with Design System
-
-**Day 1: Setting Up the Design System**
-
-```bash
-You: buddy-do "create design system with Tailwind and component library"
-```
-
-**MeMesh Generates**:
-- Tailwind configuration with custom colors
-- Base component library (Button, Input, Card)
-- Typography scale
-- Spacing system
-
-**Store Design Decisions**:
-```bash
-You: buddy-remember "Design system uses 8px spacing scale. Primary color: #3B82F6 (blue-500). Components follow atomic design: atoms → molecules → organisms"
-```
-
----
-
-**Day 4: Building Feature Components**
-
-```bash
-You: buddy-do "create product card component with image, title, price, and add-to-cart button"
-```
-
-**MeMesh Recalls**:
-```
-✅ Design system spacing scale (8px grid)
-✅ Primary color (#3B82F6)
-✅ Existing Button component (reusable)
-✅ Component structure pattern (atomic design)
-```
-
-**Result**:
-- Product card follows established patterns
-- Uses existing Button component
-- Matches spacing and color scheme
-- No style inconsistencies
-
----
-
-**Day 8: Responsive Design**
-
-```bash
-You: buddy-remember "responsive breakpoints"
-```
-
-**MeMesh Returns**:
-```
-Found 2 relevant memories:
-
-1. [Day 2] Configuration: Tailwind breakpoints
- "Using default Tailwind breakpoints: sm (640px),
- md (768px), lg (1024px), xl (1280px)"
- Tags: tailwind, responsive, config
-
-2. [Day 5] Pattern: Mobile-first approach
- "All components built mobile-first, then enhanced
- for larger screens using md: and lg: prefixes"
- Tags: responsive, mobile-first, pattern
-```
-
-**Apply Consistently**: Now you know exactly how to make the new component responsive.
-
----
-
-### Example 3: DevOps and Infrastructure
-
-**Day 1: Setting Up CI/CD**
-
-```bash
-You: buddy-do "setup GitHub Actions CI/CD pipeline"
-```
-
-**Store Infrastructure Decisions**:
-```bash
-You: buddy-remember "Using GitHub Actions for CI/CD. Workflow: lint → test → build → deploy to Vercel. Runs on pull requests and main branch merges."
-```
-
----
-
-**Day 5: Adding Environment Variables**
-
-```bash
-You: buddy-remember "deployment configuration"
-You: buddy-do "add database URL environment variable to deployment"
-```
-
-**MeMesh Recalls**:
-- CI/CD workflow structure
-- Vercel deployment setup
-- Existing environment variable pattern
-
-**Adds Variable Correctly**: Uses GitHub Secrets, updates Vercel config, follows naming convention.
-
----
-
-**Week 2: Troubleshooting Deployment**
-
-```bash
-You: buddy-remember "CI/CD issues"
-```
-
-**MeMesh Returns**:
-```
-Found 1 relevant memory:
-
-[Day 8] Lesson: Build cache issue
-"GitHub Actions build was failing due to stale cache.
-Fixed by adding cache-dependency-path: package-lock.json
-to setup-node action"
-Tags: github-actions, ci-cd, cache, troubleshooting
-```
-
-**Benefit**: Quickly recall solutions to past problems, avoid repeating debugging sessions.
-
----
-
-### Key Takeaways
-
-#### 1. **Cross-Session Context**
-MeMesh maintains context across days and weeks:
-- No need to re-explain architecture
-- Past decisions inform current work
-- Consistent patterns throughout project
-
-#### 2. **Collaborative Memory**
-Perfect for teams:
-- Onboard new members faster
-- Share tribal knowledge
-- Document decisions as you make them
-
-#### 3. **Learning from Experience**
-Build institutional knowledge:
-- Record bugs and solutions
-- Track what works and what doesn't
-- Prevent repeating mistakes
-
-#### 4. **Natural Workflow**
-No disruption to your process:
-- Store knowledge as you work
-- Recall when you need it
-- Automatic memory linking
-
----
-
-### Next Steps
-
-**Try These Workflows**:
-1. **Start a new feature**: `buddy-do "plan [feature]"` → implement → store decisions
-2. **Debug an issue**: `buddy-remember "[error]"` → investigate → store solution
-3. **Review past work**: `buddy-remember "[topic]"` → understand context
-
-**Best Practices**:
-- ✅ Store decisions immediately (don't wait until later)
-- ✅ Be specific in memory descriptions (future you will thank you)
-- ✅ Query memory before starting new work (leverage past knowledge)
-- ✅ Record bugs and solutions (build your knowledge base)
-
-**Learn More**:
-- [BEST_PRACTICES.md](./BEST_PRACTICES.md) - Effective workflows and patterns
-- [Advanced Usage](#advanced-usage) - Complex scenarios and integrations
-- [Memory System](#memory-system) - How the knowledge graph works
-
----
-
-## MCP Tools
-
-### Advanced MCP Tools
-
-These tools provide lower-level access to MeMesh capabilities. For complete API documentation with detailed schemas, examples, and error handling, see **[API_REFERENCE.md](./api/API_REFERENCE.md)**.
-
-#### memesh-create-entities
-
-**Purpose**: Create knowledge entities with explicit relationships
-
-**Usage**: Advanced users who need fine-grained control over knowledge graph structure
-
-**Quick Example**:
-```json
-{
- "entities": [
- {
- "name": "PostgreSQL Database Choice 2026-02-03",
- "entityType": "decision",
- "observations": [
- "Chose PostgreSQL over MySQL",
- "Better JSON support and performance"
- ],
- "tags": ["database", "postgresql", "architecture"]
- }
- ]
-}
-```
-
-**When to Use**:
-- Building complex knowledge graphs
-- Migrating external knowledge
-- Integrating with other systems
-
-📖 **Full Documentation**: [API_REFERENCE.md - memesh-create-entities](./api/API_REFERENCE.md#memesh-create-entities)
-
-#### memesh-generate-tests
-
-**Purpose**: Generate automated test cases using AI
-
-**Aliases**: `generate-tests` (deprecated, will be removed in v3.0.0)
-
-**Parameters**:
-- `specification`: Feature spec (optional)
-- `code`: Source code (optional)
-
-**Note**: Provide either specification or code.
-
-📖 **Full Documentation**: [API_REFERENCE.md - memesh-generate-tests](./api/API_REFERENCE.md#memesh-generate-tests)
-
----
-
-### Learning & Error Tracking
-
-#### memesh-record-mistake
-
-**Purpose**: Record errors and mistakes for learning and prevention
-
-**Parameters**:
-- `action` (required): What action the AI took
-- `errorType` (required): Error classification (`procedure-violation`, `workflow-skip`, `assumption-error`, `validation-skip`, `responsibility-lack`, `firefighting`, `dependency-miss`, `integration-error`, `deployment-error`)
-- `userCorrection` (required): User's correction/feedback
-- `correctMethod` (required): What should have been done instead
-- `impact` (required): Impact of the mistake
-- `preventionMethod` (required): How to prevent in future
-- `relatedRule` (optional): Related rule/guideline
-- `context` (optional): Additional context object
-
-**Quick Example**:
-```json
-{
- "action": "Used synchronous file read in async handler",
- "errorType": "assumption-error",
- "userCorrection": "This blocks the event loop",
- "correctMethod": "Use fs.promises.readFile() instead of fs.readFileSync()",
- "impact": "Server becomes unresponsive under load",
- "preventionMethod": "Always use async I/O in request handlers"
-}
-```
-
-**When to Use**:
-- After fixing bugs
-- Learning from errors
-- Building team knowledge
-- Preventing repeated mistakes
-
-**Benefits**:
-- Automatically stored in knowledge graph
-- Searchable via buddy-remember
-- Helps prevent repeating errors
-- Builds institutional knowledge
-
-📖 **Full Documentation**: [API_REFERENCE.md - memesh-record-mistake](./api/API_REFERENCE.md#memesh-record-mistake)
-
----
-
-### Complete API Reference
-
-For comprehensive documentation including:
-- Detailed input/output schemas
-- JSON examples for all tools
-- Error codes and handling
-- Integration patterns
-- Performance characteristics
-
-See **[API_REFERENCE.md](./api/API_REFERENCE.md)**
-
----
-
-## CLI Commands
-
-### memesh setup
-
-**Purpose**: Interactive configuration wizard
-
-**Features**:
-- Auto-detects Claude Code installation
-- Generates MCP configuration
-- Validates setup
-- Tests connection
-
-**Usage**:
-```bash
-memesh setup
-```
-
-**When to Use**:
-- First-time installation
-- Troubleshooting connection issues
-- Reconfiguring after updates
-
-See [QUICK_START.md](./QUICK_START.md) for detailed setup guide.
-
----
-
-### memesh tutorial
-
-**Purpose**: Interactive 5-minute guided tutorial
-
-**Features**:
-- 7-step walkthrough
-- Hands-on practice with buddy-do and buddy-remember
-- Progress tracking
-- Completion certificate
-
-**Usage**:
-```bash
-memesh tutorial
-```
-
-**Steps**:
-1. Welcome & Overview
-2. Setup Verification
-3. First buddy-do Command
-4. Memory Storage Demo
-5. Memory Recall Demo
-6. Advanced Features Preview
-7. Next Steps & Resources
-
-**When to Use**:
-- Learning MeMesh for the first time
-- Refreshing your knowledge
-- Training team members
-
----
-
-### memesh dashboard
-
-**Purpose**: View session health and metrics
-
-**Features**:
-- Real-time MCP server status
-- Memory usage statistics
-- Recent command history
-- Performance metrics
-- Error log summary
-
-**Usage**:
-```bash
-memesh dashboard
-```
-
----
-
-### memesh stats
-
-**Purpose**: View usage statistics
-
-**Features**:
-- Command frequency analysis
-- Token usage trends
-- Cost tracking
-- Capability usage breakdown
-- Memory growth over time
-
-**Usage**:
-```bash
-memesh stats
-memesh stats --day # Last 24 hours
-memesh stats --week # Last 7 days
-memesh stats --month # Last 30 days
-memesh stats --json # Export as JSON
-memesh stats --csv # Export as CSV
-memesh stats --verbose # Detailed statistics
-```
-
----
-
-### memesh config
-
-**Purpose**: Manage MeMesh configuration
-
-**Subcommands**:
-
-```bash
-# Show current configuration
-memesh config show
-
-# Validate MCP setup
-memesh config validate
-
-# Edit configuration in default editor
-memesh config edit
-
-# Reset configuration to defaults
-memesh config reset
-```
-
-**When to Use**:
-- Verifying setup after installation
-- Troubleshooting connection issues
-- Checking configuration paths
-
----
-
-### memesh report-issue
-
-**Purpose**: Report bugs or issues
-
-**Usage**:
-```bash
-memesh report-issue
-```
-
-**What it does**:
-- Provides GitHub issues link
-- Collects system information (future)
-- Suggests troubleshooting steps
-
----
-
-## Memory System
-
-### Knowledge Graph Architecture
-
-MeMesh uses a graph-based knowledge storage system:
-
-```
- ┌─────────────┐
- │ Entities │ (Users, APIs, Technologies, etc.)
- └──────┬──────┘
- │
- │ has properties
- │
- ┌──────▼──────┐
- │ Properties │ (name, type, metadata)
- └──────┬──────┘
- │
- │ connected by
- │
- ┌──────▼──────┐
- │ Relations │ (USES, DEPENDS_ON, CREATED_BY)
- └─────────────┘
-```
-
-### Entity Types
-
-**Automatic Classification**:
-- `Decision`: Architecture choices, technology selections
-- `Pattern`: Code patterns, conventions, standards
-- `Lesson`: Bug fixes, learnings, best practices
-- `Configuration`: Settings, environment variables
-- `Technology`: Tools, frameworks, libraries
-- `Feature`: Application features, capabilities
-- `Bug`: Issues, problems, error cases
-- `Person`: Team members, stakeholders
-- `Project`: Projects, repositories, systems
-
-### Relationship Types
-
-- `USES`: Entity A uses Entity B
-- `DEPENDS_ON`: Entity A depends on Entity B
-- `CREATED_BY`: Entity A created by Entity B
-- `RELATES_TO`: General relationship
-- `PART_OF`: Entity A is part of Entity B
-
-### Auto-Tracking (Phase 0.6)
-
-**Task Start Tracking**:
-When you use `buddy-do`, MeMesh automatically records:
-- Task description
-- Goal (extracted)
-- Reason (if provided)
-- Expected outcome (if mentioned)
-- Start timestamp
-
-**Memory Linking**:
-Memories created during a task are automatically linked to that task.
-
-**Example**:
-```bash
-buddy-do "implement login feature because users need authentication"
-
-# Auto-tracked:
-{
- task: "implement login feature",
- goal: "implement login feature",
- reason: "users need authentication",
- timestamp: "2026-01-20T10:00:00Z"
-}
-
-# Later memories automatically linked:
-buddy-remember "Using bcrypt for password hashing"
-# → Links to login feature task
-```
-
----
-
-## Task Execution
-
-### How Task Execution Works
-
-**1. Task Analysis**:
-```
-Input: "setup user authentication with JWT"
-
-Analysis:
-- Complexity: Medium (~2500 tokens)
-- Domain: Backend development
-- Required capabilities: [authentication, backend, database]
-- Keywords: [authentication, JWT, user, setup]
-```
-
-**2. Capability Matching**:
-```
-Available capabilities:
-- backend-developer: 90% match (authentication, database)
-- frontend-developer: 20% match (user interface)
-- devops: 30% match (deployment considerations)
-
-Selected: backend-developer (highest match)
-```
-
-**3. Prompt Enhancement**:
-```
-Enhanced Prompt:
-[System Context]
-Project: e-commerce-platform
-Tech Stack: Node.js, Express, PostgreSQL
-Recent Work: User registration endpoint completed
-
-[Task]
-Setup user authentication with JWT
-
-[Context]
-- Existing user model in database
-- JWT library already installed (jsonwebtoken)
-- Environment variables configured for secrets
-```
-
-### Capability Catalog
-
-**backend-developer**:
-- API development
-- Database design
-- Server-side logic
-- Authentication/authorization
-- Data validation
-
-**frontend-developer**:
-- UI components
-- State management
-- Styling and layout
-- Client-side logic
-- Responsive design
-
-**devops**:
-- CI/CD pipelines
-- Deployment automation
-- Infrastructure configuration
-- Monitoring and logging
-- Container orchestration
-
-**database-admin**:
-- Schema design
-- Query optimization
-- Migrations
-- Backups and recovery
-- Performance tuning
-
-**security-expert**:
-- Vulnerability assessment
-- Authentication systems
-- Data encryption
-- Security audits
-- Compliance
-
-**general-agent**:
-- Default fallback
-- General questions
-- Documentation
-- Planning and analysis
-
----
-
-## Configuration
-
-### MCP Configuration
-
-MeMesh is a Claude Code Plugin. The MCP server is auto-managed via the plugin's `.mcp.json` file — no manual configuration of `~/.claude/mcp_settings.json` is needed.
-
-Simply install MeMesh and restart Claude Code. If auto-configuration fails, run `memesh setup`.
-
-**For Claude Desktop** (not Claude Code CLI), see the Claude Desktop documentation for MCP configuration locations:
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-**Environment Variables**:
-
-- `DEBUG`: Enable debug logging (true/false)
-- `MEMESH_DATA_DIR`: Custom data directory (default: ~/.memesh)
-- `MEMESH_LOG_LEVEL`: Log level (error/warn/info/debug)
-
----
-
-## Visual Explorer (Streamlit UI)
-
-MeMesh includes an interactive web UI for exploring your knowledge graph visually.
-
-### Setup
-
-```bash
-cd streamlit
-pip install -r requirements.txt
-streamlit run app.py
-```
-
-### Dashboard
-
-The dashboard provides an overview of your knowledge base:
-
-- **Statistics cards**: Entity, relation, observation, and tag counts
-- **Entity Type Distribution**: Pie chart showing the breakdown of entity types
-- **Top Tags**: Bar chart of most frequently used tags over time
-- **Entity Growth**: Cumulative growth chart (day/week/month granularity)
-- **Recent Entities**: Table of latest entities with tag and observation counts
-
-### KG Explorer
-
-The Knowledge Graph Explorer provides an interactive graph visualization:
-
-- **Interactive graph**: Drag, zoom, and hover over nodes and edges
-- **Color-coded nodes**: Each entity type has a distinct color
-- **Relation edges**: Color-coded by relation type (similar_to, solves, caused_by, etc.)
-- **Filters**: Search by text (FTS5), entity type, tags, and date range
-- **Adjustable density**: Slider to control the number of displayed nodes (10–300)
-
-### Backfilling Relations
-
-If you have existing entities without relations, run the backfill script:
-
-```bash
-# Preview what will be created
-python streamlit/backfill_relations.py --dry-run
-
-# Execute (creates relations in the database)
-python streamlit/backfill_relations.py
-```
-
-The script uses a 3-layer strategy: topic/project clustering, cross-type semantic relations, and tag-based similarity.
-
----
-
-## Advanced Usage
-
-### Workflow Examples
-
-#### Workflow 1: Starting a New Feature
-
-```bash
-# 1. Recall relevant context
-buddy-remember "similar features"
-buddy-remember "architectural patterns"
-
-# 2. Plan implementation
-buddy-do "plan user profile feature with avatar upload"
-
-# 3. Execute implementation
-buddy-do "implement user profile API endpoints"
-buddy-do "create profile UI component"
-
-# 4. Store decisions
-buddy-remember "User profile feature uses S3 for avatar storage because it scales better"
-
-# 5. Document patterns
-buddy-remember "Profile endpoints follow /api/v1/users/:id/profile pattern"
-```
-
-#### Workflow 2: Debugging a Bug
-
-```bash
-# 1. Search for similar issues
-buddy-remember "login errors"
-buddy-remember "session timeout"
-
-# 2. Analyze and fix
-buddy-do "investigate why sessions expire immediately after login"
-
-# 3. Record solution
-buddy-remember "Login session bug was caused by cookie domain mismatch. Fixed by setting domain to null in session config."
-```
-
-#### Workflow 3: Code Review
-
-```bash
-# 1. Recall standards
-buddy-remember "code review checklist"
-buddy-remember "security best practices"
-
-# 2. Review implementation
-buddy-do "review authentication implementation for security issues"
-
-# 3. Store findings
-buddy-remember "Security review found: need rate limiting on login endpoint to prevent brute force"
-```
-
-### Integration with Other Tools
-
-**Git Integration**:
-```bash
-# Store commit messages as memories
-buddy-remember "feat(auth): add JWT authentication"
-
-# Recall to maintain consistency
-buddy-remember "recent authentication changes"
-```
-
-**CI/CD Integration** (Future):
-```bash
-# Store deployment info
-buddy-remember "Deployment v1.2.3 to production on 2026-01-20, includes authentication feature"
-
-# Query deployment history
-buddy-remember "recent deployments"
-```
-
-**Testing Integration**:
-```bash
-# Store test results
-buddy-remember "Test suite passing: 245/245 tests, coverage 87%"
-
-# Track test patterns
-buddy-remember "Authentication tests use mock JWT tokens"
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-For detailed troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
-
-**Quick Fixes**:
-
-1. **buddy-help not working**
- ```bash
- memesh setup
- # Restart Claude Code
- # Try: buddy-help
- ```
-
-2. **Connection errors**
- ```bash
- memesh config validate
- # Check configuration
- # Restart Claude Code
- ```
-
-3. **Slow responses**
- - Simplify task descriptions
- - Check network connection
- - Review token limits
-
-### Debug Mode
-
-Enable debug logging by setting environment variables `DEBUG=true` and `MEMESH_LOG_LEVEL=debug` in the plugin's `.mcp.json` configuration.
-
-Check logs:
-- **macOS**: `~/Library/Logs/Claude/`
-- **Windows**: `%APPDATA%\Claude\Logs\`
-
-### Getting Help
-
-1. **Check Documentation**:
- - [QUICK_START.md](./QUICK_START.md) - Getting started
- - [BEST_PRACTICES.md](./BEST_PRACTICES.md) - Effective workflows
- - [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Common issues
-
-2. **Run Commands**:
- ```bash
- memesh tutorial # Interactive learning
- memesh config validate # Check setup
- memesh report-issue # Get support
- ```
-
-3. **Community Support**:
- - GitHub Issues: https://github.com/PCIRCLE-AI/claude-code-buddy/issues
- - Discussions: https://github.com/PCIRCLE-AI/claude-code-buddy/discussions
-
----
-
-## Appendix
-
-### Command Quick Reference
-
-```
-┌─────────────────────────────────────────────────────┐
-│ MeMesh Command Reference │
-├─────────────────────────────────────────────────────┤
-│ MCP Tools (In Claude Code) │
-│ buddy-do "" Execute with memory context│
-│ buddy-remember "" Store/recall memory │
-│ buddy-help Quick help guide │
-│ │
-│ CLI Commands (In Terminal) │
-│ memesh setup Interactive setup wizard │
-│ memesh tutorial 5-minute guided tour │
-│ memesh dashboard Session health dashboard │
-│ memesh stats Usage statistics │
-│ memesh config Manage configuration │
-│ memesh report-issue Bug reporting │
-└─────────────────────────────────────────────────────┘
-```
-
-### Glossary
-
-- **MCP**: Model Context Protocol - Standard for AI tool integration
-- **Knowledge Graph**: Graph database storing entities and relationships
-- **Capability**: Specialized skill set for task execution
-- **Entity**: Node in knowledge graph (user, technology, decision, etc.)
-- **Relation**: Edge connecting entities (USES, DEPENDS_ON, etc.)
-- **Task Metadata**: Extracted information from task description
-- **Prompt Enhancement**: Adding project context to task prompts
-
-### Version History
-
-- **v2.8.0**: Tool naming unification (memesh-* prefix), A2A removal (local-first architecture), Vector semantic search with ONNX embeddings
-- **v2.7.0**: Memory retention periods updated (30/90 days), Auto-memory hooks improvements, Documentation updates
-- **v2.6.6**: ErrorClassifier integration, Enhanced error handling
-- **v2.6.5**: Interactive tutorial, Improved QUICK_START
-- **v2.6.4**: Response formatting improvements, Visual hierarchy
-- **v2.6.3**: Interactive setup wizard
-- **v2.6.2**: Phase 0.6 - Auto-tracking and memory linking
-- **v2.6.1**: Performance optimizations
-- **v2.6.0**: Smart routing with capability matching
-
----
-
-**Next Steps**:
-
-1. **Learn More**: Read [BEST_PRACTICES.md](./BEST_PRACTICES.md) for effective workflows
-2. **Try It Out**: Run `memesh tutorial` for hands-on practice
-3. **Get Support**: Visit our [GitHub Discussions](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
-4. **Contribute**: Check [CONTRIBUTING.md](../CONTRIBUTING.md) to get involved
-
----
-
-**MeMesh** — Persistent memory for Claude Code
diff --git a/docs/api/API_REFERENCE.md b/docs/api/API_REFERENCE.md
index a76b2190..eb4e4264 100644
--- a/docs/api/API_REFERENCE.md
+++ b/docs/api/API_REFERENCE.md
@@ -1,1951 +1,244 @@
-# MeMesh Plugin - API Reference
+# MeMesh Plugin -- API Reference
-**Protocol**: Model Context Protocol (MCP)
+**Protocol**: Model Context Protocol (MCP) over stdio
+**Version**: 3.0.0
---
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Authentication & Connection](#authentication--connection)
-3. [Tool Catalog](#tool-catalog)
-4. [Core Tools](#core-tools)
- - [buddy-do](#buddy-do)
- - [buddy-remember](#buddy-remember)
- - [buddy-help](#buddy-help)
-5. [Knowledge Graph Tools](#knowledge-graph-tools)
- - [memesh-create-entities](#memesh-create-entities)
-6. [Learning & Automation Tools](#learning--automation-tools)
- - [memesh-record-mistake](#memesh-record-mistake)
- - [memesh-hook-tool-use](#memesh-hook-tool-use)
-7. [System Tools](#system-tools)
- - [memesh-generate-tests](#memesh-generate-tests)
- - [memesh-metrics](#memesh-metrics)
-8. [Data Models](#data-models)
-9. [Error Reference](#error-reference)
-10. [Integration Examples](#integration-examples)
-11. [Rate Limits & Performance](#rate-limits--performance)
+## Tools
----
-
-## Introduction
-
-MeMesh Plugin is an MCP (Model Context Protocol) server that provides persistent memory management, context-aware task execution, and knowledge graph capabilities for Claude Code. This API reference documents all available MCP tools, their parameters, responses, and usage patterns.
-
-**Key Features**:
-- Context-aware task execution with memory integration
-- Persistent knowledge graph storage
-- Automatic memory linking and tagging
-- Session health monitoring
-- Test generation capabilities
-
-**Architecture**:
-```
-Claude Code CLI
- ↓
-MCP Protocol
- ↓
-MeMesh Plugin
- ↓
- ┌──────┴──────┐
- ↓ ↓
-Router Knowledge Graph
-```
-
----
-
-## Authentication & Connection
-
-MeMesh Plugin is a Claude Code Plugin. The MCP server is auto-managed via the plugin's `.mcp.json` file — no manual configuration of `~/.claude/mcp_settings.json` is needed.
-
-Simply install MeMesh Plugin and restart Claude Code. The plugin system handles MCP server registration automatically.
-
-**If auto-configuration fails**, run `memesh setup` to reconfigure.
-
-**Advanced Configuration**:
-```json
-{
- "mcpServers": {
- "memesh": {
- "command": "npx",
- "args": ["-y", "@pcircle/memesh"],
- "env": {
- "DEBUG": "true",
- "MEMESH_DATA_DIR": "/custom/path/to/data",
- "MEMESH_LOG_LEVEL": "debug"
- }
- }
- }
-}
-```
-
-**Environment Variables**:
-
-| Variable | Type | Default | Description |
-|----------|------|---------|-------------|
-| `DEBUG` | boolean | `false` | Enable debug logging |
-| `MEMESH_DATA_DIR` | string | `~/.memesh` | Data directory for knowledge graph |
-| `MEMESH_LOG_LEVEL` | string | `info` | Log level: error, warn, info, debug |
-
----
-
-## Tool Catalog
-
-MeMesh provides 8 MCP tools organized into three categories:
-
-### Core Tools (User-Facing)
-
-| Tool | Purpose | Complexity |
-|------|---------|-----------|
-| `buddy-do` | Execute tasks with memory context | Simple |
-| `buddy-remember` | Store and recall project memory | Simple |
-| `buddy-help` | Get help and command reference | Simple |
-
-### Knowledge Graph Tools (Advanced)
-
-| Tool | Purpose | Complexity |
-|------|---------|-----------|
-| `memesh-create-entities` | Create knowledge entities with auto-relations | Advanced |
-
-### Learning & Automation Tools
-
-| Tool | Purpose | Complexity |
-|------|---------|-----------|
-| `memesh-record-mistake` | Record mistakes for continuous learning | Medium |
-| `memesh-hook-tool-use` | Process tool execution events (auto-triggered) | Internal |
-
-### System Tools
-
-| Tool | Purpose | Complexity |
-|------|---------|-----------|
-| `memesh-generate-tests` | Generate test cases from specs or code | Medium |
-| `memesh-metrics` | View session metrics and memory status | Simple |
-
----
-
-## Core Tools
-
-### buddy-do
-
-**Purpose**: Execute tasks with intelligent routing to specialized capabilities.
-
-**Use Cases**:
-- Development tasks (backend, frontend, DevOps)
-- Architectural decisions
-- Code reviews and debugging
-- Documentation tasks
-- Complex planning and analysis
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "task": {
- "type": "string",
- "description": "Task description to analyze and enrich (e.g., 'setup authentication', 'fix login bug')"
- }
- },
- "required": ["task"]
-}
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Description | Example |
-|-----------|------|----------|-------------|---------|
-| `task` | string | Yes | Task description in natural language | "implement user authentication with JWT" |
-
-#### Response Format
-
-```typescript
-{
- content: [
- {
- type: "text",
- text: string // Formatted response with routing decision
- }
- ]
-}
-```
-
-**Response Structure** (parsed from formatted text):
-- Task description
-- Routing decision (approved/rejected)
-- Capability focus (e.g., backend, frontend)
-- Complexity level (simple, medium, complex)
-- Estimated tokens
-- Estimated cost
-- Enhanced prompt (for Claude to execute)
-- Duration and statistics
-
-#### Examples
-
-**Example 1: Backend Development Task**
-
-Request:
-```json
-{
- "task": "implement user authentication with JWT tokens"
-}
-```
-
-Response:
-```
-✓ BUDDY-DO SUCCESS
-
-📋 Task
-implement user authentication with JWT tokens
-
-────────────────────────────────────
-
-✓ Results
- routing:
- approved: true
- message: Task routed for capabilities: backend, authentication
- capabilityFocus: ["backend", "authentication"]
- complexity: medium
- estimatedTokens: 2500
- estimatedCost: 0.0125
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Review implementation for security best practices
- 2. Add tests for authentication flows
- 3. Store decision: buddy-remember
-
-Duration: 1.2s • Tokens: 2,500
-```
-
-**Example 2: Frontend Component**
-
-Request:
-```json
-{
- "task": "create responsive navigation bar with dark mode toggle"
-}
-```
-
-Response:
-```
-✓ BUDDY-DO SUCCESS
-
-📋 Task
-create responsive navigation bar with dark mode toggle
-
-────────────────────────────────────
-
-✓ Results
- routing:
- approved: true
- message: Task routed for capabilities: frontend, ui-design
- capabilityFocus: ["frontend", "ui-design"]
- complexity: medium
- estimatedTokens: 1800
- estimatedCost: 0.009
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Test across different screen sizes
- 2. Verify accessibility standards
- 3. Store component patterns: buddy-remember
-
-Duration: 0.9s • Tokens: 1,800
-```
-
-**Example 3: Bug Investigation**
-
-Request:
-```json
-{
- "task": "investigate why sessions expire immediately after login"
-}
-```
-
-Response:
-```
-✓ BUDDY-DO SUCCESS
-
-📋 Task
-investigate why sessions expire immediately after login
-
-────────────────────────────────────
-
-✓ Results
- routing:
- approved: true
- message: Task routed for capabilities: debugging, backend
- capabilityFocus: ["debugging", "backend"]
- complexity: medium
- estimatedTokens: 2200
- estimatedCost: 0.011
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Check session configuration
- 2. Review cookie settings
- 3. Document fix: buddy-remember
-
-Duration: 1.5s • Tokens: 2,200
-```
-
-#### Task Metadata Extraction
-
-buddy-do automatically extracts metadata from task descriptions:
-
-| Field | Pattern | Example |
-|-------|---------|---------|
-| `goal` | First sentence or "to X" | "implement login feature" |
-| `reason` | "because X", "so that X" | "users need authentication" |
-| `expectedOutcome` | "should X", "will X" | "users can log in securely" |
-
-**Example**:
-```json
-{
- "task": "add email verification because users need to confirm their accounts"
-}
-```
-
-Extracted metadata:
-```typescript
-{
- goal: "add email verification",
- reason: "users need to confirm their accounts",
- expectedOutcome: undefined // Not explicitly stated
-}
-```
-
-#### Complexity Levels
-
-| Level | Token Range | Characteristics | Examples |
-|-------|-------------|-----------------|----------|
-| Simple | < 1,000 | Quick tasks, simple queries | "format this JSON", "explain this function" |
-| Medium | 1,000-5,000 | Standard features, refactoring | "add user profile page", "refactor auth service" |
-| Complex | > 5,000 | Architecture, large features | "redesign database schema", "build payment system" |
-
-#### Best Practices
-
-✅ **Do**:
-- Use clear, specific task descriptions
-- Include context when relevant (e.g., "because we need...")
-- Mention expected outcomes
-- Use for all development tasks
-
-❌ **Don't**:
-- Use for simple questions (use buddy-help instead)
-- Use for memory searches (use buddy-remember instead)
-- Write vague descriptions ("fix stuff")
-- Include sensitive credentials in task text
-
-#### Error Responses
-
-```typescript
-// Invalid input
-{
- error: "Validation failed: task is required",
- code: "VALIDATION_FAILED"
-}
-
-// Routing failure
-{
- error: "Unable to route task: no matching capabilities",
- code: "ROUTING_FAILED"
-}
-
-// System error
-{
- error: "Router unavailable",
- code: "OPERATION_FAILED"
-}
-```
-
----
-
-### buddy-remember
-
-**Purpose**: Store and recall knowledge from your project's memory graph.
-
-**Use Cases**:
-- Store architectural decisions
-- Record bug fixes and solutions
-- Save API design patterns
-- Document project conventions
-- Search for past decisions
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "query": {
- "type": "string",
- "description": "Search query (natural language supported for semantic search)"
- },
- "mode": {
- "type": "string",
- "enum": ["semantic", "keyword", "hybrid"],
- "description": "Search mode: semantic (AI similarity), keyword (exact match), hybrid (both combined). Default: hybrid"
- },
- "limit": {
- "type": "number",
- "description": "Maximum number of results to return (1-50, default: 10)",
- "minimum": 1,
- "maximum": 50
- },
- "matchThreshold": {
- "type": "number",
- "description": "Minimum match score (0-1). Higher values return fewer but more relevant results. Default: 0.3",
- "minimum": 0,
- "maximum": 1
- },
- "allProjects": {
- "type": "boolean",
- "description": "Search across all projects (default: false, searches only current project + global memories)"
- }
- },
- "required": ["query"]
-}
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Default | Description | Example |
-|-----------|------|----------|---------|-------------|---------|
-| `query` | string | Yes | - | Search query (natural language supported) | "why did we choose PostgreSQL?" |
-| `mode` | string | No | hybrid | Search mode: `semantic`, `keyword`, `hybrid` | "keyword" |
-| `limit` | number | No | 10 | Max number of results (1-50) | 20 |
-| `matchThreshold` | number | No | 0.3 | Minimum match score (0-1) | 0.5 |
-| `allProjects` | boolean | No | false | Search across all projects | true |
-
-#### Response Format
-
-```typescript
-{
- content: [
- {
- type: "text",
- text: string // Formatted response with memories
- }
- ]
-}
-```
-
-**Response Structure** (parsed from formatted text):
-- Query text
-- Memory count
-- Memory list (with timestamps, tags, content)
-- Suggestions (if no results)
-
-#### Examples
-
-**Example 1: Store Decision**
-
-Request:
-```json
-{
- "query": "We chose PostgreSQL because it supports JSON columns and has better performance for complex queries than MySQL"
-}
-```
-
-Response:
-```
-✓ Memory Stored Successfully
-
-📋 Task
-Store project decision
-
-────────────────────────────────────
-
-✓ Results
- status: stored
- knowledge_id: "kb_1738560000123"
- tags: ["decision", "database", "postgresql"]
- timestamp: "2026-02-03T10:30:00Z"
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Memory is now searchable
- 2. Try: buddy-remember "postgresql" to verify
-
-Duration: 0.8s • Tokens: 300
-```
-
-**Example 2: Recall Memories (With Results)**
-
-Request:
-```json
-{
- "query": "database decisions",
- "limit": 3
-}
-```
-
-Response:
-```
-✓ Memory Search Complete
-
-📋 Query
-database decisions
-
-────────────────────────────────────
-
-✓ Results
- count: 3
- memories:
- 1. [2026-02-01] Decision: PostgreSQL for production
- "We chose PostgreSQL because it supports JSON..."
- Tags: decision, database, postgresql
-
- 2. [2026-02-02] Configuration: Database pooling
- "Using pg-pool with max 20 connections..."
- Tags: configuration, database, performance
-
- 3. [2026-02-03] Lesson: Connection timeout fix
- "Fixed timeouts by increasing pool timeout to 30s..."
- Tags: lesson, database, bug_fix
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Review memories above for relevant context
- 2. Apply these learnings to your current task
-
-Duration: 1.1s • Tokens: 800
-```
-
-**Example 3: No Results Found**
-
-Request:
-```json
-{
- "query": "blockchain integration"
-}
-```
-
-Response:
-```
-✓ Memory Search Complete
-
-📋 Query
-blockchain integration
-
-────────────────────────────────────
-
-✓ Results
- count: 0
-
-────────────────────────────────────
-
-💡 Next Steps
- 1. Try a broader search term
- 2. Create new memory: buddy-remember
- 3. Use different keywords
-
-Duration: 0.5s • Tokens: 200
-```
-
-#### Storage vs. Recall Detection
-
-MeMesh automatically detects whether you're storing or recalling:
-
-**Storage Indicators**:
-- Declarative statements
-- Past tense verbs ("decided", "chose", "implemented")
-- Contains factual information
-- Longer descriptions (> 50 chars)
-
-**Recall Indicators**:
-- Question words ("why", "how", "what", "when")
-- Question marks
-- Short queries
-- Search keywords
-
-#### Auto-Tagging
-
-MeMesh automatically generates tags based on content:
-
-**Entity Types**:
-- Technologies: postgresql, jwt, react, node.js
-- Concepts: authentication, database, api, testing
-- Actions: created, fixed, decided, refactored
-
-**Tag Categories**:
-- `decision` - Architectural choices
-- `lesson` - Learnings from bugs/issues
-- `pattern` - Code patterns and conventions
-- `configuration` - Settings and configs
-
-#### Best Practices
-
-✅ **Storage Best Practices**:
-- Be specific and concise
-- Include context (why, when, what)
-- Store as you work (not later)
-- Use natural language
-- Include reasons for decisions
-
-✅ **Recall Best Practices**:
-- Use keywords from your question
-- Try broader terms if no results
-- Search before starting new work
-- Combine with buddy-do for context
-
-❌ **Avoid**:
-- Storing sensitive credentials
-- Vague descriptions
-- Duplicate storage
-- Overly long queries
-
-#### Error Responses
-
-```typescript
-// Invalid input
-{
- error: "Validation failed: query is required",
- code: "VALIDATION_FAILED"
-}
-
-// Storage error
-{
- error: "Failed to store memory: database unavailable",
- code: "OPERATION_FAILED"
-}
-
-// Search error
-{
- error: "Memory search failed",
- code: "OPERATION_FAILED"
-}
-```
-
----
-
-### buddy-help
-
-**Purpose**: Get help, command reference, and usage examples.
-
-**Use Cases**:
-- First-time setup verification
-- Quick command syntax reference
-- Learn available commands
-- View examples and patterns
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "command": {
- "type": "string",
- "description": "Specific command to get help for (e.g., 'do', 'remember', '--all' for full reference)",
- "optional": true
- }
- }
-}
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Description | Example |
-|-----------|------|----------|-------------|---------|
-| `command` | string | No | Command name or "--all" for full reference | "do", "--all" |
-
-#### Response Format
-
-```typescript
-{
- content: [
- {
- type: "text",
- text: string // Formatted help text
- }
- ]
-}
-```
-
-#### Examples
-
-**Example 1: Basic Help**
-
-Request:
-```json
-{
- "command": undefined
-}
-```
-
-Response:
-```
-🤖 MeMesh Quick Start
-
-Essential Commands
-
-┌────────────────────────────────────────────┐
-│ buddy-do "" │
-└────────────────────────────────────────────┘
-❯ buddy-do "add user authentication"
-→ Routes to backend-developer, creates auth system
-
-┌────────────────────────────────────────────┐
-│ buddy-remember "" │
-└────────────────────────────────────────────┘
-❯ buddy-remember "Using JWT for sessions"
-→ Stores in Knowledge Graph with auto-tags
-
-┌────────────────────────────────────────────┐
-│ buddy-remember "" │
-└────────────────────────────────────────────┘
-❯ buddy-remember "why JWT?"
-→ Searches and recalls past decisions
-
-💡 New to MeMesh?
-Run: memesh tutorial
-
-📖 Full reference: buddy-help --all
-```
-
-**Example 2: Full Reference**
-
-Request:
-```json
-{
- "command": "--all"
-}
-```
-
-Response: (Shows detailed reference for all commands with examples)
-
-**Example 3: Specific Command**
-
-Request:
-```json
-{
- "command": "do"
-}
-```
-
-Response: (Shows detailed help for buddy-do command)
-
-#### Best Practices
-
-✅ **When to Use**:
-- First time using MeMesh
-- Forgot command syntax
-- Need examples
-- Want to see all available commands
-
-❌ **Don't Use For**:
-- Actual task execution (use buddy-do)
-- Memory searches (use buddy-remember)
+MeMesh exposes 3 tools via MCP.
---
-## Knowledge Graph Tools
-
-### memesh-create-entities
-
-**Purpose**: Create knowledge entities with explicit structure and relationships.
-
-**Use Cases**:
-- Build complex knowledge graphs
-- Store structured architectural decisions
-- Record feature implementations
-- Document bug fixes with metadata
-- Migrate external knowledge
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "entities": {
- "type": "array",
- "description": "Array of entities to create",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "Entity name (unique identifier)"
- },
- "entityType": {
- "type": "string",
- "description": "Entity type"
- },
- "observations": {
- "type": "array",
- "items": { "type": "string" },
- "description": "Array of observations (facts, notes)"
- },
- "tags": {
- "type": "array",
- "items": { "type": "string" },
- "description": "Optional tags"
- },
- "metadata": {
- "type": "object",
- "description": "Optional metadata"
- }
- },
- "required": ["name", "entityType", "observations"]
- }
- }
- },
- "required": ["entities"]
-}
-```
-
-#### Parameters
-
-| Field | Type | Required | Description | Example |
-|-------|------|----------|-------------|---------|
-| `entities` | array | Yes | Array of entity objects | See examples |
-| `entities[].name` | string | Yes | Unique entity identifier | "OAuth Integration 2026-02-03" |
-| `entities[].entityType` | string | Yes | Type of entity (see types below) | "decision", "feature" |
-| `entities[].observations` | array | Yes | Facts and notes about entity | ["Uses OAuth 2.0", "Supports Google/GitHub"] |
-| `entities[].tags` | array | No | Additional tags | ["auth", "oauth", "security"] |
-| `entities[].metadata` | object | No | Custom metadata | { "author": "KT", "priority": "high" } |
-
-#### Entity Types
-
-| Type | Description | Use Cases |
-|------|-------------|-----------|
-| `decision` | Architectural/technical decisions | "Chose PostgreSQL over MySQL" |
-| `bug_fix` | Bug fixes and root causes | "Fixed session timeout issue" |
-| `feature` | Feature implementations | "User profile feature" |
-| `lesson_learned` | Lessons from incidents | "Always validate input data" |
-| `best_practice` | Validated best practices | "Use JWT for stateless auth" |
-| `problem_solution` | Problem-solution pairs | "Solved N+1 query problem" |
-| `technical_debt` | Technical debt items | "Refactor user service needed" |
-| `optimization` | Performance optimizations | "Added database indexing" |
-| `refactoring` | Refactoring decisions | "Split monolith into services" |
-| `code_change` | Code change events | "Updated auth middleware" |
-| `test_result` | Test execution results | "All tests passing (245/245)" |
-
-#### Response Format
-
-```typescript
-{
- created: string[], // Names of created entities
- count: number, // Number created
- autoRelationsCreated: number, // Auto-inferred relations created (v2.9.3+)
- errors?: Array<{ // Errors if any
- name: string,
- error: string
- }>
-}
-```
-
-#### Auto-Relation Inference (v2.9.3+)
-
-After creating entities, MeMesh automatically infers and creates relations between new entities and existing entities that share topic keywords. This is a best-effort feature — it never blocks entity creation.
-
-**How it works:**
-1. Topic keywords are extracted from entity names (first 2 words, 3+ characters)
-2. New entities are compared against each other and against existing entities
-3. Relations are inferred based on entity type combinations:
-
-| Entity A Type | Entity B Type | Relation Created |
-|--------------|--------------|-----------------|
-| `bug_fix` | `feature` | bug_fix `solves` feature |
-| `decision` | `feature` | feature `enabled_by` decision |
-| `lesson_learned` | `bug_fix` | lesson_learned `caused_by` bug_fix |
-| Same type | Same type | `similar_to` |
+### remember
-**Limits:**
-- Maximum 50 auto-relations per batch (`MAX_AUTO_RELATIONS`)
-- Session-specific types excluded (`session_keypoint`, `session_identity`, `task_start`, `session_summary`)
-- Duplicate relations silently skipped (UNIQUE constraint)
-```
-
-#### Examples
+Store knowledge as an entity with observations, tags, and relations.
-**Example 1: Architecture Decision**
+**Input Schema**:
-Request:
-```json
-{
- "entities": [
- {
- "name": "PostgreSQL Database Choice 2026-02-03",
- "entityType": "decision",
- "observations": [
- "Chose PostgreSQL over MySQL for production database",
- "Primary reasons: JSON column support, better performance for complex queries",
- "Supports full-text search natively",
- "Better concurrency handling with MVCC"
- ],
- "tags": ["database", "postgresql", "architecture"],
- "metadata": {
- "author": "KT",
- "date": "2026-02-03",
- "impact": "high"
- }
- }
- ]
-}
-```
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Unique entity name (e.g., `"auth-decision"`, `"jwt-pattern"`) |
+| `type` | string | Yes | Entity type (e.g., `"decision"`, `"pattern"`, `"lesson"`, `"commit"`) |
+| `observations` | string[] | No | Key facts or observations about this entity |
+| `tags` | string[] | No | Tags for filtering (e.g., `"project:myapp"`, `"type:decision"`) |
+| `relations` | object[] | No | Relations to other entities |
-Response:
-```json
-{
- "created": ["PostgreSQL Database Choice 2026-02-03"],
- "count": 1
-}
-```
+**Relations object**:
-**Example 2: Bug Fix with Context**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `to` | string | Yes | Target entity name (must already exist) |
+| `type` | string | Yes | Relation type (e.g., `"implements"`, `"related-to"`) |
-Request:
-```json
-{
- "entities": [
- {
- "name": "Session Timeout Bug Fix 2026-02-03",
- "entityType": "bug_fix",
- "observations": [
- "Bug: Sessions expired immediately after login",
- "Root cause: Cookie domain was set incorrectly",
- "Solution: Changed cookie domain to null in session config",
- "Testing: Verified sessions persist for 24 hours"
- ],
- "tags": ["bug", "session", "authentication", "fixed"],
- "metadata": {
- "severity": "critical",
- "affected_users": 0,
- "fix_duration": "2 hours"
- }
- }
- ]
-}
-```
+**Response**:
-Response:
```json
{
- "created": ["Session Timeout Bug Fix 2026-02-03"],
- "count": 1
+ "stored": true,
+ "entityId": 1,
+ "name": "auth-decision",
+ "type": "decision",
+ "observations": 2,
+ "tags": 1,
+ "relations": 0
}
```
-**Example 3: Multiple Entities**
+If a relation target does not exist, the entity is still stored and `relationErrors` is included in the response.
-Request:
-```json
-{
- "entities": [
- {
- "name": "User Authentication Feature",
- "entityType": "feature",
- "observations": [
- "Implemented JWT-based authentication",
- "Supports email/password and OAuth",
- "Includes refresh token mechanism"
- ],
- "tags": ["feature", "auth", "jwt"]
- },
- {
- "name": "Authentication API Endpoints",
- "entityType": "code_change",
- "observations": [
- "POST /api/v1/auth/login",
- "POST /api/v1/auth/refresh",
- "POST /api/v1/auth/logout"
- ],
- "tags": ["api", "auth", "endpoints"]
- }
- ]
-}
-```
+**Examples**:
-Response:
```json
+// Store a decision
{
- "created": [
- "User Authentication Feature",
- "Authentication API Endpoints"
+ "name": "auth-decision",
+ "type": "decision",
+ "observations": [
+ "Chose JWT for authentication",
+ "Using RS256 algorithm for token signing"
],
- "count": 2
-}
-```
-
-#### Auto-Tagging Behavior
-
-If no `scope:` tag is provided, MeMesh automatically adds `scope:project`.
-
-**Example**:
-```json
-{
- "tags": ["decision", "database"]
-}
-```
-
-Becomes:
-```json
-{
- "tags": ["decision", "database", "scope:project"]
-}
-```
-
-#### Best Practices
-
-✅ **Do**:
-- Use descriptive entity names with dates
-- Include comprehensive observations
-- Add relevant tags for searchability
-- Use metadata for structured data
-- Group related entities in single call
-
-❌ **Don't**:
-- Create duplicate entities (check first)
-- Use vague entity names
-- Skip observations (required field)
-- Store sensitive data in observations
-
-#### Error Responses
-
-```typescript
-// Invalid entity type
-{
- created: ["Entity 1"],
- count: 1,
- errors: [
- {
- name: "Entity 2",
- error: "Invalid entity type: unknown_type"
- }
- ]
-}
-
-// Validation failure
-{
- error: "Validation failed: observations is required",
- code: "VALIDATION_FAILED"
+ "tags": ["project:myapp", "topic:auth"]
}
-// Database error
+// Store a pattern with a relation
{
- created: [],
- count: 0,
- errors: [
- {
- name: "Entity Name",
- error: "Database unavailable"
- }
+ "name": "error-handling-pattern",
+ "type": "pattern",
+ "observations": ["All API errors return {error, code, message} format"],
+ "tags": ["project:myapp"],
+ "relations": [
+ {"to": "auth-decision", "type": "related-to"}
]
}
```
---
----
-
-## Learning & Automation Tools
+### recall
-### memesh-record-mistake
+Search and retrieve stored knowledge. Uses FTS5 full-text search with optional tag filtering. Call with no query to list recent memories.
-**Purpose**: Record AI mistakes for learning and prevention — enables systematic improvement from user feedback.
+**Input Schema**:
-**Aliases**: `buddy-record-mistake` (deprecated, will be removed in v3.0.0)
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | No | Search query (FTS5 full-text search). Leave empty to list recent entities. |
+| `tag` | string | No | Filter by tag (e.g., `"project:myapp"`) |
+| `limit` | number | No | Max results (default: 20, max: 100) |
-**Use Cases**:
-- User explicitly corrects AI behavior or approach
-- Violated a documented procedure or guideline
-- Made incorrect assumptions instead of asking
-- Skipped validation step and caused problems
+**Response**:
-#### Input Schema
+Returns an array of matching entities:
```json
-{
- "type": "object",
- "properties": {
- "action": {
- "type": "string",
- "description": "What action the AI took (the mistake)"
- },
- "errorType": {
- "type": "string",
- "description": "Error classification",
- "enum": [
- "procedure-violation",
- "workflow-skip",
- "assumption-error",
- "validation-skip",
- "responsibility-lack",
- "firefighting",
- "dependency-miss",
- "integration-error",
- "deployment-error"
- ]
- },
- "userCorrection": {
- "type": "string",
- "description": "User's correction/feedback"
- },
- "correctMethod": {
- "type": "string",
- "description": "What should have been done instead"
- },
- "impact": {
- "type": "string",
- "description": "Impact of the mistake"
- },
- "preventionMethod": {
- "type": "string",
- "description": "How to prevent this in the future"
- },
- "relatedRule": {
- "type": "string",
- "description": "Related rule/guideline (optional)"
- },
- "context": {
- "type": "object",
- "description": "Additional context (optional)"
- }
- },
- "required": ["action", "errorType", "userCorrection", "correctMethod", "impact", "preventionMethod"]
-}
+[
+ {
+ "id": 1,
+ "name": "auth-decision",
+ "type": "decision",
+ "created_at": "2026-03-09 12:00:00",
+ "observations": [
+ "Chose JWT for authentication",
+ "Using RS256 algorithm for token signing"
+ ],
+ "tags": ["project:myapp", "topic:auth"],
+ "relations": [
+ {"from": "auth-decision", "to": "api-design", "type": "related-to"}
+ ]
+ }
+]
```
-#### Parameters
-
-| Parameter | Type | Required | Description | Example |
-|-----------|------|----------|-------------|---------|
-| `action` | string | Yes | What action the AI took | "Edited file without reading first" |
-| `errorType` | string | Yes | Error classification (see enum) | "procedure-violation" |
-| `userCorrection` | string | Yes | User's correction/feedback | "Must read file before editing" |
-| `correctMethod` | string | Yes | What should have been done | "Use Read tool first" |
-| `impact` | string | Yes | Impact of the mistake | "Broke file indentation" |
-| `preventionMethod` | string | Yes | How to prevent in future | "ALWAYS Read before Edit" |
-| `relatedRule` | string | No | Related rule/guideline | "READ_BEFORE_EDIT" |
-| `context` | object | No | Additional context | `{}` |
+**Examples**:
-#### Example
-
-Request:
```json
-{
- "action": "Edited ServerInitializer.ts without reading file first",
- "errorType": "procedure-violation",
- "userCorrection": "Must read file before editing - broke indentation",
- "correctMethod": "Use Read tool first to see exact content and formatting, then Edit",
- "impact": "Broke file indentation, required re-edit, wasted user time",
- "preventionMethod": "ALWAYS invoke Read tool before Edit tool - no exceptions",
- "relatedRule": "READ_BEFORE_EDIT (Anti-Hallucination Protocol)"
-}
-```
-
----
+// Search by keyword
+{"query": "authentication"}
-### memesh-hook-tool-use
+// Search with tag filter
+{"query": "auth", "tag": "project:myapp"}
-**Purpose**: Process tool execution events from Claude Code CLI for workflow automation.
+// List recent (no query)
+{}
-**Aliases**: `hook-tool-use` (deprecated, will be removed in v3.0.0)
-
-**Note**: This tool is auto-triggered by Claude Code hooks. Do not call manually.
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "toolName": {
- "type": "string",
- "description": "Tool name executed by Claude Code (e.g., 'Write', 'Edit', 'Bash')"
- },
- "arguments": {
- "type": "object",
- "description": "Tool arguments payload (tool-specific)"
- },
- "success": {
- "type": "boolean",
- "description": "Whether the tool execution succeeded"
- },
- "duration": {
- "type": "number",
- "description": "Execution duration in milliseconds (optional)"
- },
- "tokensUsed": {
- "type": "number",
- "description": "Tokens used by the tool call (optional)"
- },
- "output": {
- "type": "string",
- "description": "Tool output (optional)"
- }
- },
- "required": ["toolName", "success"]
-}
+// List recent with limit
+{"limit": 5}
```
-#### Parameters
-
-| Parameter | Type | Required | Description | Example |
-|-----------|------|----------|-------------|---------|
-| `toolName` | string | Yes | Tool executed by Claude Code | "Write" |
-| `success` | boolean | Yes | Whether execution succeeded | true |
-| `arguments` | object | No | Tool arguments payload | `{"file_path": "..."}` |
-| `duration` | number | No | Duration in milliseconds | 150 |
-| `tokensUsed` | number | No | Tokens used by tool call | 500 |
-| `output` | string | No | Tool output | "File written" |
-
---
-## System Tools
-
-### memesh-generate-tests
-
-**Purpose**: Generate automated test cases from specifications or code.
-
-**Use Cases**:
-- Create test suites for new features
-- Generate tests from requirements
-- Create unit tests from code
-- Build comprehensive test coverage
-- Accelerate test development
-
-#### Input Schema
-
-```json
-{
- "type": "object",
- "properties": {
- "specification": {
- "type": "string",
- "description": "Feature specification or requirements"
- },
- "code": {
- "type": "string",
- "description": "Source code to generate tests for"
- }
- }
-}
-```
-
-**Note**: Either `specification` or `code` must be provided (but not both).
-
-#### Parameters
+### forget
-| Parameter | Type | Required | Description | Example |
-|-----------|------|----------|-------------|---------|
-| `specification` | string | Conditional | Feature spec or requirements | "User can log in with email/password" |
-| `code` | string | Conditional | Source code to test | "function authenticate(user) { ... }" |
+Delete an entity and all its associated observations, relations, and tags.
-#### Response Format
-
-```typescript
-{
- testCode: string, // Generated test code
- message: string // Success message and instructions
-}
-```
+**Input Schema**:
-#### Examples
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Entity name to delete |
-**Example 1: Generate from Specification**
+**Response**:
-Request:
```json
-{
- "specification": "User authentication feature:\n- User can log in with email and password\n- Invalid credentials return error\n- Successful login returns JWT token\n- Token expires after 24 hours"
-}
-```
+// Entity found and deleted
+{"deleted": true, "name": "auth-decision"}
-Response:
-```json
-{
- "testCode": "describe('User Authentication', () => {\n it('should log in with valid credentials', async () => {\n const result = await authenticate({\n email: 'user@example.com',\n password: 'correctPassword'\n });\n expect(result.token).toBeDefined();\n expect(result.token).toMatch(/^eyJ/);\n });\n\n it('should reject invalid credentials', async () => {\n await expect(authenticate({\n email: 'user@example.com',\n password: 'wrongPassword'\n })).rejects.toThrow('Invalid credentials');\n });\n\n it('should return token that expires in 24 hours', async () => {\n const result = await authenticate(validCredentials);\n const decoded = jwt.decode(result.token);\n const expiresIn = decoded.exp - decoded.iat;\n expect(expiresIn).toBe(86400); // 24 hours in seconds\n });\n});",
- "message": "Test cases generated successfully. Review and adjust as needed."
-}
+// Entity not found
+{"deleted": false, "message": "Entity \"auth-decision\" not found"}
```
-**Example 2: Generate from Code**
-
-Request:
-```json
-{
- "code": "export function calculateDiscount(price: number, couponCode: string): number {\n if (price <= 0) throw new Error('Invalid price');\n \n const discounts: Record = {\n 'SAVE10': 0.1,\n 'SAVE20': 0.2,\n 'SAVE50': 0.5\n };\n \n const discount = discounts[couponCode] || 0;\n return price * (1 - discount);\n}"
-}
-```
+**Example**:
-Response:
```json
-{
- "testCode": "describe('calculateDiscount', () => {\n it('should apply 10% discount for SAVE10', () => {\n expect(calculateDiscount(100, 'SAVE10')).toBe(90);\n });\n\n it('should apply 20% discount for SAVE20', () => {\n expect(calculateDiscount(100, 'SAVE20')).toBe(80);\n });\n\n it('should apply 50% discount for SAVE50', () => {\n expect(calculateDiscount(100, 'SAVE50')).toBe(50);\n });\n\n it('should return original price for invalid coupon', () => {\n expect(calculateDiscount(100, 'INVALID')).toBe(100);\n });\n\n it('should throw error for negative price', () => {\n expect(() => calculateDiscount(-10, 'SAVE10')).toThrow('Invalid price');\n });\n\n it('should throw error for zero price', () => {\n expect(() => calculateDiscount(0, 'SAVE10')).toThrow('Invalid price');\n });\n});",
- "message": "Test cases generated successfully. Review and adjust as needed."
-}
+{"name": "auth-decision"}
```
-#### Test Generation Strategy
-
-MeMesh uses sampling to generate comprehensive test suites that cover:
-
-**Functional Testing**:
-- Happy path scenarios
-- Edge cases
-- Boundary conditions
-- Error handling
-
-**Coverage Goals**:
-- Input validation
-- Business logic
-- Error conditions
-- Return values
-
-#### Best Practices
-
-✅ **Do**:
-- Review generated tests before using
-- Adjust assertions to match your framework
-- Add additional edge cases as needed
-- Run tests to verify they work
-- Customize test descriptions
-
-❌ **Don't**:
-- Use generated tests without review
-- Assume 100% coverage
-- Skip manual test cases
-- Ignore failing generated tests
-
-#### Supported Test Frameworks
-
-Generated tests are framework-agnostic but follow common patterns compatible with:
-- Jest
-- Mocha/Chai
-- Vitest
-- Jasmine
+---
-Adjust imports and syntax as needed for your framework.
+## Data Model
-#### Error Responses
+### Entity
-```typescript
-// Missing required input
-{
- error: "Either specification or code must be provided",
- code: "VALIDATION_FAILED"
-}
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | number | Auto-incremented primary key |
+| `name` | string | Unique entity name |
+| `type` | string | Entity type |
+| `created_at` | string | ISO timestamp |
+| `metadata` | object | Optional JSON metadata |
+| `observations` | string[] | Associated observations |
+| `tags` | string[] | Associated tags |
+| `relations` | Relation[] | Outgoing relations (optional) |
-// Generation failed
-{
- error: "Test generation failed: unable to parse code",
- code: "OPERATION_FAILED"
-}
+### Relation
-// Both inputs provided
-{
- error: "Provide either specification or code, not both",
- code: "VALIDATION_FAILED"
-}
-```
+| Field | Type | Description |
+|-------|------|-------------|
+| `from` | string | Source entity name |
+| `to` | string | Target entity name |
+| `type` | string | Relation type |
+| `metadata` | object | Optional JSON metadata |
---
-### memesh-metrics
-
-**Purpose**: View MeMesh session metrics, routing configuration, and memory status.
+## Error Handling
-#### Input Schema
+All tools return errors in a standard format:
```json
{
- "type": "object",
- "properties": {
- "section": {
- "type": "string",
- "enum": ["all", "session", "routing", "memory"],
- "description": "Which metrics section to return (default: 'all')"
- }
- }
+ "content": [{"type": "text", "text": "error message"}],
+ "isError": true
}
```
-#### Parameters
-
-| Parameter | Type | Required | Default | Description | Example |
-|-----------|------|----------|---------|-------------|---------|
-| `section` | string | No | "all" | Which metrics section to return | "session" |
-
-#### Section Details
-
-- **all** (default): Returns everything below
-- **session**: Current session state — modified files, tested files, code review status
-- **routing**: Active model rules, planning enforcement, dry-run gate, recent audit log
-- **memory**: Knowledge graph size and status
-
-#### Example
-
-Request:
-```json
-{
- "section": "memory"
-}
-```
+Common errors:
+- Unknown tool name
+- Zod validation failure (missing required fields, invalid types)
+- Entity not found (for relations in `remember`)
---
-## Data Models
-
-### Entity Model
-
-```typescript
-interface Entity {
- id?: number; // Auto-generated ID
- name: string; // Unique entity name
- entityType: EntityType; // Type of entity
- observations: string[]; // Facts and notes
- tags?: string[]; // Searchable tags
- metadata?: Record; // Custom metadata
- createdAt?: Date; // Creation timestamp
-}
+## CLI Commands
-type EntityType =
- // Knowledge types
- | 'decision' // Architecture/technical decisions
- | 'bug_fix' // Bug fixes and root causes
- | 'feature' // Feature implementations
- | 'lesson_learned' // Lessons from incidents
- | 'best_practice' // Validated best practices
- | 'problem_solution' // Problem-solution pairs
- | 'technical_debt' // Technical debt items
- | 'optimization' // Performance optimizations
- | 'refactoring' // Refactoring decisions
- | 'learning_experience' // Learning patterns
- // Memory/tracking types
- | 'code_change' // Code change events
- | 'test_result' // Test execution results
- | 'session_snapshot' // Session state snapshots
- | 'project_snapshot' // Project state snapshots
- | 'workflow_checkpoint' // Workflow completions
- | 'commit' // Git commit events
- | 'prevention_rule' // Prevention rules
- | 'user_preference'; // User preferences
-```
+### memesh-view
-### Relation Model
+Generate and open an interactive HTML dashboard for exploring stored knowledge.
-```typescript
-interface Relation {
- id?: number; // Auto-generated ID
- from: string; // Source entity name
- to: string; // Target entity name
- relationType: RelationType; // Type of relationship
- metadata?: Record; // Custom metadata
- createdAt?: Date; // Creation timestamp
-}
+**Usage**:
-type RelationType =
- | 'caused_by' // A caused by B
- | 'enabled_by' // A enabled by B
- | 'follows_pattern' // A follows pattern from B
- | 'solves' // A solves B
- | 'replaced_by' // A replaced by B
- | 'depends_on' // A depends on B
- | 'similar_to' // A similar to B
- | 'evolved_from'; // A evolved from B
+```bash
+memesh-view
```
-### Memory Model
-
-```typescript
-interface Memory {
- type: string; // Entity type
- observations: string[]; // Array of observations
- timestamp?: string; // ISO 8601 timestamp
-}
-```
+**Behavior**:
-### Task Metadata Model
+1. Opens the MeMesh database (`~/.memesh/knowledge-graph.db`)
+2. Reads all entities, observations, relations, and tags
+3. Generates a self-contained HTML file with:
+ - **Knowledge graph** -- D3.js force-directed graph showing entities and relations
+ - **Entity table** -- Searchable, sortable table of all entities with observations and tags
+ - **Statistics** -- Total entities, observations, relations, and tags
+4. Opens the HTML file in the default browser
-```typescript
-interface TaskMetadata {
- goal: string; // Extracted task goal
- reason?: string; // Reason for task
- expectedOutcome?: string; // Expected result
-}
-```
+No arguments or options required. The dashboard is a static HTML file that can be shared or archived.
---
-## Error Reference
-
-### Error Codes
-
-| Code | Description | HTTP Equivalent | Common Causes |
-|------|-------------|-----------------|---------------|
-| `VALIDATION_FAILED` | Input validation error | 400 | Missing required fields, invalid types |
-| `OPERATION_FAILED` | Operation execution failed | 500 | Database error, system unavailable |
-| `RESOURCE_NOT_FOUND` | Resource not found | 404 | Entity doesn't exist |
-| `ROUTING_FAILED` | Task routing failed | 500 | No matching capability |
-| `TOOL_NOT_FOUND` | Tool doesn't exist | 404 | Invalid tool name |
-
-### Error Response Format
-
-All tools return errors in a consistent format:
-
-```typescript
-interface ErrorResponse {
- error: string; // Human-readable error message
- code: string; // Error code (see table above)
- details?: object; // Additional error details
-}
-```
-
-### Common Error Scenarios
-
-#### Validation Errors
+## Connection
-```typescript
-// Missing required field
-{
- error: "Validation failed: task is required",
- code: "VALIDATION_FAILED"
-}
-
-// Invalid type
-{
- error: "Validation failed: limit must be a number",
- code: "VALIDATION_FAILED"
-}
-
-// Out of range
-{
- error: "Validation failed: limit must be between 1 and 50",
- code: "VALIDATION_FAILED"
-}
-```
-
-#### Operation Errors
-
-```typescript
-// Database unavailable
-{
- error: "Database connection failed",
- code: "OPERATION_FAILED",
- details: {
- reason: "Connection timeout",
- path: "~/.memesh/database.db"
- }
-}
+MeMesh runs as a stdio MCP server. Claude Code manages the connection automatically via the plugin's `.mcp.json` configuration.
-// Permission denied
+```json
{
- error: "Cannot write to data directory",
- code: "OPERATION_FAILED",
- details: {
- path: "~/.memesh",
- permission: "denied"
+ "mcpServers": {
+ "memesh": {
+ "command": "node",
+ "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+ "env": { "NODE_ENV": "production" }
+ }
}
}
```
-
-#### Resource Not Found
-
-```typescript
-// Entity not found
-{
- error: "Entity not found: Non-existent Entity",
- code: "RESOURCE_NOT_FOUND"
-}
-
-// Tool not found
-{
- error: "Tool not found: invalid-tool-name",
- code: "TOOL_NOT_FOUND"
-}
-```
-
-### Error Handling Best Practices
-
-✅ **Do**:
-- Always check error codes
-- Log errors with context
-- Provide helpful error messages to users
-- Retry transient errors (with backoff)
-- Handle partial success in batch operations
-
-❌ **Don't**:
-- Ignore error responses
-- Expose sensitive error details to users
-- Retry non-transient errors indefinitely
-- Assume success without checking status
-
----
-
-## Integration Examples
-
-### Example 1: Complete Feature Development Workflow
-
-```typescript
-// 1. Search for relevant context
-const memories = await buddyRemember({
- query: "authentication patterns",
- limit: 5
-});
-
-// 2. Route implementation task
-const task = await buddyDo({
- task: "implement user authentication with JWT because we need secure API access"
-});
-
-// 3. Create entity for implementation
-await createEntities({
- entities: [
- {
- name: "User Authentication Implementation 2026-02-03",
- entityType: "feature",
- observations: [
- "Implemented JWT-based authentication",
- "Uses bcrypt for password hashing",
- "Refresh tokens stored in database",
- "Access tokens expire after 15 minutes"
- ],
- tags: ["auth", "jwt", "security", "feature"],
- metadata: {
- author: "KT",
- files: ["src/auth/jwt.ts", "src/middleware/auth.ts"],
- priority: "high"
- }
- }
- ]
-});
-
-// 4. Link to decision
-await createRelations({
- relations: [
- {
- from: "User Authentication Implementation 2026-02-03",
- to: "JWT Library Decision",
- relationType: "enabled_by"
- }
- ]
-});
-
-// 5. Generate tests
-const tests = await generateTests({
- specification: "User authentication with JWT:\n- Login with email/password\n- Token refresh\n- Token validation"
-});
-
-// 6. Store test results
-await addObservations({
- observations: [
- {
- entityName: "User Authentication Implementation 2026-02-03",
- contents: [
- "All tests passing: 42/42",
- "Coverage: 95%",
- "Security audit passed"
- ]
- }
- ]
-});
-```
-
-### Example 2: Bug Investigation and Fix
-
-```typescript
-// 1. Search for similar issues
-const similarBugs = await buddyRemember({
- query: "session timeout issues",
- limit: 10
-});
-
-// 2. Investigate
-const investigation = await buddyDo({
- task: "investigate why sessions expire immediately after login"
-});
-
-// 3. Document bug
-await createEntities({
- entities: [
- {
- name: "Session Expiry Bug 2026-02-03",
- entityType: "bug_fix",
- observations: [
- "Bug: Sessions expire immediately after login",
- "Root cause: Cookie domain set incorrectly",
- "Affected: All users on production",
- "Discovered: User reports and monitoring"
- ],
- tags: ["bug", "session", "critical", "production"],
- metadata: {
- severity: "critical",
- affectedUsers: 1523,
- discoveredAt: "2026-02-03T08:00:00Z"
- }
- }
- ]
-});
-
-// 4. Document fix
-await createEntities({
- entities: [
- {
- name: "Session Config Fix 2026-02-03",
- entityType: "code_change",
- observations: [
- "Changed cookie domain from '.example.com' to null",
- "Updated session middleware configuration",
- "Added tests for cookie settings"
- ],
- tags: ["fix", "session", "configuration"]
- }
- ]
-});
-
-// 5. Link bug and fix
-await createRelations({
- relations: [
- {
- from: "Session Expiry Bug 2026-02-03",
- to: "Incorrect Cookie Domain Config",
- relationType: "caused_by"
- },
- {
- from: "Session Config Fix 2026-02-03",
- to: "Session Expiry Bug 2026-02-03",
- relationType: "solves"
- }
- ]
-});
-
-// 6. Update with resolution
-await addObservations({
- observations: [
- {
- entityName: "Session Expiry Bug 2026-02-03",
- contents: [
- "Fixed: 2026-02-03T10:30:00Z",
- "Verified: Sessions now persist for 24 hours",
- "Deployed: Production rollout completed",
- "Impact: Zero session expiry reports since fix"
- ]
- }
- ]
-});
-```
-
-### Example 3: Knowledge Graph Building
-
-```typescript
-// Build a comprehensive knowledge graph for a project
-
-// 1. Architecture decisions
-await createEntities({
- entities: [
- {
- name: "Microservices Architecture Decision",
- entityType: "decision",
- observations: [
- "Chose microservices over monolith",
- "Reasons: Independent scaling, team autonomy, tech diversity",
- "Trade-offs: Increased complexity, distributed debugging"
- ],
- tags: ["architecture", "microservices", "decision"]
- },
- {
- name: "PostgreSQL Database Choice",
- entityType: "decision",
- observations: [
- "Selected PostgreSQL for all services",
- "Reasons: JSON support, ACID compliance, mature ecosystem"
- ],
- tags: ["database", "postgresql", "decision"]
- }
- ]
-});
-
-// 2. Service implementations
-await createEntities({
- entities: [
- {
- name: "User Service",
- entityType: "feature",
- observations: [
- "Handles user authentication and profiles",
- "Built with Node.js and Express",
- "Uses PostgreSQL for persistence"
- ],
- tags: ["service", "backend", "user"]
- },
- {
- name: "Order Service",
- entityType: "feature",
- observations: [
- "Manages order lifecycle",
- "Event-driven architecture with Kafka",
- "PostgreSQL for order storage"
- ],
- tags: ["service", "backend", "orders"]
- }
- ]
-});
-
-// 3. Build relationships
-await createRelations({
- relations: [
- {
- from: "User Service",
- to: "Microservices Architecture Decision",
- relationType: "follows_pattern"
- },
- {
- from: "User Service",
- to: "PostgreSQL Database Choice",
- relationType: "depends_on"
- },
- {
- from: "Order Service",
- to: "Microservices Architecture Decision",
- relationType: "follows_pattern"
- },
- {
- from: "Order Service",
- to: "PostgreSQL Database Choice",
- relationType: "depends_on"
- },
- {
- from: "Order Service",
- to: "User Service",
- relationType: "depends_on",
- metadata: {
- reason: "Needs user information for orders"
- }
- }
- ]
-});
-
-// 4. Add best practices
-await createEntities({
- entities: [
- {
- name: "Service Communication Best Practice",
- entityType: "best_practice",
- observations: [
- "Always use async messaging for service-to-service communication",
- "Prefer events over direct API calls",
- "Implement circuit breakers for resilience"
- ],
- tags: ["best_practice", "microservices", "resilience"]
- }
- ]
-});
-
-// 5. Link best practices
-await createRelations({
- relations: [
- {
- from: "Order Service",
- to: "Service Communication Best Practice",
- relationType: "follows_pattern"
- }
- ]
-});
-```
-
----
-
-## Rate Limits & Performance
-
-### Performance Characteristics
-
-| Operation | Typical Time | Notes |
-|-----------|-------------|-------|
-| `buddy-do` | 100-2000ms | Depends on task complexity |
-| `buddy-remember` (store) | 50-200ms | Simple database insert |
-| `buddy-remember` (search) | 100-500ms | Depends on graph size |
-| `memesh-create-entities` | 50-200ms per entity | Batch operations faster |
-| `memesh-record-mistake` | 50-200ms | Database insert |
-| `memesh-hook-tool-use` | 10-100ms | Event processing |
-| `memesh-generate-tests` | 1000-5000ms | Uses LLM sampling |
-| `memesh-metrics` | 10-100ms | Read-only aggregation |
-
-### Rate Limits
-
-**MCP Protocol Limits**:
-- No hard rate limits (local server)
-- Performance scales with system resources
-- Database operations are sequential
-
-**Best Practices**:
-- Batch entity creation when possible
-- Cache buddy-remember results when appropriate
-- Use appropriate query limits
-
-### Resource Usage
-
-**Memory**:
-- Base server: ~50-100MB
-- Knowledge graph: Grows with data (~1-10MB typical)
-- Peak usage during memesh-generate-tests: ~200-300MB
-
-**Storage**:
-- Database file: `~/.memesh/database.db`
-- Grows with entities and relations
-- Typical project: 1-50MB
-- Use SQLite VACUUM to optimize
-
-**CPU**:
-- Most operations: Low CPU usage
-- memesh-generate-tests: Medium CPU (LLM sampling)
-- memesh-metrics: Minimal CPU
-
-### Optimization Tips
-
-✅ **Optimize Performance**:
-- Batch memesh-create-entities operations
-- Use appropriate limit parameters
-- Cache buddy-remember searches
-- Clean up old entities periodically
-
-✅ **Monitor Usage**:
-- Use memesh-metrics to check memory status
-- Monitor database file size
-- Track operation latency
-- Review error rates
-
----
-
-## Appendix
-
-### Version History
-
-- **v2.6.6** (2026-02-03): Enhanced error handling, ErrorClassifier integration
-- **v2.6.5** (2026-02-02): Interactive tutorial, improved QUICK_START
-- **v2.6.4** (2026-02-01): Response formatting improvements
-- **v2.6.3** (2026-01-31): Interactive setup wizard
-- **v2.6.2** (2026-01-30): Auto-tracking and memory linking
-- **v2.6.0** (2026-01-28): Smart routing with capability matching
-
-### Related Documentation
-
-- **User Guide**: [USER_GUIDE.md](../USER_GUIDE.md) - Complete user documentation
-- **Best Practices**: [BEST_PRACTICES.md](../BEST_PRACTICES.md) - Effective workflows
-- **Quick Start**: [QUICK_START.md](../QUICK_START.md) - Getting started guide
-- **Troubleshooting**: [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) - Common issues and fixes
-- **Commands**: [COMMANDS.md](../COMMANDS.md) - CLI command reference
-
-### Support
-
-**GitHub Repository**: https://github.com/PCIRCLE-AI/claude-code-buddy
-
-**Issues**: https://github.com/PCIRCLE-AI/claude-code-buddy/issues
-
-**Discussions**: https://github.com/PCIRCLE-AI/claude-code-buddy/discussions
-
----
-
-**MeMesh Plugin** - Persistent memory and context-aware task execution for Claude Code
-
-*For questions or issues, please visit the GitHub repository or open an issue.*
diff --git a/docs/images/dashboard-screenshot.png b/docs/images/dashboard-screenshot.png
new file mode 100644
index 00000000..4ad56611
Binary files /dev/null and b/docs/images/dashboard-screenshot.png differ
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index e0829098..00000000
--- a/docs/index.html
+++ /dev/null
@@ -1,348 +0,0 @@
-
-
-
-
-
- MeMesh Plugin — Searchable Project Memory for Claude Code
-
-
-
-
-
-
-
-
-
-
-
-
MeMesh Plugin
-
Memory, smart task analysis, and workflow automation for Claude Code
-
- npm install -g @pcircle/memesh
- click to copy
-
-
-
-
-
When projects grow, it gets hard to keep track of decisions across sessions. MeMesh gives your projects searchable memory, smarter task handling, and automated workflows — so every session picks up right where you left off.
-
-
-
What it does
-
-
-
🔍
-
Searchable memory
-
Find past decisions by meaning, not just keywords. Ask "why did we choose PostgreSQL?" and get answers
-
-
-
🧠
-
Smart task analysis
-
Analyzes your task, pulls in past context, and builds an enriched plan before executing
-
-
-
⚙️
-
Workflow automation
-
Session recaps, code review reminders, smart routing, and file tracking — all automatic
-
-
-
📝
-
Learn from mistakes
-
Record errors and fixes to build a knowledge base that prevents repeated mistakes
-
-
-
🔒
-
100% local
-
All data stays on your machine. Nothing uploaded
-
-
-
⚡
-
Zero config
-
Install and restart Claude Code. That's it
-
-
-
-
3 commands, that's all
-
-
- buddy-do "task"
- Run a task with memory context
-
-
- buddy-remember "topic"
- Search past decisions and context
-
-
- buddy-help
- Show available commands
-
-
-
-
-
-
-
-
-
-