squish-memory 0.7.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "squish-memory",
+  "owner": {
+    "name": "michielhdoteth"
+  },
+  "plugins": [
+    {
+      "name": "squish",
+      "version": "0.6.0",
+      "description": "Production-ready two-tier memory system for Claude Code with 11 consolidated MCP tools. Always-visible core memory (persona, user info, project context, notes) + intelligent context paging. Advanced features: merge detection, semantic search, lifecycle management, bridge discovery. Features: 30-100x performance gains, automatic session hooks, privacy-first encryption, PostgreSQL team collaboration. Major consolidation: 39% fewer tools with same functionality.",
+      "author": {
+        "name": "michielhdoteth"
+      },
+      "license": "MIT",
+      "homepage": "https://github.com/michielhdoteth/squish",
+      "repository": "https://github.com/michielhdoteth/squish.git",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,32 @@
+{
+  "name": "squish",
+  "version": "0.6.0",
+  "description": "11 consolidated MCP tools for persistent two-tier memory system: core_memory, context_paging, merge, plus semantic search, lifecycle management, and intelligent context paging",
+  "author": {
+    "name": "michielhdoteth",
+    "url": "https://github.com/michielhdoteth"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/michielhdoteth/squish#readme",
+  "repository": "https://github.com/michielhdoteth/squish.git",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-plugin",
+    "mcp-server",
+    "memory",
+    "persistent-memory",
+    "core-memory",
+    "context-management",
+    "semantic-search",
+    "full-text-search",
+    "local-first",
+    "privacy",
+    "agent-memory",
+    "slash-commands",
+    "two-tier-architecture",
+    "model-context-protocol"
+  ],
+  "commands": "./commands/",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "squish": {
+      "command": "node",
+      "args": ["./dist/index.js"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}",
+      "env": {
+        "SQUISH_MODE": "local",
+        "NODE_ENV": "production",
+        "SQUISH_DATA_DIR": "${CLAUDE_WORKING_DIRECTORY}/.squish"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 michielhdoteth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,556 @@
+# Squish - Two-Tier Memory System for Claude Code
+
+A persistent, context-aware memory plugin for Claude Code (v0.7.0) that provides intelligent memory management with a two-tier architecture: always-in-context core memory (2KB) plus context paging for selective memory loading.
+
+**What's New in v0.7.0:**
+- **OpenClaw Gateway**: WebSocket API for OpenClaw AI assistant integration
+- **Enhanced Search**: Improved semantic search with better ranking
+- **Memory Tools**: Expanded toolkit for memory management
+
+## Features
+
+### Memory Architecture
+
+- **Core Memory (Tier 1)**: 2KB always-visible persistent memory divided into 4 sections
+  - `persona`: AI assistant personality and role definition
+  - `user_info`: Information about the user and their preferences
+  - `project_context`: Current project architecture and patterns
+  - `working_notes`: Transient notes during active work sessions
+
+- **Context Paging (Tier 2)**: Agent-controlled memory loading with token budgeting
+  - Dynamically load/evict memories based on relevance
+  - Token-aware context management (8KB default budget)
+  - Automatic memory decay and lifecycle management
+
+### MCP Tools
+
+**Core Memory Management:**
+- `/core_memory` - View, edit, or append to always-in-context memory sections
+
+**Context & Search:**
+- `/context_paging` - Load/evict/view loaded memories in current session
+- `/context` - Get project context with semantically relevant memories
+- `/search` - Full-text + semantic search across memories
+- `/context_status` - Check context window usage and loaded memories
+
+**Memory Operations:**
+- `/remember` - Store new observations, facts, decisions, and preferences
+- `/recall` - Retrieve specific memories by ID with metadata
+- `/observe` - Record tool usage and patterns observed during execution
+
+**Memory Management:**
+- `/merge` - Detect duplicates, preview/approve/reject merges
+
+**System:**
+- `/health` - Check MCP server and database connectivity
+
+### Storage
+
+- **SQLite** (local mode): Local-first, zero setup required
+- **PostgreSQL** (team mode): Shared memory across users
+- Smart embeddings: Local TF-IDF (offline) for SQLite, OpenAI/Ollama for PostgreSQL
+
+### OpenClaw Gateway (v0.7.0)
+
+Squish provides a **WebSocket gateway** for OpenClaw AI assistant integration, enabling OpenClaw agents to access Squish's memory system.
+
+**Gateway Details:**
+- **Protocol**: WebSocket
+- **Port**: 18789
+- **Messages**: search, remember, recall, status
+
+**Enable Gateway:**
+```bash
+export OPENCLAW_GATEWAY_ENABLED=true
+```
+
+**Message Format:**
+```json
+{
+  "type": "search",
+  "id": "unique-request-id",
+  "payload": {
+    "query": "authentication flow",
+    "limit": 10
+  }
+}
+```
+
+**Response Format:**
+```json
+{
+  "type": "search",
+  "id": "unique-request-id",
+  "success": true,
+  "data": {
+    "results": [...],
+    "count": 10
+  }
+}
+```
+
+## Installation
+
+### Install via Claude Code Marketplace (Recommended)
+
+```bash
+# Step 1: Add the Squish marketplace
+/plugin marketplace add https://github.com/michielhdoteth/squish.git
+
+# Step 2: Install Squish
+/plugin install squish@michielhdoteth-squish
+```
+
+### For Local Development Testing
+
+Load the plugin directly without installation:
+
+```bash
+claude --plugin-dir "C:\Users\michi\Desktop\squish-cc\squish"
+```
+
+Or on macOS/Linux:
+
+```bash
+claude --plugin-dir "/path/to/squish"
+```
+
+This loads the plugin from your development directory and allows immediate testing of changes.
+
+### For Production Installation
+
+1. Build the plugin:
+```bash
+npm install
+npm run build
+```
+
+2. Package as npm module:
+```bash
+npm pack
+```
+
+3. Install the `.tgz` file:
+```bash
+npm install -g squish-memory-0.7.0.tgz
+```
+
+## Configuration
+
+### Environment Variables
+
+**Required (SQLite mode - default):**
+- None! Works out-of-the-box with local TF-IDF embeddings
+
+**Optional (SQLite mode):**
+- `SQUISH_DATA_DIR`: Custom data directory (default: `./.squish` in project root)
+- `SQUISH_EMBEDDINGS_PROVIDER`: Force embedding provider (`none`, `local`, `openai`, `ollama`)
+
+**Team Mode (PostgreSQL):**
+- `DATABASE_URL`: PostgreSQL connection string (activates team mode)
+- `SQUISH_OPENAI_API_KEY`: OpenAI API key for embeddings (optional in team mode)
+- `SQUISH_OLLAMA_URL`: Ollama server URL for local LLM embeddings
+
+**OpenClaw Gateway (v0.7.0):**
+```bash
+# Enable OpenClaw WebSocket gateway
+OPENCLAW_GATEWAY_ENABLED=true
+```
+
+**Advanced Options:**
+```bash
+# Lifecycle management
+SQUISH_LIFECYCLE_ENABLED=true
+SQUISH_LIFECYCLE_INTERVAL=3600000  # ms
+
+# Session summarization
+SQUISH_SUMMARIZATION_ENABLED=true
+SQUISH_INCREMENTAL_THRESHOLD=10
+SQUISH_ROLLING_WINDOW_SIZE=50
+
+# Agent isolation
+SQUISH_AGENT_ISOLATION_ENABLED=true
+SQUISH_DEFAULT_VISIBILITY=private  # private|project|team|global
+```
+
+## Quick Start
+
+### 1. Initialize Core Memory
+
+Store basic information that will always be available:
+
+```bash
+/core_memory action=edit projectId=my-project section=persona content="I am a helpful assistant specialized in cloud infrastructure and DevOps."
+```
+
+### 2. Store Session Observations
+
+Record what you learn during work:
+
+```bash
+/remember projectId=my-project type=observation action=discovered target=kubernetes_pattern summary="Found the team uses GitOps with ArgoCD" tags=["kubernetes","gitops","devops"]
+```
+
+### 3. Search Your Memory
+
+Find relevant past learnings:
+
+```bash
+/search projectId=my-project query="kubernetes deployment" limit=5
+```
+
+### 4. Load Context for an Agent
+
+Load relevant memories for agent use:
+
+```bash
+/context_paging action=load sessionId=session-123 projectId=my-project memoryId=mem-456
+```
+
+## Architecture
+
+### Database Schema
+
+**Core Tables:**
+- `core_memory` - Always-in-context 2KB persistent memory
+- `memories` - Main memory storage with lifecycle tracking
+- `context_sessions` - Per-session context window tracking
+- `conversations` - Chat session records
+- `messages` - Message history with embeddings
+
+**Lifecycle Tables:**
+- `memory_associations` - Semantic relationships between memories
+- `memory_merge_proposals` - Duplicate detection proposals
+- `memory_merge_history` - Audit trail of merges
+- `memory_snapshots` - Before/after diffs for auditability
+- `session_summaries` - Incremental and rolling summaries
+
+**Search & Discovery:**
+- `entities` - Named entities (functions, files, patterns, people)
+- `entity_relations` - Relationships between entities
+- `memory_hash_cache` - Hash signatures for duplicate detection
+
+### Memory Lifecycle States
+
+Each memory has:
+- **Sector**: episodic, semantic, procedural, autobiographical, working
+- **Tier**: hot (recent/relevant), warm (accessible), cold (archived)
+- **Status**: active, merged, superseded, expired
+- **Visibility**: private (user), project, team, global
+
+### Hooks
+
+4 lifecycle hooks automatically trigger:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `SessionStart` | Session begins | Initialize session memory, load core memory |
+| `UserPromptSubmit` | User sends message | Enhance prompt with relevant memories |
+| `PostToolUse` | Tool completes | Record tool usage observations |
+| `SessionEnd` | Session closes | Persist discoveries, summarize session |
+
+## API Reference
+
+### Core Memory Operations
+
+```bash
+# View all sections
+/core_memory action=view projectId=PROJECT_ID
+
+# Edit a section
+/core_memory action=edit projectId=PROJECT_ID section=persona content="..."
+
+# Append to a section
+/core_memory action=append projectId=PROJECT_ID section=working_notes content="New observation"
+```
+
+### Memory Management
+
+```bash
+# Store a memory
+/remember projectId=PROJECT_ID type=fact content="..." tags=["tag1","tag2"]
+
+# Search memories
+/search projectId=PROJECT_ID query="search term" type=fact limit=10
+
+# Retrieve by ID
+/recall memoryId=MEMORY_ID
+
+# Get merged view
+/context projectId=PROJECT_ID include=memories include=observations limit=20
+```
+
+### Context Paging
+
+```bash
+# Load memory into session context
+/context_paging action=load sessionId=SESSION_ID projectId=PROJECT_ID memoryId=MEMORY_ID
+
+# Unload memory from session
+/context_paging action=evict sessionId=SESSION_ID memoryId=MEMORY_ID
+
+# View loaded memories
+/context_paging action=view sessionId=SESSION_ID
+
+# Check context usage
+/context_status projectId=PROJECT_ID sessionId=SESSION_ID
+```
+
+### Memory Merging
+
+```bash
+# Detect duplicate memories
+/merge projectId=PROJECT_ID action=detect
+
+# List merge proposals
+/merge projectId=PROJECT_ID action=list status=pending
+
+# Preview a merge
+/merge projectId=PROJECT_ID action=preview proposalId=PROPOSAL_ID
+
+# Approve merge
+/merge projectId=PROJECT_ID action=approve proposalId=PROPOSAL_ID reviewNotes="Approved because..."
+
+# Reject merge
+/merge projectId=PROJECT_ID action=reject proposalId=PROPOSAL_ID reviewNotes="Keep separate because..."
+
+# Get merge statistics
+/merge projectId=PROJECT_ID action=stats
+```
+
+## Database Modes
+
+### SQLite Mode (Default - Local Development)
+
+- **Storage**: `~/.squish/squish.db` (local SQLite database)
+- **Embeddings**: Local TF-IDF (no API calls, works offline)
+- **Performance**: Fast, suitable for single-user development
+- **Setup**: Zero configuration required
+- **Data**: Stored locally on machine
+
+### PostgreSQL Mode (Team - Enterprise)
+
+- **Storage**: Shared PostgreSQL database
+- **Embeddings**: Optional OpenAI or Ollama for better semantic search
+- **Performance**: Optimized for multi-user teams
+- **Setup**: Requires DATABASE_URL configuration
+- **Data**: Shared across team members with access control
+
+```bash
+# Enable PostgreSQL mode
+DATABASE_URL=postgresql://user:password@host/dbname
+SQUISH_OPENAI_API_KEY=sk-... # optional
+```
+
+## Benchmarks
+
+Squish has been tested against industry-standard datasets for memory systems.
+
+### LongMemEval Dataset
+
+| Metric | Value |
+|--------|-------|
+| **Accuracy** | 80% (16/20 correct) |
+| **Embeddings** | Nomic (nomic-embed-text) |
+| **Generation** | Claude Haiku |
+| **Judge** | Claude Haiku |
+| **Avg Latency** | ~1.2s per question |
+
+### Key Strengths
+
+- **Strong accuracy**: 80% on LongMemEval benchmark
+- **Flexible deployment**: Local embeddings with quality generation
+- **Privacy-first**: Local embeddings option available
+- **Consistent retrieval**: Successfully finds entities like names, locations, and relationships
+
+### Test Coverage
+
+The benchmark tests memory retrieval across:
+- Long-term conversational memory
+- Entity resolution (people, places, organizations)
+- Temporal reasoning (events, dates, timelines)
+- Relationship tracking (family, professional, social)
+
+### Running Benchmarks
+
+```bash
+cd ../squish-benchmarks
+
+# Pull Nomic embeddings
+ollama pull nomic-embed-text
+
+# Run LongMemEval benchmark
+bun run src/index.ts run -e nomic-embed-text -b longmemeval
+```
+
+For detailed benchmark results and methodology, see [squish-benchmarks](../squish-benchmarks/).
+
+## Development
+
+### Project Structure
+
+```
+squish/
+├── .claude-plugin/
+│   ├── plugin.json          # Plugin manifest
+│   └── marketplace.json     # Marketplace metadata
+├── .mcp.json                # MCP server configuration
+├── api/
+│   └── openclaw/
+│       └── gateway.ts       # OpenClaw WebSocket gateway (v0.7.0)
+├── core/
+│   ├── core-memory.ts       # Core memory operations
+│   ├── context-paging.ts    # Memory loading system
+│   ├── local-embeddings.ts  # TF-IDF embeddings
+│   ├── embeddings.ts        # Embedding providers
+│   └── logger.ts
+├── db/
+│   ├── index.ts             # Database adapter
+│   ├── bootstrap.ts         # Schema initialization
+│   └── adapter.ts           # SQLite/PostgreSQL abstraction
+├── drizzle/
+│   ├── schema.ts            # PostgreSQL schema
+│   └── schema-sqlite.ts     # SQLite schema
+├── skills/
+│   └── squish-memory/
+│       └── SKILL.md         # OpenClaw skill definition (v0.7.0)
+├── commands/                # Slash commands
+├── hooks/                   # Lifecycle hooks
+├── index.ts                 # MCP server entry point
+├── config.ts                # Configuration management
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Building
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm run test
+
+# Pack for distribution
+npm pack
+```
+
+### Testing
+
+```bash
+# Run comprehensive system test
+node test-v0.5.0.mjs
+
+# Start development with watch mode
+npm run dev
+```
+
+## Troubleshooting
+
+### Database Issues
+
+**Error: "database disk image is malformed"**
+- SQLite database corrupted - delete `~/.squish/squish.db` and restart
+
+**Error: "Connection refused"** (PostgreSQL mode)
+- Verify DATABASE_URL is correct: `postgresql://user:pass@host:5432/dbname`
+- Ensure PostgreSQL server is running
+
+### MCP Server Issues
+
+**Error: "Hook error: ERR_UNSUPPORTED_ESM_URL_SCHEME"**
+- Use relative paths in hooks.json instead of absolute Windows paths
+- Use `./hooks/file.js` instead of `C:\path\to\hooks.js`
+
+**Error: "Plugin not found in marketplace"**
+- Using `--plugin-dir` flag? This is expected - not installed from marketplace
+- For local development, this is normal behavior
+
+### Performance Issues
+
+**Memory is growing unbounded**
+- Enable lifecycle management: `SQUISH_LIFECYCLE_ENABLED=true`
+- Review memory decay rates in configuration
+
+### OpenClaw Gateway Issues (v0.7.0)
+
+**Gateway not starting on port 18789**
+- Check if port is already in use: `lsof -i :18789` (macOS/Linux) or `netstat -ano | findstr :18789` (Windows)
+- Verify gateway is enabled: `echo $OPENCLAW_GATEWAY_ENABLED`
+- Check logs for connection errors
+
+**OpenClaw client cannot connect**
+- Ensure gateway is running: Check Squish logs for "OpenClaw gateway listening on port 18789"
+- Verify firewall allows connections on port 18789
+- Check WebSocket client is using correct protocol (ws:// or wss://)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Commit changes: `git commit -am 'Add feature'`
+4. Push to branch: `git push origin feature/my-feature`
+5. Submit a pull request
+
+## License
+
+MIT - See LICENSE file for details
+
+## Support
+
+- GitHub Issues: https://github.com/michielhdoteth/squish/issues
+- Documentation: https://github.com/michielhdoteth/squish#readme
+- OpenClaw: https://github.com/openclaw/openclaw - Personal AI assistant platform
+
+## Changelog
+
+### v0.7.0 (Latest)
+- **OpenClaw Gateway**: WebSocket API for OpenClaw AI assistant integration
+- **Enhanced Search**: Improved semantic search with better ranking
+- **Memory Tools**: Expanded toolkit for memory management
+- **OpenClaw Skill**: Ready-to-use skill for OpenClaw installation
+
+### v0.6.0
+- Implemented hybrid memory retrieval with multi-factor scoring (semantic, recency, coactivation, importance)
+- Added fact extraction for structured knowledge discovery
+- Added entity resolver for tracking and deduplicating entities across sessions
+- Refactored capture.ts for better type safety
+- Updated plugin-wrapper to use smart search config (50 candidates → top 3)
+- Added utility functions for hook error handling
+- Reorganized test scripts into scripts/db/ and scripts/test/
+- Updated .gitignore to exclude references/ and opencode/
+- Cleaned up project for distribution
+
+### v0.5.0
+- Implemented smart embeddings strategy (local TF-IDF for SQLite, OpenAI/Ollama for PostgreSQL)
+- Added missing core_memory and context_sessions tables to bootstrap
+- Fixed plugin manifest validation for Claude Code compatibility
+- Fixed hooks path resolution for Windows compatibility
+- Consolidated 18 MCP tools to 11 with action-based API
+- Core memory fully functional with 4-section architecture
+
+### v0.4.1
+- Consolidated 25 command files to 15
+- Removed 4 phantom commands
+- Fixed validation order in MCP request handlers
+
+### v0.3.0
+- Lifecycle management with memory decay
+- Session summarization (incremental and rolling)
+- Agent-aware memory isolation
+- Memory governance and protection
+- Memory associations and graph traversal
+
+### v0.2.0
+- Vector embeddings for semantic search
+- Memory snapshots for auditability
+- Folder-scoped observations
+
+### v0.1.0
+- Initial release with core memory and context paging
+- Full-text search (FTS5)
+- Two-tier architecture

package/commands/context-paging.md

@@ -0,0 +1,51 @@
+---
+description: Manage working set (load, evict, or view loaded memories)
+---
+
+# Context Paging Management
+
+Manage your working set of memories for context tracking. Note: Claude manages its own context and token usage. These tools track which memories you're actively working with.
+
+## Actions
+
+### load
+Add a memory to your working set for active tracking.
+- Marks memory as currently relevant
+- Helps organize which memories are in your active consideration set
+- Does not affect Claude's actual context usage
+
+### evict
+Remove a memory from your working set.
+- Removes from your active tracking set
+- Memory is still stored and searchable
+- Useful when memory is no longer actively relevant
+
+### view
+View all memories currently in your working set.
+- Shows all memories you're actively tracking
+- Displays session ID and timestamp loaded
+- Lists memory content and metadata
+
+## Usage Examples
+
+Load a memory to working set:
+```
+/context-paging action=load sessionId=sess-123 memoryId=mem-uuid-456
+```
+
+Evict memory from working set:
+```
+/context-paging action=evict sessionId=sess-123 memoryId=mem-uuid-456
+```
+
+View all loaded memories in session:
+```
+/context-paging action=view sessionId=sess-123
+```
+
+## Important Notes
+
+- Working set is per-session - each Claude Code session has its own working set
+- Claude Code manages its own context window automatically
+- These tools are for your own organizational purposes
+- Memory removal from working set does not delete the memory permanently