@squidcode/forever-plugin

MCP (Model Context Protocol) plugin for Forever — a centralized persistent memory layer for Claude Code instances.

Forever lets multiple Claude Code sessions share memory and files across machines, projects, and time. This plugin connects Claude Code to your Forever server via MCP.

Prerequisites

• Node.js 18+
• A Forever account (register here)

Setup

1. Authenticate

npx @squidcode/forever-plugin login

This opens your browser for authentication (similar to gh auth login):

1. A verification code is displayed in your terminal (e.g. ABCD-EF23)
2. Your browser opens to https://forever.squidcode.com/auth/device
3. Log in if needed, then confirm the code matches and click Authorize
4. The plugin receives your token automatically — no passwords in the terminal

Credentials are saved to ~/.forever/credentials.json (mode 0600).

On successful login, Forever instructions are automatically added to ~/.claude/CLAUDE.md so Claude Code knows how to use the memory tools.

2. Add to Claude Code

claude mcp add forever -- npx @squidcode/forever-plugin

This registers the plugin as an MCP server that Claude Code will start automatically.

CLI Commands

npx @squidcode/forever-plugin <command>

| Command | Description | |--------------------|--------------------------------------------------------| | login | Authenticate with Forever (device auth flow) | | install | Add Forever instructions to ~/.claude/CLAUDE.md | | install --force | Add instructions even if already present | | log <data> | Log a memory entry from the CLI (see below) | | search <query> | Search memory entries (see below) | | help | Show help message |

Without a command, the plugin starts in MCP server mode (used by Claude Code internally).

log command

Log memory entries from any script or tool — no MCP required.

# Plain text → logged as type "summary"
npx @squidcode/forever-plugin log "deployed v2.1 to production"

# JSON → extract type, content, tags, project, sessionId
npx @squidcode/forever-plugin log '{"type":"decision","content":"chose postgres","tags":["db"]}'

Plain text is logged as a summary entry. JSON input with a content field can specify type (summary, decision, error), tags, project, and sessionId. Project, machine ID, and git context are auto-detected.

search command

Search memory entries from the CLI.

npx @squidcode/forever-plugin search "postgres migration"
npx @squidcode/forever-plugin search "auth" --type decision --limit 5

| Option | Description | |---------------------|------------------------------------------| | --project <name> | Filter by project (auto-detected if omitted) | | --type <type> | Filter by type (summary, decision, error) | | --limit <n> | Max results (default 20) |

Tools

The plugin exposes the following MCP tools:

Memory Tools

memory_log

Log an entry to Forever memory.

| Parameter | Type | Required | Description | |-------------|----------|----------|--------------------------------------| | project | string | no | Project name or git remote URL (auto-detected) | | type | enum | yes | summary, decision, or error | | content | string | yes | The content to log | | tags | string[] | no | Tags for categorization | | sessionId | string | no | Session ID for grouping entries |

memory_get_recent

Get recent memory entries for a project.

| Parameter | Type | Required | Description | |-----------|--------|----------|--------------------------------| | project | string | no | Project name or git remote URL (auto-detected) | | limit | number | no | Number of entries (default 20) |

memory_get_sessions

Get recent sessions grouped by session with machine info. Use at startup to detect cross-machine handoffs.

| Parameter | Type | Required | Description | |-----------|--------|----------|--------------------------------| | project | string | no | Project name or git remote URL (auto-detected) | | limit | number | no | Number of sessions (default 10) |

memory_search

Search memory entries across projects.

| Parameter | Type | Required | Description | |-----------|--------|----------|------------------------| | query | string | yes | Search query | | project | string | no | Filter by project | | type | enum | no | Filter by entry type | | limit | number | no | Max results (default 20) |

File Tools

memory_store_file

Store a file in Forever for cross-machine access.

| Parameter | Type | Required | Description | |------------|--------|----------|---------------------------------| | filePath | string | yes | Path to the file (relative or absolute) | | project | string | no | Project name (auto-detected) |

memory_restore_file

Restore a file from Forever to the local disk.

| Parameter | Type | Required | Description | |------------|--------|----------|---------------------------------| | filePath | string | yes | Path of the file to restore | | project | string | no | Project name (auto-detected) |

memory_share_file

Mark a file for auto-sync across machines (also stores it immediately).

| Parameter | Type | Required | Description | |------------|--------|----------|---------------------------------| | filePath | string | yes | Path to the file to share | | project | string | no | Project name (auto-detected) |

memory_unshare_file

Stop auto-syncing a file across machines.

| Parameter | Type | Required | Description | |------------|--------|----------|---------------------------------| | filePath | string | yes | Path of the file to stop sharing | | project | string | no | Project name (auto-detected) |

memory_sync_files

Sync all shared files for a project — downloads newer versions, uploads local changes.

| Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------| | project | string | no | Project name (auto-detected) |

How It Works

• The plugin runs as an MCP stdio server, started by Claude Code on demand.
• Each machine gets a unique ID (stored in ~/.forever/machine.json) for tracking which machine produced each memory entry.
• All API calls are authenticated via JWT token obtained during login.
• Files up to 1MB are supported; binary files are automatically base64-encoded.
• File deduplication uses MD5 hashing — unchanged files are not re-uploaded.

Development

git clone https://github.com/squidcode/forever-plugin.git
cd forever-plugin
npm install
npm run build

Scripts

| Script | Description | |-----------------|------------------------------| | npm run build | Compile TypeScript | | npm run dev | Watch mode | | npm run lint | Run ESLint | | npm run format| Format with Prettier | | npm run typecheck | Type-check without emit |

Pre-commit Hooks

This project uses Husky + lint-staged to enforce code quality on every commit:

• ESLint auto-fix + Prettier formatting on staged .ts files
• Full TypeScript type-check

License

MIT