@lesgo/memory-mcp 1.0.0

package/dist/writer.js

@@ -0,0 +1,162 @@
+import { cache } from './cache.js';
+import { writeQueue } from './queue.js';
+import { updateIndex } from './index-gen.js';
+import { log } from './logger.js';
+// Maximum file size: 1MB (GitHub API limit for base64 content)
+const MAX_FILE_SIZE = 1 * 1024 * 1024;
+/**
+ * Async writer manager - handles non-blocking GitHub operations
+ * Updates cache immediately, returns to agent, syncs GitHub in background
+ */
+export class AsyncWriter {
+    github;
+    pendingWrites = new Set();
+    constructor(github) {
+        this.github = github;
+    }
+    /**
+     * Save a file - updates cache immediately, syncs GitHub async
+     * Returns immediately after cache update
+     */
+    async save(category, name, content) {
+        // Validate file size
+        const contentSize = Buffer.byteLength(content, 'utf-8');
+        if (contentSize > MAX_FILE_SIZE) {
+            return {
+                success: false,
+                path: '',
+                error: `File size (${Math.round(contentSize / 1024)}KB) exceeds maximum allowed size (${MAX_FILE_SIZE / 1024}KB)`,
+            };
+        }
+        // Normalize category and name
+        const normalizedCategory = category.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+        const normalizedName = name.endsWith('.md') || name.endsWith('.yaml') || name.endsWith('.json')
+            ? name
+            : `${name}.md`;
+        const path = `${normalizedCategory}/${normalizedName}`;
+        // Get existing SHA if file exists in cache
+        const existing = cache.get(path);
+        const sha = existing?.sha;
+        // Update cache immediately (optimistic)
+        cache.set(path, content, sha ?? 'pending');
+        // Fire-and-forget GitHub sync
+        this.syncToGitHub(path, content, sha);
+        return { success: true, path };
+    }
+    /**
+     * Delete a file - removes from cache immediately, syncs GitHub async
+     */
+    async delete(path) {
+        const existing = cache.get(path);
+        if (!existing) {
+            return { success: false, error: `File not found: ${path}` };
+        }
+        // Remove from cache immediately
+        cache.delete(path);
+        // Fire-and-forget GitHub delete
+        this.deleteFromGitHub(path, existing.sha);
+        return { success: true };
+    }
+    /**
+     * Sync a file to GitHub (async, non-blocking)
+     */
+    async syncToGitHub(path, content, sha) {
+        // Prevent duplicate syncs
+        if (this.pendingWrites.has(path)) {
+            log('writer', `Sync already pending for: ${path}`);
+            return;
+        }
+        this.pendingWrites.add(path);
+        try {
+            log('writer', `Starting async sync: ${path}`);
+            const newSha = await this.github.putFile(path, content, sha);
+            // Update cache with real SHA
+            cache.set(path, content, newSha);
+            // Update index
+            await this.updateIndexSafe();
+            // Remove from queue if it was there
+            writeQueue.remove(path);
+            log('writer', `Sync complete: ${path}`);
+        }
+        catch (error) {
+            log('writer', `Sync failed for ${path}: ${error}`);
+            // Add to queue for retry
+            writeQueue.enqueue(path, content, 'save');
+        }
+        finally {
+            this.pendingWrites.delete(path);
+        }
+    }
+    /**
+     * Delete a file from GitHub (async, non-blocking)
+     */
+    async deleteFromGitHub(path, sha) {
+        if (this.pendingWrites.has(path)) {
+            return;
+        }
+        this.pendingWrites.add(path);
+        try {
+            log('writer', `Starting async delete: ${path}`);
+            await this.github.deleteFile(path, sha);
+            // Update index
+            await this.updateIndexSafe();
+            // Remove from queue if it was there
+            writeQueue.remove(path);
+            log('writer', `Delete complete: ${path}`);
+        }
+        catch (error) {
+            log('writer', `Delete failed for ${path}: ${error}`);
+            // Add to queue for retry
+            writeQueue.enqueue(path, '', 'delete');
+        }
+        finally {
+            this.pendingWrites.delete(path);
+        }
+    }
+    /**
+     * Update index without blocking on errors
+     */
+    async updateIndexSafe() {
+        try {
+            await updateIndex(this.github, cache);
+        }
+        catch (error) {
+            log('writer', `Index update failed: ${error}`);
+        }
+    }
+    /**
+     * Drain the write queue - called on startup and after successful operations
+     */
+    async drainQueue() {
+        const items = writeQueue.getAll();
+        if (items.length === 0) {
+            return;
+        }
+        log('queue', `Draining ${items.length} queued items`);
+        for (const item of items) {
+            try {
+                if (item.operation === 'save') {
+                    const existing = cache.get(item.path);
+                    await this.github.putFile(item.path, item.content, existing?.sha);
+                    writeQueue.remove(item.path);
+                    log('queue', `Drained: ${item.path}`);
+                }
+                else if (item.operation === 'delete') {
+                    const existing = cache.get(item.path);
+                    if (existing) {
+                        await this.github.deleteFile(item.path, existing.sha);
+                    }
+                    writeQueue.remove(item.path);
+                    log('queue', `Drained delete: ${item.path}`);
+                }
+            }
+            catch (error) {
+                log('queue', `Failed to drain ${item.path}: ${error}`);
+                writeQueue.incrementRetry(item.path);
+            }
+        }
+        // Update index after draining
+        await this.updateIndexSafe();
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lesgo/memory-mcp",
+  "version": "1.0.0",
+  "description": "Personal External Brain MCP Server - A stateless MCP server for syncing templates, standards, and knowledge via GitHub",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "memory-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clayton-duarte/memory-mcp.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "github",
+    "knowledge-base"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@octokit/rest": "^20.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}