squish-memory 0.9.3 → 1.0.1

package/.env.mcp.example

@@ -2,26 +2,29 @@
 SQUISH_MCP_PORT=8767
 SQUISH_MCP_SERVER_ENABLED=true
 
-# Embeddings - Hybrid mode for best quality
-SQUISH_EMBEDDINGS_PROVIDER=hybrid
-SQUISH_MULTIMODAL_EMBEDDINGS_ENABLED=true
+# Embeddings Provider: local | openai | ollama | google | none | auto
+# Default: local (TF-IDF, no API needed)
+SQUISH_EMBEDDINGS_PROVIDER=local
 
-# Google Cloud Multimodal (1408-dim vectors)
+# Model Selection (optional - uses defaults if not set)
+# SQUISH_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# SQUISH_GOOGLE_EMBEDDING_MODEL=gemini-embedding-001
+# SQUISH_OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5
+
+# Google Cloud (for google provider)
 # Get API key from: https://console.cloud.google.com/apis/credentials
-GOOGLE_CLOUD_PROJECT=your-project-id
-GOOGLE_CLOUD_LOCATION=us-central1
+# GOOGLE_CLOUD_PROJECT=your-project-id
+# GOOGLE_CLOUD_LOCATION=us-central1
 # GOOGLE_CLOUD_API_KEY=your-api-key
 # Or use service account:
 # GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
 
-# OpenAI Embeddings (optional, 1536-dim)
+# OpenAI (for openai provider or auto mode)
 # SQUISH_OPENAI_API_KEY=sk-...
 # SQUISH_OPENAI_API_URL=https://api.openai.com/v1/embeddings
-# SQUISH_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
 
-# Ollama Embeddings (optional, model-dependent dims)
+# Ollama (for ollama provider or auto mode)
 # SQUISH_OLLAMA_URL=http://localhost:11434
-# SQUISH_OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5
 
 # Embedding performance & reliability
 SQUISH_EMBEDDINGS_TIMEOUT_MS=30000
@@ -30,7 +33,7 @@ SQUISH_EMBEDDINGS_RETRY_DELAY_MS=1000
 # Per-provider overrides (optional)
 # SQUISH_OPENAI_TIMEOUT_MS=30000
 # SQUISH_OLLAMA_TIMEOUT_MS=30000
-# SQUISH_GOOGLE_MULTIMODAL_TIMEOUT_MS=30000
+# SQUISH_GOOGLE_TIMEOUT_MS=30000
 
 # QMD for local markdown search
 SQUISH_QMD_ENABLED=true

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to Squish will be documented in this file.
 
+## [1.0.0] - 2026-03-17
+
+### 🚀 Major Release - Universal Plugin Architecture
+
+#### Added - Interactive Multi-Step Wizard Installer
+- **Beautiful CLI Wizard** with 5-step installation flow using `@clack/prompts`
+- Step 1: Component Selection (CLI, MCP Server, AI Agent Plugins)
+- Step 2: Plugin Selection (Claude Code, OpenClaw, Cursor, etc.)
+- Step 3: Configuration (Local/Remote mode, Embeddings provider)
+- Step 4: Review Summary with visual confirmation
+- Step 5: Automated installation with progress spinners
+- **Quick Install Mode**: `bun run install:interactive --quick` for CLI + all plugins
+- **Dry-run support**: Preview installations without making changes
+- **Configuration persistence**: Saves settings to `~/.squish/config.json`
+
+#### Added - Universal Plugin Architecture
+- **Multi-client support**: Works with Claude Code, OpenClaw, OpenCode, Codex, Cursor, VS Code, Windsurf
+- **Plugin types**: Hooks (Claude Code), Plugin-slot (OpenClaw), MCP (all others)
+- **Auto-detection**: Detects which AI agents are already installed
+- **Source indicators**: Shows which plugins have source code available (📦)
+
+#### Added - Core Infrastructure
+- **Search Tracing System**: Debug and performance analysis for searches
+  - `core/tracing/collector.ts` - Collects search traces
+  - `core/tracing/visualizer.ts` - Visualizes trace data
+  - New MCP tools: `squish_get_search_traces`, `squish_get_trace_by_id`
+- **Namespace Support**: Hierarchical memory organization
+  - `core/namespaces/index.ts` - Namespace management
+  - `core/namespaces/uri-parser.ts` - URI parsing for namespaces
+- **Memory Layers (L0/L1/L2)**: Token-efficient retrieval
+  - `core/layers/generator.ts` - Generates memory layers
+- **Self-Iteration Job**: Conversation memory extraction
+  - `core/session-hooks/self-iteration-job.ts` - Extracts memories from conversations
+  - `core/session-hooks/session-hooks.ts` - Session lifecycle hooks
+- **Database Schema Updates**:
+  - Added `namespaces` table
+  - Added `memory_layers` table
+  - Added `search_traces` table
+
+#### Fixed - Dependencies
+- **qmd package**: Fixed from non-existent `qmd@0.15.1` to `@tobilu/qmd@2.0.1`
+- **mcporter version**: Updated from `1.2.0` to `0.7.3` (matches installed version)
+- **Scoped package support**: Dependency manager now handles `@scope/package` names
+- **Binary detection**: Properly maps scoped packages to their binary names
+
+#### Changed - Code Organization
+- **Refactored CLI**: Improved imports and removed duplicates in `index.ts`
+- **Safety Checks**: Better helper functions for algorithm validation
+- **Response Builder**: Unified response builder for algorithm handlers
+- **Config Validation**: Fixed provider validation logic
+- **Association SQL**: Fixed placeholder issues in SQL queries
+- **Directory Reorganization**: Renamed `core/sessions/` to `core/session-hooks/` for clarity
+  - Session lifecycle hooks now in dedicated directory
+  - Separates session auto-load (`core/session/`) from hooks/jobs (`core/session-hooks/`)
+
+#### Documentation
+- **Interactive Installer Guide**: Complete docs for wizard usage
+- **Plugin Architecture**: Documentation for universal plugin system
+- **Installation Guide**: Quick-start for all supported AI agents
+
+### Breaking Changes
+None - fully backward compatible with 0.9.x
+
+### Migration Notes
+- Run `bun run install:interactive` to use the new wizard
+- Existing installations continue to work without changes
+- Configuration automatically migrated on first run
+
 ## [0.9.3] - 2026-03-14
 
 ### Added - Core Memory & Embeddings Improvements (v0.9.2+)

package/README.md

@@ -73,14 +73,26 @@ Agent Action -----> [Squish Memory Layer]
 
 ## Quick Start
 
-### For Claude Code (Plugin)
+### Universal Plugin Installer (Recommended)
+```bash
+# Install for your AI assistant(s)
+npx squish-memory install-plugin --client=claude-code  # Claude Code
+npx squish-memory install-plugin --client=openclaw    # OpenClaw
+npx squish-memory install-plugin --client=opencode    # OpenCode
+npx squish-memory install-plugin --client=all         # All supported clients
+
+# Verify installation
+npx squish-memory install-plugin --client=claude-code --verify
+```
+
+### For Claude Code (Plugin) - Legacy Method
 ```bash
 # Install from marketplace
 /plugin marketplace add https://github.com/michielhdoteth/squish.git
 /plugin install squish@michielhdoteth-squish
 ```
 
-### For OpenClaw (npm)
+### For OpenClaw (npm) - Legacy Method
 ```bash
 npm install -g squish-memory
 ```
@@ -128,6 +140,50 @@ curl "http://localhost:3000/api/memories/search?q=TypeScript"
 - **Transport Agnostic**: MCP (stdio/SSE), CLI, or HTTP/WebSocket - choose your preference
 - **Storage Flexible**: SQLite for local, PostgreSQL for team deployments
 
+## Universal Plugin Architecture
+
+Squish now provides a **universal plugin system** that works as a plugin across all major AI assistant frameworks through a single manifest-driven installer.
+
+### How It Works
+1. Single `plugin-manifest.json` defines the plugin for all clients
+2. `npx squish-memory install-plugin --client=<target>` handles installation
+3. Auto-installs dependencies (mcporter, qmd) with pinned versions
+4. Generates client-specific configurations automatically
+5. Provides unified verification and troubleshooting
+
+### Supported Clients
+| Client | Installation Method | Status |
+|--------|-------------------|---------|
+| Claude Code | Plugin hooks (.claude-plugin/) | ✅ Stable |
+| OpenClaw | Memory slot via MCP bridge | ✅ Stable |
+| OpenCode | MCP server config | ✅ Stable |
+| Codex | MCP server config | ✅ Stable |
+| Cursor | MCP server config | ✅ Beta |
+| VS Code | MCP server config | ✅ Beta |
+| Windsurf | MCP server config | ✅ Beta |
+
+### Quick Installation Examples
+```bash
+# Install for Claude Code (recommended for Claude users)
+npx squish-memory install-plugin --client=claude-code --verify
+
+# Install for OpenClaw (recommended for OpenClaw users)  
+npx squish-memory install-plugin --client=openclaw --verify
+
+# Install for all supported clients
+npx squish-memory install-plugin --client=all --verify
+
+# Install for multiple specific clients
+npx squish-memory install-plugin --client=claude-code,openclaw,opencode --verify
+```
+
+### Benefits
+- **One manifest to rule them all**: Single source of truth
+- **Zero manual configuration**: Automatic dependency installation
+- **Version pinned dependencies**: Stable, reproducible builds
+- **Unified verification**: One command to check all clients
+- **Backward compatible**: Existing integrations still work
+
 ## Universal API
 
 Squish now provides a universal HTTP API that works with any AI agent:
@@ -185,18 +241,35 @@ REDIS_URL=redis://localhost:6379             # Optional for caching
 PORT=3000                                   # API server port
 ```
 
-**Optional:**
+**Configuration File (config/settings.json):**
+```json
+{
+  "embeddings": {
+    "provider": "local",
+    "models": {
+      "openai": { "model": "text-embedding-3-small" },
+      "google": { "model": "gemini-embedding-001" },
+      "ollama": { "model": "nomic-embed-text:v1.5" }
+    }
+  }
+}
+```
+
+**Environment Variables (override settings.json):**
 ```bash
 SQUISH_DATA_DIR=./.squish          # Custom data directory
-SQUISH_EMBEDDINGS_PROVIDER=local   # local, openai, ollama, google-multimodal, hybrid
+SQUISH_EMBEDDINGS_PROVIDER=local   # local, openai, ollama, google, none, auto
 
-# For better embeddings (optional)
-SQUISH_OPENAI_API_KEY=sk-...
+# Model selection (optional, uses defaults if not set)
 SQUISH_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
-SQUISH_OLLAMA_URL=http://localhost:11434
+SQUISH_GOOGLE_EMBEDDING_MODEL=gemini-embedding-001
 SQUISH_OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5
-SQUISH_GOOGLE_CLOUD_PROJECT=your-project
-SQUISH_GOOGLE_CLOUD_API_KEY=your-key
+
+# API credentials (for cloud providers)
+SQUISH_OPENAI_API_KEY=sk-...
+SQUISH_OLLAMA_URL=http://localhost:11434
+GOOGLE_CLOUD_PROJECT=your-project
+GOOGLE_CLOUD_API_KEY=your-key
 
 # Embedding performance & reliability
 SQUISH_EMBEDDINGS_TIMEOUT_MS=30000

package/bin/squish-add.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Wrapper for squish commands - launches interactive mode when no args
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+
+// If no args, launch interactive installer
+if (args.length === 0) {
+  const interactivePath = join(__dirname, '..', 'scripts', 'install-interactive.mjs');
+  const child = spawn('node', [interactivePath], {
+    stdio: 'inherit',
+    shell: false
+  });
+  child.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+} else {
+  // Pass through to install-plugin.mjs
+  const scriptPath = join(__dirname, '..', 'scripts', 'install-plugin.mjs');
+  const child = spawn('node', [scriptPath, ...args], {
+    stdio: 'inherit',
+    shell: false
+  });
+  child.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+}

package/bin/squish-rm.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Wrapper for squish remove command
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+const scriptPath = join(__dirname, 'scripts', 'install-plugin.mjs');
+
+// Add --uninstall flag
+const child = spawn('node', [scriptPath, '--uninstall', ...args], {
+  stdio: 'inherit',
+  shell: false
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/config/plugin-manifest.json

@@ -0,0 +1,152 @@
+{
+  "id": "squish-memory",
+  "name": "Squish Memory",
+  "version": "1.0.0",
+  "description": "Universal two-tier memory system for AI agents with hybrid search, core memory, and MCP-first architecture",
+  "capabilities": ["mcp", "cli", "web"],
+  "targets": {
+    "claude-code": {
+      "type": "hooks",
+      "hooks": ["SessionStart", "UserPromptSubmit", "PostToolUse", "SessionEnd"],
+      "install": {
+        "copy": [
+          { "from": ".claude-plugin/plugin.json", "to": "~/.claude/plugin.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.claude/plugin.json",
+        "toolCheck": "squish_health"
+      }
+    },
+    "openclaw": {
+      "type": "plugin-slot",
+      "slot": "memory",
+      "tools": ["memory_search", "memory_get"],
+      "install": {
+        "command": "node scripts/openclaw-bootstrap.mjs --skip-tool-check"
+      },
+      "verify": {
+        "fileExists": "~/.openclaw/openclaw-memory.json",
+        "toolCheck": "memory_search"
+      }
+    },
+    "opencode": {
+      "type": "mcp",
+      "tools": ["squish_remember", "squish_search", "squish_recall", "squish_context", "squish_health"],
+      "install": {
+        "copy": [
+          { "from": "generated/mcp/mcp-servers.json", "to": "~/.config/opencode/mcp-servers.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.config/opencode/mcp-servers.json",
+        "toolCheck": "squish_health"
+      }
+    },
+    "codex": {
+      "type": "mcp",
+      "tools": ["squish_remember", "squish_search", "squish_recall", "squish_context", "squish_health"],
+      "install": {
+        "copy": [
+          { "from": "generated/mcp/mcp-servers.json", "to": "~/.codex/mcp-servers.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.codex/mcp-servers.json",
+        "toolCheck": "squish_health"
+      }
+    },
+    "cursor": {
+      "type": "mcp",
+      "tools": ["squish_remember", "squish_search", "squish_recall", "squish_context", "squish_health"],
+      "install": {
+        "copy": [
+          { "from": "generated/mcp/mcp-servers.json", "to": "~/.cursor/mcp.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.cursor/mcp.json",
+        "toolCheck": "squish_health"
+      }
+    },
+    "vscode": {
+      "type": "mcp",
+      "tools": ["squish_remember", "squish_search", "squish_recall", "squish_context", "squish_health"],
+      "install": {
+        "copy": [
+          { "from": "generated/mcp/mcp-servers.json", "to": "~/.vscode/mcp/servers.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.vscode/mcp/servers.json",
+        "toolCheck": "squish_health"
+      }
+    },
+    "windsurf": {
+      "type": "mcp",
+      "tools": ["squish_remember", "squish_search", "squish_recall", "squish_context", "squish_health"],
+      "install": {
+        "copy": [
+          { "from": "generated/mcp/mcp-servers.json", "to": "~/.windsurf/mcp-servers.json" }
+        ]
+      },
+      "verify": {
+        "fileExists": "~/.windsurf/mcp-servers.json",
+        "toolCheck": "squish_health"
+      }
+    }
+  },
+  "dependencies": {
+    "mcporter": {
+      "version": "0.7.3",
+      "autoInstall": true,
+      "optional": false,
+      "provides": ["mcp-bridge", "openclaw-memory"]
+    },
+    "@tobilu/qmd": {
+      "version": "2.0.1",
+      "autoInstall": true,
+      "optional": false,
+      "provides": ["fast-search", "bm25", "vector-search"]
+    }
+  },
+  "auth": {
+    "modes": ["none", "token"],
+    "default": "none",
+    "token": {
+      "envVar": "SQUISH_REMOTE_TOKEN",
+      "help": "Set SQUISH_REMOTE_TOKEN for remote mode authentication"
+    }
+  },
+  "pinning": {
+    "mcporter": "0.7.3",
+    "@tobilu/qmd": "2.0.1",
+    "@modelcontextprotocol/sdk": "1.27.1"
+  },
+  "entry": {
+    "mcp": "dist/commands/mcp-server.cjs",
+    "cli": "dist/index.js",
+    "plugin": "packages/plugin-openclaw/dist/index.js"
+  },
+  "compatibility": {
+    "minNodeVersion": "18.0.0",
+    "clients": [
+      { "id": "claude-code", "minVersion": "0.62.0" },
+      { "id": "openclaw", "minVersion": "2026.2.15" },
+      { "id": "opencode", "minVersion": "0.1.0" },
+      { "id": "codex", "minVersion": "0.1.0" },
+      { "id": "cursor", "minVersion": "0.45.0" },
+      { "id": "vscode-mcp", "minVersion": "1.0.0" },
+      { "id": "windsurf", "minVersion": "0.1.0" }
+    ]
+  },
+  "healthCheck": {
+    "mcpTool": "squish_health",
+    "httpEndpoint": "/health"
+  },
+  "generated": {
+    "from": "config/plugin-manifest.json",
+    "generator": "squish-memory@1.0.0",
+    "timestamp": "2026-01-17T00:00:00.000Z"
+  }
+}