Persistent memory for Claude Code with OpenClaw integration, semantic search, and team sync
npm install squish-memorysquish remember, search, recall directly from terminal
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
/core_memory - View, edit, or append to always-in-context memory sections
/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
/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
/merge - Detect duplicates, preview/approve/reject merges
/health - Check MCP server and database connectivity
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
$3
`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
`
$3
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.
$3
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
$3
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
$3
Install and use directly from terminal:
`bash
npm install -g squish-memory
Store memories
squish remember "User prefers TypeScript for all projects" --type preference
squish remember "API uses JWT authentication" --type fact
Search memories
squish search "authentication" --limit 5
squish search "TypeScript" --type fact
View core memory
squish core_memory view
Retrieve by ID
squish recall
`
Memory Types: fact, decision, preference, observation, context
Embedding Options:
By default, Squish uses local TF-IDF embeddings (zero dependencies, works offline).
For better semantic search, configure an embedding provider:
`bash
OpenAI embeddings (best quality)
export SQUISH_OPENAI_API_KEY=sk-...
export SQUISH_EMBEDDINGS_PROVIDER=openai
Ollama local embeddings (good quality, runs locally)
export SQUISH_EMBEDDINGS_PROVIDER=ollama
export SQUISH_OLLAMA_URL=http://localhost:11434
Or set in your shell profile (~/.bashrc or ~/.zshrc)
echo "export SQUISH_OPENAI_API_KEY=sk-..." >> ~/.bashrc
echo "export SQUISH_EMBEDDINGS_PROVIDER=openai" >> ~/.bashrc
`
$3
$3
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."
`
$3
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
Find relevant past learnings:
`bash
/search projectId=my-project query="kubernetes deployment" limit=5
`
$3
Load relevant memories for agent use:
`bash
/context_paging action=load sessionId=session-123 projectId=my-project memoryId=mem-456
`
Architecture
$3
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
$3
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
$3
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
$3
`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"
`
$3
`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
`
$3
`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
`
$3
`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
$3
- 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
$3
- 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.
$3
| Metric | Value |
|--------|-------|
| Accuracy | 80% (16/20 correct) |
| Embeddings | Nomic (nomic-embed-text) |
| Generation | Claude Haiku |
| Judge | Claude Haiku |
| Avg Latency | ~1.2s per question |
$3
- 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
$3
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)
$3
`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.
Development
$3
`
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
`
$3
`bash
Install dependencies
npm install
Build TypeScript
npm run build
Run tests
npm run test
Pack for distribution
npm pack
`
$3
`bash
Run comprehensive system test
node test-v0.5.0.mjs
Start development with watch mode
npm run dev
`
Troubleshooting
$3
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
$3
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
$3
Memory is growing unbounded
- Enable lifecycle management: SQUISH_LIFECYCLE_ENABLED=true
- Review memory decay rates in configuration
$3
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`