@squidcode/forever-plugin 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP (Model Context Protocol) plugin for [Forever](https://forever.squidcode.com) — a centralized persistent memory layer for Claude Code instances.
 
-Forever lets multiple Claude Code sessions share memory across machines, projects, and time. This plugin connects Claude Code to your Forever server via MCP.
+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
 
@@ -34,30 +34,41 @@ This registers the plugin as an MCP server that Claude Code will start automatic
 
 ## Tools
 
-The plugin exposes three MCP tools:
+The plugin exposes the following MCP tools:
 
-### `memory_log`
+### Memory Tools
+
+#### `memory_log`
 
 Log an entry to Forever memory.
 
 | Parameter   | Type     | Required | Description                          |
 |-------------|----------|----------|--------------------------------------|
-| `project`   | string   | yes      | Project name or git remote URL       |
+| `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`
+#### `memory_get_recent`
 
 Get recent memory entries for a project.
 
 | Parameter | Type   | Required | Description                    |
 |-----------|--------|----------|--------------------------------|
-| `project` | string | yes      | Project name or git remote URL |
+| `project` | string | no       | Project name or git remote URL (auto-detected) |
 | `limit`   | number | no       | Number of entries (default 20) |
 
-### `memory_search`
+#### `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.
 
@@ -68,11 +79,59 @@ Search memory entries across projects.
 | `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
 

package/dist/client.d.ts

@@ -11,5 +11,7 @@ export declare function getCredentials(): Credentials | null;
 export declare function saveCredentials(creds: Credentials): void;
 export declare function getMachineConfig(): MachineConfig | null;
 export declare function saveMachineConfig(config: MachineConfig): void;
-export declare function createApiClient(): AxiosInstance | null;
+export declare function createApiClient(options?: {
+    timeout?: number;
+}): AxiosInstance | null;
 export {};

package/dist/client.js

@@ -42,7 +42,7 @@ export function saveMachineConfig(config) {
         mode: 0o600,
     });
 }
-export function createApiClient() {
+export function createApiClient(options) {
     const creds = getCredentials();
     if (!creds)
         return null;
@@ -52,6 +52,6 @@ export function createApiClient() {
             Authorization: `Bearer ${creds.token}`,
             'Content-Type': 'application/json',
         },
-        timeout: 10000,
+        timeout: options?.timeout ?? 10000,
     });
 }

package/dist/files.d.ts

@@ -0,0 +1,8 @@
+export declare function computeMd5(buffer: Buffer): string;
+export declare function isBinary(buffer: Buffer): boolean;
+export declare function readAndEncodeFile(filePath: string): {
+    content: string;
+    hash: string;
+    size: number;
+};
+export declare function writeDecodedFile(filePath: string, content: string): void;

package/dist/files.js

@@ -0,0 +1,31 @@
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+export function computeMd5(buffer) {
+    return createHash('md5').update(buffer).digest('hex');
+}
+export function isBinary(buffer) {
+    const sample = buffer.subarray(0, 8192);
+    return sample.includes(0);
+}
+export function readAndEncodeFile(filePath) {
+    const buffer = readFileSync(filePath);
+    if (buffer.length > 1_048_576) {
+        throw new Error(`File exceeds 1MB limit (${buffer.length} bytes)`);
+    }
+    const hash = computeMd5(buffer);
+    const content = isBinary(buffer)
+        ? `base64:${buffer.toString('base64')}`
+        : buffer.toString('utf-8');
+    return { content, hash, size: buffer.length };
+}
+export function writeDecodedFile(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    if (content.startsWith('base64:')) {
+        const data = Buffer.from(content.slice(7), 'base64');
+        writeFileSync(filePath, data);
+    }
+    else {
+        writeFileSync(filePath, content, 'utf-8');
+    }
+}

package/dist/index.js

@@ -7,9 +7,12 @@ import { randomBytes } from 'crypto';
 import { basename } from 'path';
 import { createApiClient } from './client.js';
 import { getOrCreateMachineId } from './machine.js';
+import { readAndEncodeFile, writeDecodedFile, computeMd5 } from './files.js';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
 const server = new McpServer({
     name: 'forever',
-    version: '0.2.0',
+    version: '0.4.0',
 });
 const machineId = getOrCreateMachineId();
 const sessionId = `${Date.now()}-${randomBytes(4).toString('hex')}`;
@@ -177,6 +180,85 @@ server.tool('memory_get_recent', 'Get recent memory entries for a project', {
         };
     }
 });
+server.tool('memory_get_sessions', 'Get recent sessions for a project, grouped by session with machine info. Use at startup to detect cross-machine handoffs.', {
+    project: z
+        .string()
+        .optional()
+        .describe('Project name or git remote URL (auto-detected from git if omitted)'),
+    limit: z
+        .number()
+        .optional()
+        .default(10)
+        .describe('Number of recent sessions to fetch'),
+}, async ({ project, limit }) => {
+    const api = createApiClient();
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    try {
+        const res = await api.get('/logs/sessions', {
+            params: { project: resolvedProject, machineId, limit },
+        });
+        const { sessions, hasRemoteActivity } = res.data;
+        if (!sessions.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No previous sessions found for "${resolvedProject}".`,
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        if (hasRemoteActivity) {
+            lines.push('⚡ REMOTE ACTIVITY DETECTED — Sessions from other machines found for this project.\n');
+        }
+        for (const s of sessions) {
+            const machine = s.machineName || 'unknown';
+            const remote = s.isRemote ? ' [REMOTE]' : ' [LOCAL]';
+            const branch = s.gitBranch ? ` on ${s.gitBranch}` : '';
+            const commit = s.gitCommit ? ` @ ${s.gitCommit}` : '';
+            lines.push(`## Session ${s.sessionId}${remote}`);
+            lines.push(`Machine: ${machine}${branch}${commit}`);
+            lines.push(`Time: ${s.startedAt} → ${s.endedAt} (${s.logCount} logs)`);
+            if (s.directory)
+                lines.push(`Directory: ${s.directory}`);
+            if (s.summary)
+                lines.push(`Summary: ${s.summary}`);
+            lines.push('');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to fetch sessions: ${err.message}`,
+                },
+            ],
+        };
+    }
+});
 server.tool('memory_search', 'Search memory entries across projects', {
     query: z.string().describe('Search query'),
     project: z.string().optional().describe('Filter by project'),
@@ -231,6 +313,390 @@ server.tool('memory_search', 'Search memory entries across projects', {
         };
     }
 });
+// --- File Storage & Sharing Tools ---
+function resolveFilePath(filePath) {
+    return resolve(process.cwd(), filePath);
+}
+server.tool('memory_store_file', 'Store a file in Forever for cross-machine access', {
+    filePath: z
+        .string()
+        .describe('Path to the file to store (relative or absolute)'),
+    project: z
+        .string()
+        .optional()
+        .describe('Project name (auto-detected from git if omitted)'),
+}, async ({ filePath, project }) => {
+    const api = createApiClient({ timeout: 30000 });
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    const absPath = resolveFilePath(filePath);
+    if (!existsSync(absPath)) {
+        return {
+            content: [
+                { type: 'text', text: `File not found: ${absPath}` },
+            ],
+        };
+    }
+    try {
+        const { content, hash, size } = readAndEncodeFile(absPath);
+        const res = await api.post('/files/store', {
+            project: resolvedProject,
+            filePath,
+            content,
+            contentHash: hash,
+            machineId,
+            sessionId,
+        });
+        const dedup = res.data.deduplicated ? ' (unchanged, skipped)' : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Stored "${filePath}" (${size} bytes)${dedup}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err.response?.data?.message || err.message;
+        return {
+            content: [
+                { type: 'text', text: `Failed to store file: ${msg}` },
+            ],
+        };
+    }
+});
+server.tool('memory_restore_file', 'Restore a file from Forever to the local disk', {
+    filePath: z.string().describe('Path of the file to restore'),
+    project: z
+        .string()
+        .optional()
+        .describe('Project name (auto-detected from git if omitted)'),
+}, async ({ filePath, project }) => {
+    const api = createApiClient({ timeout: 30000 });
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    try {
+        const res = await api.get('/files/latest', {
+            params: { project: resolvedProject, filePath },
+        });
+        if (!res.data) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No stored version found for "${filePath}"`,
+                    },
+                ],
+            };
+        }
+        const absPath = resolveFilePath(filePath);
+        writeDecodedFile(absPath, res.data.content);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Restored "${filePath}" (hash: ${res.data.contentHash})`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err.response?.data?.message || err.message;
+        return {
+            content: [
+                { type: 'text', text: `Failed to restore file: ${msg}` },
+            ],
+        };
+    }
+});
+server.tool('memory_share_file', 'Mark a file for auto-sync across machines (also stores it immediately)', {
+    filePath: z.string().describe('Path to the file to share'),
+    project: z
+        .string()
+        .optional()
+        .describe('Project name (auto-detected from git if omitted)'),
+}, async ({ filePath, project }) => {
+    const api = createApiClient({ timeout: 30000 });
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    const absPath = resolveFilePath(filePath);
+    if (!existsSync(absPath)) {
+        return {
+            content: [
+                { type: 'text', text: `File not found: ${absPath}` },
+            ],
+        };
+    }
+    try {
+        // Store the file first
+        const { content, hash, size } = readAndEncodeFile(absPath);
+        await api.post('/files/store', {
+            project: resolvedProject,
+            filePath,
+            content,
+            contentHash: hash,
+            machineId,
+            sessionId,
+        });
+        // Mark as shared
+        await api.post('/files/share', {
+            project: resolvedProject,
+            filePath,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Shared "${filePath}" (${size} bytes) — will auto-sync across machines`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err.response?.data?.message || err.message;
+        return {
+            content: [
+                { type: 'text', text: `Failed to share file: ${msg}` },
+            ],
+        };
+    }
+});
+server.tool('memory_unshare_file', 'Stop auto-syncing a file across machines', {
+    filePath: z.string().describe('Path of the file to stop sharing'),
+    project: z
+        .string()
+        .optional()
+        .describe('Project name (auto-detected from git if omitted)'),
+}, async ({ filePath, project }) => {
+    const api = createApiClient();
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    try {
+        await api.post('/files/unshare', {
+            project: resolvedProject,
+            filePath,
+        });
+        return {
+            content: [
+                { type: 'text', text: `Stopped sharing "${filePath}"` },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err.response?.data?.message || err.message;
+        return {
+            content: [
+                { type: 'text', text: `Failed to unshare file: ${msg}` },
+            ],
+        };
+    }
+});
+server.tool('memory_sync_files', 'Sync all shared files for a project — downloads newer versions, uploads local changes', {
+    project: z
+        .string()
+        .optional()
+        .describe('Project name (auto-detected from git if omitted)'),
+}, async ({ project }) => {
+    const api = createApiClient({ timeout: 30000 });
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: npx @squidcode/forever-plugin login',
+                },
+            ],
+        };
+    }
+    const resolvedProject = resolveProject(project);
+    if (!resolvedProject) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Could not detect project. Please specify a project name.',
+                },
+            ],
+        };
+    }
+    try {
+        // Get list of shared files
+        const sharedRes = await api.get('/files/shared', {
+            params: { project: resolvedProject },
+        });
+        const sharedFiles = sharedRes.data;
+        if (!sharedFiles.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No shared files for "${resolvedProject}"`,
+                    },
+                ],
+            };
+        }
+        // Build local hash map
+        const localFiles = [];
+        for (const sf of sharedFiles) {
+            const absPath = resolveFilePath(sf.filePath);
+            if (existsSync(absPath)) {
+                const buffer = readFileSync(absPath);
+                localFiles.push({
+                    filePath: sf.filePath,
+                    contentHash: computeMd5(buffer),
+                    exists: true,
+                });
+            }
+            else {
+                localFiles.push({
+                    filePath: sf.filePath,
+                    contentHash: '',
+                    exists: false,
+                });
+            }
+        }
+        // Check sync status
+        const syncRes = await api.post('/files/sync', {
+            project: resolvedProject,
+            files: localFiles.map((f) => ({
+                filePath: f.filePath,
+                contentHash: f.contentHash,
+            })),
+        });
+        const results = [];
+        let downloaded = 0;
+        let uploaded = 0;
+        let upToDate = 0;
+        for (const file of syncRes.data.files) {
+            const local = localFiles.find((f) => f.filePath === file.filePath);
+            if (file.status === 'download_needed' ||
+                (file.status === 'upload_needed' && !local?.exists)) {
+                // Download from server
+                const latestRes = await api.get('/files/latest', {
+                    params: { project: resolvedProject, filePath: file.filePath },
+                });
+                if (latestRes.data) {
+                    const absPath = resolveFilePath(file.filePath);
+                    writeDecodedFile(absPath, latestRes.data.content);
+                    results.push(`↓ ${file.filePath}`);
+                    downloaded++;
+                }
+            }
+            else if (file.status === 'upload_needed' && local?.exists) {
+                // Upload to server
+                const { content, hash } = readAndEncodeFile(resolveFilePath(file.filePath));
+                await api.post('/files/store', {
+                    project: resolvedProject,
+                    filePath: file.filePath,
+                    content,
+                    contentHash: hash,
+                    machineId,
+                    sessionId,
+                });
+                results.push(`↑ ${file.filePath}`);
+                uploaded++;
+            }
+            else {
+                upToDate++;
+            }
+        }
+        const summary = [`Synced ${sharedFiles.length} shared file(s):`];
+        if (downloaded)
+            summary.push(`  ${downloaded} downloaded`);
+        if (uploaded)
+            summary.push(`  ${uploaded} uploaded`);
+        if (upToDate)
+            summary.push(`  ${upToDate} up to date`);
+        if (results.length)
+            summary.push('', ...results);
+        return {
+            content: [{ type: 'text', text: summary.join('\n') }],
+        };
+    }
+    catch (err) {
+        const msg = err.response?.data?.message || err.message;
+        return {
+            content: [{ type: 'text', text: `Sync failed: ${msg}` }],
+        };
+    }
+});
 // Login subcommand
 if (process.argv[2] === 'login') {
     const readline = await import('readline');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcode/forever-plugin",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP plugin for Forever - Claude Memory System",
   "type": "module",
   "bin": {