squish-memory 1.0.0 → 1.0.2

package/.env.mcp.example

@@ -2,26 +2,33 @@
 SQUISH_MCP_PORT=8767
 SQUISH_MCP_SERVER_ENABLED=true
 
-# Embeddings - Hybrid mode for best quality
-SQUISH_EMBEDDINGS_PROVIDER=hybrid
-SQUISH_MULTIMODAL_EMBEDDINGS_ENABLED=true
+# CORS Configuration (comma-separated origins, * wildcard for port)
+# Default: localhost and 127.0.0.1 on any port
+# SQUISH_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:8080
 
-# Google Cloud Multimodal (1408-dim vectors)
+# Embeddings Provider: local | openai | ollama | google | none | auto
+# Default: local (TF-IDF, no API needed)
+SQUISH_EMBEDDINGS_PROVIDER=local
+
+# 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 +37,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/README.md

@@ -1,11 +1,18 @@
 # Squish - Universal Two-Tier Memory for AI Agents
 
+[![npm version](https://img.shields.io/npm/v/squish-memory)](https://www.npmjs.com/package/squish-memory)
+[![npm downloads](https://img.shields.io/npm/dm/squish-memory)](https://www.npmjs.com/package/squish-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+
 **Squish gives any AI agent persistent, intelligent memory through a two-tier architecture.** Without memory, agents forget everything between sessions. With Squish, they learn, adapt, and get smarter over time - regardless of which agent framework you use.
 
 ```bash
 npm install squish-memory
 ```
 
+**Works out-of-the-box.** No database setup required - local TF-IDF embeddings work instantly. Upgrade to vector search with OpenAI/Ollama when ready.
+
 ## Why Agents Need Memory
 
 | Without Squish | With Squish |
@@ -18,8 +25,8 @@ npm install squish-memory
 ## How It Works
 
 Squish uses a two-tier memory architecture for optimal performance:
-- **Fast Search Tier**: QMD (Quick Markdown Search) provides lightning-fast hybrid BM25 + vector search
-- **Persistent Storage Tier**: SQLite (local) or PostgreSQL (team) ensures durable, reliable memory storage
+- **Short-term Memory (QMD)**: Lightning-fast file-based search using QMD (BM25 + vector). Instant recall, optimized for recent/active context.
+- **Long-term Memory (Database)**: SQLite (local) or PostgreSQL (team) for durable, searchable storage of important memories.
 
 ```
 Agent Action -----> [Squish Memory Layer]
@@ -35,19 +42,18 @@ Agent Action -----> [Squish Memory Layer]
                      │  Write Gate  │ <-- Validate, sanitize, score
                      └──────────────┘
                             |
-                            v
-          ┌─────────────────────┐
-          │  Dual Storage Write │
-          │  ──→ QMD Index      │  (fast search)
-          │  ──→ SQLite/Postgres│  (durable storage)
-          └─────────────────────┘
-                            |
-                            v
-          ┌─────────────────────┐
-          │  Hybrid Retrieval   │
-          │  QMD Search +       │
-          │  Vector Ranking     │
-          └─────────────────────┘
+            ┌───────────────┴───────────────┐
+            v                               v
+     ┌──────────────┐              ┌──────────────┐
+     │ Short-term   │              │ Long-term    │
+     │ QMD (Files)  │              │ SQLite/PG    │
+     │ Fast recall  │              │ Persistent   │
+     └──────────────┘              └──────────────┘
+            |                               |
+            v                               v
+     ┌──────────────────────────────────────────┐
+     │  Hybrid Retrieval: QMD + Vector Ranking  │
+     └──────────────────────────────────────────┘
                             |
                             v
                      Agent Context
@@ -73,6 +79,18 @@ Agent Action -----> [Squish Memory Layer]
 
 ## Quick Start
 
+### Simple Example
+```bash
+# Store a memory
+squish remember "User prefers TypeScript"
+
+# Search memories
+squish search "preferences"
+
+# Check health
+squish health
+```
+
 ### Universal Plugin Installer (Recommended)
 ```bash
 # Install for your AI assistant(s)
@@ -241,18 +259,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
@@ -271,8 +306,8 @@ DATABASE_URL=postgresql://user:pass@host/db
 
 ### Two-Tier Memory System
 Squish employs a two-tier architecture for optimal performance and reliability:
-- **Fast Search Tier**: QMD (Quick Markdown Search) provides hybrid BM25 + vector search with sub-second response times
-- **Persistent Storage Tier**: SQLite (local mode) or PostgreSQL (team mode) ensures durable, ACID-compliant memory storage
+- **Short-term (QMD)**: File-based search using QMD (BM25 + vectors). Ultra-fast for recent context and active memories.
+- **Long-term (Database)**: SQLite (local) or PostgreSQL (team). Durable ACID-compliant storage for important memories that need persistence.
 
 ### Universal Interfaces
 - **MCP Server**: Native integration for Claude Code, OpenClaw, and any MCP-compatible agent

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

@@ -1,7 +1,7 @@
 {
   "id": "squish-memory",
   "name": "Squish Memory",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Universal two-tier memory system for AI agents with hybrid search, core memory, and MCP-first architecture",
   "capabilities": ["mcp", "cli", "web"],
   "targets": {

package/config/settings.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "./settings.schema.json",
+  "embeddings": {
+    "provider": "local",
+    "models": {
+      "openai": {
+        "model": "text-embedding-3-small",
+        "availableModels": [
+          "text-embedding-3-small",
+          "text-embedding-3-large"
+        ]
+      },
+      "google": {
+        "model": "gemini-embedding-001",
+        "availableModels": [
+          "gemini-embedding-001",
+          "gemini-embedding-2"
+        ]
+      },
+      "ollama": {
+        "model": "nomic-embed-text:v1.5",
+        "availableModels": [
+          "nomic-embed-text:v1.5",
+          "mxbai-embed-large"
+        ]
+      }
+    }
+  },
+  "api": {
+    "openai": {
+      "apiKey": null,
+      "apiUrl": "https://api.openai.com/v1/embeddings"
+    },
+    "google": {
+      "apiKey": null,
+      "projectId": null
+    },
+    "ollama": {
+      "url": "http://localhost:11434"
+    }
+  },
+  "mcp": {
+    "serverPort": 8767,
+    "serverEnabled": true
+  },
+  "features": {
+    "lifecycleEnabled": true,
+    "summarizationEnabled": true,
+    "agentIsolation": true
+  }
+}