---
title: Squish - Full Documentation
description: Extended documentation for Squish, a local-first memory runtime for AI agents.
url: https://squishplugin.dev
version: 1.5.0
---

# Squish - Full Documentation

## Overview

Squish is a local-first memory runtime for AI agents. It captures durable signal from agent sessions, derives beliefs (decisions, constraints, preferences), and restores context when sessions restart. Squish works with ChatGPT, Claude Code, Cursor, OpenCode, and any MCP-compatible tool.

## Architecture

### Memory Flow

```
Agent Session -> Capture -> Store (SQLite/PostgreSQL) -> Derive Beliefs -> Restore Context
                      |
                      v
              CLI / MCP / Web UI (inspection)
```

### Core Components

1. **Memory Store** - SQLite (local) or PostgreSQL (shared). Stores observations, facts, decisions, context, preferences, and notes.
2. **Belief Engine** - Derives durable beliefs from raw observations. Beliefs are inspectable runtime state that agents can query.
3. **MCP Server** - 15 tools for memory operations (remember, recall, context, health, etc.). Runs locally on port 3001.
4. **CLI** - Command-line interface for memory operations, installer, and diagnostics.
5. **Web UI** - Local dashboard at localhost:3000 for browsing and managing memories.
6. **Cloud Sync** - Optional cloud storage at squishplugin.dev with OAuth authentication.

### Storage Architecture

| Component | Technology | Purpose |
|-----------|-----------|---------|
| Memory Store | SQLite (local) / PostgreSQL (cloud) | Persistent memory storage |
| MCP Server | TypeScript + Express | Tool interface for agents |
| CLI | TypeScript + Node.js | Command-line interface |
| Web UI | React 19 + Vite | Browser-based management |
| Cloud API | Node.js + Express | Remote sync and management |
| Auth | OAuth 2.0 | Cloud authentication |
| Payments | Stripe | Subscription management |
| Analytics | PostHog | Usage tracking |

## Installation

### Prerequisites

- Node.js 18+ (for npm)
- npm (for global package installation)

### Install Commands

```bash
# Install globally
npm i -g squish-memory

# Run the interactive installer
squish install

# Or install for a specific tool
npx squish-memory install --tool claude
npx squish-memory install --tool chatgpt
npx squish-memory install --tool cursor
npx squish-memory install --tool opencode
```

### What the Installer Does

1. Installs the `squish-memory` npm package globally
2. Creates a `.squish/` directory in your home folder
3. Initializes a SQLite database for memory storage
4. Configures MCP server settings for your chosen tools
5. Sets up the local web UI
6. Optionally connects to Squish Cloud

## CLI Reference

### Core Commands

| Command | Description | Example |
|---------|-------------|---------|
| `squish install` | Interactive installer | `squish install` |
| `squish remember <text>` | Store a memory | `squish remember "use TypeScript strict mode"` |
| `squish recall <query>` | Search memories | `squish recall "project preferences"` |
| `squish context` | Show project context | `squish context` |
| `squish doctor` | Check runtime status | `squish doctor` |
| `squish cloud` | Cloud onboarding | `squish cloud` |
| `squish stats` | Memory statistics | `squish stats` |
| `squish recent` | Recent memories | `squish recent --days 7` |
| `squish stale` | Show stale memories | `squish stale --days 30` |
| `squish pin <id>` | Pin a memory | `squish pin abc123` |
| `squish unpin <id>` | Unpin a memory | `squish unpin abc123` |
| `squish link` | Manage memory links | `squish link add --from abc --to def` |
| `squish projects` | List projects | `squish projects` |
| `squish onboarding` | Show onboarding status | `squish onboarding` |

### Global Options

| Option | Description |
|--------|-------------|
| `--project <path>` | Specify project path |
| `--json` | Output in JSON format |
| `--verbose` | Verbose logging |
| `--help` | Show help |

## MCP Server

### Tools Available

The Squish MCP server exposes 15 tools:

| Tool | Description |
|------|-------------|
| `squish_remember` | Store a memory |
| `squish_recall` | Search memories by query |
| `squish_context` | Get project context |
| `squish_stats` | Memory statistics |
| `squish_recent` | Recent memories by period |
| `squish_stale` | Stale memories |
| `squish_inspect` | Inspect why a memory was retained |
| `squish_link` | Manage memory associations |
| `squish_pin` | Pin/unpin memories |
| `squish_list_pinned` | List pinned memories |
| `squish_health` | System health check |
| `squish_forget` | Delete memories |
| `squish_on_session_start` | Session start hook |
| `squish_on_session_end` | Session end hook |
| `squish_on_tool_use` | Tool use capture hook |

### MCP Configuration

```json
{
  "mcpServers": {
    "squish": {
      "command": "npx",
      "args": ["-y", "squish-memory", "mcp"],
      "env": {
        "SQUISH_DB_PATH": "~/.squish/memory.db"
      }
    }
  }
}
```

### MCP Server Location

- Local server: `http://localhost:3001`
- Cloud API: `https://api.squishplugin.dev`

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SQUISH_DB_PATH` | `~/.squish/memory.db` | SQLite database path |
| `SQUISH_CLOUD_URL` | `https://api.squishplugin.dev` | Cloud API URL |
| `SQUISH_MCP_PORT` | `3001` | MCP server port |
| `SQUISH_UI_PORT` | `3000` | Web UI port |
| `SQUISH_LOG_LEVEL` | `info` | Logging level |

### Database Schema

The SQLite database uses the following tables:

- **memories** - Core memory storage (id, content, type, project, created_at, accessed_at, confidence)
- **beliefs** - Derived beliefs (id, content, type, source_ids, created_at)
- **tags** - Memory tags (id, memory_id, tag)
- **links** - Memory associations (id, from_id, to_id, type, weight)
- **projects** - Project registry (id, path, name, created_at)
- **sessions** - Session tracking (id, project_id, started_at, ended_at)

## Cloud Features

### Squish Cloud

Squish Cloud is a managed service that adds:

- Cross-tool memory sync (same memory across ChatGPT, Claude Code, Cursor)
- Web-based memory management
- Team collaboration features
- API access for custom integrations
- Automatic backups

### Cloud Pricing

| Plan | Price | Requests/Mo | Features |
|------|-------|-------------|----------|
| Free | $0 | 2,000 | Unlimited memory, CLI + ChatGPT/Claude |
| Pro | $19/mo | 50,000 | Cross-tool sync, API access |
| Team | $49/mo | 200,000 | Team collaboration, shared workspaces |
| Scale | $149/mo | 1M+ | Custom integrations, SLA |

### OAuth Setup

1. Visit https://squishplugin.dev/cloud
2. Click "Sign In" (uses Clerk authentication)
3. Authorize Squish Cloud
4. Run `squish cloud` to connect your local instance

## Compatible Tools

| Tool | Integration Method | Notes |
|------|-------------------|-------|
| ChatGPT | MCP via custom GPT | Requires ChatGPT Plus for custom GPTs |
| Claude Code | Native MCP | Built-in MCP support |
| Cursor | MCP configuration | Add to cursor.json |
| OpenCode | Native MCP | Automatic detection |
| Local Agents | MCP server | Any MCP-compatible agent |
| Custom Tools | REST API | Use the Cloud API |

### Tool-Specific Setup

#### Claude Code
```bash
# Add to ~/.claude/claude.json
{
  "mcpServers": {
    "squish": {
      "command": "npx",
      "args": ["-y", "squish-memory", "mcp"]
    }
  }
}
```

#### Cursor
```json
// Add to ~/.cursor/mcp.json
{
  "mcpServers": {
    "squish": {
      "command": "npx",
      "args": ["-y", "squish-memory", "mcp"]
    }
  }
}
```

## Troubleshooting

### Common Issues

**MCP server won't start**
- Check Node.js version: `node --version` (needs 18+)
- Check port availability: `lsof -i :3001`
- Restart: `squish doctor`

**Memories not persisting**
- Check database path: `SQUISH_DB_PATH`
- Verify disk space
- Check file permissions on `~/.squish/`

**Cloud sync not working**
- Re-authenticate: `squish cloud`
- Check internet connection
- Verify API endpoint: `curl https://api.squishplugin.dev/health`

### Diagnostics

```bash
# Full system check
squish doctor

# Check database integrity
squish doctor --verbose

# View MCP server logs
squish doctor --logs
```

## API Reference

### REST API (Cloud)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/memories` | GET | List memories |
| `/api/memories` | POST | Create memory |
| `/api/memories/:id` | GET | Get memory |
| `/api/memories/:id` | DELETE | Delete memory |
| `/api/recall` | POST | Search memories |
| `/api/context` | GET | Get project context |

### Authentication

All API requests require OAuth 2.0 Bearer token:
```
Authorization: Bearer <token>
```

## Contributing

Squish is open-source (MIT). Contributions welcome:

1. Fork the repository: https://github.com/4m-labs/squish
2. Create a feature branch
3. Submit a pull request

## Links

- **Website**: https://squishplugin.dev
- **GitHub**: https://github.com/4m-labs/squish
- **npm**: https://www.npmjs.com/package/squish-memory
- **Cloud**: https://squishplugin.dev/cloud
- **Docs**: https://squishplugin.dev/docs
- **Organization**: https://4mlabs.io
- **Issues**: https://github.com/4m-labs/squish/issues