@pcircle/memesh 2.10.1 → 3.0.0

package/.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" }
     }
   }
 }

package/README.md

@@ -1,286 +1,187 @@
-<div align="center">
+<p align="center">
+  <h1 align="center">MeMesh LLM Memory</h1>
+  <p align="center">
+    <strong>The lightest universal AI memory layer.</strong><br />
+    One SQLite file. Any LLM. Zero cloud.
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
+    <a href="https://pypi.org/project/memesh/"><img src="https://img.shields.io/badge/pip-memesh-3b82f6?style=flat-square" alt="PyPI" /></a>
+  </p>
+</p>
 
-<img src="docs/images/memesh-logo.svg" alt="MeMesh" width="80" />
-
-# MeMesh Plugin
-
-### Your AI coding sessions deserve memory.
+---
 
-MeMesh Plugin gives Claude Code persistent, searchable memory — so every session builds on the last.
+Your AI forgets everything between sessions. **MeMesh fixes that.**
 
-[![npm version](https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@pcircle/memesh)
-[![Downloads](https://img.shields.io/npm/dm/@pcircle/memesh?style=flat-square&color=blue)](https://www.npmjs.com/package/@pcircle/memesh)
-[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org)
-[![MCP](https://img.shields.io/badge/MCP-compatible-purple?style=flat-square)](https://modelcontextprotocol.io)
+Install once, configure in 30 seconds, and every AI tool you use — Claude, GPT, LLaMA, or any MCP client — gets persistent, searchable, evolving memory. No cloud. No Neo4j. No vector database. Just one SQLite file.
 
 ```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)
-
-</div>
-
-> **Note**: This project was originally called "Claude Code Buddy" and has been renamed to MeMesh Plugin to avoid potential trademark issues.
-
----
-
-## The Problem
-
-You're deep into a project with Claude Code. You made important decisions three sessions ago — which auth library, why you chose that database schema, what patterns to follow. But Claude doesn't remember. You repeat yourself. You lose context. You waste time.
-
-**MeMesh Plugin fixes this.** It gives Claude a persistent, searchable memory that grows with your project.
-
----
-
-## How It Works
-
-<table>
-<tr>
-<td width="50%">
-
-### 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.
-
-</td>
-<td width="50%">
-
-### 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.
-
-</td>
-</tr>
-</table>
-
 ---
 
-## What You Get
+## Dashboard
 
-**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.
+<p align="center">
+  <img src="docs/images/dashboard-search.png" alt="MeMesh Search" width="100%" />
+</p>
 
-**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.
+<p align="center">
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics" width="100%" />
+</p>
 
-**Proactive Recall** — MeMesh automatically surfaces relevant memories when you start a session, hit a test failure, or encounter an error. No manual searching needed.
+<p align="center">
+  <img src="docs/images/dashboard-browse.png" alt="MeMesh Browse" width="100%" />
+</p>
 
-**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.
+Run `memesh` to open the interactive dashboard with Search, Browse, Analytics, Manage, and Settings.
 
 ---
 
-## Get Started
-
-**Prerequisites**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 20+
+## Quick Start
 
 ```bash
-npm install -g @pcircle/memesh
-```
-
-Restart Claude Code. That's it.
-
-**Verify** — type in Claude Code:
+# Store a memory
+memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 
-```
-buddy-help
-```
+# Search memories (finds "OAuth" even if you search "login security" with Smart Mode)
+memesh recall "login security"
 
-You should see a list of available commands.
+# Archive outdated memories (soft-delete, never lost)
+memesh forget --name "old-auth-design"
 
-<details>
-<summary><strong>Install from source</strong> (contributors)</summary>
+# Open the dashboard
+memesh
 
-```bash
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
-npm install && npm run build
+# Start HTTP API (for Python SDK, integrations)
+memesh serve
 ```
 
-</details>
+### Python
 
----
+```python
+from memesh import MeMesh
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `buddy-do "task"` | Execute a task with full memory context |
-| `buddy-remember "topic"` | Search past decisions and context |
-| `buddy-help` | Show available commands |
+m = MeMesh()  # connects to localhost:3737
+m.remember("auth", "decision", observations=["Use OAuth 2.0 with PKCE"])
+results = m.recall("auth")
+```
 
-**Real examples:**
+### Any LLM (OpenAI function calling format)
 
 ```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 export-schema --format openai
+# → JSON array of tools, paste into your OpenAI/Claude/Gemini API call
 ```
 
-All data stays on your machine with automatic 90-day retention.
-
 ---
 
-## How is this different from CLAUDE.md?
+## Why MeMesh?
 
-| | 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 |
+Most AI memory solutions need Neo4j, vector databases, API keys, and 30+ minutes of setup. MeMesh needs **one command**.
 
-**They work together.** CLAUDE.md tells Claude *how* to work. MeMesh Plugin remembers *what* you've built.
+| | **MeMesh** | Mem0 | Zep | Anthropic Memory |
+|---|---|---|---|---|
+| **Install** | `npm i -g` (5 sec) | pip + Neo4j + VectorDB | pip + Neo4j | Built-in (cloud) |
+| **Storage** | Single SQLite file | Neo4j + Qdrant | Neo4j | Cloud |
+| **Search** | FTS5 + scoring + LLM expansion | Semantic + BM25 | Temporal graph | Key lookup |
+| **Privacy** | 100% local, always | Cloud option | Self-host | Cloud |
+| **Dependencies** | 6 | 20+ | 10+ | 0 (but cloud-locked) |
+| **Offline** | Yes | No | No | No |
+| **Dashboard** | Built-in (5 tabs) | None | None | None |
+| **Price** | Free | Free/Paid | Free/Paid | Included w/ API |
 
 ---
 
-## Platform Support
+## Features
 
-| Platform | Status |
-|----------|--------|
-| macOS | ✅ |
-| Linux | ✅ |
-| Windows | ✅ (WSL2 recommended) |
+### 6 Memory Tools
 
-**Works with:** Claude Code CLI · VS Code Extension · Cursor (via MCP) · Any MCP-compatible editor
+| Tool | What it does |
+|------|-------------|
+| **remember** | Store knowledge with observations, relations, and tags |
+| **recall** | Smart search with multi-factor scoring and LLM query expansion |
+| **forget** | Soft-archive (never deletes) or remove specific observations |
+| **consolidate** | LLM-powered compression of verbose memories |
+| **export** | Share memories as JSON between projects or team members |
+| **import** | Import memories with merge strategies (skip / overwrite / append) |
 
----
-
-## Visual Explorer (Streamlit UI)
+### 3 Access Methods
 
-MeMesh Plugin includes an interactive web UI for exploring your knowledge graph visually.
+| Method | Command | Best for |
+|--------|---------|----------|
+| **CLI** | `memesh` | Terminal, scripting, CI/CD |
+| **HTTP API** | `memesh serve` | Python SDK, dashboard, integrations |
+| **MCP** | `memesh-mcp` | Claude Code, Claude Desktop, any MCP client |
 
-**Dashboard** — Overview of your knowledge base with entity statistics, type distribution, tag trends, and growth over time.
+### 4 Auto-Capture Hooks
 
-<div align="center">
-<img src="docs/images/streamlit-dashboard.png" alt="MeMesh Dashboard" width="800" />
-</div>
+| Hook | Trigger | What it captures |
+|------|---------|-----------------|
+| **Session Start** | Every session | Loads your top memories by relevance |
+| **Post Commit** | After `git commit` | Records commit with diff stats |
+| **Session Summary** | When Claude stops | Files edited, errors fixed, decisions made |
+| **Pre-Compact** | Before compaction | Saves knowledge before context is lost |
 
-**KG Explorer** — Interactive graph visualization with color-coded entity types, relation edges, FTS5 full-text search, and filtering by type, tags, and date range.
+### Smart Features
 
-<div align="center">
-<img src="docs/images/streamlit-kg-explorer.png" alt="MeMesh KG Explorer" width="800" />
-</div>
-
-**Quick start:**
-
-```bash
-cd streamlit
-pip install -r requirements.txt
-streamlit run app.py
-```
+- **Knowledge Evolution** — `forget` archives, not deletes. `supersedes` relations replace old decisions with new ones. History is preserved.
+- **Smart Recall** — LLM expands your search query into related terms. "login security" finds "OAuth PKCE".
+- **Multi-Factor Scoring** — Results ranked by relevance (35%) + recency (25%) + frequency (20%) + confidence (15%) + temporal validity (5%).
+- **Conflict Detection** — Warns when memories contradict each other.
+- **Auto-Decay** — Stale memories (30+ days unused) gradually fade in ranking. Never deleted.
+- **Namespaces** — `personal`, `team`, `global` scopes for organizing and sharing.
 
 ---
 
 ## Architecture
 
-```mermaid
-graph TB
-    CC[Claude Code CLI] <-->|MCP Protocol| MCP[MCP Server]
-
-    MCP --> TH[Tool Handlers]
-    TH --> MT[Memory Tools]
-    TH --> ST[System Tools]
-    TH --> HT[Hook Tools]
-
-    MT --> UMS[Unified Memory Store]
-    MT --> KG[Knowledge Graph]
-
-    UMS --> SE[Search Engine]
-    KG --> FTS[FTS5 Full-Text Search]
-    KG --> VS[Vector Search]
-
-    VS --> EMB[ONNX Embeddings]
-    VS --> SVA[sqlite-vec Adapter]
-
-    KG --> DB[(SQLite DB)]
-    UMS --> DB
-
-    DB -.->|Read-Only| ST_UI[Streamlit Visual Explorer]
-
-    style CC fill:#4F46E5,color:#fff
-    style MCP fill:#7C3AED,color:#fff
-    style DB fill:#0891B2,color:#fff
-    style ST_UI fill:#06B6D4,color:#fff
-    style EMB fill:#10B981,color:#fff
 ```
-
-**How memory flows through the system:**
-
-```mermaid
-sequenceDiagram
-    participant U as You (in Claude Code)
-    participant M as MeMesh Plugin
-    participant KG as Knowledge Graph
-    participant E as Embeddings (ONNX)
-
-    U->>M: "Use JWT for auth"
-    M->>KG: Create entity (decision)
-    KG->>E: Generate embedding (local)
-    E-->>KG: 384-dim vector
-    KG-->>M: Stored + auto-relations inferred
-
-    Note over U,E: Next session...
-
-    U->>M: buddy-remember "auth"
-    M->>KG: Hybrid search (FTS5 + semantic)
-    KG->>E: Encode query
-    E-->>KG: Query vector
-    KG-->>M: Ranked results
-    M-->>U: "You decided JWT for auth because..."
+                    ┌─────────────────┐
+                    │   Core Engine   │
+                    │  (6 operations) │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
 ```
 
-Everything runs locally. No cloud. No API calls. Your data never leaves your machine.
-
----
-
-## Documentation
+**Core** is framework-agnostic — the same `remember`/`recall`/`forget` logic runs identically whether invoked from terminal, HTTP, or MCP.
 
-| Doc | Description |
-|-----|-------------|
-| [Getting Started](docs/GETTING_STARTED.md) | Step-by-step setup guide |
-| [User Guide](docs/USER_GUIDE.md) | Full usage guide with examples |
-| [Commands](docs/COMMANDS.md) | Complete command reference |
-| [Architecture](docs/ARCHITECTURE.md) | Technical deep dive |
-| [Contributing](CONTRIBUTING.md) | Contribution guidelines |
-| [Development](docs/DEVELOPMENT.md) | Dev setup for contributors |
+**Dependencies**: `better-sqlite3`, `sqlite-vec`, `@modelcontextprotocol/sdk`, `zod`, `express`, `commander`
 
 ---
 
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
-
----
+## Development
 
-## License
+```bash
+git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
+cd memesh-llm-memory
+npm install
+npm run build
+npm test -- --run    # 289 tests
+```
 
-MIT — See [LICENSE](LICENSE)
+Dashboard development:
+```bash
+cd dashboard
+npm install
+npm run dev          # Vite dev server with hot reload
+npm run build        # Build to single HTML file
+```
 
 ---
 
-<div align="center">
-
-**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)
+## License
 
-</div>
+MIT — [PCIRCLE AI](https://pcircle.ai)