@nxuss/lemma 0.6.1 → 0.7.1

package/README.md

@@ -1,10 +1,11 @@
-# 🧠 Lemma v0.6.1
+# 🧠 Lemma v0.7.0
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE)
-[![Build Status](https://img.shields.io/badge/tests-101%20passed-brightgreen.svg?style=flat-square)]()
-[![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)]()
-[![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)]()
+[![Build Status](https://img.shields.io/badge/tests-101%20passed-brightgreen.svg?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-13-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -132,13 +133,13 @@ Create or edit `lemma.config.json` in your project root to disable or fine-tune
 {
   "system": {
     "autoConfigure": {
-      "disabled": false,   // Set to true to disable all automated IDE/shell overrides
-      "editor": true,      // Set to false to prevent Cursor/Windsurf setting updates
-      "shell": true,       // Set to false to prevent .zshrc/.bashrc overrides
-      "claude": true       // Set to false to prevent Claude Desktop MCP updates
+      "disabled": false,
+      "editor": true,
+      "shell": true,
+      "claude": true
     },
     "clipboardWatcher": {
-      "disabled": false    // Set to true to prevent clipboard watching
+      "disabled": false
     }
   }
 }
@@ -146,6 +147,58 @@ Create or edit `lemma.config.json` in your project root to disable or fine-tune
 
 ---
 
+## 🛠️ MCP Tools Reference (v0.7.0 — 13 Tools)
+
+When connected via `lemma mcp`, your Chat IDE gains access to **13 native tools** covering workspace navigation, code safety, semantic memory, and AI cost optimization.
+
+### 🗂️ Workspace Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `read_workspace_file` | Read a file with automatic token compression (up to 80% savings) and privacy scrubbing. |
+| `write_workspace_file` | Write content to a file, creating directories as needed. |
+| `apply_workspace_patch` | Smart search-and-replace patch — safe against duplicate matches. |
+| `list_workspace_dir` | Recursively list the project structure up to a configurable depth. |
+| `search_workspace` | Fast text search (grep) across all project files with optional extension filter. |
+| `run_workspace_command` | Execute bash commands (tests, linters, git) in the workspace root. Returns stdout/stderr. |
+
+### 🔬 Code Intelligence Tools ✨ NEW in v0.7.0
+
+| Tool | Description |
+| :--- | :--- |
+| `get_ast_hologram` | **Holographic AST Map.** Scans the workspace and returns a dense JSON index of all exported symbols (classes, functions, interfaces, types, consts) with their file paths and line numbers. Use this **instead of reading individual files** — saves up to 90% tokens when navigating large codebases. |
+| `validate_patch_sandbox` | **AST Multiverse Auto-Debugger.** Validates a proposed patch in an isolated sandbox (`/tmp`) **before** applying it to the workspace. Runs `tsc --noEmit` and bracket-balance checks. Returns a clear `✅ SAFE TO APPLY` or `❌ DO NOT APPLY` verdict with full diagnostics. |
+
+### 🧠 Brain & Memory Tools ✨ NEW in v0.7.0
+
+| Tool | Description |
+| :--- | :--- |
+| `search_memory` | Semantic search across The Brain — retrieves past solutions and context from all your projects. |
+| `store_memory` | Explicitly save a key technical decision, code snippet, or architecture note into The Brain for future sessions. |
+| `query_hybrid_consensus` | **Hybrid Consensus Engine.** Checks The Brain for a cached answer at a configurable similarity threshold (default 80%). Brain **HIT** → instant response, zero cloud tokens spent. Brain **MISS** → instructs the IDE to proceed with cloud and auto-stores the result afterward. |
+| `get_telepathic_hints` | **Proactive Telepathy.** Given the path of the file being edited, automatically surfaces the top N most relevant memories and past solutions from The Brain — no explicit query needed. Front-loads context before you write a single line. |
+
+### ⚙️ Optimization & Privacy Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `scrub_privacy` | Mask PII, API keys, and secrets from any text block using the Privacy Firewall. |
+| `squeeze_prompt` | Compress code blocks and boilerplate in any prompt — up to 80% token reduction. |
+| `get_routing_advice` | Analyze a prompt and get the optimal model recommendation from the Complexity Router. |
+| `auto_heal` | Diagnose and auto-heal the latest local server crash from Lemma's live context logs. |
+| `get_project_onboarding` | Download a one-shot architectural mental model of the current project codebase. |
+
+### 📡 MCP Resources
+
+| Resource URI | Description |
+| :--- | :--- |
+| `lemma://runtime/context` | Live application errors, stack traces, and runtime state. Subscribable — your IDE gets notified the instant a crash happens. |
+| `lemma://stats/usage` | Current token savings, cost report, and cache hit metrics in JSON. |
+| `lemma://project/onboarding` | Dynamic project architecture guide compiled on demand. |
+| `lemma://multiverse/timeline` | Chronological AST diff timeline of the last 10 code micro-snapshots. |
+
+---
+
 ## 💎 Tier Comparison
 
 | Feature | 🆓 Free (Standard) | 💎 Pro ($12/mo) |
@@ -157,6 +210,10 @@ Create or edit `lemma.config.json` in your project root to disable or fine-tune
 | **AST Time-Travel Telemetry** | ❌ None | **Codebase Multiverse (Cap 10 AST Snapshots) 💎** |
 | **Kiro/Cursor Composer Bypass** | ❌ None | **Smart Patches & Sandbox Terminal MCP 💎** |
 | **Zero-Shot Onboarding Guide** | ❌ None | **Codebase Architecture Map MCP 💎** |
+| **AST Hologram** | ❌ None | **Symbol Map — 90% token savings 💎** |
+| **Sandbox Patch Validator** | ❌ None | **Pre-flight code safety checks 💎** |
+| **Hybrid Consensus Engine** | ❌ None | **Brain-first query routing 💎** |
+| **Proactive Telepathy** | ❌ None | **Auto-surfaced context hints 💎** |
 | **Telemetry Dashboard** | Basic Stats | **Time-Travel Debugger & 60fps Graph** |
 | **Limits** | 300 requests/mo | **Unlimited Agentic Power** |
 
@@ -174,16 +231,16 @@ You don't need to change your habits. Just point your tool's "Base URL" to Lemma
 *   **Custom Apps:** Replace `https://api.openai.com/v1` with `http://localhost:8081/v1` in your SDK initialization.
 
 ### 💎 Pro Integration (Model Context Protocol - MCP)
-For **Lemma Pro** users, you can expose Lemma's entire intelligence layer (Privacy Firewall, Semantic Brain Search, and Auto-Heal, plus the new Composer Bypass Suite, AST Timeline, and Zero-Shot Onboarding Map) directly as native tools using the **Model Context Protocol (MCP)**. This lets the LLM read, search, write, patch, and compile files in your workspace autonomously.
+For **Lemma Pro** users, expose Lemma's entire intelligence layer — Privacy Firewall, Semantic Brain, AST Hologram, Sandbox Validator, Hybrid Consensus, and Proactive Telepathy — directly as native tools using the **Model Context Protocol (MCP)**. This lets the LLM read, search, write, patch, validate, and compile files autonomously.
 
-#### 🟢 Cursor:
+#### 🟢 Cursor / Antigravity / Windsurf:
 1. Go to **Settings > Features > MCP**.
 2. Click **+ Add New MCP Server**.
 3. Configure the server:
    * **Name**: `Lemma`
    * **Type**: `command`
    * **Command**: `lemma mcp`
-4. Click **Save**. A green **"Connected"** dot will appear, confirming that the IDE has loaded all of Lemma's tools.
+4. Click **Save**. A green **"Connected"** dot will appear, confirming that the IDE has loaded all 13 of Lemma's tools.
 
 #### 🟢 Claude Desktop:
 Add the following to your `claude_desktop_config.json` configuration file:
@@ -202,7 +259,8 @@ Add the following to your `claude_desktop_config.json` configuration file:
 1.  **Privacy:** Your IDE won't leak your secrets to the cloud.
 2.  **Context:** Lemma syncs your runtime crashes directly to your chat window.
 3.  **Speed:** Instant responses for similar questions via Semantic Cache.
-4.  **Observability:** Gorgeous dashboard showing you exactly how much cash and tokens you are saving.
+4.  **Intelligence:** AST Hologram + Hybrid Consensus = dramatically fewer tokens spent per session.
+5.  **Observability:** Gorgeous dashboard showing you exactly how much cash and tokens you are saving.
 
 ---
 

package/dist/cjs/cli/lemma-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA8NA,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAkMnJ;AAED,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AAm2DD,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AAwOA,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAkMnJ;AAED,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA03DD,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}

package/dist/cjs/cli/lemma-proxy.js

@@ -104,6 +104,15 @@ async function writeJson(file, data) {
 function projectHash(name) {
     return crypto_1.default.createHash('sha1').update(name).digest('hex').slice(0, 12);
 }
+function getCollectionName(projectName) {
+    let cleanName = projectName.replace(/[^a-zA-Z0-9._-]/g, '_');
+    cleanName = cleanName.replace(/^[^a-zA-Z0-9]+/, '');
+    cleanName = cleanName.replace(/[^a-zA-Z0-9]+$/, '');
+    if (cleanName.length < 3) {
+        cleanName = 'lemma_proj_' + cleanName;
+    }
+    return `lemma-cache-${cleanName}`;
+}
 function detectProject() {
     const pkgPath = path_1.default.join(process.cwd(), 'package.json');
     if (fs_1.default.existsSync(pkgPath)) {
@@ -617,7 +626,7 @@ async function semanticGet(provider, prompt, projectName = 'global') {
     let localHit = null;
     try {
         const collection = await chroma.getOrCreateCollection({
-            name: `lemma-cache-${projectName}`,
+            name: getCollectionName(projectName),
             embeddingFunction: dummyEmbeddingFunction,
             metadata: { "hnsw:space": "cosine" }
         });
@@ -656,7 +665,7 @@ async function semanticGet(provider, prompt, projectName = 'global') {
     // ─── Cross-Project Bug Telepathy Fallback ───
     try {
         const collections = await chroma.listCollections();
-        const projectCollections = collections.filter((c) => c.name.startsWith('lemma-cache-') && c.name !== `lemma-cache-${projectName}`);
+        const projectCollections = collections.filter((c) => c.name.startsWith('lemma-cache-') && c.name !== getCollectionName(projectName));
         for (const colInfo of projectCollections) {
             try {
                 const col = await chroma.getOrCreateCollection({
@@ -709,7 +718,7 @@ async function semanticSet(provider, prompt, data, projectName = 'global') {
         return;
     try {
         const collection = await chroma.getOrCreateCollection({
-            name: `lemma-cache-${projectName}`,
+            name: getCollectionName(projectName),
             embeddingFunction: dummyEmbeddingFunction,
             metadata: { "hnsw:space": "cosine" }
         });
@@ -1100,7 +1109,7 @@ class LemmaServer {
                 // Try to query ChromaDB for semantic cache count
                 try {
                     const collection = await chroma.getOrCreateCollection({
-                        name: `lemma-cache-${this.projectName}`,
+                        name: getCollectionName(this.projectName),
                         embeddingFunction: dummyEmbeddingFunction,
                         metadata: { "hnsw:space": "cosine" }
                     });
@@ -1156,28 +1165,46 @@ class LemmaServer {
                     const emb = await getEmbedding(query);
                     if (!emb)
                         throw new Error('Failed to generate embedding');
-                    const collection = await chroma.getOrCreateCollection({
-                        name: `lemma-cache-${this.projectName}`,
-                        embeddingFunction: dummyEmbeddingFunction,
-                        metadata: { "hnsw:space": "cosine" }
-                    });
-                    const results = await collection.query({
-                        queryEmbeddings: [emb],
-                        nResults: 10
-                    });
-                    const formatted = (results.ids[0] || []).map((id, i) => {
-                        const meta = results.metadatas[0][i];
-                        const dists = results.distances;
-                        const dist = (dists && dists[0] && dists[0][i] !== null && dists[0][i] !== undefined) ? dists[0][i] : 1.0;
-                        return {
-                            id,
-                            prompt: meta.prompt,
-                            response: JSON.parse(meta.response),
-                            timestamp: meta.timestamp,
-                            similarity: 1 - dist
-                        };
-                    });
-                    res.json({ results: formatted });
+                    let allResults = [];
+                    // 1. Query all collections starting with 'lemma-cache' for cross-project search
+                    const collections = await chroma.listCollections();
+                    const targetCollections = collections.filter((c) => c.name.startsWith('lemma-cache'));
+                    for (const colInfo of targetCollections) {
+                        try {
+                            const collection = await chroma.getOrCreateCollection({
+                                name: colInfo.name,
+                                embeddingFunction: dummyEmbeddingFunction,
+                                metadata: { "hnsw:space": "cosine" }
+                            });
+                            const results = await collection.query({
+                                queryEmbeddings: [emb],
+                                nResults: 5
+                            });
+                            const originProject = colInfo.name === 'lemma-cache' ? 'global' : colInfo.name.replace('lemma-cache-', '');
+                            (results.ids[0] || []).forEach((id, i) => {
+                                const meta = results.metadatas[0][i];
+                                const dists = results.distances;
+                                const dist = (dists && dists[0] && dists[0][i] !== null && dists[0][i] !== undefined) ? dists[0][i] : 1.0;
+                                let parsedResponse = meta.response;
+                                try {
+                                    parsedResponse = JSON.parse(meta.response);
+                                }
+                                catch { }
+                                allResults.push({
+                                    id,
+                                    prompt: meta.prompt,
+                                    response: parsedResponse,
+                                    timestamp: meta.timestamp,
+                                    similarity: 1 - dist,
+                                    project: originProject
+                                });
+                            });
+                        }
+                        catch { }
+                    }
+                    // 2. Sort all project results by similarity descending
+                    allResults.sort((a, b) => b.similarity - a.similarity);
+                    res.json({ results: allResults.slice(0, 10) });
                 }
                 catch (e) {
                     res.status(500).json({ error: e.message });
@@ -1206,7 +1233,7 @@ class LemmaServer {
                     }
                     // Clear Chroma DB collection
                     try {
-                        await chroma.deleteCollection({ name: `lemma-cache-${this.projectName}` }).catch(() => { });
+                        await chroma.deleteCollection({ name: getCollectionName(this.projectName) }).catch(() => { });
                     }
                     catch (e) {
                         console.error(`[CacheClear] Failed to clear Chroma collection: ${e.message}`);
@@ -1223,7 +1250,7 @@ class LemmaServer {
                     // Selective delete from Chroma DB collection using provider metadata filter
                     try {
                         const collection = await chroma.getOrCreateCollection({
-                            name: `lemma-cache-${this.projectName}`,
+                            name: getCollectionName(this.projectName),
                             embeddingFunction: dummyEmbeddingFunction,
                             metadata: { "hnsw:space": "cosine" }
                         });
@@ -1291,7 +1318,7 @@ class LemmaServer {
                         const emb = await getEmbedding("architectural design guidelines and core stack configuration decisions");
                         if (emb) {
                             const collection = await chroma.getOrCreateCollection({
-                                name: `lemma-cache-${this.projectName}`,
+                                name: getCollectionName(this.projectName),
                                 embeddingFunction: dummyEmbeddingFunction,
                                 metadata: { "hnsw:space": "cosine" }
                             });
@@ -1362,7 +1389,7 @@ class LemmaServer {
                         return res.status(500).json({ error: 'Failed to generate embedding' });
                     }
                     const collection = await chroma.getOrCreateCollection({
-                        name: `lemma-cache-${this.projectName}`,
+                        name: getCollectionName(this.projectName),
                         embeddingFunction: dummyEmbeddingFunction,
                         metadata: { "hnsw:space": "cosine" }
                     });