@nxuss/lemma 1.19.0 → 1.21.0

package/.agents/skills/lemma/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: lemma
+description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa `lemma call <tool>` vía bash para acceder a 70+ tools sin MCP nativo.
+user-invocable: true
+allowed-tools: bash
+---
+
+# Lemma para Muse
+
+Eres Muse Code (muse-spark). Tienes **Lemma MCP** disponible — gateway de caché semántica, firewall de privacidad y memoria persistente. Muse no expone MCP nativamente, así que llamas a Lemma vía **CLI `lemma call`** (wrapper sobre `mcp-server.js` por stdio) + **proxy local**.
+
+## Qué es Lemma
+
+- **Proxy local** en `http://localhost:8081` — cachea respuestas LLM (BM25 + embeddings), ahorra tokens/dinero.
+- **Brain persistente** en `~/.lemma-cache/lemma_brain.json` + memoria por proyecto.
+- **MCP server** con 70+ tools — las mismas que usan Claude Code / Cursor / Codex, aquí vía `lemma call`.
+
+> **Nota de compatibilidad:** Este skill NO afecta a Claude Code, Cursor, Codex ni otros CLIs con MCP nativo. Ellos siguen usando `mcp__lemma__*` directo. Las reglas globales de `AGENTS.md` (MANDATORY RULES) aplican a clientes con MCP nativo; si eres Muse, **este skill tiene prioridad** sobre `AGENTS.md` para decidir cuándo usar Lemma.
+
+## Cuándo usar Lemma (Muse)
+
+| Tarea | Qué hacer con Lemma |
+|---|---|
+| Pregunta que puede estar ya resuelta | `search_memory` antes de razonar |
+| Pregunta atada a archivos concretos (mismo prompt + mismos archivos) | `state_hash_cache` con `action=lookup` antes, `store` después |
+| Conocimiento que debe sobrevivir sesiones | `search_memory` / `store_memory` (con `derivedFrom`) |
+| Leer/listar/buscar workspace | Usa tus tools nativos (`read_file`, `bash ls/grep`) — Lemma añade scrubbing si lo llamas, pero no es obligatorio |
+| Tarea mecánica → decidir modelo barato | `get_routing_advice` |
+| Aplicar patch | `validate_patch_sandbox` primero |
+| "¿Cuánto ahorramos?" | `token_receipt` |
+
+Si Lemma no encaja, usa tu tool nativo. No fuerces Lemma donde no aporta.
+
+## Cómo llamar a Lemma desde Muse (preferido)
+
+Usa el wrapper `lemma call` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como `node ./lemma-proxy.cjs call` o `node ./bin/lemma-call.js` o `npx @nxuss/lemma call` si instalaste global.
+
+```bash
+# 1. Lookup en memoria antes de razonar (preferido — wrapper)
+node ./lemma-proxy.cjs call search_memory --query "tu pregunta"
+# o JSON explícito:
+node ./lemma-proxy.cjs call search_memory '{"query":"tu pregunta"}'
+
+# 2. Busca en workspace (con scrubbing)
+node ./lemma-proxy.cjs call search_workspace --query "texto" --maxResults 10
+
+# 3. Guarda solución verificada
+node ./lemma-proxy.cjs call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
+
+# 4. Lista tools disponibles
+node ./lemma-proxy.cjs call --list
+
+# Pipe también funciona:
+echo '{"query":"hello"}' | node ./bin/lemma-call.js search_memory
+```
+
+**Alternativa raw (solo si el wrapper no está disponible):**
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_memory","arguments":{"query":"tu pregunta"}}}' | node ./mcp-server.js
+```
+
+Para tráfico LLM real (cache del proxy), asegúrate que el daemon corre:
+
+```bash
+node ./lemma-proxy.cjs status
+node ./lemma-proxy.cjs start
+```
+
+## Cero config en este repo
+
+Si clonaste `lemma` y lo abriste con Muse, **no necesitas correr ningún comando**. Este repo ya trae:
+- `.agents/skills/lemma/SKILL.md` (este archivo) — Muse lo detecta al abrir el workspace
+- `AGENTS.md` con guard clause para Muse
+- `bin/lemma-call.js` + `lemma-proxy.cjs call` (wrapper sin JSON manual)
+- `mcp-server.js` como fallback sin build
+
+Muse te pedirá confiar el workspace la primera vez (prompt interactivo). Una vez que aceptas, el skill queda activo automáticamente — sin `lemma init`, sin `npm run build` manual. Para uso total (70+ tools) el wrapper resuelve `dist/cjs/mcp/index.js` → `mcp-server.js`; si `dist` no existe se auto-construye o usa el fallback con las tools core.
+
+## Sandbox y permisos
+
+Muse corre con sandbox por workspace. El proxy (`localhost:8081`) y el brain (`~/.lemma-cache/`) están **fuera** del workspace, así que:
+
+- La primera vez Muse pregunta si confías el workspace — di que sí. Después queda recordado, no necesitas `--trust-workspace` manual cada vez (solo si lo abres con flag explícito).
+- Si ves `permission denied`, acepta el trust prompt y re-intenta; no necesitas `--disable-sandbox`.
+- El wrapper prioriza `dist/cjs/mcp/index.js` y cae a `mcp-server.js` si aún no hay build — cero pasos extra.
+
+## Flujo obligatorio al iniciar sesión
+
+1. Llama `search_memory` vía `lemma call` con el tema de la tarea.
+2. Si hay hit, verifícalo contra el código actual antes de presentarlo.
+3. Al terminar con solución verificada (tests pasaron), llama `store_memory` vía `lemma call`.
+
+## Flujo para bugs
+
+1. `get_telepathic_hints` vía `lemma call` si necesitas contexto de runtime.
+2. `search_memory` con el mensaje de error.
+
+## Regla dura
+
+Si tu respuesta viene de un cache hit, dilo explícitamente: "esto viene de memoria cacheada". Nunca presentes un hit como razonamiento fresco. Y nunca guardes una solución no verificada.
+
+## Verificación (opcional)
+
+En este repo no necesitas instalar nada — ya está listo. Solo si quieres verificar:
+
+```bash
+# Wrapper responde (sin JSON manual)
+node ./lemma-proxy.cjs call --list | head -c 500
+node ./lemma-proxy.cjs call get_project_onboarding '{}' | head -c 800
+
+# Proxy (solo si usas cache de tráfico LLM)
+node ./lemma-proxy.cjs status
+```
+
+Para **otros proyectos** (no este repo), instala Lemma una vez:
+
+```bash
+npx @nxuss/lemma init   # genera .agents/skills/lemma/SKILL.md + AGENTS.md en ese proyecto
+# o
+npm i -D @nxuss/lemma && npx lemma init
+```
+
+> Generado por `lemma init` — @nxuss/lemma para Muse.

package/README.md

@@ -27,10 +27,12 @@ to an auditable ledger, never an estimate.
 
 ```bash
 npm install -g @nxuss/lemma
-lemma init      # auto-configures MCP for your IDE
+lemma init      # auto-configures MCP for your IDE (Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode)
 lemma start     # gateway + dashboard on http://localhost:8081
 ```
 
+> **Muse** — no setup needed. This repo is already Muse-compatible zero-config: clone and open with `muse` — the skill at `.agents/skills/lemma/SKILL.md` auto-loads and `lemma call` works via `bash`. See [MCP integration](#-mcp-integration).
+
 ---
 
 ## ✨ What Lemma actually does
@@ -154,9 +156,11 @@ Customize via `lemma.config.json`:
 
 | Client | Setup |
 | :--- | :--- |
+| **Muse** (`muse` CLI · Muse Spark) | **Zero-config** — clone this repo and open with `muse`; skill at `.agents/skills/lemma/SKILL.md` auto-loads, `lemma call` wrapper via `bash` (no MCP native needed). No `lemma init` required. |
 | OpenCode | `lemma init` — registers itself in `~/.opencode.json`, zero config. |
 | Cursor / Windsurf / Kiro / Antigravity | Settings → MCP → add server, command `lemma mcp`. |
 | Claude Desktop | Add to `mcpServers`: `{ "lemma": { "command": "npx", "args": ["-y", "@nxuss/lemma", "mcp"] } }` |
+| Claude Code / Codex CLI | `lemma init` — auto-configures MCP + sets gateway (`ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` → `http://localhost:8081`). |
 
 Once connected, Lemma auto-injects its TurboMode system prompt on handshake — states the goal
 (reduce what enters context without ever costing a correct answer) and enforces it: a tool call

package/bin/init.js

@@ -205,7 +205,7 @@ function configureClaudeDesktop() {
 const FALLBACK_LEMMA_TOOL_NAMES = [
   'read_workspace_file', 'write_workspace_file', 'create_workspace_file', 'list_workspace_dir',
   'search_workspace', 'apply_workspace_patch', 'run_workspace_command', 'output_region',
-  'search_memory', 'store_memory', 'smarter_cache',
+  'search_memory', 'get_memory', 'store_memory', 'update_memory', 'smarter_cache',
   'get_project_onboarding', 'get_telepathic_hints', 'get_ast_hologram',
   'get_symbol_surgical_context', 'compress_context',
   'squeeze_prompt', 'turbosqueeze', 'wormhole_squeeze',
@@ -282,11 +282,14 @@ tokens sale más cara que los tokens que ahorra.
 | Agregar un método/función a un archivo existente | \`mcp__lemma__surgical_ast_insert\` | Patch quirúrgico en vez de reescribir el archivo completo |
 | Antes de aplicar un patch generado | \`mcp__lemma__validate_patch_sandbox\` | Valídalo antes de escribirlo, no después |
 | "¿Cuánto ahorramos de verdad?" | \`mcp__lemma__token_receipt\` | Bitácora auditable real, no una cifra inventada |
+| Leer una memoria por su id (antes de editarla, o para un id que traes de otra sesión) | \`mcp__lemma__get_memory\` | Lectura determinista: \`search_memory\` es un ranking y puede no devolver la entrada que buscas. Editar un documento vivo sin leerlo antes es editarlo a ciegas |
+| Corregir o extender una memoria que ya existe | \`mcp__lemma__update_memory\` | Reescribe en su sitio conservando id, hits y las aristas \`derivedFrom\`. \`store_memory\` siempre crea un id nuevo: re-guardar una versión corregida deja las dos y la búsqueda devuelve una mezcla arbitraria de ambas |
 | Guardar una solución para el futuro | \`mcp__lemma__store_memory\` | Solo después de verificarla (tests pasaron, el usuario confirmó) — una solución mala guardada se vuelve un cache hit falso más adelante |
 | Una memoria salió STALE pero la verificaste y sigue siendo correcta | \`mcp__lemma__refresh_memory\` | Re-ancla la evidencia conservando id, hits y las aristas \`derivedFrom\`; guardar un casi-duplicado pierde las tres (y el dedup suele rechazarlo) |
 | Una memoria está simplemente mal, no solo mal encajada | \`mcp__lemma__forget_memory\` | Borrado real. Para "no era lo que buscaba en esta consulta" usa \`downvote_memory\`: esa memoria puede ser la correcta para otra pregunta |
 
-Ambas están en el toolbox (\`action="call"\`), no en la lista anunciada.
+El ciclo de vida completo (\`search\` → \`get\` → \`update\`/\`refresh\`/\`forget\`) está anunciado:
+ante una memoria desactualizada, corrígela; no guardes otra al lado.
 
 ## No todas las tools de Lemma están en tu lista
 
@@ -427,9 +430,18 @@ function configureClaudeCodeGateway(anthropicApiKey) {
 
 const LEMMA_RULES_CONTENT = `# Lemma MCP — Autonomous Behaviors
 
-> ⚠️ MANDATORY RULES — Follow without exception.
+> ⚠️ MANDATORY RULES — Follow without exception **for MCP-native clients**.
 
-The MCP server \`lemma\` is connected. NEVER use native tools when a Lemma equivalent exists.
+The MCP server \`lemma\` is connected. For clients with native MCP support
+(Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode), NEVER use native tools
+when a Lemma equivalent exists.
+
+> **Muse Code:** you DO NOT have native \`mcp__lemma__*\` tools. For you,
+> \`AGENTS.md\` is advisory. Follow \`.agents/skills/lemma/SKILL.md\` instead —
+> it has priority and uses \`lemma call\` via bash. Do not enforce the table
+> below as a hard block; use it only when \`lemma call\` actually helps.
+
+## Mandatory Substitutions (MCP-native clients only)
 
 ## Mandatory Substitutions
 
@@ -452,6 +464,8 @@ The MCP server \`lemma\` is connected. NEVER use native tools when a Lemma equiv
 2. Call \`search_memory\` with the task topic — recall past solutions
 3. When done: call \`store_memory\` with the solution
 
+> Muse: use \`node ./lemma-proxy.cjs call <tool>\` (see \`.agents/skills/lemma/SKILL.md\`).
+
 ## Bug Reporting
 
 1. Call \`get_telepathic_hints\` with the relevant file
@@ -474,6 +488,17 @@ function updateAgentsMd() {
     const existing = fs.readFileSync(agentsMdPath, 'utf8');
     if (!existing.includes('@nxuss/lemma')) {
       fs.appendFileSync(agentsMdPath, '\n---\n\n' + LEMMA_RULES_CONTENT, 'utf8');
+    } else if (!existing.includes('Muse Code:') || !existing.includes('MCP-native clients')) {
+      // Migrate old Lemma AGENTS.md (pre-Muse guard) to new version with Muse compatibility
+      // Replace the old block in-place to preserve any user content above it
+      const lemmaBlockRegex = /# Lemma MCP[\s\S]*?\*Auto-generated by `lemma init` — @nxuss\/lemma\*/;
+      if (lemmaBlockRegex.test(existing)) {
+        const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
+        fs.writeFileSync(agentsMdPath, updated, 'utf8');
+      } else {
+        // Fallback: append new block
+        fs.appendFileSync(agentsMdPath, '\n---\n\n' + LEMMA_RULES_CONTENT, 'utf8');
+      }
     }
   } else {
     fs.writeFileSync(agentsMdPath, LEMMA_RULES_CONTENT, 'utf8');
@@ -546,21 +571,25 @@ function configureKiro() {
   return true;
 }
 
-// OpenCode: register MCP server in opencode.json
+// OpenCode: register MCP server in opencode.json + Muse skill
 const MUSE_SKILL_CONTENT = `---
 name: lemma
-description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse.
+description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa lemma call <tool> vía bash para acceder a 70+ tools sin MCP nativo.
+user-invocable: true
+allowed-tools: bash
 ---
 
 # Lemma para Muse
 
-Eres Muse Code (muse-spark). Tienes disponible **Lemma MCP** — gateway de caché semántica, firewall de privacidad y memoria persistente. Este skill te enseña a usarlo sin MCP nativo (Muse no habla MCP aún): todo es vía CLI + proxy local.
+Eres Muse Code (muse-spark). Tienes **Lemma MCP** disponible — gateway de caché semántica, firewall de privacidad y memoria persistente. Muse no expone MCP nativamente, así que llamas a Lemma vía **CLI \`lemma call\`** (wrapper sobre \`mcp-server.js\` por stdio) + **proxy local**.
 
 ## Qué es Lemma
 
 - **Proxy local** en \`http://localhost:8081\` — cachea respuestas LLM (BM25 + embeddings), ahorra tokens/dinero.
 - **Brain persistente** en \`~/.lemma-cache/lemma_brain.json\` + memoria por proyecto.
-- **MCP server** con 70+ tools — las mismas que usan Claude Code / Cursor / Codex, pero aquí las llamas vía \`npx @nxuss/lemma\` o \`node mcp-server.js\` por \`bash\`.
+- **MCP server** con 70+ tools — las mismas que usan Claude Code / Cursor / Codex, aquí vía \`lemma call\`.
+
+> **Nota de compatibilidad:** Este skill NO afecta a Claude Code, Cursor, Codex ni otros CLIs con MCP nativo. Ellos siguen usando \`mcp__lemma__*\` directo. Las reglas globales de \`AGENTS.md\` (MANDATORY RULES) aplican a clientes con MCP nativo; si eres Muse, **este skill tiene prioridad** sobre \`AGENTS.md\` para decidir cuándo usar Lemma.
 
 ## Cuándo usar Lemma (Muse)
 
@@ -576,61 +605,94 @@ Eres Muse Code (muse-spark). Tienes disponible **Lemma MCP** — gateway de cach
 
 Si Lemma no encaja, usa tu tool nativo. No fuerces Lemma donde no aporta.
 
-## Cómo llamar a Lemma desde Muse
+## Cómo llamar a Lemma desde Muse (preferido)
 
-Muse no tiene \`mcp__lemma__*\` tools nativas. Llama al servidor MCP por **stdio** vía bash:
+Usa el wrapper \`lemma call\` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como \`node ./lemma-proxy.cjs call\` o \`node ./bin/lemma-call.js\` o \`npx @nxuss/lemma call\` si instalaste global.
 
 \`\`\`bash
-# 1. Lookup en memoria antes de razonar
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_memory","arguments":{"query":"tu pregunta"}}}' | node ./mcp-server.js
+# 1. Lookup en memoria antes de razonar (preferido — wrapper)
+node ./lemma-proxy.cjs call search_memory --query "tu pregunta"
+# o JSON explícito:
+node ./lemma-proxy.cjs call search_memory '{"query":"tu pregunta"}'
 
-# 2. Tool genérico - busca en workspace (con scrubbing)
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_workspace","arguments":{"query":"texto"}}}' | node ./mcp-server.js
+# 2. Busca en workspace (con scrubbing)
+node ./lemma-proxy.cjs call search_workspace --query "texto" --maxResults 10
 
 # 3. Guarda solución verificada
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"store_memory","arguments":{"content":"solución verificada","tags":["bugfix"]}}}' | node ./mcp-server.js
+node ./lemma-proxy.cjs call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
+
+# 4. Lista tools disponibles
+node ./lemma-proxy.cjs call --list
+
+# Pipe también funciona:
+echo '{"query":"hello"}' | node ./bin/lemma-call.js search_memory
 \`\`\`
 
-O usa el wrapper más simple si está instalado:
+**Alternativa raw (solo si el wrapper no está disponible):**
 
 \`\`\`bash
-npx -y @nxuss/lemma mcp   # servidor MCP stdio
-lemma search "query"      # CLI directa si instalaste lemma global
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_memory","arguments":{"query":"tu pregunta"}}}' | node ./mcp-server.js
 \`\`\`
 
-Para el proxy de cache (tráfico LLM real), asegúrate que el daemon corre:
+Para tráfico LLM real (cache del proxy), asegúrate que el daemon corre:
 
 \`\`\`bash
 node ./lemma-proxy.cjs status
 node ./lemma-proxy.cjs start
 \`\`\`
 
+## Cero config en este repo
+
+Si clonaste \`lemma\` y lo abriste con Muse, **no necesitas correr ningún comando**. Este repo ya trae:
+- \`.agents/skills/lemma/SKILL.md\` (este archivo) — Muse lo detecta al abrir el workspace
+- \`AGENTS.md\` con guard clause para Muse
+- \`bin/lemma-call.js\` + \`lemma-proxy.cjs call\` (wrapper sin JSON manual)
+- \`mcp-server.js\` como fallback sin build
+
+Muse te pedirá confiar el workspace la primera vez (prompt interactivo). Una vez que aceptas, el skill queda activo automáticamente — sin \`lemma init\`, sin \`npm run build\` manual. Para uso total (70+ tools) el wrapper resuelve \`dist/cjs/mcp/index.js\` → \`mcp-server.js\`; si \`dist\` no existe se auto-construye o usa el fallback con las tools core.
+
+## Sandbox y permisos
+
+Muse corre con sandbox por workspace. El proxy (\`localhost:8081\`) y el brain (\`~/.lemma-cache/\`) están **fuera** del workspace, así que:
+
+- La primera vez Muse pregunta si confías el workspace — di que sí. Después queda recordado, no necesitas \`--trust-workspace\` manual cada vez (solo si lo abres con flag explícito).
+- Si ves \`permission denied\`, acepta el trust prompt y re-intenta; no necesitas \`--disable-sandbox\`.
+- El wrapper prioriza \`dist/cjs/mcp/index.js\` y cae a \`mcp-server.js\` si aún no hay build — cero pasos extra.
+
 ## Flujo obligatorio al iniciar sesión
 
-1. Llama \`search_memory\` con el tema de la tarea.
+1. Llama \`search_memory\` vía \`lemma call\` con el tema de la tarea.
 2. Si hay hit, verifícalo contra el código actual antes de presentarlo.
-3. Al terminar con solución verificada (tests pasaron), llama \`store_memory\`.
+3. Al terminar con solución verificada (tests pasaron), llama \`store_memory\` vía \`lemma call\`.
 
 ## Flujo para bugs
 
-1. \`get_telepathic_hints\` si necesitas contexto de runtime.
+1. \`get_telepathic_hints\` vía \`lemma call\` si necesitas contexto de runtime.
 2. \`search_memory\` con el mensaje de error.
 
 ## Regla dura
 
 Si tu respuesta viene de un cache hit, dilo explícitamente: "esto viene de memoria cacheada". Nunca presentes un hit como razonamiento fresco. Y nunca guardes una solución no verificada.
 
-## Instalación / verificación
+## Verificación (opcional)
+
+En este repo no necesitas instalar nada — ya está listo. Solo si quieres verificar:
 
 \`\`\`bash
-# Re-configura todo (incluye Muse skill)
-node ./bin/init.js
+# Wrapper responde (sin JSON manual)
+node ./lemma-proxy.cjs call --list | head -c 500
+node ./lemma-proxy.cjs call get_project_onboarding '{}' | head -c 800
 
-# Verifica que el proxy está arriba
-curl -s http://localhost:8081/health || echo "proxy down"
+# Proxy (solo si usas cache de tráfico LLM)
+node ./lemma-proxy.cjs status
+\`\`\`
 
-# Verifica MCP responde
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ./mcp-server.js | head -c 500
+Para **otros proyectos** (no este repo), instala Lemma una vez:
+
+\`\`\`bash
+npx @nxuss/lemma init   # genera .agents/skills/lemma/SKILL.md + AGENTS.md en ese proyecto
+# o
+npm i -D @nxuss/lemma && npx lemma init
 \`\`\`
 
 > Generado por \`lemma init\` — @nxuss/lemma para Muse.
@@ -647,6 +709,24 @@ function configureMuse() {
   } catch { return false; }
 }
 
+function ensureKiroMigratesAgentsMd() {
+  // Kiro's configureKiro also touches AGENTS.md — ensure it migrates the same way
+  const cwd = process.cwd();
+  const agentsMdPath = path.join(cwd, 'AGENTS.md');
+  try {
+    if (fs.existsSync(agentsMdPath)) {
+      const existing = fs.readFileSync(agentsMdPath, 'utf8');
+      if (existing.includes('@nxuss/lemma') && (!existing.includes('Muse Code:') || !existing.includes('MCP-native clients'))) {
+        const lemmaBlockRegex = /# Lemma MCP[\s\S]*?\*Auto-generated by `lemma init` — @nxuss\/lemma\*/;
+        if (lemmaBlockRegex.test(existing)) {
+          const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
+          fs.writeFileSync(agentsMdPath, updated, 'utf8');
+        }
+      }
+    }
+  } catch {}
+}
+
 function configureOpenCode() {
   const cwd = process.cwd();
   const opencodePath = path.join(cwd, 'opencode.json');

package/bin/lemma-call.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Lemma Call — one-shot MCP tool invocation for CLIs without native MCP (Muse, etc.)
+ *
+ * Usage:
+ *   node bin/lemma-call.js <tool_name> [json_args]
+ *   node bin/lemma-call.js search_memory '{"query":"hello"}'
+ *   echo '{"query":"hello"}' | node bin/lemma-call.js search_memory
+ *   node bin/lemma-call.js --list                    # lists available tools
+ *
+ * Also via npx:
+ *   npx @nxuss/lemma call search_memory '{"query":"hello"}'
+ *
+ * Resolves MCP server path the same way as bin/init.js and mcp-server.js:
+ *   1. dist/cjs/mcp/index.js (built)
+ *   2. mcp-server.js (fallback/legacy)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+function resolveMcpServer() {
+  const candidates = [
+    path.join(__dirname, '..', 'dist', 'cjs', 'mcp', 'index.js'),
+    path.join(__dirname, '..', 'mcp-server.js'),
+    path.join(__dirname, 'mcp-server.js'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  // Zero-config: try to auto-build dist if missing and tsc is available (fresh clone without build)
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const { execSync } = require('child_process');
+      // Only attempt if typescript is installed (npm install was run)
+      execSync('npx tsc --project tsconfig.cjs.json --outDir ./dist/cjs 2>&1', { cwd: path.join(__dirname, '..'), stdio: 'ignore', timeout: 30000 });
+      const built = path.join(__dirname, '..', 'dist', 'cjs', 'mcp', 'index.js');
+      if (fs.existsSync(built)) return built;
+    }
+  } catch {}
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    return { help: true };
+  }
+  if (args.includes('--list') || args.includes('--tools')) {
+    return { list: true };
+  }
+  // tool name is first non-flag arg
+  let tool = null;
+  let jsonArg = null;
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (!tool) {
+      tool = a;
+    } else if (!jsonArg) {
+      jsonArg = a;
+    }
+  }
+  // Flags like --query "hello" should become jsonArg object
+  let jsonObj = null;
+  if (jsonArg) {
+    try { jsonObj = JSON.parse(jsonArg); } catch (e) {
+      console.error(`[lemma-call] Invalid JSON args: ${e.message}`);
+      process.exit(2);
+    }
+  } else if (Object.keys(flags).length > 0) {
+    jsonObj = flags;
+    // coerce common string flags
+    for (const k of Object.keys(jsonObj)) {
+      if (jsonObj[k] === 'true') jsonObj[k] = true;
+      if (jsonObj[k] === 'false') jsonObj[k] = false;
+    }
+  }
+  return { tool, jsonObj, flags };
+}
+
+function readStdin() {
+  return new Promise(resolve => {
+    if (process.stdin.isTTY) return resolve(null);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => data += chunk);
+    process.stdin.on('end', () => {
+      const t = data.trim();
+      if (!t) return resolve(null);
+      try { resolve(JSON.parse(t)); } catch { resolve(t); }
+    });
+    // If stdin never ends (no pipe), timeout
+    setTimeout(() => resolve(null), 100);
+  });
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv);
+  if (parsed.help) {
+    console.log(`lemma-call — one-shot Lemma MCP tool invocation
+
+Usage:
+  node bin/lemma-call.js <tool> [json]
+  node bin/lemma-call.js search_memory '{"query":"hello"}'
+  node bin/lemma-call.js search_memory --query "hello"
+  echo '{"query":"hello"}' | node bin/lemma-call.js search_memory
+  node bin/lemma-call.js --list
+  npx @nxuss/lemma call <tool> [json]   (via lemma-proxy.cjs)
+`);
+    process.exit(0);
+  }
+
+  const mcpPath = resolveMcpServer();
+  if (!mcpPath) {
+    console.error('[lemma-call] MCP server not found. Run `npm run build` first.');
+    process.exit(1);
+  }
+
+  // --list mode: proper MCP handshake (initialize → tools/list)
+  if (parsed.list) {
+    const initReq = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'lemma-call', version: '1.0.0' } } }) + '\n';
+    const initialized = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+    const listReq = JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' }) + '\n';
+    const child = spawn(process.execPath, [mcpPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '';
+    child.stdout.on('data', d => out += d.toString());
+    child.stderr.on('data', () => {}); // ignore watcher noise
+    child.stdin.write(initReq);
+    child.stdin.write(initialized);
+    child.stdin.write(listReq);
+    child.stdin.end();
+    // Give server time to respond before close (MCP is stream-oriented)
+    await new Promise(r => setTimeout(r, 800));
+    try { child.kill(); } catch {}
+    await new Promise(r => child.on('close', r).on('error', r));
+    // Parse all JSON-RPC response lines, find the tools/list result (id:2)
+    const lines = out.trim().split('\n').filter(Boolean);
+    let tools = null;
+    for (const line of lines) {
+      try {
+        const j = JSON.parse(line);
+        if (j.id === 2 && j.result && Array.isArray(j.result.tools)) { tools = j.result.tools; break; }
+        if (j.result && Array.isArray(j.result.tools) && !tools) tools = j.result.tools;
+      } catch {}
+    }
+    if (tools) {
+      console.log(JSON.stringify(tools.map(t => t.name), null, 2));
+    } else {
+      // Fallback: try last line approach
+      try {
+        const res = JSON.parse(lines[lines.length - 1] || '{}');
+        const t = res.result?.tools || [];
+        if (t.length) console.log(JSON.stringify(t.map(x => x.name), null, 2));
+        else console.log(out.trim().split('\n').pop() || '[]');
+      } catch {
+        console.log(out.trim() || '[]');
+      }
+    }
+    process.exit(0);
+  }
+
+  if (!parsed.tool) {
+    console.error('[lemma-call] Missing tool name. Try --help');
+    process.exit(2);
+  }
+
+  let argsObj = parsed.jsonObj;
+  // If no args from CLI, try stdin
+  if (!argsObj) {
+    const stdinData = await readStdin();
+    if (stdinData && typeof stdinData === 'object') argsObj = stdinData;
+    else if (typeof stdinData === 'string' && stdinData) {
+      try { argsObj = JSON.parse(stdinData); } catch { argsObj = { query: stdinData }; }
+    }
+  }
+  if (!argsObj) argsObj = {};
+
+  // MCP handshake: initialize → initialized → tools/call (required by SDK)
+  const initReq = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'lemma-call', version: '1.0.0' } } }) + '\n';
+  const initialized = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+  const request = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 2,
+    method: 'tools/call',
+    params: { name: parsed.tool, arguments: argsObj }
+  }) + '\n';
+
+  const child = spawn(process.execPath, [mcpPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', d => stdout += d.toString());
+  child.stderr.on('data', d => stderr += d.toString());
+  child.stdin.write(initReq);
+  child.stdin.write(initialized);
+  child.stdin.write(request);
+  // Keep stdin open briefly for server to process; MCP SDK buffers responses
+  await new Promise(r => setTimeout(r, 500));
+  child.stdin.end();
+  // Wait for response with timeout
+  const exitCode = await Promise.race([
+    new Promise(resolve => child.on('close', resolve)),
+    new Promise(resolve => setTimeout(() => { try { child.kill(); } catch {}; resolve(0); }, 5000))
+  ]);
+
+  // MCP server returns JSON-RPC with result.content[].text — find id:2 response
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  let parsedRes = null;
+  for (const line of lines) {
+    try {
+      const j = JSON.parse(line);
+      if (j.id === 2) { parsedRes = j; break; }
+    } catch {}
+  }
+  if (!parsedRes) {
+    try { parsedRes = JSON.parse(lines[lines.length - 1] || ''); } catch {}
+  }
+
+  if (parsedRes && parsedRes.result) {
+    // Pretty-print the tool result for Muse to read easily
+    const content = parsedRes.result.content;
+    if (Array.isArray(content)) {
+      for (const c of content) {
+        if (c.text) {
+          // Try to pretty-print if text is JSON
+          try {
+            const j = JSON.parse(c.text);
+            console.log(JSON.stringify(j, null, 2));
+          } catch {
+            console.log(c.text);
+          }
+        } else {
+          console.log(JSON.stringify(c, null, 2));
+        }
+      }
+    } else {
+      console.log(JSON.stringify(parsedRes.result, null, 2));
+    }
+    // Propagate isError as exit code
+    if (parsedRes.result.isError) process.exit(1);
+    process.exit(0);
+  }
+
+  if (parsedRes && parsedRes.error) {
+    console.error(`[lemma-call] MCP error: ${parsedRes.error.message || JSON.stringify(parsedRes.error)}`);
+    if (stderr.trim()) console.error(stderr.trim());
+    process.exit(1);
+  }
+
+  // Fallback: dump raw output
+  if (stdout.trim()) console.log(stdout.trim());
+  if (stderr.trim()) console.error(stderr.trim());
+  process.exit(exitCode || 0);
+}
+
+main().catch(e => { console.error('[lemma-call]', e.message); process.exit(1); });