@pcircle/memesh 2.11.0 → 3.0.0

package/README.md

@@ -1,86 +1,187 @@
-# MeMesh Plugin
+<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>
+
+---
+
+Your AI forgets everything between sessions. **MeMesh fixes that.**
+
+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.
 
-Minimal persistent memory plugin for Claude Code. Remembers decisions, patterns, and context across sessions.
+```bash
+npm install -g @pcircle/memesh
+```
+
+---
+
+## Dashboard
+
+<p align="center">
+  <img src="docs/images/dashboard-search.png" alt="MeMesh Search" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-browse.png" alt="MeMesh Browse" width="100%" />
+</p>
+
+Run `memesh` to open the interactive dashboard with Search, Browse, Analytics, Manage, and Settings.
 
-[![npm version](https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=cb3837)](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)
+---
 
-## Installation
+## Quick Start
 
 ```bash
-npm install -g @pcircle/memesh
-```
+# Store a memory
+memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 
-## What it does
+# Search memories (finds "OAuth" even if you search "login security" with Smart Mode)
+memesh recall "login security"
 
-MeMesh gives Claude Code persistent memory through 3 MCP tools, 2 hooks, and a CLI dashboard:
+# Archive outdated memories (soft-delete, never lost)
+memesh forget --name "old-auth-design"
 
-### MCP Tools
+# Open the dashboard
+memesh
 
-| 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) |
+# Start HTTP API (for Python SDK, integrations)
+memesh serve
+```
 
-### Hooks
+### Python
 
-| Hook | Event | What |
-|------|-------|------|
-| Session Start | `SessionStart` | Auto-recalls project-specific + recent global memories |
-| Post Commit | `PostToolUse` (Bash) | Records git commits as knowledge entities |
+```python
+from memesh import MeMesh
 
-### CLI
+m = MeMesh()  # connects to localhost:3737
+m.remember("auth", "decision", observations=["Use OAuth 2.0 with PKCE"])
+results = m.recall("auth")
+```
 
-| Command | Description |
-|---------|-------------|
-| `memesh-view` | Generate and open an interactive HTML dashboard |
+### Any LLM (OpenAI function calling format)
 
 ```bash
-memesh-view
+memesh export-schema --format openai
+# → JSON array of tools, paste into your OpenAI/Claude/Gemini API call
 ```
 
-![MeMesh Dashboard](docs/images/dashboard-screenshot.png)
+---
+
+## Why MeMesh?
+
+Most AI memory solutions need Neo4j, vector databases, API keys, and 30+ minutes of setup. MeMesh needs **one command**.
+
+| | **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 |
 
-## How it works
+---
 
-- **Storage**: SQLite database at `~/.memesh/knowledge-graph.db`
-- **Search**: FTS5 full-text search (no vector embeddings)
-- **Isolation**: Tag-based project filtering (`project:<name>`)
-- **Schema**: entities, observations, relations, tags + FTS5 virtual table
-- **Validation**: All tool inputs validated with Zod schemas
+## Features
+
+### 6 Memory Tools
+
+| 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) |
+
+### 3 Access Methods
+
+| 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 |
+
+### 4 Auto-Capture Hooks
+
+| 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 |
+
+### Smart Features
+
+- **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
 
 ```
-src/
-├── cli/
-│   └── view.ts           # HTML dashboard generator (D3.js graph + stats)
-├── db.ts                 # SQLite database (open/close/migrate, FTS5)
-├── knowledge-graph.ts    # Entity CRUD, relations, FTS5 search
-├── index.ts              # Package exports
-└── mcp/
-    ├── server.ts         # MCP server entry point (stdio transport)
-    └── tools.ts          # 3 tool handlers + Zod validation
-
-scripts/hooks/
-├── session-start.js      # Auto-recall on session start
-└── post-commit.js        # Git commit tracking
+                    ┌─────────────────┐
+                    │   Core Engine   │
+                    │  (6 operations) │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
 ```
 
-**Dependencies** (3): `better-sqlite3`, `@modelcontextprotocol/sdk`, `zod`
+**Core** is framework-agnostic — the same `remember`/`recall`/`forget` logic runs identically whether invoked from terminal, HTTP, or MCP.
+
+**Dependencies**: `better-sqlite3`, `sqlite-vec`, `@modelcontextprotocol/sdk`, `zod`, `express`, `commander`
+
+---
 
 ## Development
 
 ```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
+```
+
+Dashboard development:
+```bash
+cd dashboard
 npm install
-npm run build       # TypeScript compile + chmod executables
-npm test            # 73 tests (vitest, BDD style)
-npm run typecheck   # tsc --noEmit
+npm run dev          # Vite dev server with hot reload
+npm run build        # Build to single HTML file
 ```
 
+---
+
 ## License
 
-MIT
+MIT — [PCIRCLE AI](https://pcircle.ai)