squish-memory 1.0.2 → 1.2.0

package/.env.example

@@ -0,0 +1,146 @@
+# Squish Environment Configuration
+# Copy this file to .env and customize as needed
+
+# =============================================================================
+# MODE (default: local)
+# =============================================================================
+# local  - SQLite database, TF-IDF embeddings (no API key needed)
+# remote - PostgreSQL + Redis, provider-backed embeddings
+
+SQUISH_MODE=local
+
+# =============================================================================
+# DATABASE (remote mode only)
+# =============================================================================
+DATABASE_URL=postgres://squish:squish_dev@localhost:5432/squish
+REDIS_URL=redis://localhost:6379
+
+# =============================================================================
+# LOCAL MODE DATA DIRECTORY
+# =============================================================================
+SQUISH_DATA_DIR=./.squish
+
+# =============================================================================
+# MCP SERVER
+# =============================================================================
+SQUISH_MCP_PORT=8767
+SQUISH_MCP_SERVER_ENABLED=false
+
+# CORS (comma-separated origins, * wildcard for port)
+# SQUISH_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:8080
+
+# =============================================================================
+# EMBEDDINGS PROVIDER
+# =============================================================================
+# Options: local | openai | ollama | google | none | auto
+# local = TF-IDF (no API key needed)
+# auto  = Try OpenAI > Ollama > Google > local fallback
+SQUISH_EMBEDDINGS_PROVIDER=local
+
+# OpenAI (example: set both key and model)
+# SQUISH_OPENAI_API_KEY=sk-...
+# SQUISH_OPENAI_API_URL=https://api.openai.com/v1/embeddings
+# SQUISH_OPENAI_EMBEDDING_MODEL=<openai-embedding-model>
+
+# Ollama (example: set URL and model served by your local Ollama)
+# SQUISH_OLLAMA_URL=http://localhost:11434
+# SQUISH_OLLAMA_EMBEDDING_MODEL=<ollama-embedding-model>
+
+# LM Studio (example: set URL and model loaded in LM Studio)
+# SQUISH_LM_STUDIO_URL=http://localhost:1234
+# SQUISH_LM_STUDIO_EMBEDDING_MODEL=<lm-studio-embedding-model>
+
+# Transformers.js local (example: set a Hugging Face ONNX embedding model)
+# SQUISH_LOCAL_MODEL=<huggingface-onnx-embedding-model>
+
+# Google Cloud
+# 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
+# SQUISH_GOOGLE_EMBEDDING_MODEL=<google-embedding-model>
+
+# Embedding reliability
+SQUISH_EMBEDDINGS_TIMEOUT_MS=30000
+SQUISH_EMBEDDINGS_MAX_RETRIES=3
+SQUISH_EMBEDDINGS_RETRY_DELAY_MS=1000
+
+# Optional LLM graph enrichment (off by default for launch-safe local mode)
+SQUISH_LLM_ENABLED=false
+# SQUISH_LLM_PROVIDER=openai
+# SQUISH_LLM_ENDPOINT=http://localhost:1234
+# SQUISH_LLM_EXTRACTION_MODEL=<llm-extraction-model>
+# SQUISH_LLM_REASONING_MODEL=<llm-reasoning-model>
+
+# =============================================================================
+# QMD (local markdown search)
+# =============================================================================
+SQUISH_QMD_ENABLED=false
+# SQUISH_QMD_COLLECTIONS=./qmd-collections
+# SQUISH_QMD_FALLBACK=hybrid
+
+# =============================================================================
+# LIFECYCLE & MEMORY
+# =============================================================================
+SQUISH_LIFECYCLE_ENABLED=true
+SQUISH_SUMMARIZATION_ENABLED=true
+SQUISH_GOVERNANCE_ENABLED=true
+
+# Memory tier decay (v1.1.0+)
+# Threshold for tier demotion: memories below this score get demoted (default: 0.1)
+# SQUISH_DECAY_THRESHOLD=0.1
+# Decay job cron schedule (default: hourly)
+# SQUISH_LIFECYCLE_DECAY_CRON=0 * * * *
+
+# =============================================================================
+# ENCRYPTION (v1.1.0+)
+# =============================================================================
+# Client-side AES-256-GCM encryption for memory content
+# Set passphrase to enable encryption (requires existing memories to be re-encrypted)
+# SQUISH_ENCRYPTION_PASSPHRASE=your-secure-passphrase
+
+# Core memory limits (v0.9.2+)
+# SQUISH_CORE_MEMORY_TOTAL_BYTES=16384
+# SQUISH_CORE_MEMORY_SECTION_BYTES=4096
+
+# =============================================================================
+# SUPABASE / NEON (v1.1.0+)
+# =============================================================================
+# Remote PostgreSQL backend (use either Supabase OR Neon, not both)
+# SUPABASE_URL=https://your-project.supabase.co
+# SUPABASE_SERVICE_KEY=your-service-key
+# NEON_PROJECT_ID=your-neon-project-id
+# NEON_SERVICE_KEY=your-service-key
+
+# =============================================================================
+# GRAPH BOOST (v1.1.0+)
+# =============================================================================
+# Scoring weight for graph boost in recall (default: 1.5)
+# Higher = more influence from memory associations
+# SQUISH_WEIGHT_GRAPH_BOOST=1.5
+# SQUISH_GRAPH_AUTO_BUILD=true
+# SQUISH_GRAPH_EXTRACTION_METHOD=auto
+
+# =============================================================================
+# MANAGED MODE (Squish Cloud)
+# =============================================================================
+# SQUISH_MANAGED_MODE=false
+# SQUISH_MANAGED_API_URL=https://api.squish.dev
+# SQUISH_MANAGED_API_KEY=your-api-key
+
+# =============================================================================
+# REMOTE AUTH
+# =============================================================================
+# Token-based auth (primary)
+# SQUISH_REMOTE_TOKEN=
+
+# OAuth (optional)
+# SQUISH_OAUTH_AUTH_URL=
+# SQUISH_OAUTH_TOKEN_URL=
+# SQUISH_OAUTH_CLIENT_ID=
+
+# =============================================================================
+# OPENCLAW GATEWAY
+# =============================================================================
+OPENCLAW_GATEWAY_ENABLED=false

package/CHANGELOG.md

@@ -2,6 +2,208 @@
 
 All notable changes to Squish will be documented in this file.
 
+## [1.2.0] - 2026-04-19
+
+### Added - QMD Integration
+
+- **Dependency**: Add @tobilu/qmd@^2.1.0 as npm package
+- **Wrapper**: New core/search/qmd-wrapper.ts with search, query, vsearch, embed functions
+- **Usage as library**: Uses SDK library API (not CLI MCP wrapper)
+
+### Added - Persistent Hot Cache (Karpathy-Style)
+
+- **Persistent storage**: .squish/hot-cache.json survives restart
+- **Deduplication**: SHA256 hash-based content deduplication
+- **Stale prevention**: Entries flagged after 7 days without reference
+- **Auto-clean**: Entries older than 14 days removed on load
+- **Session integration**: Loaded on auto-load, saved on session end
+- **Size limit**: ~500 words max with trim-to-recent policy
+
+### Changed - Memory Runtime
+
+- **Simplified lifecycle**: Removed deprecated warm tier (hot/cold only now)
+- **Updated schemas**: Both SQLite and Postgres tier columns now hot|cold
+- **Updated lifecycle**: TIER_THRESHOLDS only has hot and cold thresholds
+- **Updated scorer**: Removed warm scoring bonuses
+- **Updated CLI**: Descriptions reflect simplified tier system
+
+## [1.2.0] - 2026-04-19
+
+### Added - Belief System (Derived Semantic Layer)
+
+- **Belief extraction from memories**: Automatically extracts beliefs from durable memories
+- **Belief types**: decision, preference, constraint, failure_cause, state_change, dispute
+- **Belief decay engine**: 30-day half-life, disputed beliefs decay 1.5x faster
+- **Source tracking**: Each belief tracks source memories for provenance
+- **Integration**: Beliefs extracted on both explicit and auto-capture durable writes
+
+### Changed - Schema Integration
+
+- **Canonical schema**: Belief tables now in SQLite and Postgres drizzle schemas
+- **Bootstrap migration**: Belief table creation included in db/bootstrap.ts
+- **Decay fields**: last_confirmed_at, belief_decay_rate, source_count, confidence
+
+### Changed - Scheduler Resilience
+
+- **Catch-up logic**: On scheduler init, checks for missed jobs and runs catch-up
+- **Grace period**: Jobs with elapsed > 1.5x expected interval trigger catch-up
+- **Handles sleep/wake**: No more missed jobs when machine is off/sleeping
+
+### Added - Query Functions
+
+- **getAllBeliefs()**: Query all beliefs for a project with filtering
+- **searchBeliefs()**: Search beliefs by statement content
+- **Provenance display**: Memory inspection shows source count, evidence preview
+
+### Fixed - Trust Surfaces
+
+- **Beliefs in context**: Context state now includes extracted beliefs
+- **Beliefs in trust report**: Trust report surfaces belief summaries
+- **Enhanced inspect**: Memory explain shows belief provenance
+
+### Added - Signal-Aware Memory Runtime
+- **Signal distillation engine**: Captured events are now classified as `discard`, `session-only`, `durable-distilled`, or `durable-raw+distilled`
+- **Session working set**: Active files, recent commands, failures, hypotheses, active places, and graph cues are compacted for wake-up continuity
+- **Raw fallback snapshots**: Nuance-sensitive durable events can keep linked raw artifacts without polluting normal retrieval
+- **Incremental place + graph routing**: Durable writes now feed place assignment and graph enrichment as part of the same runtime loop
+
+### Added - Trust-Oriented CLI And MCP Surfaces
+- **`squish health`**: New health command for project scope, subsystem status, and next-step guidance
+- **`squish inspect` / `squish_inspect`**: Explanation path for why a memory exists, whether raw fallback exists, and how legacy records should be read
+- **Structured MCP trust outputs**: `squish_context`, `squish_health`, and `squish_stats` now expose current project, runtime state, and recovery guidance in a predictable shape
+
+### Changed - Project Context And Wake-Up Semantics
+- **Canonical current project**: Normal context output now prefers the real workspace path and suppresses legacy placeholder project noise
+- **Wake-up order**: Session working set and active runtime state are surfaced before broad durable recall
+- **Stats semantics**: Durable memory totals are now clearly separated from capture-era signal telemetry
+
+### Fixed - Trust Consistency
+- **`squish doctor` coherence**: Doctor now reads as one combined trust-and-diagnostics command instead of two stacked reports
+- **Legacy inspection**: Older memories now report `legacy-durable` instead of `unknown`, with explicit provenance text
+- **Release verification path**: Added `bun run verify:mcp` for packaged MCP health verification
+
+### Docs
+- README, CLI reference, install quickstart, architecture notes, and release notes updated to match the automatic memory runtime and current command surface
+
+### Added - Unified Write Path (squish_remember)
+- **New unified memory tool**: `squish_remember` auto-detects memory vs learning routing
+- **Auto-type detection**: Detects `success`, `failure`, `fix`, `observation`, `decision`, `preference`, `note`, `reflection`
+- **Hot/cold tier support**: Automatic routing to appropriate storage tier
+- **Code pattern detection**: Recognizes code changes, errors, fixes in agent outputs
+- **Place and pin flags**: Support for place-based and pinned memories
+
+### Added - Graph Auto-Update
+- **Auto-update graph on remember**: Knowledge graph updated automatically when memories are stored
+- **Auto-update graph on link**: Graph updated when associations are created between memories
+- **Integration**: Graph module now integrated into main write path (was previously standalone)
+
+### Added - New CLI Commands
+- **`squish run web`**: Start web UI on port 37777
+- **`squish migrate`**: Unify multiple .squish folders into single location
+- **Full CLI suite**: 10+ commands (remember, search, recall, recent, context, stats, forget, link, stale, clean)
+
+### Added - Memory Decay System
+- **Enabled by default**: Memory decay now runs automatically (was broken in 1.1.x)
+- **Configurable intervals**: Sector decay intervals now configurable via env vars
+- **Auto-clean enabled**: Automatic cleanup of expired memories (was dry-run only)
+- **Fixed**: Removed dead code and consolidated decay logic
+
+### Added - add-mcp Integration
+- **Universal MCP installation**: Replaced manual config writing with `add-mcp`
+- **Multi-client support**: Works with Zed, Goose, Gemini CLI, Claude Code, Cursor, OpenCode, Windsurf
+- **Global flag**: `--global` flag for user-level installation
+- **Simplified installer**: `bin/install-interactive.mjs` rewritten to use add-mcp
+
+### Fixed - v1.1.5 Issues
+- **bin/ tracked in git**: Removed from .gitignore, now included in npm package
+- **CLI commands work**: Fixed npm publishing issue that broke CLI
+- **Type safety**: Fixed LSP errors, obsidian-vault import path, cron types
+
+### Refactored - Code Cleanup
+- **Consolidated estimateTokens**: Moved from 5 files to single source (`core/context/context-window.ts`)
+- **Consolidated MemoryDiff**: Moved from 2 files to `core/snapshots/comparison.ts`
+- **Removed stubs**: Deleted `core/autosave.ts`, `core/external-folder/`, `core/config.js`
+- **Implemented placeholders**: `readFromVault()` in obsidian-vault now functional
+
+### Refactored - Legacy Removal
+- **Removed hooks/**: No longer needed (add-mcp handles installation)
+- **Removed install scripts**: `bin/install-claude-code.sh`, `bin/install-opencode.sh` deleted
+- **Removed config/hooks/**: Hook config files for Claude Code, Cursor, OpenCode, Windsurf deleted
+- **Removed unused config files**: 10+ unused JSON configs deleted (mcp.json, plugin.json, etc.)
+- **Removed core/adapters/scripts/**: Legacy adapter install scripts deleted
+
+### Refactored - MD Docs Cleanup
+- **Removed from core/commands/**: 11 .md files deleted (docs belong in README/CHANGELOG)
+- **Updated package.json**: Removed explicit .md file entries from files array
+
+## [1.1.6] - 2026-04-13
+
+### Fixed - MCP HTTP Transport Migration
+- **Migrated MCP HTTP from SSE to Streamable HTTP**: The deprecated SSE transport wasn't working. Now uses `StreamableHTTPServerTransport` from the MCP SDK with proper session handling.
+
+### Fixed - Database Schema Migrations
+- Added `session_summaries` table
+- Added `memory_associations.metadata` column
+- Added `memories_fts.summary` column (recreates FTS table)
+
+### Added - QMD Dependency
+- Added `qmd` as bundled dependency
+
+## [1.1.5] - 2026-04-11
+
+### Added - Release Prep Enhancements
+- **New environment variables**: SQUISH_ENCRYPTION_PASSPHRASE, SQUISH_DECAY_THRESHOLD, SQUISH_LIFECYCLE_DECAY_CRON, SUPABASE_URL, SUPABASE_SERVICE_KEY, NEON_PROJECT_ID, NEON_SERVICE_KEY, SQUISH_WEIGHT_GRAPH_BOOST
+- **PostgreSQL schema**: Added memory_associations, namespaces, and maintenance_jobs tables for full parity with SQLite
+- **Release workflow**: Fixed test step to skip when no tests configured
+
+### Added - Wiki Storage
+- **Memory storage module**: New core/memory/markdown/markdown-storage.ts for memory file storage
+- **Memory hooks**: New core/memory/hooks.ts for memory lifecycle hooks
+
+### Changed - Version Bump
+- Updated all version references from 1.1.0 to 1.1.5
+
+## [1.1.0] - 2026-03-28
+
+### Changed - Launch Surface Cleanup
+- Removed legacy CLI commands `observe` and `projects`
+- Removed legacy MCP tools `squish_observe` and `squish_projects`
+- `squish learn` is now the single capture path for `success`, `failure`, `fix`, and `observation`
+- `squish context --list-projects` is now the single project discovery path
+- Launch docs and help now reflect the final 18-tool MCP surface
+
+## [1.1.0-enhanced] - 2026-03-27
+
+### Added - Security & Encryption
+- **Client-side encryption**: AES-256-GCM encryption for sensitive memories
+- **Optional encryption**: Controlled via `SQUISH_ENCRYPTION_PASSPHRASE` env var
+- **Encryption MCP tools**:
+  - `squish_set_passphrase`: Set encryption passphrase (writes to `.squish/.env`)
+  - `squish_rotate_key`: Rotate passphrase and re-encrypt all memories
+- **New schema columns**: `encrypted_content`, `encryption_nonce`, `is_encrypted`, `status`
+
+### Added - Graph-Boosted Retrieval
+- **Graph associations**: Memories linked by coactivation count
+- **Boost computation**: `weight * coactivationCount` per association
+- **Hybrid search integration**: Graph boost added to RRF scoring
+- **Configurable weight**: `SQUISH_WEIGHT_GRAPH_BOOST` (default: 1.5)
+
+### Added - Memory Lifecycle
+- **Decay scheduler**: Automatic tier promotion/demotion based on importance
+- **Tier system**: hot → warm → cold → expired
+- **Cron-based**: Configurable via `SQUISH_LIFECYCLE_DECAY_CRON`
+- **New schema columns**: `status`, `decay_rate`, `last_decay_at`
+
+### Added - Supabase Backend Support
+- **PostgreSQL via Supabase**: New backend option
+- **Auto-detection**: Uses Supabase when `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` are set
+- **Drizzle ORM**: Full compatibility with existing queries
+
+### Changed - Memory Types
+- Replaced `jot` type with `note`
+- Added `reflection` type
+- Updated categorizer, merge strategies, and two-stage detector
+
 ## [1.0.0] - 2026-03-17
 
 ### 🚀 Major Release - Universal Plugin Architecture